Class RearrangePkgFrame


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

    This class allows a user to specify the arrangement of the files on both the package-summary.html files, and the package-frame.html files that are generated by Java Doc. Though the Frames option has been depracted by later versions of Java Doc, this was an extremely useful/convenient way to traverse Java Doc web-pages.

    Both the Package Summary pages, and the Frame pages lists arrange the entities on the page for a particular package in categories such as: Classes, Interfaces, Enums, Errors, Exceptions and also Annotations. If such a list is just to generic and ordinary to be useful, new orders and new sections may be created using this class.

    For a more visual explanation of what the primary method in this class does, please review the following before and after screen clips for a re-arranged package-frame.html file:

    RearrangePkgFrame Example

    The image below shows how a package-summary.html file is changed:

    PackageSummaries 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




Stateless Class: This class neither contains any program-state, nor can it be instantiated.
The @StaticFunctional Annotation may also be called 'The Spaghetti Report'
  • 1 Constructor(s), 1 declared private, zero-argument constructor
  • 4 Method(s), 4 declared static
  • 6 Field(s), 6 declared static, 6 declared final


    • 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 - If any of the class, interfaces, enums, etc... that were lited in the original frames file, or package-summary page were not listed in the provided arrays, then this exception throws.
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
         for (int i=0; i < items.packages.length; i++)
         {
             String[] leftOut = new String[0];
                    
             if (items.usesFrames) leftOut = RearrangePkgFrame.runFrames(
                 items.packages[i],       rootJavaDocDirectory,
                 items.sectionNames[i],   items.sectionContents[i],
                 sw
             );
        
             if (leftOut.length > 0) throwLeftOut(items.packages[i], leftOut, sw);
        
             leftOut = RearrangePkgFrame.runPackageSummaries(
                 items.packages[i],       rootJavaDocDirectory,
                 items.sectionNames[i],   items.sectionContents[i],
                 sw
             );
        
             if (leftOut.length != 0) throwLeftOut(items.packages[i], leftOut, sw);
         }
        
      • runFrames

        protected static java.lang.String[] runFrames​
                    (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
        <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, Errors and Annotations.

        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 (and Annotations - but who writes those?).

        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, error or annotation), and if any one of those items are 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
         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)
         {
             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", ioe,
                 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);
        
      • runPackageSummaries

        protected static java.lang.String[] runPackageSummaries​
                    (java.lang.String pkgName,
                     java.lang.String rootJavaDocDir,
                     java.lang.String[] sectionNames,
                     java.lang.String[][] sectionCIETEELists,
                     StorageWriter sw)
                throws FramesException
        
        Upgrade's the 'package-summary.html' page by re-arranging the lists of class, interfaces, enums, exceptions, errors and annotations according to the user requested arrays.
        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, Errors and Annotations.

        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 (and Annotations - but who writes those?).

        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, error or annotation), and if any one of those items are 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
        162
        163
        164
        165
        166
        167
        168
        169
        170
        171
        172
        173
        174
        175
        176
        177
        178
        179
        180
        181
         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 pkgSummHTMLFileName =
             rootJavaDocDir + pkgName.replace(".", File.separator) + "/package-summary.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> pkgSummPage;
        
         try
         { 
             pkgSummPage = HTMLPage.getPageTokens
                 (FileRW.loadFileToString(pkgSummHTMLFileName), false);
         }
         catch (IOException ioe)
         {
             throw new JavaDocHTMLParseException(
                 "Unable to load HTML Package Summary Web-page for package [" + pkgName + "].  " +
                 "Was attempting to load file: [" + pkgSummHTMLFileName + "], when the " +
                 "IOException was thrown.  See IOException that was thrown with ioe.getCause() " +
                 "for more details", ioe,
                 pkgSummHTMLFileName, "entire class"
             );
         }
        
         // Builds a TreeMap of all of the table rows on the "Package Summary" JavaDoc HTML Page.
         HNLIInclusive                       iter    = PackageSummary.iterator(pkgSummPage);
         TreeMap<String, Vector<HTMLNode>>   entries = new TreeMap<>();
        
         // Fill the TreeMap with all of the table-rows on the page.  These are going to be completely
         // rearranged in the next step.
         while (iter.hasNext())
         {
             Vector<HTMLNode>    cieteeVec   = iter.next();
             int                 pos         = TagNodeFind.first(cieteeVec, TC.OpeningTags, "a");
             String              cietee      = cieteeVec.elementAt(pos + 1).str;
        
             entries.put(cietee, cieteeVec);
         }
        
         StringBuilder sb = new StringBuilder();
        
         // Open the main list!
         sb.append(
             "<UL CLASS=\"blockList\">\n" +
             "<LI CLASS=\"blockList\">\n" +
             "<TABLE CLASS=\"typeSummary\" BORDER=\"0\" cellpadding=\"3\" cellspacing=\"0\" " +
             "summary=\"Summary table, listing Classes, Interfaces and Enums, etc...\">\n"
         );
        
         for (int i=0; i < sectionNames.length; i++)
         {
             // The "Section Names" define which tables are being created, and what names those tables
             // will have.
             sb.append(
                 /*
                 "<li class=\"blockList\">\n" +
                 "<table class=\"typeSummary\" border=\"0\" cellpadding=\"3\" cellspacing=\"0\" summary=\"Summary table, listing Classes, Interfaces and Enums, etc...\">\n" +
                 "<caption><span>" + sectionNames[i] + "</span><span class=\"tabEnd\">&nbsp;</span></caption>\n" +
                 */
                 "<TR><TD COLSPAN=2>&nbsp;</TD>\n" +
                 "<TR><TH COLSPAN=2 CLASS=PSUMM><SPAN>" + sectionNames[i] + "</SPAN></TH></TR>\n" +
                 "<TR>\n" +
                 "\t<TH CLASS=\"colFirst\" scope=\"col\">Java Entity</TH>\n" +
                 "\t<TH CLASS=\"colLast\" scope=\"col\">Description</TH>\n" +
                 "</TR>\n"
                 // "<tbody>\n"
             );
        
             // This list is merely/simply just the list of classes, interfaces, etc.. that the user
             // provided that should be inserted into the new-table that was just created in the line
             // above.
             String[] list = sectionCIETEELists[i];
        
             // In Java-Doc, inside of a "package-summary.html" file, the table-rows have alternating
             // colors - from gray-to-white.  Since the original HTML Table Rows were just copied and
             // saved to a tree-map, the background-colors for those rows need to be changed, or else
             // they won't be "alternating".
             boolean     altOrRow    = true;
        
             for (int j=0; j < list.length; j++)
             {
                 if (list[j].length() == 0)
                 {
                     sb.append(
                         "<TR class=\"" + (altOrRow ? "altColor" : "rowColor") + "\">\n" +
                         "\t<TD class=\"colFirst\">&nbsp;</TD>\n" +
                         "\t<TD class=\"colLast\"><div class=\"block\">&nbsp;</div></TD>\n" +
                         "</TR>\n"
                     );
        
                     altOrRow = ! altOrRow;
                     continue;
                 }
        
                 // This is retrieved from the TreeMap of Table-Rows which was built inside the 
                 // previous loop (above).  All *this* loop is doing is re-arranging the table rows
                 // inside of new tables which are ordered according to the big-arrays
                 Vector<HTMLNode> cieteeVec = entries.remove(list[j]);
        
                 if (cieteeVec == null) throw new FramesException(
                     "There was an error while processing the 'package-summary.html' file:\n" +
                     pkgSummHTMLFileName + '\n' +
                     "One of the classses, interfaces, enums, etc was not found: " + list[j] + '\n' +
                     "It apparently wasn't included inside the original package-summary.html file."
                 );
        
                 /*
                 System.out.println(
                     "list[j]: " + list[j] + '\n' +
                     StrCSV.toCSV(list, false, true, null) + '\n' +
                     "cieteeVec:" + cieteeVec
                 );
                 */
        
                 // Make sure that the new rows have alternating colors like they did inside the
                 // original tables,
                 TagNode tn = ((TagNode) cieteeVec.elementAt(0)).setAV
                     ("class", altOrRow ? "altColor" : "rowColor", null);
        
                 // Insert the alternatve-version of the <TR> element which has the correct table-row
                 // background color, then toggle the background color boolean
                 cieteeVec.setElementAt(tn, 0);
                 altOrRow = ! altOrRow;
        
                 // Append this <TR> ... </TR> into the StringBuilder.
                 // NOTE: This is a little inefficent to convert this to a String, because (below)
                 // it is converted right back into an HTML Vector, but oh well.
                 //
                 // TO-DO: Use a Stream of Vector<HTMLNode> instead. 
                 sb.append(Util.pageToString(cieteeVec));
                 sb.append('\n');
             }
        
            // sb.append("</tbody>\n</table>\n</li>\n");
         }
        
         // Close off the main list!
         sb.append("</TABLE>\n</UL>\n");
        
         // If not all of the entries were used, then something went wrong with the lists / arrays
         // that the user provided.  Return the list of classes, interfaces, etc... that were
         // left out.  The main-processing loop will convert this list into an exception throw.
         if (entries.size() > 0) return entries.keySet().toArray(new String[entries.size()]);
        
         // Replace the original "package-summary.html" file main-list.  The main-list is actually
         // just a <UL>...</UL> element.  Insert the newly created lists.  The new list has several
         // tables in it.
         DotPair             theMainList = PackageSummary.listAll(pkgSummPage);
         Vector<HTMLNode>    newMainList = HTMLPage.getPageTokens(sb.toString(), false);
        
         // Now replace the original List of classes, interfaces, enums etc...
         Util.replaceRange(pkgSummPage, theMainList, newMainList);
        
         // Write the updated "package-summary.html" page to disk.
         try
             { FileRW.writeFile(Util.pageToString(pkgSummPage), pkgSummHTMLFileName); }
         catch (Exception e)
         {
             throw new JavaDocError(
                 "There was an IOException while attempting to write the file " +
                 "[" + pkgSummHTMLFileName + "]\n Please see the Throwable.getCause() for " +
                 "more information."
             );
         }
        
         // If the code did have unused CIET, then this method would have already returned.
         //  All CIET were properly placed, so return an empty array.
         String[] ret = new String[0];
         return ret;