PackageSummaryHTML.java.html

package Torello.JavaDoc;

import static Torello.Java.C.*;

import Torello.HTML.*;
import Torello.HTML.NodeSearch.*;

import Torello.Java.FileRW;
import Torello.Java.StringParse;
import Torello.Java.StrCSV;
import Torello.Java.StrIndexOf;

import Torello.Java.Additional.Ret2;
import Torello.Java.Additional.Ret3;

import Torello.JDUInternal.GeneralPurpose.Messager;
import Torello.JDUInternal.GeneralPurpose.GetHeaderTags;

import Torello.JDUInternal.DataClasses.UserUpgradeFilesConfig.PkgSort;
import Torello.JDUInternal.DataClasses.ClassUpgradeData.PathsAndTypes;
import Torello.JDUInternal.DataClasses.ClassUpgradeData.UpgradeSettings;

import Torello.JDUInternal.HTMLProcessors.Rearrange.RearrangePkgSummaryFile;
import Torello.JDUInternal.HTMLProcessors.Rearrange.RearrangePkgFrameFile;

import Torello.JDUInternal.HTMLProcessors.CleanerFixer.CleanPackageSummaryFile;

import Torello.JDUInternal.HTMLProcessors.HiLiteSource.HiLiteDividers;

import Torello.JDUInternal.ParseHTML.PackageSummary;
import Torello.JDUInternal.UserConfigReaders.RetrievePkgSortConfigClass;

import java.io.File;
import java.io.IOException;
import java.io.Serializable;

import Torello.Java.ReadOnly.ReadOnlyVector;
import Torello.Java.ReadOnly.ROTreeSetBuilder;
import Torello.Java.ReadOnly.ReadOnlyTreeSet;

import java.util.*;

import java.util.function.Consumer;

/**
 * A class that parses and encapsulates the contents of a <B>{@code 'package-summary.html'}</B>
 * File.
 */
