Class RearrangePkgFrame


  • public class RearrangePkgFrame
    extends java.lang.Object
    RearrangePkgFrame Class - Documentation.

    This class allows a user to specify as many sections as needed such that the "Package Frame" web-page - which is the HTML Page that lists all of the classes, interfaces, enums, errors, and exceptions - may be re-arranged to look nicer. If you have selected the "Use Frames" version of the Java Doc page that you are looking at right now, the original sub-lists / sections (classes, interfaces, enums, etc...) have since been replaced by different, less-generic, category names including these listed below:

    • Builder & Dispatch (Main A.P.I.)
    • Process javadoc HTML (Internal Use)
    • Parse javadoc HTML (Internal Use)
    • JavaParser-Bridge (external JAR)
    • Enums
    • Exceptions
    • Errors

    This example is just being used to (hopefully) elucidate / explain the purpose of this particular class. This example, again, if you are using the "Frames" version of the Java Doc Web Page Tool lists the classes, interfaces, etc... for the page you are looking at right now. Originally (before processing is done by this class) the HTML Page for the list of elements in this package originally had these section-names instead listed here, below:

    • Interfaces
    • Classes
    • Enums
    • Exceptions
    • Errors


    For a more visual explanation of what the primary method in this class does, please review the following before and after screen clips:

    RearrangePkgFrame Example

    Note that the input arrays are provided by the following 'Constants Class'. Click below to see the names of all the classes, interfaces, etc.. arranged such that the final page appears as above in the provided screen-capture image.

    Torello.Build.Helper.PackageItems.java


    Static (Functional) API: The methods in this class are all (100%) defined with the Java Key-Word / Key-Concept 'static'. Furthermore, there is no way to obtain an instance of this class, because there are no public (nor private) constructors. Java's Spring-Boot, MVC feature is *not* utilized because it flies directly in the face of the light-weight data-classes philosophy. This has many advantages over the rather ornate Component Annotations (@Component, @Service, @AutoWired, etc... 'Java Beans') syntax:

    • The methods here use the key-word 'static' which means (by implication) that there is no internal-state. Without any 'internal state' there is no need for constructors in the first place! (This is often the complaint by MVC Programmers).
    • A 'Static' (Functional-Programming) API expects to use fewer data-classes, and light-weight data-classes, making it easier to understand and to program.
    • The Vectorized HTML data-model allows more user-control over HTML parse, search, update & scrape. Also, memory management, memory leakage, and the Java Garbage Collector ought to be intelligible through the 'reuse' of the standard JDK class Vector for storing HTML Web-Page data.

    The power that object-oriented programming extends to a user is (mostly) limited to data-representation. Thinking of "Services" as "Objects" (Spring-MVC, 'Java Beans') is somewhat 'over-applying' the Object Oriented Programming Model. Like most classes in the Java-HTML JAR Library, this class backtracks to a more C-Styled Functional Programming Model (no Objects) - by re-using (quite profusely) the key-word static with all of its methods, and by sticking to Java's well-understood class Vector

    Static Fields: The methods in this class do not create any internal state that is maintained - however there are a few private & static fields defined. These fields are instantiated only once during the Class Loader phase (and only if this class shall be used), and serve as data 'lookup' fields (static constants). View this class' source-code in the link provided below to see internally used data.

    Internally a few private, static Vector<HTMLNode> fields are maintained in order to avoid re-instatiating / calling a constructor for certain HTML snippets that are re-inserted into a Package Frame HTML Page over and over again. These are {static-constants}. There is also a 'TextNode' and 'String' - final, static field.



    • Field Detail

      • JD_FRAMES_WARNING_MESSAGE

        public static final java.lang.String JD_FRAMES_WARNING_MESSAGE
        In order to generate 'package-frame.html' files, you must pass the --frames switch to the Java Doc Command Line Tool. When you do, you will receive this warning messsage.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
        1
        2
        3
        4
        5
        public static final String JD_FRAMES_WARNING_MESSAGE =
                "javadoc: warning - You have specified to generate frames, by using the --frames option.\n" +
                "The default is currently to not generate frames and the support for \n" +
                "frames will be removed in a future release.\n" +
                "To suppress this warning, remove the --frames option and avoid the use of frames.\n";
        
    • Method Detail

      • runAll

        public static void runAll​(RearrangePkgFrame.PackageItems items,
                                  java.lang.String rootJavaDocDirectory,
                                  StorageWriter sw)
                           throws FramesException
        This will iterate all 'package-frame.html' files, and convert them to look like the requested sorting defined by 'items' (an instance of 'PackageItems').
        Parameters:
        items - An instance of static inner-class 'Package Items'
        rootJavaDocDirectory - The root javadoc/ directory.
        Throws:
        FramesException
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
         for (int i=0; i < items.packages.length; i++)
         {
             String[] leftOut = RearrangePkgFrame.run(
                 items.packages[i],       rootJavaDocDirectory,
                 items.sectionNames[i],   items.sectionContents[i],
                 sw
             );
        
        
             if (leftOut.length != 0)
             {
                 StringBuilder sb = new StringBuilder();
        
                 for (String cietee : leftOut)
                     sb.append(
                         "For Package [" + items.packages[i] + "], apparently the page " +
                         "for [" + cietee + "] was not included in the final-output page.\n"
                     );
        
                 String s = sb.toString();
                 sw.print(s);
                 throw new FramesException(s);
             }
         }
        
      • run

        protected static java.lang.String[] run​
                    (java.lang.String pkgName,
                     java.lang.String rootJavaDocDir,
                     java.lang.String[] sectionNames,
                     java.lang.String[][] sectionCIETEELists,
                     StorageWriter sw)
                throws FramesException
        
        Later versions of Java-Doc have since deprecated the "Frames" option, although it is still present within the program, itself. If the "--frames" is used, both package-lists and class / interface / enum etc.. lists will be generated, and a brief or short one paragraph warning message is printed that frames are not popular in browser land. Don't believe it too much, the frames version of a Java-Doc page makes the documentation at least an order of magnitude more useable for a programmer learning an API. All modern browsers have absolutely no problems handling frames. It was a brief wave of fear that occurred in the early 2000's.

        Below is a snippet from a Package Frame List HTML Page. This is what the raw HTML looks like, and this is what needs to be rearranged. It is rearranged such that the final page resembles the lists, categories and order requested by the two String-array input parameters to this method.

        HTML Elements:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        16
         <h2 title="Classes">HTML Search Classes</h2>
         <ul title="Classes">
         <li><a href="ARGCHECK.html" title="class in Torello.HTML.NodeSearch" target="classFrame">ARGCHECK</a></li>
         <li><a href="JS.html" title="class in Torello.HTML.NodeSearch" target="classFrame">JS</a>
         <BR /><BR />
         <li><a href="TagNodeCount.html" title="class in Torello.HTML.NodeSearch" target="classFrame">TagNodeCount</a></li>
         <li><a href="TagNodeFind.html" title="class in Torello.HTML.NodeSearch" target="classFrame">TagNodeFind</a></li>
         <li><a href="TagNodeGet.html" title="class in Torello.HTML.NodeSearch" target="classFrame">TagNodeGet</a></li>
         <li><a href="TagNodePeek.html" title="class in Torello.HTML.NodeSearch" target="classFrame">TagNodePeek</a></li>
         <li><a href="TagNodePoll.html" title="class in Torello.HTML.NodeSearch" target="classFrame">TagNodePoll</a></li>
         <li><a href="TagNodeRemove.html" title="class in Torello.HTML.NodeSearch" target="classFrame">TagNodeRemove</a>
         <BR /><BR />
         </li>
         ...
         </ul>
         
        
        Parameters:
        pkgName - This is the name of the original, fully-qualified, 'Package Name'.
        rootJavaDocDir - In order to 'translate' a java package-name into a directory on disk, this method requires that the root-directory where the Java-Doc Tool has most recently left the latest build's Java-Doc output web-pages be passed to this method via this parameter.
        sectionNames - This should be a list of "Section Names" - specifically the sections in the list of classes, interfaces, enumerated-types (and exceptions/errors) in a "Frame Version" of a Java-Doc Generated Package Documentation Page. The default section names generated by the Java-Doc Tool are: Classes, Interfaces, Enums, Exceptions and Errors.

        NOTE: This array should be parallel to the 2-D array parameter 'sectionCIETLists'. The 'higher-order array' of the 2-D array parameter 'sectionCIETLists' is the array-index that needs to be parallel with this array parameter ('sectionNames').
        sectionCIETEELists - This array should contain the actual desired / expected contents of the "CIETEE Section". For instance, the default behavior of the Java-Doc Tool is to place all classes under a section named (surprisingly) 'Classes', and of course interfaces under a section named 'Interfaces', and so on and so forth.

        NOTE: In this Java Doc Upgrader Tool Package, the acronym CIET refers to Classes, Interfaces or Enumerated-Types (enums). The acronym CIETEE has the same meaning, but tacks on Exceptions and Errors to this list.

        NOTE: This array be built such that it is parallel to input array parameter 'sectionNames'. The first String-array parameter must contain the desired / expected names of the new sections, while the second parameter should hold the list of classes, interfaces, enums, exceptions and errors that belong in that parallel-array 'Section Name' on the output Java-Doc web-page for a particular package.
        sw - Output progress messages are sent to this StorageWriter.
        Returns:
        If any classes, interfaces, enums, exceptions or errors were left out, or "not found", anywhere in the 2-D input-array parameter sectionCIETEELists, then the String-array parameter that is returned from this method will list any / all Classes, Interfaces, Enums, Exceptions or Errors that the user seems to have (perhaps, accidentally) left out.

        Unless it is the intention of the user to eliminate the documentation for a particular page, the length of this return array should be zero. If it is not, it means that the final class-list frame page has not included a link for a CIETEE that did, in fact, have a Java-Doc generated HTML Page.
        Throws:
        java.lang.NullPointerException - If any of the input parameter arrays contain any null values. Also if any of the basic-String parameters contain null, then this exception will throw.
        FramesException - This method expects that every one of the class, interface, enumerated-type, exception or errors listed in the 2-D 'sectionCIETLists' array parameter to be identified on the original Package-Frame Web-Page that the Java-Doc tool generated for the package whose page is being rearranged.

        When this method executes, it will search the HTML Frame Web-Page for the particular section-item (again: this is always a class, interface, enum, exception, or error), and if any one of those items is not found on the original page, it will force a FramesException to throw. This behaviour cannot be bypassed.
        JavaDocHTMLParseException - This shall throw if there are any problems or errors while reading the original/default HTML Page for the Package-List that was initially created by the JavaDoc Tool. It should be unlikely that this exception throws, but the checks are in-place to prevent an uninformative 'NullPointerException' which makes debugging more difficult.
        ParallelArrayException - If 'sectionNames' is not the same length as the 2-D Array 'sectionCIETEELists'.
        Code:
        Exact Method Body:
          1
          2
          3
          4
          5
          6
          7
          8
          9
         10
         11
         12
         13
         14
         15
         16
         17
         18
         19
         20
         21
         22
         23
         24
         25
         26
         27
         28
         29
         30
         31
         32
         33
         34
         35
         36
         37
         38
         39
         40
         41
         42
         43
         44
         45
         46
         47
         48
         49
         50
         51
         52
         53
         54
         55
         56
         57
         58
         59
         60
         61
         62
         63
         64
         65
         66
         67
         68
         69
         70
         71
         72
         73
         74
         75
         76
         77
         78
         79
         80
         81
         82
         83
         84
         85
         86
         87
         88
         89
         90
         91
         92
         93
         94
         95
         96
         97
         98
         99
        100
        101
        102
        103
        104
        105
        106
        107
        108
        109
        110
        111
        112
        113
        114
        115
        116
        117
        118
        119
        120
        121
        122
        123
        124
        125
        126
        127
        128
        129
        130
        131
        132
        133
        134
        135
        136
        137
        138
        139
        140
        141
        142
        143
        144
        145
        146
        147
        148
        149
        150
        151
        152
        153
        154
        155
        156
        157
        158
        159
        160
        161
         if (pkgName == null) throw new NullPointerException
             ("The package-name parameter 'pkgName' was passed a null value.");
        
         if (rootJavaDocDir == null) throw new NullPointerException(
             "The root Java-Doc directory-name parameter 'rootJavaDocDir' was passed a null " +
             "value."
         );
        
         // This check is probably redunant.  It is also the quickest check that can be made.
         ParallelArrayException.check
             (sectionNames, "sectionNames", true, sectionCIETEELists, "sectionCIETEELists", true);
        
         // The filename of the package-frame list of contents (an 'HTML' page)
         String pkgFrameHTMLFileName =
             rootJavaDocDir + pkgName.replace(".", File.separator) + "/package-frame.html";
        
         // This portion of the code attempts to load the Package-Frame list of classes, interfaces
         // enums, errors and exceptions into a Vectorized-HTML page.
         Vector<HTMLNode> framesPkgPage;
        
         try
         { 
             framesPkgPage = HTMLPage.getPageTokens
                 (FileRW.loadFileToString(pkgFrameHTMLFileName), false);
         }
         catch (IOException ioe)
         {
             System.out.println("IOException: " + ioe.toString());
             ioe.printStackTrace();
             throw new JavaDocHTMLParseException(
                 "Unable to load HTML Frames Package Web-page for package [" + pkgName + "].  " +
                 "Was attempting to load file: [" + pkgFrameHTMLFileName + "], when the " +
                 "IOException was thrown.  See IOException that was thrown with ioe.getCause() " +
                 "for more details",
                 pkgFrameHTMLFileName, "entire class"
             );
         }
        
         // Excepting the first line "Package Name" (HTML Header <H1> Element), the entire page
         // list-contents are wrapped in a surrounding HTML <DIV> element that looks like as below:
         // <div class="indexContainer">
         DotPair mainDIV = InnerTagFindInclusive.first
             (framesPkgPage, "div", "class", TextComparitor.EQ, "indexContainer");
        
         if (mainDIV == null) throw new JavaDocHTMLParseException(
             "The original Java-Doc Generated HTML File for this package, having file-name " +
             '[' + pkgFrameHTMLFileName + "], did not have a main/surrounding HTML Divider " +
             "(<DIV class=\"indexContainer\">) Element.  Fatal Error, exiting.",
             pkgFrameHTMLFileName, "entire class"
         );
        
         // This will hold the **ORIGINAL** section lists.
         Vector<HTMLNode> original =
             Util.pollRange(framesPkgPage, mainDIV.start + 1, mainDIV.end);
        
         // This is the new / updated sublist.  This shall be re-inserted into the package
         // frames page when once all of the list items have been rearranged.
         Vector<HTMLNode> output = new Vector<>();
        
         for (int i=0; i < sectionNames.length; i++)
         {
             // This is the "extraneous" (does not appear to be used much by the Java-Doc CSS)
             // open-section HTML Element
             output.addAll(OPEN_SECTION);
        
             // This is the sub-list header
             output.addAll(
                 HTMLPage.getPageTokens(
                     '\n' +
                     "<H2 TITLE='" + sectionNames[i] + "'>" + sectionNames[i] + "</H2>\n" +
                     "<UL TITLE='" + sectionNames[i] + "'>\n",
                     false)
             );
        
             // Since 'sectionCIETLists' and 'sectionNames' are parallel arrays, this string
             // array is the list of desired list items (HTML '<LI>' Elements) for the sub-list
             // or 'section' category which we are currently iterating.
             String[] list = sectionCIETEELists[i];
        
             for (int j=0; j < list.length; j++)
             {
                 // This is the name of the class, interface, enum, exception or error that
                 // is being moved to a new, user-requested / user-created subsection.
                 String cieteeName = list[j].trim();
        
                 // This is how to insert a BLANK LINE
                 if (cieteeName.length() == 0)
                 {
                     output.addAll(EMPTY_LIST_ITEM);
                     continue;
                 }
            
                 // This line finds a TextNode that contains (exactly) the name of the class,
                 // interface, enumerated-type, error or exception as a text-string
                 int pos = TextNodeFind.first(original, TextComparitor.EQ, cieteeName);
        
                 // If this string is not found, the user has made an error in his request.
                 // For now, this is dealt with by throwing an exception.
                 if (pos == -1) throw new FramesException(
                     "One of the class, interface, enumerated-type, error or exceptions " +
                     "listed [" + cieteeName + "] for intended Package Frame Section " + 
                     "[" + sectionNames[i] + "] was not actually found within the original " +
                     "package frame HTML Page for [" + pkgName + "] that was generated by " +
                     "Java Doc."
                 );
        
                 // Retrieve the actual HTML List Item Element.  It looks as follows:
                 // <li><a href="TagNodeCount.html" title="class in Torello.HTML.NodeSearch" target="classFrame">TagNodeCount</a></li>
                 DotPair dp  = Surrounding.first(original, pos , "li");
        
                 if (dp == null) throw new FramesException(
                     "There was an error finding the surrounding HTML List Item (<LI>) elements " +
                     "for [" + cieteeName + "] for intended Package Frame Section [" +
                     sectionNames[i] + "] in package [" + pkgName + "].  Further information is " +
                     "not available, though the text itself was, indeed, identified on the " +
                     "Package-Frames HTML Page."
                 );
        
                 output.addAll(Util.pollRange(original, dp));
                 output.add(NEW_LINE);
             }
        
             output.addAll(CLOSE_UL);
             output.addAll(CLOSE_SECTION);
         }
        
         // All of the original lists/sections have been removed.  This was done before the loop.
         // Now insert the newly created lists that are in order / accordance with the users
         // requests.
         framesPkgPage.addAll(mainDIV.start + 1, output);
        
         // Re-write the original file to disk.
         sw.println("Writing File:\t" + C.BYELLOW + pkgFrameHTMLFileName + C.RESET);
         try
             { FileRW.writeFile(Util.pageToString(framesPkgPage), pkgFrameHTMLFileName); }
         catch (IOException ioe)
         {
             throw new JavaDocError(
                 "There was an IOException while attempting to write the file " +
                 "[" + pkgFrameHTMLFileName + "]\n Please see the Throwable.getCause() for " +
                 "more information."
             );
         }
        
         // Java's Streams are easiest for building lists of undetermined size.
         Stream.Builder<String> b = Stream.builder();
        
         // Retrieve any list elements that were not included in the
         for (Vector<HTMLNode> li : TagNodePollInclusive.all(original, "li"))
         {
             String s = Util.textNodesString(li);
             if (s == null) continue;
             s = s.trim();
             if (s.length() == 0) continue;
             b.accept(s);
         }
                
         // Return the list of any classes, interfaces, enumerated-types, errors or exceptions
         // that were not listed in the input-section list arrays.  Perhaps a particular class,
         // etc... was accidentally left out.
         return b.build().toArray(String[]::new);