package Torello.JavaDoc;

import java.io.Serializable;

import java.util.*;
import java.util.stream.*;

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

import static Torello.Java.C.*;

import Torello.JDUInternal.GeneralPurpose.JDUProcessor;
import Torello.JDUInternal.HTMLProcessors.EmbedTag.EmbedTagTopDescription;
import Torello.JDUInternal.ParseJavaSource.JavaSourceCodeFile;

import Torello.JDUInternal.GeneralPurpose.Messager;
import Torello.JDUInternal.GeneralPurpose.MessagerVerbose;

import Torello.Java.ReadOnly.ReadOnlyMap;

/**
 * Maintains a suite of statistics about all Java project-wide source-code files.
 * 
 * <BR />As the Upgrade Processors are executed, this class maintains a few statistics about the
 * build, and produces the {@code Stats} HTML instance, which is subsequently linked to a
 * {@code 'Stats'} button on output Java Doc Web-Pages - <I>and also returned to the user after
 * calling the ugrader</I>.
 * 
 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=UPSTATS>
 */
public class Stats implements java.io.Serializable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;

    // Package-Level instances of 'Stats' will have their package-names saved here.
    // For the "Complete-Project" Stats instance, this will be null.
    private final String packageName;

    // Each Package has it's own / recursive instance of 'Stats'
    // For the Package-Level instances of 'Stats' - this field will be null.
    private final Map<String, Stats> packageStatsMap;

    /**
     * Global Stats are maintained, but so are package-local statistics.  This reetrieves the
     * package-local statistics instance.
     * @param packageName The name of one of the upgraded Java Packages, as a {@code String}.
     * @return The package-level instance of {@code 'Stats'} for that package.
     */
    public Stats getPackageStats(String packageName)
    { return packageStatsMap.get(packageName); }

    // A Pointer to the "Project-Global Embed-Tags Map"
    private final ReadOnlyMap<String, String> globalTagsMap;

    // A Count-Total for the "Project-Global Embed-Tags Map"
    private final Map<String, Integer> globalTagsCount;

    /**
     * Retrieving a count of all Project-Global Tags is done with this getter.  <I>It is important
     * to remember that an instance of {@code 'Stats'} may be a <B>Project-Global</B> instance, or a
     * <B>Package-Local</B> instance</I>.  If {@code 'this'} instance of {@code Stats} is the 
     * 'Project-Global' instance, the integer count-values inside the returned-{@code Map} will be
     * aggregate totals (for the whole project) of the number of times your External-HTML
     * {@code <EMBED>} tags were used.
     * 
     * <BR /><BR />If this method is invoked on one of the Package-Local {@code 'Stats'} instances,
     * the returned-{@code Map} will hold integer count-values for the Project-Global
     * {@code <EMBED>} tags were used <I>inside the particular package for which {@code 'this'}
     * statistics-instance was built.</I>
     * 
     * <BR /><BR /><B STYLE='color:red'>NOTE:</B> The complete dump of the statistics-tables for
     * the Java HTML Jar Library may be viewed by clicking on the {@code 'Stats'} link in the top
     * right corner of this page.  The data-tables there show the exact data that's inside the
     * {@code Map's}-tables of this class.
     * 
     * @return If {@code 'this'} instance of {@code 'Stats'} is the 'Project-Global' instance, the
     * returned-{@code Map} will be the 'Project-Totals' use-count for all Globally-Defined
     * {@code <EMBED class='external-html ..>'} Tags.
     * 
     * <BR /><BR />If {@code 'this'} instance of {@code 'Stats'} is a 'Package-Local' instance,
     * the returned-{@code Map} will have <B>Package-Local use-counts</B> for all of the
     * <B>Globallly-Defined Tags.</B>
     */
    @SuppressWarnings("unchecked")
    public Map<String, Integer> getGlobalTagsCount()
    { return (HashMap<String, Integer>) ((HashMap<String, Integer>) globalTagsCount).clone(); }

    // A reference pointer to the "Package-Local Embed-Tag Map", (ID's ==> FileNames)
    // NOTE: For the top-level main 'Stats' instance, this will remain null

    private final ReadOnlyMap<String, String> packageTagsMap;

    // Keeps a count of the use of all "Package-Local Embed-Tags"
    // NOTE: For the top-level main 'Stats' instance, this will remain null

    private final Map<String, Integer> packageTagsCount;

    /**
     * This retrieves an integer count-{@code Map} of all Package-Local Embedded HTML
     * (External-HTML) Tags.  If {@code 'this'} instance of {@code 'Stats'} is the Top-Level,
     * Project-Global instance of {@code 'Stats'}, this method returns null.
     * 
     * @return A {@code Map} containing counts of the number of times a Package-Local
     * {@code <EMBED CLASS='external-html'>} Tag has been used on web-pages that are inside
     * that particular package.
     *
     * <BR /><BR />This method returns null if {@code 'this'} instance of {@code 'Stats'} is
     * the Global-Instance, rather than one of the Package-Local Instances.
     */
    @SuppressWarnings("unchecked")
    public Map<String, Integer> getPackageTagsCount()
    {
        return (packageTagsCount == null)
            ? null
            : (HashMap<String, Integer>) ((HashMap<String, Integer>) packageTagsCount).clone();
    }

    // This builds a "Global Stats" that doesn't have any Global Embed-Tags.  This is the constructor
    // used by configuration-class "Upgrade" in the "fields initializers" section.
    //
    // SPECIFICALLY: The following line is the "first initialization used".
    //              protected Stats stats = new Stats();
    //
    // If the User registers a global Embed-Tags Map, then this instance is SIMPLY-DISCARDED 
    // (Garbage Collected), and a new instance assigned to that Upgrade Field.
    //
    // AGAIN: Usually this instance is built, **BUT** then replaced if the user configures the
    //        upgrade class with a Global Embed Tags map.  In the Java HTML JAR an instance is
    //        built using this constructor, but then destoyed immediately after registering.
    //        This is not a big enough waste - when compared to the alternative (which is writing
    //        another "register map" method).
    //
    // FOR USERS WHO DO NOT REGISTER A GLOBAL EMBED TAGS MAP, THE INSTANCE CREATED BY THIS
    // CONSTRFUCTOR - OBVIOUSLY - WON'T BE GARBAGE COLLECTED.

    Stats()
    {
        this.packageName        = null;
        this.packageStatsMap    = new HashMap<>();
        this.packageTagsMap     = null;
        this.packageTagsCount   = null;
        this.globalTagsMap      = null;
        this.globalTagsCount    = null;
    }

    // Constructor for global-stats instance 
    // NO MESSGER USE

    Stats(ReadOnlyMap<String, String> globalTagsMap)
    {
        // This is a 'JavaDocError' rather than a message to the messager because this should
        // *NEVER* occur.  At the time of the writing of this exception-check, this constructor is
        // invoked from the 'Upgrade' Confguration class.  A null-check is done there on th euser
        // input.  If that changes or moves, it should be thought of as "My Fault" not
        // "Their Fault" - so this has to be a 'THROW' rather than a 'MESSAGER' error.
        //
        // Keep these here because this class seems Ultra-Simple at first glance, but because it
        // is ALL ABOUT DATA, it is sort of more DIFFICULT than one might expect.
        //
        // The Exception/Errors in this class ARE ALL FOR MISTAKES that should NEVER happen, NO
        // MATTER WHAT the user has entered or passed to the Upgrade-Configuration class.

        if (globalTagsMap == null) Messager.assertFailCheckup(
            "A null 'globalTagsMap' was passed to the Stats Constructor.  If there are no " +
            "Global Embed Tags being used with this Project, the Upgrade-Configuration class " +
            "is supposed to be using the Stats-class zero-argument constructor"
        );

        this.packageName        = null;
        this.packageStatsMap    = new HashMap<>();

        // The "Global Stats" instance doesn't have PackageTags
        // AGAIN: This constructor is the Constructor for the "Global Stats" instance.

        this.packageTagsMap     = null;
        this.packageTagsCount   = null;

        this.globalTagsMap      = globalTagsMap;
        this.globalTagsCount    = new HashMap<>();

        // This must be initialized here.  Even if a Tag is not used, knowing that it's count
        // is ZERO is helpful to the user.  If we leave it null here, yes, that could be
        // interpreted as a ZERO, but it looks nicer here, and at the end to put a zero, rather
        // than leaving it null and reverse-checking the global-map.

        Integer ZERO = Integer.valueOf(0);

        // Initialize the PROJECT-GLOBAL tag-count map.
        for (String embedTag : globalTagsMap.keySet()) this.globalTagsCount.put(embedTag, ZERO);
    }

    // Constructor for package-stats instances
    private Stats(String packageName, ReadOnlyMap<String, String> packageTagsMap)
    {
        this.packageName        = packageName;
        this.packageStatsMap    = null;         // This instance **IS** a "Package Stats"

        this.globalTagsMap      = null;         // This is not needed
        this.globalTagsCount    = new HashMap<>();

        this.packageTagsMap     = packageTagsMap;
        this.packageTagsCount   = (packageTagsMap == null) ? null : new HashMap<>();

        Integer ZERO = Integer.valueOf(0);

        if (packageTagsCount != null)

            for (String embedTag : this.packageTagsMap.keySet())
                this.packageTagsCount.put(embedTag, ZERO);
    }

    // This is called by "MainFilesProcessor" right before processing the Java Doc Web-Pages
    // for a particular Java Package.  At this point in that code, the 'packageTagsMap' has just
    // been read in from the 'upgrade-files/external-html/external-html-ids.properties' file.
    //
    // If the user didn't write any External-HTML Files, then the 'packageTagsMap' instance will
    // be null.  That is OK, that is only one of the many statistics that are maintained by this
    // class.
    //
    // MESSAGER:
    //  1) USES:        assertFailGeneralPurpose
    //  2) INVOKED-BY:  RetrieveEmbedTagMapPropFiles - only once
    //  3) RETURNS:     NOTHING
    //  4) THROWS:      UpgradeException (assertFailGeneralPurpose)
    //
    // ONE ASSERT STATEMENT WHICH THEORETICALLY SHOULD BE UNREACHABLE
    // ONLY SETS FileName if unreachable-code is actually reached.
    //
    // EXPORT_PORTAL METHOD
    // This method is used by Package UserConfigReaders, and doesn't need to be exported to the user
    // Stats.run is NOT STATIC!!!

    void registerPackage(
            String                      packageName,
            ReadOnlyMap<String, String> packageTagsMap,
            Stats                       topLevelStatsInstance
        )
    {
        // AGAIN: This should never be null, no matter what input the user has provided.  If
        //        this is null, it means (mostly) that something else was changed (probably in
        //        class 'Upgrade' or 'MainFilesProcessor').  Throw this to signify that it is
        //        MY FAULT - NOT THEIR FAULT.

        if (topLevelStatsInstance == null)
        {
            Messager.setCurrentFileName("No-File Processing", "Unreachable Code Reached");

            Messager.assertFailGeneralPurpose(
                "The instance of Stats passed to topLevelStatsInstance is null.\n" +
                "Niether the top-level 'Stats' instance, nor the Package-Local instances " +
                "should ever be null.\n" +
                "Currently attempting to build Package-Local 'Stats' instance for package: " +
                "    [" + BGREEN + packageName + RESET + "]\n" +
                BRED + "NOTE:" + RESET + " This is the developers fault.",
                null
            );
        }

        topLevelStatsInstance.packageStatsMap.put
            (packageName, new Stats(packageName, packageTagsMap));
    }

    /** The name of the Statistics HTML file saved to the root JavaDoc Directory. */
    protected static final String STATS_HTML_FILENAME = "Stats.html";


    // ********************************************************************************************
    // ********************************************************************************************
    // Stats Fields: BASIC
    // ********************************************************************************************
    // ********************************************************************************************


    /** @return A count of the total number of lines of {@code '.java'} files. */
    public int numLines() { return numLines; }
    private int numLines;

    /** @return A count of the total number of bytes of {@code '.java'} files. */
    public int numBytes() { return numBytes; }
    private int numBytes;

    /** @return A count of the total number of HiLited HTML {@code <DIV>} Elements. */
    public int numHiLitedDivs() { return numHiLitedDivs; }
    private int numHiLitedDivs = 0;


    // ********************************************************************************************
    // ********************************************************************************************
    // Stats: Entity (METHOD, FIELD, CONSTRUCTOR, ANNOTATION_ELEM, ENUM_CONSTANT)
    // ********************************************************************************************
    // ********************************************************************************************


    /** @return A count of the total number of methods found during the upgrade. */
    public int numMethods() { return numMethods; }
    private int numMethods = 0;

    /** @return A count of the total number of constructors found during the upgrade. */
    public int numConstructors() { return numConstructors; }
    private int numConstructors = 0;

    /** @return A count of the total number of fields found during the upgrade. */
    public int numFields() { return numFields; }
    private int numFields = 0;

    /** @return A count of the total number of annotation-elements found during the upgrade. */
    public int numAnnotationElems() { return numAnnotationElems; }
    private int numAnnotationElems = 0;

    /** @return A count of the total number of enum-constants found during the upgrade. */
    public int numEnumConstants() { return numEnumConstants; }
    private int numEnumConstants = 0;


    // ********************************************************************************************
    // ********************************************************************************************
    // Stats: HILITED-Entity (METHOD, FIELD, CONSTRUCTOR, ANNOTATION_ELEM, ENUM_CONSTANT)
    // ********************************************************************************************
    // ********************************************************************************************


    /** @return A count of the total number of method bodies hilited by the upgrader. */
    public int numHiLitedMethods() { return numHiLitedMethods; }
    private int numHiLitedMethods = 0;

    /** @return A count of the total number of constructor bodies hilited by the upgrader. */
    public int numHiLitedConstructors() { return numHiLitedConstructors; }
    private int numHiLitedConstructors = 0;

    /** @return A count of the total number of field declarations hilited by the upgrader. */
    public int numHiLitedFields() { return numHiLitedFields; }
    private int numHiLitedFields = 0;

    /**
     * @return A count of the total number of annotation-element declarations hilited by the
     * upgrader.
     */
    public int numHiLitedAnnotationElems() { return numHiLitedAnnotationElems; }
    private int numHiLitedAnnotationElems = 0;

    /**
     * @return A count of the total number of enumeration-constant declarations hilited by the
     * upgrader.
     */
    public int numHiLitedEnumConstants() { return numHiLitedEnumConstants; }
    private int numHiLitedEnumConstants = 0;


    // ********************************************************************************************
    // ********************************************************************************************
    // Stats: DOCUMENTED-Entity (METHOD, FIELD, CONSTRUCTOR, ANNOTATION_ELEM, ENUM_CONSTANT)
    // ********************************************************************************************
    // ********************************************************************************************


    /** @return A count of the total number of methods that were documented by Java Doc. */
    public int numDocumentedMethods() { return numDocumentedMethods; }
    private int numDocumentedMethods = 0;

    /** @return A count of the total number of constructors that were documented by Java Doc. */
    public int numDocumentedConstructors() { return numDocumentedConstructors; }
    private int numDocumentedConstructors = 0;

    /** @return A count of the total number of fields that were documented by Java Doc. */
    public int numDocumentedFields() { return numDocumentedFields; }
    private int numDocumentedFields = 0;

    /**
     * @return A count of the total number of annotation-elements that were documented by
     * Java Doc.
     */
    public int numDocumentedAnnotationElems() { return numDocumentedAnnotationElems; }
    private int numDocumentedAnnotationElems = 0;

    /**
     * @return A count of the total number of annotation-elements that were documented by
     * Java Doc.
     */
    public int numDocumentedEnumConstants() { return numDocumentedEnumConstants; }
    private int numDocumentedEnumConstants = 0;


    // ********************************************************************************************
    // ********************************************************************************************
    // Stats: STATIC-Entity (METHOD, FIELD)
    // ********************************************************************************************
    // ********************************************************************************************


    /** @return A count of the total number of {@code static} methods found during the upgrade. */
    public int numStaticMethods() { return numStaticMethods; }
    private int numStaticMethods = 0;

    /** @return A count of the total number of {@code static} fields found during the upgrade. */
    public int numStaticFields() { return numStaticFields; }
    private int numStaticFields = 0;


    // ********************************************************************************************
    // ********************************************************************************************
    // Stats: FINAL-Entity (METHOD, FIELD, CONSTRUCTOR)
    // ********************************************************************************************
    // ********************************************************************************************


    /** @return A count of the total number of {@code final} methods found by the upgrade. */
    public int numFinalMethods() { return numFinalMethods; }
    private int numFinalMethods = 0;

    /** @return A count of the total number of {@code final} constructors found by the upgrader. */
    public int numFinalConstructors() { return numFinalConstructors; }
    private int numFinalConstructors = 0;

    /** @return A count of the total number of {@code final} fields found by the upgrader. */
    public int numFinalFields() { return numFinalFields; }
    private int numFinalFields = 0;


    // ********************************************************************************************
    // ********************************************************************************************
    // Stats: PUBLIC-Entity (METHOD, FIELD, CONSTRUCTOR)
    // ********************************************************************************************
    // ********************************************************************************************


    /** @return A count of the total number of {@code public} methods found by the upgrader. */
    public int numPublicMethods() { return numPublicMethods; }
    private int numPublicMethods = 0;

    /** @return A count of the total number of {@code public} constructors found by the upgrader.*/
    public int numPublicConstructors() { return numPublicConstructors; }
    private int numPublicConstructors = 0;

    /** @return A count of the total number of {@code public} fields found by the upgrader. */
    public int numPublicFields() { return numPublicFields; }
    private int numPublicFields = 0;


    // ********************************************************************************************
    // ********************************************************************************************
    // Stats: PROTECTED-Entity (METHOD, FIELD, CONSTRUCTOR)
    // ********************************************************************************************
    // ********************************************************************************************


    /** @return The total number of {@code protected} methods found during the upgrade. */
    public int numProtectedMethods() { return numProtectedMethods; }
    private int numProtectedMethods = 0;

    /** @return The total number of {@code protected} constructors found during the upgrade. */
    public int numProtectedConstructors() { return numProtectedConstructors; }
    private int numProtectedConstructors = 0;

    /** @return The total number of {@code protected} fields found during the upgrade. */
    public int numProtectedFields() { return numProtectedFields; }
    private int numProtectedFields = 0;


    // ********************************************************************************************
    // ********************************************************************************************
    // Stats: PRIVATE-Entity (METHOD, FIELD, CONSTRUCTOR)
    // ********************************************************************************************
    // ********************************************************************************************


    /** @return The total number of {@code private} methods found during the upgrade. */
    public int numPrivateMethods() { return numPrivateMethods; }
    private int numPrivateMethods = 0;

    /** @return The total number of {@code private} constructors found during the upgrade. */
    public int numPrivateConstructors() { return numPrivateConstructors; }
    private int numPrivateConstructors = 0;

    /** @return The total number of {@code private} fields found during the upgrade. */
    public int numPrivateFields() { return numPrivateFields; }
    private int numPrivateFields = 0;


    // ********************************************************************************************
    // ********************************************************************************************
    // Stats: OTHER-Entity (FIELD only)
    // ********************************************************************************************
    // ********************************************************************************************


    /** @return A count of the total number of {@code transient} fields found during the upgrade.*/
    public int numTransientFields() { return numTransientFields; }
    private int numTransientFields = 0;

    /** @return A count of the total number of {@code volatile} fields found during the upgrade. */
    public int numVolatileFields() { return numVolatileFields; }
    private int numVolatileFields = 0;



    // ********************************************************************************************
    // ********************************************************************************************
    // Stats Per Package, **AND** Embed-Tags Stats
    // ********************************************************************************************
    // ********************************************************************************************


    // ***Optimization Fields***
    // The same package will be referenced, over and over, until the package has completed
    // These tags are used hundreds of times in some of the packages.

    private String  LAST_USED_packageName   = null;
    private Stats   LAST_USED_packageStats  = null;


    // Increments the total-count by 1 for a particular embed-tag
    //
    // NOTE: The whole 'LAST_USED_' PHENOMENON is an optimization, so that these tables are not
    //       looked up in the Hashtable every single time they are used.
    //
    // MESSAGER:
    //  1) INVOKES:     assertFailGeneralPurpose (100% my fault, not there fault)
    //  2) INVOKED-BY:  **ONLY ONCE**, from 'EmbedTag', (inside a loop)
    //  3) RETURN:      NOTHING
    //  4) THROWS:      UpgradeException (assertFailGeneralPurpose)

    void incrementTag(String packageName, String embedTag, boolean globalTagOrPackageTag)
    {
        if (    (this.LAST_USED_packageName == null)
            ||  (! this.LAST_USED_packageName.equals(packageName)))
        {
            this.LAST_USED_packageName  = packageName;
            this.LAST_USED_packageStats = this.packageStatsMap.get(packageName);

            // This should never happen, but if it does, this exception is more meaningful than
            // NullPointerException.  It isn't any better though!
            //
            // (IF NULL, THIS IS MY FAULT, NOT THEIR FAULT, and at the time of the writing of this
            // code, THIS CANNOT HAPPEN.  HOWEVER, if something is changed, then this exception
            // throw is more intelligent than NPE)

            if (this.LAST_USED_packageStats == null)

                Messager.assertFailGeneralPurpose(
                    "The Package-Stats instance for Package [" + packageName + "] returned null " +
                    "from the Global-Stats field 'packageStatsMap'\n" +
                    "Processing Embed-Tag [" + BCYAN + embedTag + RESET + "], a " +
                    (globalTagOrPackageTag ? "Global" : "Package-Local") + " Tag.",
                    null
                );
        }

        if (globalTagOrPackageTag)
        {
            Integer globalCount = this.globalTagsCount.get(embedTag);

            // This should never happen, but if it does, this exception is more meaningful than
            // NullPointerException.  It isn't any better though!
            //
            // SEE ABOVE COMMENT

            if (globalCount == null)

                Messager.assertFailGeneralPurpose(
                    "The Global-Stats instance returned a null count, but these are all " +
                    "supposed to have been initialized to zero.\n" +
                    "Processing Embed-Tag [" + BCYAN + embedTag + RESET + "], a Global Tag.",
                    null
                );

            this.globalTagsCount.put(embedTag, globalCount + 1);

            // These are **ALWAYS NULL** the first time they are used.
            Integer i = this.LAST_USED_packageStats.globalTagsCount.get(embedTag);

            this.LAST_USED_packageStats.globalTagsCount.put(embedTag, (i == null) ? 1 : (i+1));
        }
        else
        {
            // These exception throws are being used more like Java 'assert' statements.  If an
            // error occurs, it means that I changed something else, somplace else, and forgot
            // about this part.  As of the time of the writing of this exception check, this
            // field CAN NEVER BE NULL WHEN THIS LINE IS EXECUTED.

            if (this.LAST_USED_packageStats.packageTagsCount == null)

                Messager.assertFailGeneralPurpose(
                    "While processing Embed-Tags for package [" + packageName + "]\n" +
                    "The Package-Local Stats-Instance had a NULL-MAP reference for map " +
                    "'packageTagsCount'.\n" +
                    "Currently attempting to increment counter for (Package-Local) Embed-Tag " +
                    "[" + BCYAN + embedTag + RESET + "].",
                    null
                );

            Integer packageCount = this.LAST_USED_packageStats.packageTagsCount.get(embedTag);

            // EXCEPTION-THROW COMMENT: SAME AS ABOVE.  This code is theoretically unreachable, 
            // but every developer has been known to change something else, somewhere else, and
            // at the same time forgetting how that change might affect THIS CODE (below)
            //
            // HERE, if 'packageCount' were null, this would BY MY FAULT, NOT THE USERS FAULT.

            if (packageCount == null)
            {
                if (embedTag.equals(EmbedTagTopDescription.JDHBI_RESERVED_EMBED_TAG_FILE_ID))
                    this.LAST_USED_packageStats.packageTagsCount.put(embedTag, 1);

                else Messager.assertFailGeneralPurpose(
                    "While retrieving Embed-Tag Count Data for Package-Local Embed-Tag " +
                    "[" + embedTag + "]\n" +
                    "Located in Package [" + packageName + "]\n" +
                    "The Embed-Tag-Count found in the packageTagsCount-Map had a null-Integer.  " +
                    "But these are all initialized to zero.",
                    null
                );
            }

            else this.LAST_USED_packageStats.packageTagsCount.put(embedTag, packageCount + 1);
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Update Stats for a single File
    // ********************************************************************************************
    // ********************************************************************************************


    // Increments all the counters by the value in the given parameters
    // This is package-visible, because it really serves little purpose outside of this
    // package.
    //
    // NOTE: 'jdhf' is only used for the "getMethods", "geFields" things.  It is not asked for
    //       'fileVec'
    //
    // MESSAGER:
    //  1) INVOKES:     assertFailGeneralPurpose
    //  2) INVOKED-BY:  THIS METHOD IS ONLY INVOKED ONCE, FROM DetailsFilesProcesor
    //  3) RETURNS:     void - NOTHING
    //  4) THROWS:      UpgradeException (assertFailGeneralPurpose)
    //
    // EXPORT_PORTAL METHOD
    // This method is used by Package HTMLProcessors, and doesn't need to be exported to the user
    // Stats.run is NOT STATIC!!!

    void run(
            JavaSourceCodeFile jscf, JavaDocHTMLFile jdhf,
            int numHLM, int numHLC, int numHLF, int numHLAE, int numHLEC,
            int numHLD
        )
    {
        Method[]            mArr = jscf.getMethods();
        Constructor[]       cArr = jscf.getConstructors();
        Field[]             fArr = jscf.getFields();
        AnnotationElem[]    eArr = jscf.getAnnotationElems();
        EnumConstant[]      xArr = jscf.getEnumConstants();

        final Stats ps = this.packageStatsMap.get(jdhf.packageName);

        // Currently, this has been verified to be impossible.  If something changes, a
        // 'JavaDocError' throw is the best way to handle it.  Note that the 'cost' of doing
        // this null-check is absolutely minimal.

        if (ps == null) Messager.assertFailGeneralPurpose(
            "While attempting to update the both the Global and the Package-Local " +
            "Stats-Instance for JavaSourceCodeFile:\n    " +
            '[' + BYELLOW + jscf.fileName + RESET + '\n' +
            "The Package-Local Stats-Instance that was returned from the Package-Stats Map " +
            "was null.",
            null
        );

        // If this is an inner-class, then the number of lines in the class (and the number of
        // bytes) will already have been counted when the Enclosing-Class was tallied.
        // If this is an inner-class, just skip the counting of the lines/bytes for the class

        if (! jdhf.isInner)
        {
            ps.numLines                     += jdhf.typeLineCount;
            this.numLines                   += jdhf.typeLineCount;
            ps.numBytes                     += jdhf.typeSizeChars;
            this.numBytes                   += jdhf.typeSizeChars;
        }

        ps.numHiLitedDivs                   += numHLD;
        this.numHiLitedDivs                 += numHLD;

        ps.numMethods                       += mArr.length;
        this.numMethods                     += mArr.length;
        ps.numHiLitedMethods                += numHLM;
        this.numHiLitedMethods              += numHLM;
        ps.numDocumentedMethods             += jdhf.numMethods();
        this.numDocumentedMethods           += jdhf.numMethods();

        ps.numConstructors                  += cArr.length;
        this.numConstructors                += cArr.length;
        ps.numHiLitedConstructors           += numHLC;
        this.numHiLitedConstructors         += numHLC;
        ps.numDocumentedConstructors        += jdhf.numConstructors();
        this.numDocumentedConstructors      += jdhf.numConstructors();

        ps.numFields                        += fArr.length;
        this.numFields                      += fArr.length;
        ps.numHiLitedFields                 += numHLF;
        this.numHiLitedFields               += numHLF;
        ps.numDocumentedFields              += jdhf.numFields();
        this.numDocumentedFields            += jdhf.numFields();

        ps.numAnnotationElems               += eArr.length;
        this.numAnnotationElems             += eArr.length;
        ps.numHiLitedAnnotationElems        += numHLAE;
        this.numHiLitedAnnotationElems      += numHLAE;
        ps.numDocumentedAnnotationElems     += jdhf.numAnnotationElems();
        this.numDocumentedAnnotationElems   += jdhf.numAnnotationElems();

        ps.numEnumConstants                 += xArr.length;
        this.numEnumConstants               += xArr.length;
        ps.numHiLitedEnumConstants          += numHLEC;
        this.numHiLitedEnumConstants        += numHLEC;
        ps.numDocumentedEnumConstants       += jdhf.numEnumConstants();
        this.numDocumentedEnumConstants     += jdhf.numEnumConstants();

        for (Method m : mArr) m.modifiers.forEach((String modifier) ->
        {
            switch (modifier)
            {
                case "static"       :   this.numStaticMethods++;
                                        ps.numStaticMethods++;
                                        break;
                case "public"       :   this.numPublicMethods++;
                                        ps.numPublicMethods++;
                                        break;
                case "protected"    :   this.numProtectedMethods++;
                                        ps.numProtectedMethods++;
                                        break;
                case "private"      :   this.numPrivateMethods++;
                                        ps.numPrivateMethods++;
                                        break;
                case "final"        :   this.numFinalMethods++;
                                        ps.numFinalMethods++;
                                        break;
            }
        });

        for (Constructor c : cArr) c.modifiers.forEach((String modifier) ->
        {
            switch (modifier)
            {
                case "public"       :   this.numPublicConstructors++;
                                        ps.numPublicConstructors++;
                                        break;
                case "protected"    :   this.numProtectedConstructors++;
                                        ps.numProtectedConstructors++;
                                        break;
                case "private"      :   this.numPrivateConstructors++;
                                        ps.numPrivateConstructors++;
                                        break;
                case "final"        :   this.numFinalConstructors++;
                                        ps.numFinalConstructors++;
                                        break;
            }
        });

        for (Field f : fArr) f.modifiers.forEach((String modifier) ->
        {
            switch (modifier)
            {
                case "static"       :   this.numStaticFields++;
                                        ps.numStaticFields++;
                                        break;
                case "public"       :   this.numPublicFields++;
                                        ps.numPublicFields++;
                                        break;
                case "protected"    :   this.numProtectedFields++;
                                        ps.numProtectedFields++;
                                        break;
                case "private"      :   this.numPrivateFields++;
                                        ps.numPrivateFields++;
                                        break;
                case "final"        :   this.numFinalFields++;
                                        ps.numFinalFields++;
                                        break;
                case "transient"    :   this.numTransientFields++;
                                        ps.numTransientFields++;
                                        break;
                case "volatile"     :   this.numVolatileFields++;
                                        ps.numVolatileFields++;
                                        break;
            }
        });
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // To String
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Generates a {@code String} that enapsulates all of the counters / running-totals inside
     * this data statistic class.
     * 
     * @return A {@code String} representation of this class.  Only includes statistics about
     * use of methods, constructors, fields etc...  <B>DOES NOT INCLUDE</B> statistics regarding
     * the use of the {@code <EMBED CLASS='external-html' ...>} tags.
     */
    public String toString()
    {
        StringBuilder sb = new StringBuilder();

        for (String packageName : packageStatsMap.keySet()) sb.append(
            "Stats for Package: [" + BCYAN + packageName + RESET + "]:\n\n" +
            StrIndent.indent(toStringINTERNAL(packageStatsMap.get(packageName)), 4) + '\n'
        );

        sb.append("UPGADE / BUILD TOTAL:\n\n" + toStringINTERNAL(this));

        return sb.toString();
    }

    private static String toStringINTERNAL(Stats s)
    {
        return
            StringParse.rightSpacePad("" + StringParse.commas(s.numLines), 12)                       + "Total Lines of Source Code\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numBytes), 12)                       + "Total Bytes of Source Code\n" +
            '\n' +
            StringParse.rightSpacePad("" + StringParse.commas(s.numHiLitedDivs), 12)                 + "HiLited DIV Tags\n" +
            '\n' +
            StringParse.rightSpacePad("" + StringParse.commas(s.numMethods), 12)                     + "Source Total Methods\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numFields), 12)                      + "Source Total Fields\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numConstructors), 12)                + "Source Total Constructors\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numAnnotationElems), 12)             + "Source Total Annotation Elements\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numEnumConstants), 12)               + "Source Total Enumeration Constants\n" +
            '\n' +
            StringParse.rightSpacePad("" + StringParse.commas(s.numHiLitedMethods), 12)              + "Method Bodies HiLited\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numHiLitedFields), 12)               + "Fields Declarations HiLited\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numHiLitedConstructors), 12)         + "Constructors Bodies HiLited\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numHiLitedAnnotationElems), 12)      + "Annotation Elements HiLited\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numHiLitedEnumConstants), 12)        + "Enumeration Constants HiLited\n" +
            '\n' +
            StringParse.rightSpacePad("" + StringParse.commas(s.numDocumentedMethods), 12)           + "JavaDoc Documented Methods\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numDocumentedFields), 12)            + "JavaDoc Documented Fields\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numDocumentedConstructors), 12)      + "JavaDoc Documented Constructors\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numDocumentedAnnotationElems), 12)   + "JavaDoc Documented Annotation Elements\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numDocumentedEnumConstants), 12)     + "JavaDoc Documented Enumeration Constants\n" +
            '\n' +
            StringParse.rightSpacePad("" + StringParse.commas(s.numStaticMethods), 12)               + "Static Methods\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numStaticFields), 12)                + "Static Fields\n" +
            '\n' +
            StringParse.rightSpacePad("" + StringParse.commas(s.numFinalMethods), 12)                + "Final Methods\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numFinalFields), 12)                 + "Final Fields\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numFinalConstructors), 12)           + "Final Constructors\n" +
            '\n' +
            StringParse.rightSpacePad("" + StringParse.commas(s.numPublicMethods), 12)               + "Public Methods\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numPublicFields), 12)                + "Public Fields\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numPublicConstructors), 12)          + "Public Constructors\n" +
            '\n' +
            StringParse.rightSpacePad("" + StringParse.commas(s.numProtectedMethods), 12)            + "Protected Methods\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numProtectedFields), 12)             + "Protected Fields\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numProtectedConstructors), 12)       + "Protected Constructors\n" +
            '\n' +
            StringParse.rightSpacePad("" + StringParse.commas(s.numPrivateMethods), 12)              + "Private Methods\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numPrivateFields), 12)               + "Private Fields\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numPrivateConstructors), 12)         + "Private Constructors\n" +
            '\n' +
            StringParse.rightSpacePad("" + StringParse.commas(s.numTransientFields), 12)             + "Transient Fields\n" +
            StringParse.rightSpacePad("" + StringParse.commas(s.numVolatileFields), 12)              + "Volatile Fields\n";
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Inserting Link into JavaDoc Directory MAIN-OVERVIEW FRAMES
    // ********************************************************************************************
    // ********************************************************************************************


    private static final String HEADER =
        "<HTML>\n<HEAD>\n" +
        "<TITLE>Statistics</TITLE>\n" +
        "<LINK rel='icon' type='image/jpg' href='favicon.jpg' />\n" +
        "<LINK rel='stylesheet' type='text/css' href='stylesheets/Colors.css' />\n" +
        "<LINK rel='stylesheet' type='text/css' href='stylesheets/Upgrader-Widgets.css' />\n" +
        "</HEAD>\n" +
        "<BODY CLASS=STATS>\n";

    private static final String FOOTER = "\n</BODY>\n</HTML>\n";

    // Writes a Java-Doc Viewable HTML File explaining the Statistics
    // RETURN This shall return TRUE when the file was successfully written
    //
    // MESSAGER:
    //  1) INVOKES:     println, assertFailGeneralPurpose
    //  2) INVOKED-BY:  Only called once in Upgrade.upgrade, No Where Else
    //  3) RETURNS:     void - NOTHING
    //  4) THROWS:      UpgradeException (assertFailGeneralPurpose)

    void saveStatsHTMLFile(String saveFileDirectory)
    {
        Messager.println("\nWriting Statistics to Root Java Doc Directory.");

        StringBuilder html = new StringBuilder();

        html.append(HEADER);

        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Regular Stats - Methods, Fields, etc... - (almost identical to: 'toString')
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        html.append("<TABLE CLASS=STATS>\n");

        for (Map.Entry<String, Stats> packageStats : packageStatsMap.entrySet())
        {
            // Method, Constructor, Field, Counts  etc... - COUNTS FOR EACH PACKAGE
            html.append(
                "\n\n\t<TR><TD COLSPAN=3>&nbsp;<BR /><BR /><BR /></TD></TR>\n" +
                "\t<TR><TH ID='" +
                packageStats.getKey() +  // Using the Package-Name as the HTML-ID for finding it
                "' COLSPAN=3>\n\t\tStats for Package: <SPAN CLASS=PNSTATS>" +
                packageStats.getKey() +  // Package-Name (as String)
                "</SPAN></TH></TR>\n" +
                toHTML_INTERNAL(packageStats.getValue()) + "\n\n" // Package-Stats (as Stats)
            );

            // This was broken up into a separate method becuse it is so long
            //
            // NO MESSAGER, NO THROWS - EXCEPT ONE LINE OF Messager.println(...)

            append_one_packages_embed_tag_statistics(packageStats, html);
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Method, Constructor, Field etc... - COUNT-TOTALS FOR COMPLETE PROJECT
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        html.append(
            "\n\n\n\t<TR><TD COLSPAN=3>&nbsp;<BR /><BR /><BR /></TD></TR>\n" +
            "\n\t<TR><TH COLSPAN=3><SPAN CLASS=PNTSTATS>UPGADE / BUILD TOTAL:</SPAN></TH></TR>" +
            toHTML_INTERNAL(this)
        );

    
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Embed-Tag Count Totals ... - FOR COMPLETE PROJECT
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        html.append(
            "\n\t<TR><TD COLSPAN=3>&nbsp;</TD></TR>\n" +
            "\n\n\t<TR><TH COLSPAN=3><SPAN CLASS=PNTSTATS>Complete Upgrade Totals:" +
            "</SPAN></TH></TR>\n"
        );

        if (this.globalTagsMap != null)

            // NO MESSAGER, NO THROWS
            tagCountToHTML(
                globalTagsCount, this.globalTagsMap, html,
                true,   // YES, Print the Zero-Count
                true    // This is the GLOBAL TagsMap Count
            );

        html.append("</TABLE>\n");


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Write File, Exit
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        html.append(FOOTER);

        String saveFileName = saveFileDirectory + STATS_HTML_FILENAME;

        try
            { FileRW.writeFile(html, saveFileName); }

        catch (Exception ioe)
        {
            Messager.setCurrentFileName
                (saveFileName, "Computed Project-Statistics HTML-Page");

            Messager.assertFailGeneralPurpose
                (ioe, "Exception Writing Stats.html - <A> Anchor Links will be broken.", null);
        }

        if (MessagerVerbose.isVerbose())
            MessagerVerbose.println("Wrote File: " + BYELLOW + saveFileName + RESET);
    }

    // This method was extracted out of the loop and turned into an independent method.
    // It looks better this way.  That's all.
    //
    // NO MESSAGER, NO THROWS - EXCEPT ONE LINE OF Messager.println(...)

    private void append_one_packages_embed_tag_statistics
        (Map.Entry<String, Stats> packageStats, StringBuilder html)
    {
        Stats s = packageStats.getValue();

        if (MessagerVerbose.isVerbose()) MessagerVerbose.println
            ("Printing Stats to HTML for Package: " + packageStats.getKey());

        // Absolute number of "Package-Local Embed Tags" are used - regardless of whether there
        // were any "Package-Local Embed Tags" even defined.
        int nPkgTags = (s.packageTagsCount == null) ? 0 : s.packageTagsCount.size();

        // Absolute number for "Package-Local Use of Global Embed Tags"
        int nGblTags = (s.globalTagsCount == null) ? 0 : s.globalTagsCount.size();

        // IF A SPECIFIC PACKAGE DOES NOT USE <EMBED CLASS='external-html'> TAGS, SKIP IT.
        if ((nPkgTags == 0) && (nGblTags == 0)) return;

        html.append(
            "\n\n\t<TR><TH COLSPAN=3>Embed Tag FILE-ID Counts for Package: " +
            "<SPAN CLASS=PNSTATS>" + packageStats.getKey() + "</SPAN></TH></TR>\n"
        );

        if (nGblTags > 0) // Package-Local USE OF *GLOBAL Embed-Tags
        {
            html.append(
                "\n\t<TR><TD COLSPAN=3>&nbsp;</TD></TR>\n" +
                "\n\t<TR><TD COLSPAN=3><B>Global &lt;EMBED&gt; Tags Used:</B></TD></TR>\n"
            );

            // NO MESSAGER, NO THROWS
            tagCountToHTML(
                s.globalTagsCount, this.globalTagsMap, html,
                false,  // Don't mention zero-counts (there cannot be any, anyway)
                        // Since this is "Package Use of Global-Tags", it's not important
                        //
                true    // This tells it that these are global-counts, so it prints it properly
            );
        }

        if (nPkgTags > 0) // Package-Local Tags
        {
            html.append(
                "\n\t<TR><TD COLSPAN=3>&nbsp;</TD></TR>\n" +
                "\n\t<TR><TD COLSPAN=3><B>Package-Local &lt;EMBED&gt; Tags Used:</B></TD></TR>\n"
            );

            // NO MESSAGER, NO THROWS
            tagCountToHTML(
                s.packageTagsCount, s.packageTagsMap, html,
                true,   // Print the zero-counts, These are Package-Tags, so if the user didn't
                        // did not use some tags, put a notice about it.
                        //
                false   // This tells it that these are local-counts, so it prints it properly
            );
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Generating Stats HTML Files
    // ********************************************************************************************
    // ********************************************************************************************


    // This merely builds an HTML table out of an instance of Stats
    // NOTE: It **DOES NOT** include the "Package-Level" stats Tables.
    //       That is done recursively.
    //
    // NO MESSAGER, NO THROWS

    private static String toHTML_INTERNAL(Stats s)
    {
        return
            "\t<TR CLASS=BLANK><TD COLSPAN=3>&nbsp;</TD>\n" +

            "\t<TR><TD>" + StringParse.commas(s.numLines)                       + "</TD><TD COLSPAN=2>Total Lines of Source Code</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numBytes)                       + "</TD><TD COLSPAN=2>Total Bytes of Source Code</TD></TR>\n" +
            "\t<TR CLASS=BLANK><TD COLSPAN=3>&nbsp;</TD>\n" +

            "\t<TR><TD>" + StringParse.commas(s.numHiLitedDivs)                 + "</TD><TD COLSPAN=2>HiLited DIV Tags</TD></TR>\n" +
            "\t<TR CLASS=BLANK><TD COLSPAN=3>&nbsp;</TD>\n" +

            "\t<TR><TD>" + StringParse.commas(s.numMethods)                     + "</TD><TD COLSPAN=2>Source Total Methods</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numFields)                      + "</TD><TD COLSPAN=2>Source Total Fields</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numConstructors)                + "</TD><TD COLSPAN=2>Source Total Constructors</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numAnnotationElems)             + "</TD><TD COLSPAN=2>Source Total Annotation Elements</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numEnumConstants)               + "</TD><TD COLSPAN=2>Source Total Enumeration Constants</TD></TR>\n" +
            "\t<TR><TD COLSPAN=3>&nbsp;</TD>\n" +

            "\t<TR><TD>" + StringParse.commas(s.numHiLitedMethods)              + "</TD><TD COLSPAN=2>Method Bodies HiLited</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numHiLitedFields)               + "</TD><TD COLSPAN=2>Fields Declarations HiLited</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numHiLitedConstructors)         + "</TD><TD COLSPAN=2>Constructors Bodies HiLited</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numHiLitedAnnotationElems)      + "</TD><TD COLSPAN=2>Annotation Elements HiLited</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numHiLitedEnumConstants)        + "</TD><TD COLSPAN=2>Enumeration Constants HiLited</TD></TR>\n" +
            "\t<TR CLASS=BLANK><TD COLSPAN=3>&nbsp;</TD>\n" +

            "\t<TR><TD>" + StringParse.commas(s.numDocumentedMethods)           + "</TD><TD COLSPAN=2>JavaDoc Documented Methods</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numDocumentedFields)            + "</TD><TD COLSPAN=2>JavaDoc Documented Fields</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numDocumentedConstructors)      + "</TD><TD COLSPAN=2>JavaDoc Documented Constructors</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numDocumentedAnnotationElems)   + "</TD><TD COLSPAN=2>JavaDoc Documented Annotation Elements</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numDocumentedEnumConstants)     + "</TD><TD COLSPAN=2>JavaDoc Documented Enumeration Constants</TD></TR>\n" +
            "\t<TR CLASS=BLANK><TD COLSPAN=3>&nbsp;</TD>\n" +

            "\t<TR><TD>" + StringParse.commas(s.numStaticMethods)               + "</TD><TD COLSPAN=2>Static Methods</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numStaticFields)                + "</TD><TD COLSPAN=2>Static Fields</TD></TR>\n" +
            "\t<TR CLASS=BLANK><TD COLSPAN=3>&nbsp;</TD>\n" +

            "\t<TR><TD>" + StringParse.commas(s.numFinalMethods)                + "</TD><TD COLSPAN=2>Final Methods</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numFinalFields)                 + "</TD><TD COLSPAN=2>Final Fields</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numFinalConstructors)           + "</TD><TD COLSPAN=2>Final Constructors</TD></TR>\n" +
            "\t<TR CLASS=BLANK><TD COLSPAN=3>&nbsp;</TD>\n" +

            "\t<TR><TD>" + StringParse.commas(s.numPublicMethods)               + "</TD><TD COLSPAN=2>Public Methods</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numPublicFields)                + "</TD><TD COLSPAN=2>Public Fields</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numPublicConstructors)          + "</TD><TD COLSPAN=2>Public Constructors</TD></TR>\n" +
            "\t<TR CLASS=BLANK><TD COLSPAN=3>&nbsp;</TD>\n" +

            "\t<TR><TD>" + StringParse.commas(s.numProtectedMethods)            + "</TD><TD COLSPAN=2>Protected Methods</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numProtectedFields)             + "</TD><TD COLSPAN=2>Protected Fields</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numProtectedConstructors)       + "</TD><TD COLSPAN=2>Protected Constructors</TD></TR>\n" +
            "\t<TR CLASS=BLANK><TD COLSPAN=3>&nbsp;</TD>\n" +

            "\t<TR><TD>" + StringParse.commas(s.numPrivateMethods)              + "</TD><TD COLSPAN=2>Private Methods</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numPrivateFields)               + "</TD><TD COLSPAN=2>Private Fields</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numPrivateConstructors)         + "</TD><TD COLSPAN=2>Private Constructors</TD></TR>\n" +
            "\t<TR CLASS=BLANK><TD COLSPAN=3>&nbsp;</TD>\n" +

            "\t<TR><TD>" + StringParse.commas(s.numTransientFields)             + "</TD><TD COLSPAN=2>Transient Fields</TD></TR>\n" +
            "\t<TR><TD>" + StringParse.commas(s.numVolatileFields)              + "</TD><TD COLSPAN=2>Volatile Fields</TD></TR>\n" +
            "\t<TR CLASS=BLANK><TD COLSPAN=3>&nbsp;</TD>\n";
    }

    // This one works slightly differently than the previous "toHTML" function
    // It places the appended text inside the passed StringBuilder
    //
    // NO MESSAGER, NO THROWS

    private static void tagCountToHTML(
            Map<String, Integer>        embedTagsCount,
            ReadOnlyMap<String, String> embedTagsMap,
            StringBuilder               sb,
            boolean                     printZeros,
            boolean                     globalOrLocal
        )
    {
        StringBuilder zerosCountSB = new StringBuilder();

        sb.append("\t<TR><TD COLSPAN=3>&nbsp;</TD></TR>\n");

        for (ReadOnlyMap.Entry<String, String> embedTag : embedTagsMap.entrySet())
        {
            Integer count = embedTagsCount.get(embedTag.getKey());

            if (count == null) continue;

            String s =
                "\t<TR>" +
                "<TD>" + StringParse.commas(count) + "</TD>" +
                "<TD>" + embedTag.getKey() + "</TD>" +
                "<TD>" + embedTag.getValue() + "</TD>" +
                "</TR>\n";

            if (count > 0) sb.append(s);

            if (printZeros && (count == 0)) zerosCountSB.append(s);
        }

        sb.append("\t<TR><TD COLSPAN=3>&nbsp;</TD></TR>\n");

        if (printZeros && (zerosCountSB.length() > 0))

            sb.append(
                "\n\t<TR><TD COLSPAN=3>&nbsp;</TD></TR>\n" +
                "\n\t<TR><TD COLSPAN=3><B>Unused " +
                    (globalOrLocal ? "Global" : "Package-Local ") +
                    "&lt;EMBED&gt; Tags:</B></TD></TR>\n" +
                "\n\t<TR><TD COLSPAN=3>&nbsp;</TD></TR>\n" +
                zerosCountSB.toString() +
                "\n\t<TR><TD COLSPAN=3>&nbsp;</TD></TR>\n"
            );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Generating Stats Buttons
    // ********************************************************************************************
    // ********************************************************************************************


    // This is the "Stats" button that's inserted into the pages
    private static final Vector<HTMLNode> nodesToInsert =
        HTMLPage.getPageTokens("<LI><A>Stats</A></LI>\n", false);

    // In the above defined Vector, the <LI> has an HTML Anchor <A> at Vector-index 1.
    private static final int ANCHOR_POS = 1;

    // Used by: "ExtraFilesProcessor"
    //
    // MESSAGER:
    //  1) INVOKES:     warning *ONLY*
    //  2) INVOKED-BY:  *ONCE* ExtraFilesProcessor
    //  3) RETURNS:     NOTHING
    //  4) THROWS:      NOTHING INTENTIONAL
    //
    // EXPORT_PORTAL METHOD
    // This method is used by Package HTMLProcessors, and doesn't need to be exported to the user.

    static void addStatsButton(Vector<HTMLNode> page, String dotDots, String packageName)
    {
        AVT avt =
            AVT.cmp("class", TextComparitor.C, "navList").and(
            AVT.cmp("title", TextComparitor.EQ, "Navigation"));

        Vector<SubSection> navMenus = InnerTagPeekInclusive.all(page, avt, "ul");

        if (navMenus.size() < 2)
        {
            Messager.warning
                ("No Navigtion Menus Found, not adding a 'Stats.html' Link.", JDUProcessor.Stats);
            return;
        }

        SubSection topNav = navMenus.elementAt(0);
        SubSection tailNav = navMenus.elementAt(1);

        // MESSAGER:
        //  1) INVOKES:     Messager.warning
        //  2) INVOKED-BY:  HERE
        //  3) RETURN:      'false' if the Messager *WAS* used on warning
        //  4) THROWS:      NO THROW STATEMENTS

        if (! addStatsButton(topNav.html, tailNav.html, dotDots, packageName)) return;

        ReplaceNodes.r(page, topNav);
        ReplaceNodes.r(page, tailNav);
    }

    // Used by: "MainFilesProcessor"
    // Inserts a button into the Navigation Bar on a Java Doc HTML Page.
    //
    // MESSAGER:
    //  1) INVOKES:     Messager.warning
    //  2) INVOKED-BY:  Twice - MainFilesProcessor (once), addStatsButton (above)
    //  3) RETURN:      'false' if the Messager *WAS* used on warning
    //  4) THROWS:      NO THROW STATEMENTS
    //
    // EXPORT_PORTAL METHOD
    // This method is used by Package HTMLProcessors, and doesn't need to be exported to the user.

    @SuppressWarnings("unchecked") // The clone invocation
    static boolean addStatsButton(
            Vector<HTMLNode> navBarTop, Vector<HTMLNode> navBarBottom,
            String dotDots, String packageName
        )
    {
        // Find: <ul class="navList" title="Navigation">
        AVT avt =
            AVT.cmp("class", TextComparitor.C, "navList").and(
            AVT.cmp("title", TextComparitor.EQ, "Navigation"));

        // Get the Pertinent Navigator-Menu.  It is a sub-part of the overall Navigation-Bar
        // The Stats Button is added to the first Navigation-List <UL> of both the bottom
        // and top Navigation-Bar.

        DotPair topDP       = InnerTagFindInclusive.first(navBarTop, avt, "ul");
        DotPair bottomDP    = InnerTagFindInclusive.first(navBarBottom, avt, "ul");

        // Print some pointless warnings.  This will one day break.  Warning messages are better
        // than Unknown-Exceptions.  Not everybody uses the Navigation-Menus, and what will
        // happen once a user runs this without them is currently unknown.

        boolean topNull     = topDP == null;
        boolean tailNull    = bottomDP == null;

        if (topNull && tailNull)
        {
            Messager.warning("This page does not have any Navigatin Menus", JDUProcessor.Stats);
            return false;
        }

        else if (topNull || tailNull)
        {
            if (topNull) Messager.warning
                ("Page does not have a Top Navigation Menu.", JDUProcessor.Stats);

            if (tailNull) Messager.warning
                ("Page does not have a Tail Navigation Menu.", JDUProcessor.Stats);

            return false;
        }

        // Clone the STATIC-FINAL 'nodesToInsert' Vector.
        Vector<HTMLNode> v = (Vector<HTMLNode>) nodesToInsert.clone();

        // The HTML <A HREF=...> elemet that needs the RELATIVE-PATH URL w/ 'dotDots'
        TagNode anchor = (TagNode) nodesToInsert.elementAt(ANCHOR_POS);

        // Set the HREF for the anchor-url link
        anchor = anchor.setAV("HREF", dotDots + "Stats.html#" + packageName, SD.SingleQuotes);

        // Replace the old HTML Anchor Element with the updated one having the
        // relative path String to the base Java Doc directory.

        v.setElementAt(anchor, ANCHOR_POS);

        // Insert the updated navigator-menu item into the page, AS THE LAST ELEMENT 
        // of the menu (beginning at the node JUST-BEFORE the one located at navMenu.end)

        /*if (! topNull)  */ navBarTop.addAll(topDP.end, v);
        /*if (! tailNull) */ navBarBottom.addAll(bottomDP.end, v);

        return true;
    }
}