package Torello.JavaDoc;

import Torello.HTML.HTMLNode;
import Torello.HTML.TagNode;
import Torello.HTML.Replaceable;
import Torello.HTML.Util;
import Torello.HTML.Balance;
import Torello.HTML.Replacement;

import Torello.Java.StrCmpr;
import Torello.Java.StrIndent;
import Torello.Java.StrReplace;
import Torello.Java.FileRW;

import Torello.Java.Additional.Ret2;

import Torello.Java.ReadOnly.ReadOnlyList;

import static Torello.Java.C.*;

import Torello.JDUInternal.Miscellaneous.Where.JDUUserAPI;
import Torello.JavaDoc.Messager.Messager;
import Torello.JavaDoc.Messager.Where_Am_I;

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

import java.io.File;
import java.util.function.Predicate;
import java.util.function.Consumer;
import java.util.function.Function;

/**
 * Retains all information parsed from a <CODE>'&#46;html'</CODE> Java-Doc web-page, and borrows
 * any missing information that was found in the <CODE>'&#46;java'</CODE> source-code file; note
 * that an instance-reference of this class may be rerieved, and used, to further change a Java
 * Doc page by registering a visitor-handler with the configuration class {@link Upgrade} by
 * calling <B>{@link Upgrade#setExtraTasks(Consumer)}</B>.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=PROG_MOD_HTML>
 * <EMBED CLASS='external-html' DATA-FILE-ID=JD_HTML_F>
 */