public class PackageSummaryHTML implements Serializable
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Static-Final Constant Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;

    /** Deprecated, but useful API Error-Message */
    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";

    /*
    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"
    );
    */

    private static final Vector<HTMLNode> TABLE_START = HTMLPage.getPageTokens(
        "<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",
        false
    );

    private static final Vector<HTMLNode> TABLE_END =
        HTMLPage.getPageTokens("</UL>\n</LI>\n</TABLE>\n", false);

    private static final char FSEP = File.separator.charAt(0);

    private static final String PKG_SUMM_HTML = "Package Summary HTML";

    private static final TagNode BODY_WITH_CSS_CLASS_TN = new TagNode("<BODY CLASS=C30>");


    // ********************************************************************************************
    // ********************************************************************************************
    // final Class-Data Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /** The name of the Java Package represented by this instance. */
    public final String packageName;

    // Contains the top Navigation Bar's HTML 
    // This, and all SubSection instances, must be private, because they are mutable

    private final SubSection head;

    // Contains the top Navigation Bar's HTML 
    private final SubSection topNavBar;

    // Contains the bottom Navigation Bar's HTML
    private final SubSection bottomNavBar;

    // THe Top-Description HTML/Text
    private final SubSection description;

    // The rows (which contain CIET/Types) of this 'package-summary.html' File
    private final Vector<Vector<HTMLNode>> cietRowHTML;

    private final Vector<String> cietRowSimpleNames;

    private final TreeMap<String, Vector<HTMLNode>> rowTM = new TreeMap<>();

    // This is needed for the "package-frame.html" file generation in later JavaDoc versions where
    // the "--frames" switch was deprecated.  This is only used internally.
    //
    // Note, this could theoretically be public - although "they" wouldn't have much use for it
    // that I can think of...  But mainly, the class "PkgSort" is not really accessible to the end
    // user.  Therefore it shall remain package-private

    final PkgSort sorter;


    // ********************************************************************************************
    // ********************************************************************************************
    // Simple Accessor Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Allows a User to both retrieve and to modify the contents of the
     * {@code 'package-summary.html'} {@code <HEAD>}-Section.
     * 
     * @return Vectorized-HTML of this Web-Page's {@code <HEAD>...</HEAD>} Section.
     */
    public Vector<HTMLNode> head() { return this.head.html; }

    /**
     * Allows a User to both retrieve and to modify the contents of the
     * {@code 'package-summary.html'} Nav-Bar.
     * 
     * @return Vectorized-HTML of this Web-Page's Upper Navigation Menu-Bar.
     */
    public Vector<HTMLNode> topNavBar()
    { return (this.topNavBar == null) ? null : this.topNavBar.html; }

    /**
     * Allows a User to both retrieve and to modify the contents of the
     * {@code 'package-summary.html'} Nav-Bar.
     * 
     * @return Vectorized-HTML of this Web-Page's Lower Navigation Menu-Bar.
     */
    public Vector<HTMLNode> bottomNavBar()
    { return (this.bottomNavBar == null) ? null : this.bottomNavBar.html; }

    /**
     * Allows a User to both retrieve and to modify the contents of the
     * {@code 'package-summary.html'} Description Text-Area.
     * 
     * @return Vectorized-HTML of this Web-Page's Main Description Box.
     */
    public Vector<HTMLNode> description() { return this.description.html; }


    // ********************************************************************************************
    // ********************************************************************************************
    // Default Package-Summary Cleaner
    // ********************************************************************************************
    // ********************************************************************************************


    private static final String[] searches = { ".", "<br/>", "\n" };

    public static final void defaultCleaner(Vector<HTMLNode> cietSummary)
    {
        // boolean VERBOSE = MessagerVerbose.isVerbose();

        // System.out.println("INSIDE MY LAMBDA:\n" + Util.pageToString(cietSummary));

        int i=0, nodePos=-1;

        /*
        if (VERBOSE) MessagerVerbose.println
            ("cietSummary: " + BGREEN + Util.pageToString(cietSummary) + RESET);
        */

        while ((nodePos == -1) && (i < searches.length))
            nodePos = TextNodeFind.first(cietSummary, TextComparitor.CN_CI, searches[i++]);

        if (nodePos == -1)
        {
            // if (VERBOSE) MessagerVerbose.println("No String Markers Found!  Exiting...");
            return;
        }

        String  s   = cietSummary.elementAt(nodePos).str;
        int     pos = StrIndexOf.first_CI(s, searches[--i]);

        /*
        if (VERBOSE) MessagerVerbose.println("s: " + s);
        */

        s = s.substring(0, pos);

        /*
        if (VERBOSE) MessagerVerbose.println("s.substring: " + s);
        */

        if (s.length() != 0)
            cietSummary.setElementAt(new TextNode(s), nodePos++);

        if (nodePos < cietSummary.size())
            Util.Remove.range(cietSummary, nodePos, cietSummary.size());

        // Util.removeAllTagNodes(cietSummary);
        // CHANGED March 2nd 2022

        TagNodeRemove.allExcept(cietSummary, TC.Both, "a", "b", "i", "code", "span");

        /*
        if (VERBOSE) MessagerVerbose.println(
            BCYAN + Util.pageToString(cietSummary) + RESET +
            "\n************************************************************\n"
        );
        */
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // This class Main-Builder (Constructor)
    // ********************************************************************************************
    // ********************************************************************************************


    public PackageSummaryHTML(
            final String                jdPkgSummFName,
            final PathsAndTypes.Builder pathsTypesBuilder,
            final UpgradeSettings       settings
        )
    {
        Messager.setCurrentFileName(jdPkgSummFName, "'package-summary.html' File");

        final String dotDotsFileSystem = StringParse.dotDots
            (jdPkgSummFName, pathsTypesBuilder.rootJavaDocDirectory, File.separatorChar);

        final String dotDotsUrls = (File.separatorChar == '/')
            ? dotDotsFileSystem
            : dotDotsFileSystem.replace(File.separatorChar, '/');

        final Consumer<Vector<HTMLNode>> packageSummaryCleaner = settings.packageSummaryCleaner;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Calculate the Package-Name.  This is the very first time this is done.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final String packageSubDir = jdPkgSummFName.substring(
            pathsTypesBuilder.rootJavaDocDirectory.length(),

            // "/package-summary.html" ==> String-Length = 21
            jdPkgSummFName.length() - 21
        );

        // As of February, 2024, this is now a public final String field
        packageName = packageSubDir.replace(FSEP, '.');

        // Read the file from disk and parse into Vectorized-HTML
        Vector<HTMLNode> fileVec =
            loadHTMLFile(jdPkgSummFName, "package-summary.html");


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Check for a PackageSummarySort.class File - check all Class-Path Source-Code Dirs
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final ArrayList<String> sorters = new ArrayList<>(4);

        for (String dir : pathsTypesBuilder.rootSourceFileDirectories)
        {
            String fileName = dir + packageSubDir + FSEP + "upgrade-files" + FSEP +
                "config-classes" + FSEP + "PackageSummarySort.class";

            File f = new File(fileName);

            if (f.exists() && f.isFile()) sorters.add(fileName);
        }

        if (sorters.size() > 1) Messager.userErrorHalt(
            "Multiple Package Sorters were found:\n" +
            StrCSV.toCSV(sorters, fName -> "    " + fName + '\n', true, null)
        );

        // This is an instance of "PkgSort"  As of February 2024, it must be retained as an 
        // instance-field of this class, in case the "package-frame.html" file must be built from
        // scratch.  (Thereby allowing for later javadoc versions, where `--frames` was deprecated
        // to continue to have a 'packge-frame.html' file anyway)

        sorter = (sorters.size() == 0)
            ? null
            : RetrievePkgSortConfigClass.readConfigurationClassFromDisk
                (sorters.get(0), packageName);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Sort **OR** just Clean-Up the CIET/Type List on this web-page
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if (sorter != null)
        {
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Read the File's Contents & Sort if needed.
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            // Used to build the Master CIET/Type List for registering with 'pathsTypes'
            ROTreeSetBuilder<String> cietSimpleNamesList = new ROTreeSetBuilder<>();

            // Builds a TreeMap of all of the table rows on the "Package Summary" JavaDoc HTML Page
            HNLIInclusive iter = PackageSummary.iteratorTypeRows(fileVec);

            // Save the rows by CIET-Name in a TreeMap
            // Map-Key:     CIET Simple-Name
            // Map-Value:   Table-Row of HTML <TR> ... </TR>

            final 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>    cietHTML        = iter.next();
                int                 pos             = TagNodeFind.first(cietHTML, TC.OpeningTags, "a");
                String              cietSimpleName  = cietHTML.elementAt(pos + 1).str;

                entries.put(cietSimpleName, cietHTML);      // Saved for Sorting
                cietSimpleNamesList.add(cietSimpleName);    // Saved to PathsAndTypes
            }

            final Ret2<
                Vector<String>,
                Vector<Vector<HTMLNode>>
            > r2 = RearrangePkgSummaryFile.run(sorter.sections, sorter.types, entries);

            // If there were errors, then the above function might return null.  Halt the
            // constructor here, BUT do not throw so that all of the PackageSummaryHTML's can
            // execute, FIRST, before quitting.

            if (r2 == null)
            {
                // Prevent `javac` complaints: (final field may not have been initialized)
                this.cietRowHTML        = null;
                this.cietRowSimpleNames = null;

                // These are all SubSection instances
                this.head = this.topNavBar = this.bottomNavBar = this.description = null;

                return;
            };

            this.cietRowSimpleNames = r2.a;
            this.cietRowHTML        = r2.b;

            // Update the Global Package-Name ==> CIET/Type List TreeMap (Inside PathsAndTypes)
            pathsTypesBuilder.packageCIETLists.put(packageName, cietSimpleNamesList.build());
        }

        else
        {
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Read the File's Contents & Clean-It
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            Ret3
            <
                Vector<String>,             // cietRowSimpleNames
                Vector<Vector<HTMLNode>>,   // cietRowHTML
                ReadOnlyTreeSet<String>     // cietSimpleNamesList
            >
            r3 = CleanPackageSummaryFile.run(fileVec);

            this.cietRowSimpleNames = r3.a;
            this.cietRowHTML        = r3.b;

            // Update the Global Package-Name ==> CIET/Type List TreeMap (Inside PathsAndTypes)
            pathsTypesBuilder.packageCIETLists.put(packageName, r3.c);
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Build the Updated 'package-summary.html' Page
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // This DotPair contains the entire Summary-Table in a package-summary.html file
        DotPair dp = InnerTagFindInclusive.first
            (fileVec, "ul", "class", TextComparitor.C, "blockList");

        // Build the new Package-Summary CIET/Type Table
        final Vector<HTMLNode> newTable = new Vector<>();

        newTable.addAll(TABLE_START);

        for (Vector<HTMLNode> cietHTML : this.cietRowHTML) newTable.addAll(cietHTML);

        newTable.addAll(TABLE_END);

        // Insert the new Table into the same location where the old table had been placed
        ReplaceNodes.r(fileVec, dp, newTable);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Check if there is a User-Provided (or Default) "Package Summary Cleaner"
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // MESSAGER: Messager.isVerbose, println only
        if (packageSummaryCleaner != null)
            CleanPackageSummaryFile.run(fileVec, packageSummaryCleaner);

        // MESSAGER:
        //  1) INVOKES:     assertFailGeneralPurpose, assertFailHTML
        //  2) INVOKED-BY:  ExtraFilesProcessor (once) MainFilesProcessor (once), method above
        //  3) RETURNS:     Number of HiLited <DIV>'s (maybe zero, if zero)
        //  4) THROWS:      asserFail ==> JavaDocHTMLParseException & UpgradeException

        HiLiteDividers.hiLite(fileVec, settings.hiLiter);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Retrieve the <HEAD>...</HEAD> Header
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        this.head = TagNodePeekInclusive.first(fileVec, "head");

        if (this.head == null) Messager.assertFailHTML(
            "This 'package-summary.html' page does not appear to have a <HEAD>...</HEAD> Element",
            PKG_SUMM_HTML
        );


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // The Top Navigation-Bar - There may be pages which do not have a NavBar
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // NOTE: I just noticed that the Navigation-Bar is a series of <DIV>'s, and there is no
        //       surrounding HTML divider.  We have to find the first open-<DIV>, and the last
        //       closing </DIV>

        int sPos = CommentNodeFind.first
            (fileVec, head.location.end, -1, s -> s.contains("=== START OF TOP NAVBAR ==="));

        int ePos;

        if (sPos == -1)
        {
            this.topNavBar = null;
            ePos = head.location.end;
        }

        else
        {
            ePos = CommentNodeFind.first
                (fileVec, sPos, -1, s -> s.contains("=== END OF TOP NAVBAR ==="));

            sPos = TagNodeFind.first(fileVec, sPos, ePos, TC.OpeningTags, "div");
            ePos = TagNodeFind.last(fileVec, sPos, ePos, TC.ClosingTags, "div");

            dp = new DotPair(sPos, ePos);

            this.topNavBar = new SubSection(dp, Util.cloneRange(fileVec, dp));
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Package-Description
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        this.description = TagNodePeekInclusive.first(fileVec, ePos, -1, "section");

        if (this.description == null) Messager.assertFailHTML
            ("This Package returned a null Description", PKG_SUMM_HTML);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // The Bottom Navigation-Bar, There may be pages which do not have a NavBar
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // Searching through "CommentNode" instances is much faster since the
        // if (HTMLNode.isCommentNode()) is the fastest of the search-specifies...  There aren't
        // many comment's in a javadc page (much fewer than the number of TagNode's & TextNode's)
        //
        // ALSO: as explained in the "Top Navigation-Bar" getter-section (way above this part),
        //       The Bottom and Top Bar's are a series of "sibling" <DIV> Tags, and you have to
        //       get the first opening-<DIV> and the last closing-</DIV>

        sPos = CommentNodeFind.first(fileVec, s -> s.contains("== START OF BOTTOM NAVBAR =="));

        if (sPos == -1) this.bottomNavBar = null;

        else
        {
            ePos = CommentNodeFind.first
                (fileVec, sPos, -1, s -> s.contains("=== END OF BOTTOM NAVBAR ==="));

            if (ePos == -1) Messager.assertFailHTML("BOTTOM NAVBAR End-Marker not found", null);

            sPos = TagNodeFind.first(fileVec, sPos, ePos, TC.OpeningTags, "div");
            ePos = TagNodeFind.last(fileVec, sPos, ePos, TC.ClosingTags, "div");
    
            dp = new DotPair(sPos, ePos);

            this.bottomNavBar = new SubSection(dp, Util.cloneRange(fileVec, dp));
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Meta-Tags in Header, Stats Button in Navigation Bar
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final List<HTMLNode> tags = GetHeaderTags.packageSummaryHTMLTags(
                ((settings.cssFiles == null) ? null : settings.cssFiles.customizedCSS),
                dotDotsUrls,
                settings.faviconImageFileName,
                settings.headerTags
            )
            .wrapToImmutableList();

        this.head.html.addAll(1, tags);

        Stats.addStatsButton(this.topNavBar(), this.bottomNavBar(), dotDotsUrls, packageName);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Re-Build the Page-Vector
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        Replaceable[] replaceables =
            { this.head, this.topNavBar, this.description, this.bottomNavBar };

        fileVec = ReplaceNodes.r(fileVec, Arrays.asList(replaceables), false).a;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Write the new 'package-summary.html' to Disk
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        try
            { FileRW.writeFile(Util.pageToString(fileVec), jdPkgSummFName); }

        catch (IOException ioe)
        {
            Messager.assertFailGeneralPurpose
                (ioe, "Failed Writing 'package-summary.html' File", null);
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Handle 'package-frame.html' - IF IT EXISTS
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // Requirements:
        //      1) User has provided a Package-Sorter
        //      2) JavaDoc has created a package-frame.html file

        // "package-summary.html" ==> "summary.html" ==> length() is 12
        final String jdPkgFrameFName =
            jdPkgSummFName.substring(0, jdPkgSummFName.length() - 12) + "frame.html";

        final File f = new File(jdPkgFrameFName);

        // Now check that the package-frame.html file exists, and is an HTML-File
        if (f.exists() && f.isFile())
        {
            Messager.setCurrentFileName(jdPkgSummFName, "'package-frame.html' File");
    
            // Read the file from disk and parse into Vectorized-HTML
            fileVec =
                loadHTMLFile(jdPkgFrameFName, "package-summary.html");


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Rearrange 'package-frame.html'
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            if (sorter != null)
                RearrangePkgFrameFile.run(fileVec, sorter.sections, sorter.types);


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Original "Package-Frame Cleaner" - Moved Here from EFP, November 2023
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            fileVec.setElementAt(
                BODY_WITH_CSS_CLASS_TN,     /* <BODY CLASS=C30> */
                TagNodeFind.first(fileVec, TC.OpeningTags, "body")
            );

            /*
            // February 2024, EVEN-BETTER
            // Just do <BODY CLASS=C30> inside of a 'package-frame.html' file INSTEAD OF ALL OF
            // THESE STUPID "extra CSS Classses"
            // SEE ABOVE 3 LOC

            for (TagNodeIndex tni : TagNodePeek.all(fileVec, TC.OpeningTags, "h1", "h2", "ul"))

                if (tni.n.tok.equals("h1"))            
                    fileVec.setElementAt(
                        tni.n.appendCSSClass(CSSTags.CSS_CLASS_FOR_PKG_FRAME_H1, null),
                        tni.index
                    );

                else if (tni.n.tok.equals("h2"))
                    fileVec.setElementAt(
                        tni.n.appendCSSClass(CSSTags.CSS_CLASS_FOR_PKG_FRAME_H2, null),
                        tni.index
                    );

                else // if (tni.n.tok.equals("ul"))
                    fileVec.setElementAt(
                        tni.n.appendCSSClass(CSSTags.CSS_CLASS_FOR_PKG_FRAME_UL, null),
                        tni.index
                    );
            */


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Meta-Tags in Header
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            final int pkgFrameHeaderPos = TagNodeFind.first(fileVec, TC.OpeningTags, "HEAD");

            fileVec.addAll(pkgFrameHeaderPos + 1, tags);


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Write 'package-frame.html' back to disk
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            try
                { FileRW.writeFile(Util.pageToString(fileVec), jdPkgFrameFName); }

            catch (IOException ioe)
            {
                Messager.assertFailGeneralPurpose
                    (ioe, "Failed Writing 'package-summary.html' File", null);
            }
        }

    }


    // ********************************************************************************************
    // ********************************************************************************************
    // A Little Helper That Could
    // ********************************************************************************************
    // ********************************************************************************************


    private static Vector<HTMLNode> loadHTMLFile(final String fileName, final String fileKind)
    {
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Load The Package-Summary HTML File from disk.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // Temp Variable, the file as a String
        final String fileAsStr;

        try
            { fileAsStr = FileRW.loadFileToString(fileName); }

        catch (Exception e)
        {
            throw (Error) /* Shut-Up Compiler */ Messager.assertFailGeneralPurpose(
                e,
                "I/O Exception throwm attempting to load " + fileKind + " file from disk",
                null
            );
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Parse The Summary HTML File from the raw-file text-string
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // This portion of the code attempts to load the Package-Frame list of classes, 
        // interfaces enums, errors and exceptions into a Vectorized-HTML page.

        final Vector<HTMLNode> fileVec;

        try
            { fileVec = HTMLPage.getPageTokens(fileAsStr, false); }

        // It seems ridiculous to check for this exception, but oh well, this always does have
        // the upside that if class HTMLPage does break (for whatever reason), what has
        // happened would be much easier to identify

        catch (Exception e)
        {
            throw (Error) /* Shut-Up Compiler */ Messager.assertFailHTML(
                e,
                "Error Parsing HTML in file " + fileKind + " using class HTMLPage.parsePgeTokens",
                null
            );
        }

        return fileVec;
    }
}