package Torello.JavaDoc;

import Torello.HTML.*;
import Torello.HTML.NodeSearch.*;
import Torello.JDUInternal.HTMLProcessors.Other.*;
import Torello.JDUInternal.ParseHTML.*;
import Torello.Java.Additional.*;
import Torello.Java.*;

import Torello.Java.ReadOnly.ReadOnlyArrayList;
import Torello.Java.ReadOnly.ReadOnlyList;

import static Torello.Java.C.*;

import Torello.JDUInternal.GeneralPurpose.Messager;

import Torello.JDUInternal.ParseJavaSource.JavaSourceCodeFile;

import Torello.JDUInternal.DataClasses.MainLoopData.JDHFHeaderFacts;

import Torello.JDUInternal.DataClasses.ClassUpgradeData.UpgradePredicates;
import Torello.JDUInternal.DataClasses.ClassUpgradeData.PathsAndTypes;

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

import java.io.File;
import java.util.function.Predicate;
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>
 * 
 * @see JavaSourceCodeFile
 */
@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;


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

    // 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;


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


    // ********************************************************************************************
    // ********************************************************************************************
    // Getters: Summaries
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * An {@code Iterator} that iterates the Summary Tables defined on this page.
     * 
     * @return An Instance of {@code Iterator<SummaryTableHTML>}.
     * 
     * <BR /><BR /><B STYLE='color: red;'>NOTE:</B> There is a <B>raw-type</B> used by the 
     * {@code Iterator} that is returned.  If this method is invoked, it will either generate
     * compiler warnings, or the @{@code SuppressWarnings("rawtypes")} annotation will need to be
     * applied (and, likely, the suppressing of {@code "unchecked"} warnings will also have to be
     * applied eventually)
     */
    @SuppressWarnings("rawtypes")
    public Iterator<SummaryTableHTML> allNonNullSummaryTables()
    { return new RemoveUnsupportedIterator<>(allNonNullSummaryTables.iterator()); }

    /**
     * An {@code Stream} of the Summary Tables defined on this page.
     * 
     * @return An Instance of {@code Stream<SummaryTableHTML>}.
     * 
     * <BR /><BR /><B STYLE='color: red;'>NOTE:</B> There is a <B>raw-type</B> used by the 
     * {@code Stream} that is returned.  If this method is invoked, it will either generate
     * compiler warnings, or the @{@code SuppressWarnings("rawtypes")} annotation will need to be
     * applied (and, likely, the suppressing of {@code "unchecked"} warnings will also have to be
     * applied eventually)
     */
    @SuppressWarnings("rawtypes")
    public Stream<SummaryTableHTML> allNonNullSummaryTablesStream()
    { return allNonNullSummaryTables.stream(); }


    // ********************************************************************************************
    // ********************************************************************************************
    // 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;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor and Constructor-Helper
    // ********************************************************************************************
    // ********************************************************************************************


    // MESSAGER
    //  1) INVOKES:     assertFailHTML
    //  2) INVOKED-BY:  MainFilesProcessor *ONLY* (once)
    //  3) RETURNS:     NOTHING, this is a constructor
    //  4) THROWS:      JavaDocHTMLParseException (assertFailHTML)
    //
    //  NOTE: This makes many calls to the "ReflHTML" constructor, which obeys these 
    //        Messager Rules as well.  (Expects nothing, only uses assertFailHTML)

    public JavaDocHTMLFile(
            final UpgradePredicates     predicates,
            final PathsAndTypes         pathsTypes,
            final String                jdHTMLFileName,
            final JavaSourceCodeFile    jscf,
            final RelativePathStr       dotDots,
            final JDHFHeaderFacts       jdhfHeaderFacts
        )
    {
        // The 'super' constructor must be on the first line.  This is the signature of that
        // Constructor.
        //
        // protected ParsedFile​(
        //      String fileName, String name, String packageName, CIET ciet,
        //      String[] genericParameters, String fullyQualifiedName
        // )

        super(
            jdHTMLFileName, // HTML File Name
            jdhfHeaderFacts.simpleNameWithGenerics, // Un-Qualified-Name, Including GTP's (if any)
            jdhfHeaderFacts.packageName,            // The Java "Package Name"
            jdhfHeaderFacts.ciet,                   // CIET, This is the source-code file 'kind'
            jdhfHeaderFacts.genericParams,          // List of "GTP Names" - if there are any
            jdhfHeaderFacts.cietFullNameNoGenerics, // Fully Qualified Class Name, Without GTP's
                                                    // NOT USED: jdhfHeaderFacts.srcCodeFileName
            jscf.startLineNumber,
            jscf.endLineNumber,
            jscf.jdStartLineNumber,
            jscf.jdEndLineNumber,
            jscf.typeLineCount,
            jscf.typeSizeChars,
            jscf.javaSrcFileAsStr
        );


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


        // NOW, THIS IS PRIVATE, IT WASN'T IN THE PAST.
        // Since breaking up the processing into small pieces (optimization), this MUST BE PRIVATE

        final Vector<HTMLNode> fileVec = this.fileVec = jdhfHeaderFacts.fileVec;

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

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


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // URL to the corresponding "/src-html/" file (if it exists) - **INCLUDING LINE-NUMBERS**
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // For "inner-classes", there is now a new-and-improved way to link to the JavaDoc source
        // file.  JavaDoc actually makes a mess out of **INNER-CLASSES** by making a duplicate /
        // copy of the Java-Source-Code-As-HTML for each-and-every inner-class!  This means that
        // if there were say... 10 inner classes ... (as in Torello.Browser classes), there are
        // 10 COPIES OF THE EXACT SAME FILES
        //
        // This helps clean that up...  Note that the actual deletion of these duplicate src-file's
        // is actually done by class "ExtraFilesProcessor" (right at the top of the class)
        //
        // NOTE: Perhaps the Java 17 JavaDoc doesn't make this seriously egregious error, but the
        //       JavaDoc released with JDK 11 seems to be doing that.  I need to start upgrading
        //       for JDK 17 pretty soon...
        //
        // ALSO: Upgrade.getSrcHTMLFile(..) ==> a one-line of code HashMap lookup (no Messager)

        this.srcAsHTMLFileURL = this.isInner

            ? this.dotDots.fileSystem + pathsTypes.srcHTMLFiles.get(
                this.packageName + '.' +
                this.simpleName.substring(0, this.simpleName.indexOf('.'))
            )
            : this.dotDots.fileSystem + pathsTypes.srcHTMLFiles.get(this.fullyQualifiedName);

        /*
        if (this.isInner) System.out.println(
            "srcAsHTMLFile: " + this.srcAsHTMLFileURL +
            "\n" + this.packageName + '.' +
            this.simpleName.substring(0, this.simpleName.indexOf('.'))
        );
        */


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

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

        else this.hiLitedSrcFileURL =

            "hilite-files/" +
            (this.isInner
                ? this.simpleName.substring(0, this.simpleName.indexOf('.'))
                : this.simpleName) +
            ".java.html";


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // REMOVE THIS STUFF, **IF REQUESTED**  DO THIS **BEFORE** THE PARSING EVEN STARTS
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // The user has the option of removing an **ENTIRE** details section, on request.  This is
        // particularly useful for things like an "enum" that has lots of constants where each 
        // constant detail would be documented ad nauseum.  This also used by the search-classes in
        // the NodeSearch package where, for example, InnerTagFind has 100 methods, each of which
        // take some slightly different variant of the exact same parameters.
        //
        // NOTE: The user even has the option of removing **ALL** Details (from all
        // detail-sections)
        //
        // BTW: Every time you try to find where there is a test to check the value of
        //      "methodDetailsRemoved" or "methodDetailsRemoved", remember, these Detail-Removal
        //      Steps happen BEFORE THIS FILE'S HTML-CONTENT IS EVEN PARSED INTO Refl's !!!
        //      SO - NO, The class "DetailsProcessor" doesn't check these booleans before
        //      processing these ReflHTML's, because these Detail/ReflHTML's are never even created
        //      to begin with - Notice the Details.removeAllDetails happens, right here, right now.

        if (predicates.removeAllDetailsFilter.test(this.fullyQualifiedName))
        {
            try
                { Details.removeAllDetails(fileVec); }

            catch (Exception e)
                { Messager.assertFailHTML(e, "Unexpected-Exception Removing Details HTML", null); }

            this.methodDetailsRemoved = this.fieldDetailsRemoved = this.constructorDetailsRemoved =
                this.ecDetailsRemoved = this.aeDetailsRemoved = true;
        }

        // Same-Story, but this only removes sub-sections of the generalized "Details Sections" on
        // a Java-Doc Web-Page.  The "Constructor Details" could be removed without removing the
        // Method-Details at all.

        else try 
        {
            UpgradePredicates p = predicates;

            if (this.methodDetailsRemoved =
                    p.removeAllMethodDetailsFilter.test(this.fullyQualifiedName))
                Details.removeAllDetails(fileVec, Entity.METHOD);

            if (this.fieldDetailsRemoved =
                    p.removeAllFieldDetailsFilter.test(this.fullyQualifiedName))
                Details.removeAllDetails(fileVec, Entity.FIELD);

            if (this.constructorDetailsRemoved =
                    p.removeAllConstructorDetailsFilter.test(this.fullyQualifiedName))
                Details.removeAllDetails(fileVec, Entity.CONSTRUCTOR);

            if (this.ecDetailsRemoved =
                    p.removeAllECDetailsFilter.test(this.fullyQualifiedName))
                Details.removeAllDetails(fileVec, Entity.ENUM_CONSTANT);

            if (this.aeDetailsRemoved =
                    p.removeAllAEDetailsFilter.test(this.fullyQualifiedName))
                Details.removeAllDetails(fileVec, Entity.ANNOTATION_ELEM);
        }

        catch (Exception e)
        {
            Messager.assertFailHTML(e, "Unexpected-Exception Removing Details HTML", null);

            throw new UnreachableError();
                // Since this is a constructor, "return Messager..."" **CANNOT** work here.\
                // If this is not here => compiler gives "might not have been initialized" errors
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Header-Footer
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // INVOKED-BY: JavaDocHTMLFile *ONLY* (once)

        this.headerFooter = new HeaderFooterHTML(fileVec, this.ciet);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Now add the CSS-Tags to the header & footer, do this here...
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // INVOKED-BY: JavaDocHTMLFile Constructor (once)

        if (predicates.cssTagsFilter.test(this.fullyQualifiedName))
            CSSTagsTopAndSumm.addTagsToDetailBanners(fileVec);


        // ****************************************************************************************
        // ****************************************************************************************
        // DETAILS ENTRIES
        // ****************************************************************************************
        // ****************************************************************************************


        HNLIInclusive       iter;
        Vector<HTMLNode>    details;
        DotPair             dp;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Parse the Java Doc HTML "Method Details", one by one.  Add to internal Vectors.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        Function<DotPair, ReflHTML<Method>> getMethod = (DotPair methodDetail) ->
        {
            // Retrieve the signature of the method from the Java Doc HTML
            final DotPair signature = TagNodeFindInclusive.first
                (fileVec, methodDetail.start, methodDetail.end, "pre");

            if (signature == null) Messager.assertFailHTML
                ("Method Detail Section does not appear to have a Signature <PRE>", null);

            // SignatureParse.parseECSignature: is called twice:
            //  Once from JavaDocHTMLFile-Constructor: using the Detail-HTML-Signature
            //  Once from SummaryTableHTML-Constructor: using the Summary-HTML-Signature
            //
            // USES: Messager.assertFailHTML() (JavaDocHTMLParseException)

            final Method method = SignatureParse.parseMethodSignature
                (Util.textNodesString(fileVec, signature), jscf, this);

            // ParsedFile (parent-class) "addMethod" (it's a one-liner, no Messager)
            addMethod(method);

            return new ReflHTML<>(
                method, methodDetail, fileVec, Entity.METHOD,
                getDetailID(fileVec, methodDetail, method),
                this.isInner ? this.srcAsHTMLFileURL : null
            );
        };

        List<DotPair> l = Details.sectionAllDetailsDP(fileVec, Entity.METHOD);

        this.allMethodDetails = new ReadOnlyArrayList<>(l, getMethod, l.size());


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Parse the Java Doc HTML "Constructor Details", one by one.  Add to internal Vectors.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        Function<DotPair, ReflHTML<Constructor>> getConstructor = (DotPair constructorDetail) ->
        {
            // Retrieve the signature of the constructor from the Java Doc HTM
            final DotPair signature = TagNodeFindInclusive.first
                (fileVec, constructorDetail.start, constructorDetail.end, "pre");

            if (signature == null) Messager.assertFailHTML
                ("Constructor Detail Section does not appear to have a Signature <PRE>", null);

            // SignatureParse.parseConstructorSignature: is called twice:
            //  Once from JavaDocHTMLFile-Constructor: using the Detail-HTML-Signature
            //  Once from SummaryTableHTML-Constructor: using the Summary-HTML-Signature
            //
            // USES: Messager.assertFailHTML() (JavaDocHTMLParseException)

            final Constructor constructor = SignatureParse.parseConstructorSignature
                (Util.textNodesString(fileVec, signature), jscf, this);

            // ParsedFile (parent-class) "addConstructor" (it's a one-liner, no Messager)
            addConstructor(constructor);

            return new ReflHTML<>(
                constructor, constructorDetail, fileVec, Entity.CONSTRUCTOR,
                getDetailID(fileVec, constructorDetail, constructor),
                this.isInner ? this.srcAsHTMLFileURL : null
            );
        };

        l = Details.sectionAllDetailsDP(fileVec, Entity.CONSTRUCTOR);

        this.allConstructorDetails = new ReadOnlyArrayList<>(l, getConstructor, l.size());


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Parse the Java Doc HTML "Field Details", one by one.  Add to internal Vectors.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        Function<DotPair, ReflHTML<Field>> getField = (DotPair fieldDetail) ->
        {
            // Retrieve the signature of the field from the Java Doc HTML
            final DotPair signature = TagNodeFindInclusive.first
                (fileVec, fieldDetail.start, fieldDetail.end, "pre");

            if (signature == null) Messager.assertFailHTML
                ("Field Detail Section does not appear to have a Signature <PRE>", null);

            // SignatureParse.parseFieldSignature: is called twice:
            //  Once from JavaDocHTMLFile-Constructor: using the Detail-HTML-Signature
            //  Once from SummaryTableHTML-Constructor: using the Summary-HTML-Signature
            //
            // USES: Messager.assertFailHTML() (JavaDocHTMLParseException)
            //
            // HERE, pass 'genericParameters' because Java Doc inserts the definition into
            // the signature on the web-page.  They have to be removed, or JP throws exception.

            final Field field = SignatureParse.parseFieldSignature(
                Util.textNodesString(fileVec, signature),
                genericParameters.size() > 0,
                jscf, this
            );

            // ParsedFile (parent-class) "addField" (it's a one-liner, no Messager)
            addField(field);

            return new ReflHTML<>(
                field, fieldDetail, fileVec, Entity.FIELD,
                getDetailID(fileVec, fieldDetail, field),
                this.isInner ? this.srcAsHTMLFileURL : null
            );
        };

        l = Details.sectionAllDetailsDP(fileVec, Entity.FIELD);

        this.allFieldDetails = new ReadOnlyArrayList<>(l, getField, l.size());


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Parse the Java Doc HTML "Enumeration-Constant Details".  Add to the internal Vectors.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        Function<DotPair, ReflHTML<EnumConstant>> getEC = (DotPair ecDetail) ->
        {
            // Retrieve the signature of the enumeration-constant from the Java Doc HTML
            final DotPair signature = TagNodeFindInclusive.first
                (fileVec, ecDetail.start, ecDetail.end, "pre");

            if (signature == null) Messager.assertFailHTML
                ("EC Detail Section does not appear to have a Signature <PRE>", null);

            // SignatureParse.parseECSignature: is called twice:
            //  Once from JavaDocHTMLFile-Constructor: using the Detail-HTML-Signature
            //  Once from SummaryTableHTML-Constructor: using the Summary-HTML-Signature
            //
            // USES: Messager.assertFailHTML() (JavaDocHTMLParseException)

            final EnumConstant ec = SignatureParse.parseECSignature
                (Util.textNodesString(fileVec, signature), jscf, this);

            // ParsedFile (parent-class) "addEnumConstant" (it's a one-liner, no Messager)
            addEnumConstant(ec);

            return new ReflHTML<EnumConstant>(
                ec, ecDetail, fileVec, Entity.ENUM_CONSTANT,
                getDetailID(fileVec, ecDetail, ec),
                this.isInner ? this.srcAsHTMLFileURL : null
            );
        };

        l = Details.sectionAllDetailsDP(fileVec, Entity.ENUM_CONSTANT);

        this.allECDetails = new ReadOnlyArrayList<>(l, getEC, l.size());


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Parse the Java Doc HTML "Annotation-Element Details".  Add to the internal Vectors.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        Function<DotPair, ReflHTML<AnnotationElem>> getAE = (DotPair aeDetail) ->
        {
            // Retrieve the signature of the annotation-element from the Java Doc HTML
            final DotPair signature = TagNodeFindInclusive.first
                (fileVec, aeDetail.start, aeDetail.end, "pre");

            if (signature == null) Messager.assertFailHTML
                ("Detail Section does not appear to have a Signature <PRE>", null);

            // SignatureParse.parseAESignature: is called twice:
            //  Once from JavaDocHTMLFile-Constructor: using the Detail-HTML-Signature
            //  Once from SummaryTableHTML-Constructor: using the Summary-HTML-Signature
            //
            // USES: Messager.assertFailHTML() (JavaDocHTMLParseException)

            final AnnotationElem ae = SignatureParse.parseAESignature
                (Util.textNodesString(fileVec, signature), jscf, this);

            // ParsedFile (parent-class) "addAnnotationElem" (it's a one-liner, no Messager)
            addAnnotationElem(ae);

            return new ReflHTML<AnnotationElem>(
                ae, aeDetail, fileVec, Entity.ANNOTATION_ELEM,
                getDetailID(fileVec, aeDetail, ae),
                this.isInner ? this.srcAsHTMLFileURL : null
            );
        };

        l = Details.sectionAllDetailsDP(fileVec, Entity.ANNOTATION_ELEM);

        this.allAEDetails = new ReadOnlyArrayList<>(l, getAE, l.size());


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


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

        RetN r = SummaryTableHTML.parseAllSummaryTables(fileVec, jscf, this);

        this.methodSummaryTable         = r.GET(1);
        this.fieldSummaryTable          = r.GET(2);
        this.constructorSummaryTable    = r.GET(3);
        this.ecSummaryTable             = r.GET(4);
        this.oaeSummaryTable            = r.GET(5);
        this.raeSummaryTable            = r.GET(6);
        this.ntSummaryTable             = r.GET(7);

        @SuppressWarnings("rawtypes")
        Stream.Builder<SummaryTableHTML> b = Stream.builder();
        
        if (methodSummaryTable != null)         b.accept(methodSummaryTable);
        if (fieldSummaryTable != null)          b.accept(fieldSummaryTable);
        if (constructorSummaryTable != null)    b.accept(constructorSummaryTable);
        if (ecSummaryTable != null)             b.accept(ecSummaryTable);
        if (oaeSummaryTable != null)            b.accept(oaeSummaryTable);
        if (raeSummaryTable != null)            b.accept(raeSummaryTable);
        if (ntSummaryTable != null)             b.accept(ntSummaryTable);

        allNonNullSummaryTables = b.build().collect(Collectors.toCollection(Vector::new));
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Retrieve a Detail CSS ID
    // ********************************************************************************************
    // ********************************************************************************************


    // This just extracts the little HTML ID for the detail-element, This is used by the
    // NavButton class
    //
    // NOTE: The HTML for an Annotation-Element (StaticFunction: "Excuses", "Excused")
    //       is every-so-slightly different.  The <A ID=..> is AFTER the element

    private static String getDetailID
        (Vector<HTMLNode> fileVec, DotPair detailLoc, Declaration d)
    {
        // Usually this works, except for annotations (look before the top/start of the loc)
        DotPair anchorLocation = InnerTagFindInclusive.last
            (fileVec, detailLoc.start - 20, detailLoc.start, "a", "id");

        // If this is an AnnotationElement, ==> Look in ahead, (after the start), rather
        // than behind, which is what was just done.

        if (anchorLocation == null) if (d instanceof AnnotationElem)
            anchorLocation = InnerTagFindInclusive.first
                (fileVec, detailLoc.start, detailLoc.start + 20, "a", "id");

        // Since this error has never happened (except with AnnotationElements), we should
        // presume that it will never happen, and if it does, an informative error message
        // is printed.  The Jump-Foward and Jump-Backward Navigation-Buttons help the UI a lot.

        if (anchorLocation == null) Messager.assertFailHTML
            ("No Anchor with ID Attribute Found for this Detail Element", d.signature);

        /*
        // Make sure that there is a small Comment with a white-space body in it.  That's the
        // best effort at checking / making sure this is the right <A ID>...
        //
        // NOTE: This has been eliminated, but I'm not exactly sure why.

        CommentNode c       = null;
        boolean     found   = false;

        for (int i = (anchorLocation.start + 1); i < anchorLocation.end; i++)

            if ((c = fileVec.elementAt(i).ifCommentNode()) != null)
                if (c.body.trim().length() == 0)
                    { found=true; break; }

        if (! found) Messager.assertFailHTML
            ("Anchor with ID does not have <!-- -->", d.signature);
        */

        // Get the TagNode
        TagNode tn = (TagNode) fileVec.elementAt(anchorLocation.start);

        // The last sanity check is that the Anchor *DOES NOT* have an HREF=... (which almost
        // all <A> Anchor Tags usually do).  Except when used for these purposes, they are useless
        // with an HREF=... Attribute
        //
        // If this one has an HREF=... presume it is the wrong one, and complain...

        if (tn.has("href")) Messager.assertFailHTML
            ("Anchor with ID also has HREF=... Attribute for this Detail Element", d.signature);

        return tn.AV("id");
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // 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 /* Made Public With The Big-Move, was Package-Private */
    Ret2<TreeSet<String>, TreeSet<String>> allIDsAndHREFs()
    {
        TreeSet<String> allIDs      = new TreeSet<>();
        TreeSet<String> allHREFs    = new TreeSet<>();
        TagNode tn;

        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);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // simple features exported by this class.
    // ********************************************************************************************
    // ********************************************************************************************


    // 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.assertFailGeneralPurpose
            ("For some odd reason, the updatedFileVec has not been set", null);

        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.assertFailGeneralPurpose
            ("For some odd reason, the updatedFileVec has not been set", null);

        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.updatedFileVec = ReplaceNodes.r(fileVec, replaceables, false).a;
    }


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