@Torello.JavaDoc.Annotations.JDHeaderBackgroundImg(EmbedTagFileID="REFLECTION_HTML_CLASS")
public final class JavaDocHTMLFile extends ParsedFile implements java.io.Serializable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID>  */
    public static final long serialVersionUID = 1;

    // When the Messager Reports its errors, this class passes this reference to the Messager
    // to facilitate the printing of that information (What class encountered an error or warning
    // that needs to be printed by the Messager).
    // 
    // This is officially Package-Private (rather than private, which it normally is), because
    // this Class is large enough to have justified breaking it up into smaller, private/hidden
    // "Helper-Chunks".  I like that expression.
    // 
    // The "Helper-Chunks" are in the same package, and they need access to this field

    static final Where_Am_I WHERE_AM_I = JDUUserAPI.JavaDocHTMLFile;


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor
    // ********************************************************************************************
    // ********************************************************************************************


    // This Constructor does very little work.  It is not a completely empty body, but the vast 
    // majority of the field computations for this class are done in the package:
    // 
    // Torello.JDUInternal.Parse.HTML.JDHF
    // 
    // This Constructor mostly copies its Field-Values from Data-Records that have been computed
    // in the classes in that package.  There is a brief amount of computation done here, below.
    // 
    // Keeping HTML-Parsing code in a separate, internal, package allows me to "localize" the
    // complicated parsing code into a single location - far away from the end user.  This code
    // is dependent upon which of the Java-Doc Versions is being used.
    // 
    // Since October of 2024, HTML-Parsing Code has been moved to a single, JDUInternal,
    // suite of directories that are much easier to manage.  This constructor, for instance, just
    // block copies nearly all of the fields from one of those JDUInternal Data-Record Classes.

    public JavaDocHTMLFile(
            final Torello.JDUInternal.MainJDU.ClassUpgradeData.UpgradePredicates    predicates,
            final Torello.JDUInternal.MainJDU.ClassUpgradeData.PathsAndTypes        pathsTypes,

            // Full-Path of this JavaDoc HTML-File
            final String jdHTMLFileName,

            // Same as above, but only the Directory-Name is included - File-Name has been removed
            final String javaDocPackageDirName,

            // Java-Doc Package-Directory Name where Hi-Lited Source-Files are stored for this pkg
            final String javaDocPkgHiLitedSrcCodeDirName,

            final Torello.JDUInternal.Parse.Java.JSCF.JavaSourceCodeFile jscf,

            final RelativePathStr dotDots,

            // August 2024: Stopped passing JDHFHeaderFacts, rip it apart, pass these instead
            final String                simpleNameWithContainersAndGenerics,
            final String                packageName,
            final CIET                  ciet,
            final ReadOnlyList<String>  genericParameters,
            final String                cietFullNameNoGenerics,
            final Vector<HTMLNode>      fileVec,

            // The Members-Entites of this CIET/Type (Methods, Fields, Constructors, EC's & AE's)
            final Torello.JDUInternal.Parse.HTML.JDHF.MemberDetails.D1_JDHFMembers jdhfMembers,


            // This was moved out of this constructor body, and into the S2_LoopFiles...
            // This is needed to build the JDHFMembers instance.  Now, therefore, it has to be
            // passed into this constructor

            final String srcAsHTMLFileURL,

            // New class which handles any / all User-Requested Details removal
            final Torello.JDUInternal.Parse.HTML.JDHF.D2_RemovedDetails removedDetails,


            // The Package-Summary HTML-File
            // The User may obtain access to this file, via the reference stored inside of this
            // Class.
            //
            // March 28th, 2025
    
            final PackageSummaryHTML pkgSummaryHTML
        )
    {
        super(
            jdHTMLFileName,

            // java.util.Map.Entry<K, V>  ==>  Map.Entry<K, V>
            simpleNameWithContainersAndGenerics,

            // java.util.Map.Entry<K, V>  ==>  java.util
            packageName,

            // java.util.Map.Entry<K, V>  ==>  CIET.CLASS
            ciet,

            // java.util.Map.Entry<K, V>  ==>  "K", and "V"
            genericParameters,

            // java.util.Map.Entry<K, V>  ==>  java.util.Map.Entry
            cietFullNameNoGenerics,

            // java.util.Map.Entry<K, V>  ==?  Entry
            jscf.typeNameJOW,

            jscf.startLineNumber,
            jscf.endLineNumber,
            jscf.jdStartLineNumber,
            jscf.jdEndLineNumber,
            jscf.typeLineCount,
            jscf.typeSizeChars,
            jscf.javaSrcFileAsStr,

            jdhfMembers.methods,
            jdhfMembers.fields,
            jdhfMembers.constructors,
            jdhfMembers.enumConstants,
            jdhfMembers.annotationElements,


            // I think this is the right way to do things...  This might change one day to ensure
            // that only Nested-Types that are visible on the Java-Doc Page are actually included
            // in this list
            // 
            // For now, any Inner-Type that is identified by the Source-Code Parser will be visible
            // in an instance of JDHF - EVEN IF JAVADOC DID NOT CREATE ANY HTML FOR THAT NESTED-TYPE

            jscf.nestedTypes
        );


        // ****************************************************************************************
        // ****************************************************************************************
        // BEGINNING INITIALIZATIONS
        // ****************************************************************************************
        // ****************************************************************************************


        this.fileVec = fileVec;

        // The directory name of the 'javadoc/' sub-directory that contained this '.html' File
        this.javaDocPackageDirName = javaDocPackageDirName;


        // The directory name of the 'javadoc/' sub-directory that contains any / all Hi-Lited 
        // HTML-Files for this particular package.

        this.javaDocPkgHiLitedSrcCodeDirName = javaDocPkgHiLitedSrcCodeDirName;

        // The relative-path string to the root javadoc directory (comprised of "../../..")
        this.dotDots = dotDots;

        // The mirros for @StaticFunctional **AND** JDHeaderBackgroundImg
        this.typeAnnotationMirrors = jscf.typeAnnotationMirrors;


        // This used to be computed inside this constructor body.  Now it is computed inside the
        // Main Processing Loop for JDHF Files

        this.srcAsHTMLFileURL = srcAsHTMLFileURL;


        // March, 2025: The User has access to the parsed 'package-summary.html' File
        // This has been parsed for many years, but a way to actually access this file (other than
        // internally), was not provided until recently.

        this.pkgSummaryHTML = pkgSummaryHTML;


        // ****************************************************************************************
        // ****************************************************************************************
        // DETAILS ENTRIES - Computed in Class JDHFMembers Constructor (October 2024)
        // ****************************************************************************************
        // ****************************************************************************************


        // These are all ReadOnlyList's of Torello.JavaDoc.ReflHTML<? extends Declaration>
        this.allMethodDetails       = jdhfMembers.methodsREFL;
        this.allFieldDetails        = jdhfMembers.fieldsREFL;
        this.allConstructorDetails  = jdhfMembers.ctorsREFL;
        this.allECDetails           = jdhfMembers.ecREFL;
        this.allAEDetails           = jdhfMembers.aeREFL;


        // ****************************************************************************************
        // ****************************************************************************************
        // User-Requested Details-Removal:  Done in separate; class, just copy over the booleans
        // ****************************************************************************************
        // ****************************************************************************************


        // These are all booleans.  These are only TRUE if (and only if) the User has requested
        // that all Details for a particular section have, indeed, been removed.

        this.methodDetailsRemoved       = removedDetails.methodDetailsRemoved;
        this.fieldDetailsRemoved        = removedDetails.fieldDetailsRemoved;
        this.constructorDetailsRemoved  = removedDetails.constructorDetailsRemoved;
        this.ecDetailsRemoved           = removedDetails.ecDetailsRemoved;
        this.aeDetailsRemoved           = removedDetails.aeDetailsRemoved;


        // ****************************************************************************************
        // ****************************************************************************************
        // Compute the Hilited Source File URL.
        // ****************************************************************************************
        // ****************************************************************************************


        // The class "NavButtons" will use this FileURL.  The class HiLiteSrcCodeFile will actually
        // do that hiliting.
        // 
        // This should be null if the file isn't being hilited.

        if (! predicates.hiLiteSourceCodeFileFilter.test(this.fullNameNoGenerics))
            this.hiLitedSrcFileURL = null;

        else this.hiLitedSrcFileURL =

            "hilite-files/" +

            // The Top-Level Parent-Container HiLited '.html' File is the one to use.  This code is
            // making sure to "re-use" the already hilited parent container class!

            (this.isInner
                ? this.simpleNameWithPossibleContainers.substring
                    (0, this.simpleNameWithPossibleContainers.indexOf('.'))
                : this.simpleNameWithPossibleContainers) +
            ".java.html";


        // ****************************************************************************************
        // ****************************************************************************************
        // Header & Footer
        // ****************************************************************************************
        // ****************************************************************************************


        // All this does is facilitating moving the constructor body to package:
        // Torello.JDUInternal.Parse.HTML.Other
        // 
        // The User's API is all contained in:
        // Torello.JavaDoc.HeaderFooterHTML
        // 
        // This makes it easier for the user to read & understand the stuff he needs, and much more
        // importantly, the complicated Parse-HTML is essentially completely contained in package:
        // 
        // Torello.JDUInternal.Parse

        this.headerFooter = new HeaderFooterHTML
            (new Torello.JDUInternal.Parse.HTML.HeaderFooter.D1_HeaderFooterRec
                (fileVec, this.ciet /*, jscf Passed to make debugging this record easier */));

        // Now add the CSS-Tags to the header & footer, do this here...
        if (predicates.cssTagsFilter.test(this.fullNameNoGenerics))
            Torello.JDUInternal.Features.INSERT_CSS_TAGS.API_CSSTagsTopAndSumm
                .addTagsToDetailBanners(fileVec);


        // ****************************************************************************************
        // ****************************************************************************************
        // SUMMARIES ENTRIES
        // ****************************************************************************************
        // ****************************************************************************************


        // if (! Q.YN(C.BGREEN + "Should this continue?" + C.RESET)) System.exit(1);

        Torello.JDUInternal.Parse.HTML.SummaryTable.D1_AllSummaryTables allSummTables =

            Torello.JDUInternal.Parse.HTML.SummaryTable.API_GetSummaryTables.build(
                fileVec, jscf, this,


                // NOTE: There is a "bang" / "not" / "exclamation point" because the name of this
                //       filter is parameter is "retainRemoveDescriptions"
                // 
                // But the name of this filter is "SummaryRemoveFilter"
                // I have tested this thing. 

                ! predicates.summaryRemoveFilter.test(this.fullNameNoGenerics)
            );


        this.methodSummaryTable         = allSummTables.methodSummaryTable;
        this.fieldSummaryTable          = allSummTables.fieldSummaryTable;
        this.constructorSummaryTable    = allSummTables.constructorSummaryTable;
        this.ecSummaryTable             = allSummTables.ecSummaryTable;
        this.raeSummaryTable            = allSummTables.raeSummaryTable;
        this.oaeSummaryTable            = allSummTables.oaeSummaryTable;
        this.ntSummaryTable             = allSummTables.ntSummaryTable;

        this.allNonNullSummaryTables = allSummTables.allNonNullSummaryTables;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // END CONSTRUCTOR !!!
    // ********************************************************************************************
    // ********************************************************************************************


    // ********************************************************************************************
    // ********************************************************************************************
    // Primary (Final) Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This provides the relative path-{@code String} from {@code 'this'} Java Doc generated
     * {@code '.html'} File to the root Java Doc Directory.
     */
    public final RelativePathStr dotDots;

    /**
     * Directory-Name of the Java-Doc Sub-Directory that contains this Java-Doc
     * {@code '.html'}-File.  This sub-directory should just be the name of the Root Java-Doc
     * Directory, with this class' Full Package-Name appended to it.
     * 
     * <BR /><BR />If the JPMS (Java Platform Module System) has been used by a User-Project
     * that contains multiple Java-Modules, then this directory shall also be pre-fixed with the
     * relevant module containing this directory.
     */
    public final String javaDocPackageDirName;

    /**
     * Directory-Name of the Java-Doc Sub-Directory that contains the Hi-Lited Source-Code
     * {@code '.html'}-Files for the Java-Classes which are included in the Java-Package to which
     * this particular Java-Class belongs.
     * 
     * <BR /><BR />Unless instructed otherwise, the JDU spends effort to provide Syntax-HiLited
     * {@code '.html'}-Files for each and every one of the Classes in a User's Java-Project.  These
     * files are each saved in the Hi-Lite Directory that is germaine / relevant for the given
     * Java-Package to which the given Java-Class belongs.
     */
    public final String javaDocPkgHiLitedSrcCodeDirName;

    /**
     * Directory-Name of the Java-Doc Sub-Directory that 
     */

    // The HTML Vector for a Java Doc web-page
    private final Vector<HTMLNode> fileVec;

    // This is where the 'updated-vector' is saved after the changes have been recommitted.
    private Vector<HTMLNode> updatedFileVec = null;

    /**
     * The HTML that occurs directly above the Summary-Tables is the header.  The HTML that is
     * located below the Detail-Entries is the footer.
     */
    public final HeaderFooterHTML headerFooter;

    /**
     * This is the File-{@code URL} to use if a need to link to the corresponding
     * {@code "/src-html/"} file is necessary.
     * 
     * <BR /><BR />This is a <B STYLE='color: red;'>relative</B>-URL that contains the requisite
     * number of 'dot-dots' to reach the file from the location where this Java Doc HTML File is
     * located.
     */
    public final String srcAsHTMLFileURL;

    /**
     * This is the File-{@code URL} to use if a need to link to the corresponding
     * {@code "/hilite-files/"} file is necessary.
     * 
     * <BR /><BR />This is a <B STYLE='color: red;'>relative</B>-URL that is relative to the file
     * from the location where this Java Doc HTML File is located.  Specifically, this
     * {@code String} begins with the text {@code "/hilite-files/"}, followed by the type-name,
     * and ending with the extension {@code ".java.html"}
     */
    public final String hiLitedSrcFileURL;

    /**
     * This is a reference to the parsed, {@code 'package-summary.html'} File for the Project's
     * 'Java-Package' to which this class belongs.
     */
    public final PackageSummaryHTML pkgSummaryHTML;


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // The HTML Details as Vector<ReflHTML<?>>
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

    /**
     * This is the list of all constructors in the "Constructor Details", stored as
     * Reflection-HTML instances
     */
    public final ReadOnlyList<ReflHTML<Constructor>> allConstructorDetails;

    /**
     * This is the list of all fields in the "Field Details", stored as Reflection-HTML
     * instances
     */
    public final ReadOnlyList<ReflHTML<Field>> allFieldDetails;

    /**
     * This is the list of all methods in the "Method Details", stored as Reflection-HTML
     * instances
     */
    public final ReadOnlyList<ReflHTML<Method>> allMethodDetails;

    /**
     * This is the list of all constants in the "Enumerated Constant Details", stored as
     * Reflection-HTML instances
     */
    public final ReadOnlyList<ReflHTML<EnumConstant>> allECDetails;

    /**
     * This is the list of all elements in the "Annotation Element Details", stored as
     * Reflection-HTML instances
     */
    public final ReadOnlyList<ReflHTML<AnnotationElem>> allAEDetails;


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // The HTML Summaries as SummaryTableHTML
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

    /** The HTML for a Method Summary */
    public final SummaryTableHTML<Method> methodSummaryTable;

    /** The HTML for a Field Summary Table */
    public final SummaryTableHTML<Field> fieldSummaryTable;

    /** The HTML for a Constructor Summary Table */
    public final SummaryTableHTML<Constructor> constructorSummaryTable;

    /** The HTML for an Enum-Constant Summary Table */
    public final SummaryTableHTML<EnumConstant> ecSummaryTable;

    /** The HTML for an Optional Annotation Element Summary Table */
    public final SummaryTableHTML<AnnotationElem> oaeSummaryTable;

    /** The HTML for a Required Annotation Element Summary Table */
    public final SummaryTableHTML<AnnotationElem> raeSummaryTable;

    /** The HTML for a Nested-Class (Inner-Class) Summary Table */
    public final SummaryTableHTML<NestedType> ntSummaryTable;

    /** all non-null {@link SummaryTableHTML} instances */
    @SuppressWarnings("rawtypes")
    public final ReadOnlyList<SummaryTableHTML> allNonNullSummaryTables;


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // Booleans for remembering whether a Details Section was removed completely
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

    /** Identifies if this Java Doc HTML Page has had it's Method Details Removed */
    public final boolean methodDetailsRemoved;

    /** Identifies if this Java Doc HTML Page has had it's Constructor Details Removed */
    public final boolean constructorDetailsRemoved;

    /** Identifies if this Java Doc HTML Page has had it's Field Details Removed */
    public final boolean fieldDetailsRemoved;

    /** Identifies if this Java Doc HTML Page has had it's Enumeration Constant Details Removed */
    public final boolean ecDetailsRemoved;

    /** Identifies if this Java Doc HTML Page has had it's Annotation-Element Details Removed */
    public final boolean aeDetailsRemoved;


    // ********************************************************************************************
    // ********************************************************************************************
    // Find Methods: Methods that accept a String / int
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns a list as a {@code java.util.stream.Stream} of all Reflected-HTML-{@link Method}
     * instances that have a name equal to {@code 'methodName'}.
     * 
     * @param methodName The name of the method being searched for.
     * 
     * @return A Java Stream containing all {@link Method}-{@link ReflHTML} instances that match
     * the provided {@code 'methodName'} criteria.
     */
    public Stream<ReflHTML<Method>> findMethodHTML(String methodName)
    {
        return allMethodDetails
            .stream()
            .filter((ReflHTML<Method> refl) -> refl.entity.name.equals(methodName));
    }

    /**
     * Returns a list as a {@code java.util.stream.Stream} of all Reflected-HTML-{@link Method}
     * instances that have the specified number of parameters.
     * 
     * @param numParameters The number of parameters contained by the {@link Method} being searched
     * for.
     * 
     * @return A Java Stream containing all {@link Method}-{@link ReflHTML} instances that match
     * the provided {@code 'numParameters'} criteria.
     */
    public Stream<ReflHTML<Method>> findMethodHTML(int numParameters)
    {
        return allMethodDetails
            .stream()
            .filter((ReflHTML<Method> refl) -> refl.entity.numParameters() == numParameters);
    }
    
    /**
     * Returns a list as a {@code java.util.stream.Stream} of all
     * Reflected-HTML-{@link Constructor} instances that have the specified number of parameters.
     * 
     * @param numParameters The number of parameters contained by the {@link Constructor} being
     * searched for.
     * 
     * @return A Java Stream containing all {@link Constructor}-{@link ReflHTML} instances that
     * match the provided {@code 'numParameters'} specifier.
     */
    public Stream<ReflHTML<Constructor>> findConstructorHTML(int numParameters)
    {
        return allConstructorDetails
            .stream()
            .filter((ReflHTML<Constructor> refl) -> refl.entity.numParameters() == numParameters);
    }

    /**
     * The Reflected-HTML Field having the specified name, or null if no such field exists
     * 
     * @param fieldName The name of the field being searched
     * 
     * @return The {@code ReflHTML<Field>} instance, from {@code 'this'} Java Doc Page, whose name
     * matches {@code fieldName}, or null it wasn't found.
     */
    public ReflHTML<Field> findFieldHTML(String fieldName)
    {
        for (ReflHTML<Field> f : allFieldDetails) if (f.entity.name.equals(fieldName)) return f;
        return null;
    }

    /**
     * The Reflected-HTML Enum-Constant having the specified name, or null if no such constant
     * exists
     * 
     * @param enumConstantName The name of the constant being searched
     * 
     * @return The {@code ReflHTML<EnumConstant>} instance, from {@code 'this'} Java Doc Page,
     * whose name matches {@code enumConstantName}, or null it wasn't found.
     * 
     * @throws UpgradeException Only a Java {@link CIET}/Type {@code 'enum'} is allowed to declare
     * Enum-Constants, and therefore this exception throws <I>when this method is invoked on a
     * Java Doc HTML File that doesn't represent an {@code enum}.</I>
     */
    public ReflHTML<EnumConstant> findECHTML(String enumConstantName)
    {
        if (this.ciet != CIET.ENUM) throw new UpgradeException(
            "Finding Enumeration-Constants is only possible with HTML Files for Java 'enum' " +
            "Type's.  This file is of type [" + this.ciet.toString() + "]"
        );

        for (ReflHTML<EnumConstant> ec : allECDetails)
            if (ec.entity.name.equals(enumConstantName))
                return ec;

        return null;
    }

    /**
     * The Reflected-HTML Annotation-Element having the specified name, or null if no such element
     * exists
     * 
     * @param annotationElemName The name of the constant being searched
     * 
     * @return The {@code ReflHTML<EnumConstant>} instance, from {@code 'this'} Java Doc Page,
     * whose name matches {@code annotationElemName}, or null it wasn't found.
     * 
     * @throws UpgradeException Only a Java {@link CIET}/Type {@code '@interface'} is allowed to
     * declare Annotation-Elements, and therefore this exception throws <I>when this method is
     * invoked on a Java Doc HTML File that doesn't represent an annotation.</I>
     */
    public ReflHTML<AnnotationElem> findAEHTML(String annotationElemName)
    {
        if (this.ciet != CIET.ANNOTATION) throw new UpgradeException(
            "Finding Annotation-Elements is only possible with HTML Files for Java '@interface' " +
            "(Annotation) Type's.  This file is of type [" + this.ciet.toString() + "]"
        );

        for (ReflHTML<AnnotationElem> ae : allAEDetails)
            if (ae.entity.name.equals(annotationElemName))
                return ae;

        return null;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Find Refl<HTML> Entities
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Finds a matching {@link ReflHTML} instance whose internal {@code 'entity'} field has an
     * ID number that matches input-parameter {@code 'declarationID'}.
     * 
     * @param declarationID Whenever any instance of a sub-class of {@link Declaration} is created,
     * it is given a unique id that uniquely identifies it across the entire life-cycle of the JVM
     * that is currently running.
     * 
     * @param c This must be a Java {@code java.lang.Class} from one of the following:
     * {@link Constructor}, {@link Method}, {@link Field}, {@link EnumConstant} or
     * {@link AnnotationElem}.
     * 
     * <BR /><BR /><B>NOTE:</B> This class is very easily obtained by simple using the
     * {@code 'enum'} field {@link Entity#upgraderReflectionClass}.  To pass the appropriate class
     * for a method, simply pass {@code Entity.METHOD.upgraderReflectionClass} to this parameter.
     * 
     * <BR /><BR /><B>ALSO:</B> Even more easy (if you know the member/entity type), you can
     * hard-code / hand-type the class yourself - for instance {@code Method.class}.  If you were
     * searching for a {@code ReflHTML<Field>}, you would pass {@code Field.class} to this
     * parameter.
     * 
     * @return The {@link ReflHTML} instance whose HTML describes the Method, Field, or Constructor
     * etc... whose actual Reflected-class has an ID that matches {@code 'declarationID'}.  Note
     * that the second parameter {@code 'c'} is primarily used to "speed up" the search process.
     * 
     * <DIV CLASS=EXAMPLE>{@code
     * // Note the 'Method' being passed is Torello.JavaDoc.Method (not java.lang.reflect.Method)
     * ReflHTML<Method> refl = jdhf.findEntity(someEntityID, Method.class);
     * }</DIV>
     * 
     * @throws IllegalArgumentException If the value passed to {@code 'declarationID'} is negative.
     */
    @SuppressWarnings("unchecked") // Seems like the Java-Compiler is failing on this one.
    public <ENTITY extends Declaration> ReflHTML<ENTITY> findReflHTML
        (int declarationID, Class<ENTITY> c)
    {
        if (declarationID < 0) throw new IllegalArgumentException
            ("You have passed a negative declarationID: " + declarationID);

        if (Constructor.class.equals(c)) // This is **CLEARLY** not an unchecked cast!
            for (ReflHTML<Constructor> r : allConstructorDetails)
                { if (r.entity.id == declarationID) return (ReflHTML<ENTITY>) r; }

        else if (Method.class.equals(c))
            for (ReflHTML<Method> r : allMethodDetails)
                { if (r.entity.id == declarationID) return (ReflHTML<ENTITY>) r; }

        else if (Field.class.equals(c))
            for (ReflHTML<Field> r : allFieldDetails)
                { if (r.entity.id == declarationID) return (ReflHTML<ENTITY>) r; }

        else if (EnumConstant.class.equals(c))
            for (ReflHTML<EnumConstant> r : allECDetails)
                { if (r.entity.id == declarationID) return (ReflHTML<ENTITY>) r; }

        else if (AnnotationElem.class.equals(c))
            for (ReflHTML<AnnotationElem> r : allAEDetails)
                { if (r.entity.id == declarationID) return (ReflHTML<ENTITY>) r; }

        return null;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Links-Checker Access-Method
    // ********************************************************************************************
    // ********************************************************************************************


    // StrReplace Helper String[]-Arrays
    private static final String[] MATCH_STRS    = { "%3C", "%3E", "%5B", "%5D" };
    private static final String[] REPLACE_STRS  = { "&lt;" , "&gt;", "[", "]" };


    // This Retrieves all CSS-ID's and all <A HREF=...> (the HREF part) from every HTMLNode in
    // this set, and checks returns them as two TreeSet's.
    //
    // Ret2.a: All CSS-ID's found on the page - *NOTE*, this is the *POST-PROCESSED* page
    // Ret2.b: All HREF Attributes inside of every <A>/Anchor on this page
    //
    // This is called by the LinksChecker class

    public Ret2<TreeSet<String>, TreeSet<String>> allIDsAndHREFs()
    {
        TreeSet<String> allIDs      = new TreeSet<>();
        TreeSet<String> allHREFs    = new TreeSet<>();
        TagNode         tn          = null;

        for (HTMLNode n : updatedFileVec)

            if ((tn = n.openTagPWA()) != null)
            {
                String id   = tn.AV("id");
                String href = tn.AV("href");

                if (id != null) allIDs.add(id);

                if (href != null)
                {
                    if (href.equals("#top")) continue;

                    if (StrCmpr.startsWithXOR(
                            href, "http://", "https://", "/",
                            "javascript:"
                    ))
                        continue;

                    allHREFs.add(StrReplace.r(href, MATCH_STRS, REPLACE_STRS));
                }
            }

        return new Ret2<>(allIDs, allHREFs);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Internal Utility Methods
    // ********************************************************************************************
    // ********************************************************************************************


    // Checks the validity of the HTML on a Java Doc Web-page
    // @return The Balance Report, generated by class {@link Balance}.  The ;identifies any
    // potential unmatched HTML tags.
    //
    // EXPORT_PORTAL METHOD
    // This method is used by Package HTMLProcessors, and doesn't need to be exported to the user.

    Hashtable<String, Integer> checkValidity()
    {
        if (updatedFileVec == null) Messager.assertFail(
            "For some odd reason, the updatedFileVec has not been set",
            null,
            WHERE_AM_I
        );

        return Balance.checkNonZero(Balance.check(updatedFileVec));
    }

    // Saves the Vectorized-HTML back to the file on disk from whence it was loaded.
    // @throws IOException This propogates any / all exceptions which might be thrown when
    // trying to write the file to the file-system.
    //
    // EXPORT_PORTAL METHOD
    // This method is used by Package HTMLProcessors, and doesn't need to be exported to the user.

    void commitFileToDisk() throws java.io.IOException
    {
        if (updatedFileVec == null) Messager.assertFail(
            "For some odd reason, the updatedFileVec has not been set",
            null,
            WHERE_AM_I
        );

        FileRW.writeFile(Util.pageToString(this.updatedFileVec), this.fileName);
    }


    // Collates and inserts any changes made to the Sub-Sections back into the main page
    //
    // NO MESSAGER, NO THROWS, THE DATA IS ALL PRIVATE
    //
    // EXPORT_PORTAL METHOD
    // This method is used by Package HTMLProcessors, and doesn't need to be exported to the user.

    @SuppressWarnings("unchecked") // The Vector<Replaceable> cast
    void commitChanges()
    {
        final TreeSet<Replaceable> replaceables = new TreeSet<>();

        allNonNullSummaryTables.forEach(
            (@SuppressWarnings("rawtypes") SummaryTableHTML sTable) ->
                replaceables.addAll((Vector<Replaceable>) sTable.allReplaceables())
        );

        for (ReflHTML<Method> r : allMethodDetails)
            replaceables.addAll(r.allReplaceables());

        for (ReflHTML<Field> r : allFieldDetails)
            replaceables.addAll(r.allReplaceables());

        for (ReflHTML<Constructor> r : allConstructorDetails)
            replaceables.addAll(r.allReplaceables());

        for (ReflHTML<AnnotationElem> r : allAEDetails)
            replaceables.addAll(r.allReplaceables());

        for (ReflHTML<EnumConstant> r : allECDetails)
            replaceables.addAll(r.allReplaceables());

        replaceables.addAll(headerFooter.allReplaceables());


        // This is one of those "assert" moments.  This exception is not EVER supposed to throw, 
        // however, if it does, it is likely because of some grave error that was made inside of
        // this class Constructor.  When this happens, it is better to print the file name that has
        // caused this exception throw, quickly.
        // 
        // Generally UNHANDLED EXCEPTIONS are supposed to signify a more serious design flaw, so
        // it is better (IMHO) to just let them bubble up to the top, and FIX THE BUG ASAP.
        // 
        // If this throws, make sure the print the file-name, and hope it is easy to figure out
        // what just happened.

        try 
            { this.updatedFileVec = Replacement.run(fileVec, replaceables, false).a; }

        catch (Torello.HTML.ReplaceablesOverlappingException e)
        {
            System.out.println(
                '\n' +
                "Currently Processing - this.fileName:\n" +
                "    [" + BYELLOW + this.fileName + RESET + "]\n" +
                "ParsedFile.quickSummary():\n" +
                StrIndent.indent(this.quickSummary(), 4)
            );

            throw e;
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // THE NEW-THING: Garbage-Collector Helper?
    // ********************************************************************************************
    // ********************************************************************************************
    //
    // Does this help?  Is this "good" for the Garbage-Collect?  Is this going to speed it up,
    // or slow it down?  This is just a "C-Styled" FREE or DESTORY method...
    // It isn't publicly visible anyway...

    void clear()
    {
        headerFooter.clear();

        // private final Vector<SummaryTableHTML> allNonNullSummaryTables;
        for (@SuppressWarnings("rawtypes") SummaryTableHTML st : allNonNullSummaryTables)
            st.clear();
    }


}