package Torello.JavaDoc;

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

import Torello.Java.*;
import Torello.Java.Additional.*;

import static Torello.Java.C.*;

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

import Torello.Java.ReadOnly.ReadOnlyList;

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

import java.util.function.Function;

/**
 * This class stores the HTML for a Summary-Table - which is the table at the top of a Java Doc
 * Page listing all of one type of entities present in the CIET/Type.  
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=PROG_MOD_HTML>
 * <EMBED CLASS='external-html' DATA-FILE-ID=SUMM_TABLE_HTML>
 * 
 * @param <ENTITY> This will take one of six type's: {@link Method}, {@link Constructor},
 * {@link Field}, {@link EnumConstant}, {@link AnnotationElem} or {@link NestedType}.   The HTML
 * contained by this class correspond directly to the HTML contained by a Summary-Table of one of
 * section of one of these Entities / Members.
 */
@JDHeaderBackgroundImg(EmbedTagFileID="REFLECTION_HTML_CLASS")
public class SummaryTableHTML<ENTITY extends Declaration>
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected 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).

    private static final Where_Am_I WHERE_AM_I = JDUUserAPI.SummaryTableHTML;


    // ********************************************************************************************
    // ********************************************************************************************
    // Summary-Table Header-Row Titles
    // ********************************************************************************************
    // ********************************************************************************************


    // For the other "Entity Kinds":
    // 
    //  Entity.FIELD:           3 columns   (Modifier/Type, Name & Description)
    //  Entity.METHOD:          3 columns   (Modifier/Type, Name & Description)
    //  Entity.ANNOTATION_ELEM: 3 columns   (Modifier/Type, Name & Description)
    //  Entity.INNER_CLASS:     3 columns   (Modifier/Type, Name & Description)
    // 
    //  Entity.ENUM_CONSTANT:   2 columns   (Name & Description)
    // 
    //  Entity.CONSTRUCTOR: VARIES - Sometimes "Modifier/Type" is included, and Sometimes not!
    // 
    // NOTE: Please see the FULL-EXTENDED-EXPLANATION BELOW (where this field is defined!)
 
    /**
     * Column-Names for the varies types of columns in a Summary-Table
     * 
     * <BR /><BR />For each of the "Entity Kinds", these are the standard column names which are
     * present inside of a typical Java-Doc Summary-Table.  Note that, generally, each of these
     * "Entities" have very similar (if not, identical) Column-Names.  Only the last two entries in
     * this table differ at all:
     * 
     * <BR /><BR /><TABLE ID=Col-Names-Table CLASS=JDBriefTable>
     * <TR><TH>Summary-Kind</TH><TH>Columns</TH></TR>
     * <TR>
     *      <TD>{@link Entity#FIELD}:</TD>
     *      <TD>3 columns (Modifier/Type, Field &amp; Description)</TD>
     * </TR>
     * <TR>
     *      <TD>{@link Entity#METHOD}:</TD>
     *      <TD>3 columns (Modifier/Type, Method &amp; Description)</TD>
     * </TR>
     * <TR>
     *      <TD>{@link Entity#ANNOTATION_ELEM}:</TD>
     *      <TD>3 columns (Modifier/Type, Required-Element or Optional-Element &amp;
     *          Description)</TD>
     * </TR>
     * <TR>
     *      <TD>{@link Entity#INNER_CLASS}:</TD>
     *      <TD>3 columns   (Modifier, Class &amp; Description)</TD>
     * </TR>
     * 
     * <TR><TD COLSPAN=2>&nbsp;</TD></TR>
     * 
     * <TR>
     *      <TD>{@link Entity#ENUM_CONSTANT}:</TD>
     *      <TD>2 columns (Name &amp; Description)</TD>
     * </TR>
     * 
     * <TR><TD COLSPAN=2>&nbsp;</TD></TR>
     * 
     * <TR>
     *      <TD>{@link Entity#CONSTRUCTOR}:</TD>
     *      <TD> <B STYLE='color: red;'>VARIES</B>
     *           Sometimes "Modifier/Type" is included, and Sometimes not!
     *      </TD>
     * </TR>
     * </TABLE>
     */
    public enum ColNames
    {
        Method          ("Method"),
        Field           ("Field"),
        Constructor     ("Constructor"),
        EnumConstant    ("Enum Constant"),
        OptionalElement ("Optional Element"),
        RequiredElement ("Required Element"),
        Interface       ("Interface"),
        Class           ("Class"),

        Modifier        ("Modifier"),
        ModifierType    ("Modifier and Type"),
        Description     ("Description");

        public final String colName;

        private static final TreeMap<String, ColNames> namesTM = new TreeMap<>();

        static 
        {
            ColNames.namesTM.put(ColNames.Method.colName,           ColNames.Method);
            ColNames.namesTM.put(ColNames.Field.colName,            ColNames.Field);
            ColNames.namesTM.put(ColNames.Constructor.colName,      ColNames.Constructor);
            ColNames.namesTM.put(ColNames.EnumConstant.colName,     ColNames.EnumConstant);
            ColNames.namesTM.put(ColNames.OptionalElement.colName,  ColNames.OptionalElement);
            ColNames.namesTM.put(ColNames.RequiredElement.colName,  ColNames.RequiredElement);
            ColNames.namesTM.put(ColNames.Interface.colName,        ColNames.Interface);
            ColNames.namesTM.put(ColNames.Class.colName,            ColNames.Class);
            ColNames.namesTM.put(ColNames.Modifier.colName,         ColNames.Modifier);
            ColNames.namesTM.put(ColNames.ModifierType.colName,     ColNames.ModifierType);
            ColNames.namesTM.put(ColNames.Description.colName,      ColNames.Description);
        }

        private ColNames(final String colName)
        { this.colName = colName; }

        public static ColNames findCol(final String colName)
        { return ColNames.namesTM.get(colName); }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Simple Constructor
    // ********************************************************************************************
    // ********************************************************************************************


    public SummaryTableHTML(
            final TagNodeIndex              openingCinzelH3,
            final Entity                    tableType,
            final TagNodeIndex              tableOpen,
            final TagNodeIndex              tableClose,
            final JavaDocHTMLFile           jdhf,
            final Vector<HTMLNode>          headerRow,
            final Vector<Vector<HTMLNode>>  tableRows,
            final Vector<ENTITY>            rowEntities,
            final boolean                   retainRemoveDescriptions,
            final int                       numColumnsInOriginalTable,
            final ReadOnlyList<ColNames>    initialColumns,
            final ReadOnlyList<ColNames>    postProcessedColumns
        )
    {
        this.openingCinzelH3            = openingCinzelH3;
        this.tableType                  = tableType;
        this.tableOpen                  = tableOpen;
        this.tableClose                 = tableClose;
        this.jdhf                       = jdhf;
        this.headerRow                  = headerRow;
        this.tableRows                  = tableRows;
        this.rowEntities                = rowEntities;
        this.retainRemoveDescriptions   = retainRemoveDescriptions;
        this.numColumnsInOriginalTable  = numColumnsInOriginalTable;
        this.initialColumns             = initialColumns;
        this.postProcessedColumns       = postProcessedColumns;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // The Main Fields of this Class.
    // ********************************************************************************************
    // ********************************************************************************************


    /** Indicates what type of Summary-Table this is (Methods, Fields, Constructor's, etc). */
    public final Entity tableType;

    /** The opening {@code <TABLE>} tag, for a Summary-Section Table */
    public final TagNodeIndex tableOpen;

    /** The closing {@code </TABLE>} tag, for a Summary-Section Table */
    public final TagNodeIndex tableClose;

    /**
     * This is just a <B>"Back-Pointer"</B> to the {@link JavaDocHTMLFile} that contains this
     * Summary-Table
     */
    public final JavaDocHTMLFile jdhf;


    // There is an *EXTENDED* explanation of this newly added field in the Constructor
    // above - at the top of this class.  Added 03/2025 (March, during "Java One Conference")

    /**
     * This {@code final} / constant {@code boolean}-Flag is simply provided to indicate whether
     * or not the Upgrader-Logic has removed the Summary-Description Setences from the Table-Rows 
     * of this table.
     * 
     * <BR /><BR />The default behavior for this Upgrader-Tool is to remove all Summary-Sentences 
     * for every type / kind of Entity-Summary Table on each Java-Doc Web-Page.  Note, though, 
     * that this "Default Behavior" is easily by-passed by providing a simple {@code Predicate} to 
     * the Upgrader-Tool's Configuration-Class {@link Upgrade#setSummaryRemoveFilter(Predicate)}.
     * 
     * <BR /><BR />It shall be "an eventuality" to provide a "Fine Grained Control" over this 
     * removal Descision-Predicate so that a user may specify which Entity Summary-Tables retain 
     * their Summary-Sentences, and which shall have them stripped or removed from their Web-Page 
     * UI's.
     * 
     * <BR /><BR />As of March of 2025, this feature is not available yet.  Either <B>ALL</B> 
     * Summary-Sentences must be removed from <B>EVERY</B> Summary-Table located at the top of 
     * a Java-Doc Web-Page, <B STYLE='color: red;'><I>*OR*</I></B> none of them shall be removed.
     * 
     * <BR /><BR />Again, see the Configuration-Setting Method in class <B>{@link Upgrade}</B> to 
     * read more about this feature:
     * <B>{@link Upgrade#setSummaryRemoveFilter(Predicate) setSummaryRemoveFilter}</B>
     */
    public final boolean retainRemoveDescriptions;


    // The Red Banner-H3, with Cinzel-Font that says "Method Summary" or "Field Summary"
    // Package-Private *AND* final
    //
    // EXPORTED BY THE EXPORT_PORTAL, Used in: CSSTagsTopAndSumm

    final TagNodeIndex openingCinzelH3;


    // The First Row / Title Row of a Summary-Section Table
    // Package-Private *AND* final
    //
    // EXPORTED BY THE EXPORT_PORTAL, Used in: CleanSummaries and RearrangeEntitySummaries

    final Vector<HTMLNode> headerRow;


    // The HTML Row's of every row in the table, except the initial header-row,
    // and this is "Package-Visible".  There is a getter below.

    private Vector<Vector<HTMLNode>> tableRows;


    // The actual Reflection-Declaration for each of these rows.  For Inner-Classes the type
    // parameter 'ENTITY' is String.  For the other 5 it is their 'Declaration' inheriting class.
    // This is also Package-Visible only.

    private Vector<ENTITY> rowEntities;


    // At least in JDK-11, The **CONSTRUCTOR-TABLE** that was generated for the following classes,
    // had the following number of columns:
    // 
    // * Torello.HTML.TagNode - 2 Columns (Signature & Description)
    // * Torello.HTML.HTMLNode - 3 Columns (Modifier/Type, Signature & Description)

    /**
     * The following integer should be an accurate count on the **ORIGINAL** number of columns that
     * were created by 'javadoc' when the original HTML-Table was output.  For every one of the 
     * Summary-Tables, this is an easy computation, except, apparently for Constructors...
     */
    public final int numColumnsInOriginalTable;

    /**
     * The column names present in this Summary-HTML Table.  To view the JDK-Standard Columns 
     * which are present in a Java-Doc Summary-Table, please review the contents of 
     * <B><A HREF=#Col-Names-Table>this table</A></B>
     */
    public final ReadOnlyList<ColNames> initialColumns;

    /**
     * One of the commonly features of the Upgrader-Tool is to remove the Summary-Sentence 
     * Description-Column from the Entities in a Java-Doc Web-Page.  When this occurs, the
     * {@link ColNames#Description} column is removed.
     * 
     * <BR /><BR />When the {@code Description}-Column of a Summary-Table has been removed, this
     * list will contain one fewer element than the contents of the list {@link #initialColumns}
     */
    public final ReadOnlyList<ColNames> postProcessedColumns;


    // ********************************************************************************************
    // ********************************************************************************************
    // Table-Rows: Number of Rows
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Retrieve the total number of Table-Rows in the Summary-Table.
     * @return The number of HTML {@code <TR>...</TR>} elements in this Summary-Table
     */
    public int numRows() { return tableRows.size(); }

    /**
     * Retrieve the number of Table-Rows that have Title-Bars in this Summary-Table.
     * @return The number of HTML {@code <TR>...</TR>} elements in this Summary-Table which contain
     * Title-Bars, rather than entity/member signature URL-Links.
     */
    public int numTitleBarRows()
    {
        int counter = 0;
        for (ENTITY e : rowEntities) if (e == null) counter++;
        return counter;
    }

    /**
     * Retrieve the number of Entity/Member Signatures which occupy a Table-Row in this
     * Summary-Table
     * @return The number of HTML {@code <TR>...</TR>} elements in this Summary-Table which contain
     * entity/member signature URL-Links.
     */
    public int numSignatureRows()
    {
        int counter = 0;
        for (ENTITY e : rowEntities) if (e != null) counter++;
        return counter;
    }

    /**
     * This method simply scans the internal {@code 'rowEntities'} list / {@code Vector} to check
     * each element to determine if it contains one of the User-Provided descriptive orange-banner
     * titles, or contains an actual Entity/Member {@code URL}-Link.
     * 
     * <BR /><BR />The members of a type are listed in enum {@link Entity}.  JavaDoc Upgrader
     * refers to Class or Interface members as "Entities."  A Summary-Table on a Java-Doc Page -
     * <I>after a Summary HTML Table Sort - will have some HTML Table-Rows with Members / Entities,
     * and some Rows having orange-colored horizontal banner Title-Bars</I>.
     * 
     * <BR /><BR />When the HTML Table-Row ({@code '<TR> ... </TR>'}) has an {@code <A>-URL}
     * link to one of the members of the class (a method, field, constructor, etc...), the returned
     * array will contain {@code TRUE} for that index.  When the row contains a Title-Bar, the
     * array-index for that row will contain {@code FALSE}.
     * 
     * @return A {@code boolean[]}-Array whose length is equal to the number of rows in this
     * Summary-Table, and whose {@code boolean} values are {@code TRUE} if the Table-Row contains
     * a {@code URL}-Link to one of the entities (Methods, Constructors, Fields, etc...) of the
     * CIET / Type.
     */
    public boolean[] memberRows()
    {
        boolean[]   ret = new boolean[rowEntities.size()];
        int         i   = 0;

        for (ENTITY e : rowEntities) ret[i++] = (e != null);

        return ret;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Table-Rows: Getters by index / row number
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * If you have a chosen / desired HTML Summary-Table Row (with a selected summary
     * element/item) - you may pass the table-row index of that item to retrieve the
     * {@code rowIndex}<SUP>th</SUP> instance of {@link ReflHTML} that contains the
     * Detail-Element Parsed-HTML corresponding to that row.
     * 
     * @param rowIndex Any one of the Summary-HTML Table-Rows.  Each Summary-Table Row is either a
     * Title-Bar {@code <TR>} / Row, or it is a {@link Entity} / Member Table {@code <TR>} Row.  
     * {@link Entity}-Rows are HTML {@code <TR>}-Rows that simply contain an Anchor {@code <A>} 
     * link to one of this CIET's Members / Entites.
     * 
     * <BR /><BR />For example, if {@code 'this'} Summary-Table instance were for Method's, and the
     * Table-Row index for the {@code 'toString()'} Method were passed to parameter
     * {@code 'rowIndex'}, this method would return the {@link ReflHTML} for the {@code toString}
     * Method.
     * 
     * <BR /><BR />The returned {@link ReflHTML} instance would contain all of the parsed
     * HTML information for the method {@code toString}.
     * 
     * <BR /><BR />If this parameter points to a Table-Row that contains an Orange-Colored 
     * Title-Bar (generated by the Summary-Sorters), rather than an Entity/Member Signature,
     * then this method will return null.
     * 
     * @return The parsed detailed HTML explanation for the Summary-Table item chosen by parameter
     * {@code 'rowIndex'}.
     *
     * <BR /><BR /><B STYLE='color: red;'>IMPORTANT:</B> When parameter {@code 'rowIndex'} is
     * passed a value that <I>is not out of bounds for the {@code 'rowEntities'} vector</I>,
     * but is a row that contains an orange Title-Bar, in such cases there is no detail-member
     * (no instance of {@code ReflHTML}) to return.  When a {@code 'rowIndex'} for a Title-Bar
     * row is passed, this method will return null, gracefully.
     * 
     * @throws IndexOutOfBoundsException If {@code rowIndex} is not properly chosen as per the
     * number of rows in the table.  If there are {@code '10'} rows-items in this table, then the
     * {@code rowIndex} parameter should be between {@code '0'} and {@code '9'}.
     */
    @SuppressWarnings("unchecked")  // NOTE: The cast on the 'return' line.  It *IS* checked
                                    // but the compiler isn't smart enough to see that!
    public ReflHTML<ENTITY> getRowDetail(int rowIndex)
    {
        // Look up the "rowIndex" row in the "rowEntities" vector which just contains the list of
        // rows on this Summary HTML Table.  The "ENTITY" is one of the 5 reflected-HTML classes
        // used by this package (Method, Field, Constructor etc...)

        ENTITY selectedEntityMember = rowEntities.elementAt(rowIndex);

        // Some rows contain only title information.  In such cases, there is no detail-element
        // associated with this table-row.  It is just a title!!  When the user has passed a title
        // row to parameter 'rowIndex', just return null.

        if (selectedEntityMember == null) return null;

        // Use JavaDocHTMLFile.findReflHTML(int, Class) to get the ReflHTML needed.
        // NOTE: this.tableType.upgraderReflectionClass <==> ENTITY.class

        return (ReflHTML<ENTITY>) jdhf.findReflHTML
            (selectedEntityMember.id, this.tableType.upgraderReflectionClass);
    }

    /**
     * Retrieve the {@code i}<SUP>th</SUP> HTML {@code <TR>} (row) from  {@code this} Summary-Table
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>{@link Entity}-Member Rows:</B>
     * 
     * <BR />If {@code 'rowIndex'} is pointing to one of the entities / members of the class (such
     * as a Field, Method or Constructor etc...), then the HTML {@code <A ...>} Anchor-{@code URL}
     * for that {@link Entity} is returned.  The returned HTML-{@code Vector} will contain
     * everything between the {@code <TR>} and the {@code </TR>} for that Table-Row.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Title-Bar Rows:</B>
     *  
     * <BR />Not every row in a Summary-Table is guaranteed to have an Entity/Member Signature
     * instance.  Bear in mind that whenever a user sorts Summary-Table Row's into Categories or
     * Sections, then any &amp; all Section / Category Title-Bar Rows will be present in the
     * Summary-Table HTML.
     * 
     * <BR /><BR />Title-Bar rows are the horizontal, fading-orange bars that line the Table of
     * Contents (Summary-Tables).  These orange-colored banners have a brief, one-sentence
     * description for a small group of methods, fields or constructors.
     * 
     * <BR /><BR />If parameter {@code 'rowIndex'} is pointing to a Title-Bar, then the parsed
     * HTML-{@code Vector} for that Title-Bar is returned. 
     * 
     * <BR /><BR />In all other cases, the entity/member Signature is returned as a  result from a
     * call to this method.
     * 
     * @param rowIndex The row number to retrieve
     * @return All HTML between the {@code <TR>} and the {@code </TR>} for one table-summary row.
     * 
     * @throws IndexOutOfBoundsException If {@code 'rowIndex'} is not within the bounds of the list
     * of rows
     */
    public Vector<HTMLNode> getRowHTML(int rowIndex)
    { return tableRows.elementAt(rowIndex); }

    /**
     * Retrieve the {@code i}<SUP>th</SUP> entity.  The returned instance will be one of the six
     * subclasses of class {@code Declaration}, as decided by the type-parameter {@code ENTITY}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>{@link Entity}-Member Rows:</B>
     * 
     * <BR />If {@code 'rowIndex'} is pointing to one of the entities / members of the class (such
     * as a Field, Method or Constructor etc...), then the reflected-class for that {@link Method},
     * {@link Field}, {@link Constructor} is returned.  If {@code 'this'} Summary-Table has
     * Generic-Type {@code SummaryTableHTML<Field>}, then the returned {@link ENTITY} will be a
     * {@link Field} class instance.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Title-Bar Rows:</B>
     * 
     * <BR />Not every row in a Summary-Table is guaranteed to have an Entity/Member Signature
     * instance.  Bear in mind that whenever a user sorts Summary-Table Row's into Categories or
     * Sections, then any &amp; all Section / Category Title-Bar Rows will be present in the
     * Summary-Table HTML.
     * 
     * <BR /><BR />Title-Bar rows are the horizontal, fading-orange bars that line the Table of
     * Contents (Summary-Tables).  These orange-colored banners have a brief, one-sentence
     * description for a small group of methods, fields or constructors.
     * 
     * <BR /><BR />If parameter {@code 'rowIndex'} is pointing to a Title-Bar, <I>then this method
     * shall default and return null!</I>
     * 
     * @param rowIndex The entity-number (row-number) to retrieve from {@code this} Summary-Table.
     * 
     * @return The refected-information for one Summary-Table row.
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ENTITY_GP>
     * 
     * @throws IndexOutOfBoundsException If {@code 'rowIndex'} is not within the bounds of the list
     * of rows
     */
    public ENTITY getRowEntity(int rowIndex)
    { return rowEntities.elementAt(rowIndex); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Table-Rows: Getters by index / row number, USING Ret2's for more complete information.
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Retrieve <B STYLE='color: red;'><I>both</I></B> the row-HTML
     * <B STYLE='color: red;'><I>and</I></B> the reflected-entity information for the
     * {@code i}<SUP>th</SUP> row in {@code this} Summary-Table.
     * 
     * <BR /><BR />Not every row in a Summary-Table is guaranteed to have a Member Signature.  
     * When Summary-Table's are sorted into categories or sections, then a Summary-Table may also
     * have a Title-Bar row.  It is (hopefully) obvious that a Title-Bar row would not contain an
     * associated {@code 'ENTITY'} (Method, Field, Constructor, etc...).
     * 
     * @param rowIndex The entity-number / row-number to retrieve from {@code this} Summary-Table.
     * 
     * @return An instance of 
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_RET2_ENTITY_VEC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ENTITY_GP>
     * 
     * @throws IndexOutOfBoundsException If {@code 'rowIndex'} is not within the bounds of the list
     * of rows
     */
    public Ret2<ENTITY, Vector<HTMLNode>> getRowEntityAndHTML(int rowIndex)
    { return new Ret2<>(rowEntities.elementAt(rowIndex), tableRows.elementAt(rowIndex)); }

    /**
     * Retrieve <B STYLE='color: red;'><I>both</I></B> the row-HTML
     * <B STYLE='color: red;'><I>and</I></B> and the corresponding / matching instance of 
     * {@link ReflHTML} for the {@code i}<SUP>th</SUP> row in {@code this} Summary-Table
     * 
     * <BR /><BR />Not every row in a Summary-Table is guaranteed to have a Member Signature.  
     * When Summary-Table's are sorted into categories or sections, then a Summary-Table may also
     * have a Title-Bar row.  It is (hopefully) obvious that a Title-Bar row would not contain an
     * associated {@code 'ReflHTML'} HTML Data-Object either.
     * 
     * @param rowIndex The entity-number / row-number to retrieve from {@code this} Summary-Table.
     * 
     * @return An instance of 
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_RET2_REFL_VEC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ENTITY_GP>
     * 
     * @throws IndexOutOfBoundsException If {@code i} is not within the bounds of the list of rows
     * @see #getRowDetail(int)
     */
    public Ret2<ReflHTML<ENTITY>, Vector<HTMLNode>> getRowDetailAndHTML(int rowIndex)
    { return new Ret2<>(getRowDetail(rowIndex), tableRows.elementAt(rowIndex)); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Table-Rows: Stream's
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * A {@code Stream} that contains {@code this} Summary-Table's rows, as Vectorized-HTML
     *
     * @return A stream of Vectorized-HTML Table-Rows for {@code this} Summary-Table.
     *
     * <BR /><BR />Note that a Java {@code Stream} is easily converted into just about any
     * necessary data-type, as explained in the table below:
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=STREAM_CONVERT_T>
     */
    public Stream<Vector<HTMLNode>> rowHTMLStream() { return tableRows.stream(); }

    /**
     * A {@code Stream} that contains all Summary-Table row-entities, as instances of the reflected
     * information class {@code ENTITY} (this class' sole type-parameter).
     * 
     * <BR /><BR />Generic Type-Parameter {@code ENTITY} will be one of the six concrete subclasses
     * of class {@link Declaration}.
     * 
     * @return A stream of entities contained by {@code this} Summary-Table.
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ENTITY_GP>
     *
     * <BR /><BR />Note that a Java {@code Stream} is easily converted into just about any
     * necessary data-type, as explained in the table below:
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=STREAM_CONVERT_T>
     */
    public Stream<ENTITY> rowEntityStream() { return rowEntities.stream(); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Table-Rows: Entire Table
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Retrieve a {@code Stream} that contains <B><I>every</I></B> Summary-Table Row.
     * 
     * <BR /><BR />The specific contents of this {@code Stream} are instances of {@link Ret2},
     * which contain <B STYLE='color: red;'><I>both</I></B> the reflected-entity information
     * (instance of Type-Parameter {@code ENTITY}) <B STYLE='color: red;'><I>and</I></B> the
     * Vectorized-HTML Table-Row, as well.
     * 
     * @return A Java Stream containing instances of 
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_RET2_ENTITY_VEC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ENTITY_GP>
     */
    public Stream<Ret2<ENTITY, Vector<HTMLNode>>> entityAndHTMLStream()
    {
        final Stream.Builder<Ret2<ENTITY, Vector<HTMLNode>>> b = Stream.builder();

        for (int rowIndex=0; rowIndex < rowEntities.size(); rowIndex++)
            b.accept(new Ret2<>(rowEntities.elementAt(rowIndex), tableRows.elementAt(rowIndex)));

        return b.build();
    }

    /**
     * Retrieve the entire list of Table-Rows in this HTML Summary-Table into a {@code Vector}.
     * 
     * @return A Java Stream containing instances of 
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_RET2_REFL_VEC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ENTITY_GP>
     */
    public Stream<Ret2<ReflHTML<ENTITY>, Vector<HTMLNode>>> reflAndHTMLStream()
    {
        final Stream.Builder<Ret2<ReflHTML<ENTITY>, Vector<HTMLNode>>> b = Stream.builder();

        for (int rowIndex=0; rowIndex < rowEntities.size(); rowIndex++)
            b.accept(new Ret2<>(getRowDetail(rowIndex), tableRows.elementAt(rowIndex)));

        return b.build();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Table-Rows: FIND-METHODS
    // ********************************************************************************************
    // ********************************************************************************************


    private void CHECK_IS_CALLABLE()
    {
        if (this.tableType.isCallable()) return;

        final String kind = this.tableType.upgraderReflectionClass.getSimpleName();

        throw new UpgradeException(
            "This 'find' method may only be used on SummaryTableHTML instances for Method or " +
                "Constructor Summary Tables.\n" +
            "This is a SummaryTableHTML<" + kind + "> instance, and this find method may not be " +
                "used.\n" +
            "CIET/Type Member Names for " + kind + "'s cannot be overloaded, so therefore you " +
                "should use the simple/standard find(String) method instead."
        );
    }

    private void CHECK_NUM_PARAMS(final int numParams)
    {
        if (numParams < 1) throw new IllegalArgumentException(
            "This find method will only search for Callable's (Method's and Constructor's) that" +
            "accept at least 1 parameter.  You have passed [" + numParams + "] to parameter " +
            "'numParams'.  This is not allowed." +
            ((numParams == 0)
                ? "\nWhen searching for a zero-argument Callable, use " +
                    "SummaryTableHTML.find(String)"
                : "")
        );
    }

    /**
     * Retrieves the first Entity/Member whose name matches {@code name}.  When searching a
     * {@code SummaryTableHTML<Field>}, {@code SummaryTableHTML<EnumConstant>} or 
     * {@code SummaryTableHTML<AnnotationElem>}, the name of the entity/member will uniquely
     * identify it amongst the others in the table.
     * 
     * <BR /><BR />Due to Java's function overloading, there may be many cases where a
     * member {@code 'name'} is not sufficient to uniquely identify it (for Method's and 
     * Constructor's).  In such cases (e.g. overloaded methods) this method simply return the index
     * of the first match it finds.
     * 
     * @param name The name of the entity / member, as a {@code java.lang.String}
     * 
     * @return The index of the (first) HTML Table-Row that contains the specified {@link Entity}.
     * If this Summary-Table does not have any member-signatures by that {@code 'name'}, then
     * {@code -1} will be returned.
     */
    public int find(String name)
    {
        ENTITY e = null;

        for (int i=0; i < rowEntities.size(); i++)

            // After a sort, all Title-Rows have null Row-Entity elements
            // Make sure to skip any row completely if it is a Title-Row

            if ((e = rowEntities.elementAt(i)) != null)
                if (e.name.equals(name))
                    return i;

        return -1;
    }

    /**
     * Retrieves the first Entity/Member whose name matches {@code 'methodOrCtorName'}.
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ONLY_CALBL>
     * 
     * @param methodOrCtorName <EMBED CLASS='external-html' DATA-FILE-ID=ST_M_OR_C_NAME>
     * 
     * @return The index of the first HTML Table-Row that matches this specified name.  If this
     * Summary-Table does not have any (Method or Constructor) Member-Signatures by that name,
     * then {@code -1} is returned.
     */
    public int findFirst(String methodOrCtorName)
    {
        CHECK_IS_CALLABLE();

        ENTITY e = null;

        for (int i=0; i < rowEntities.size(); i++)

            // After a sort, all Title-Rows have null Row-Entity elements
            // Make sure to skip any row completely if it is a Title-Row

            if ((e = rowEntities.elementAt(i)) != null)
                if (e.name.equals(methodOrCtorName))
                    return i;

        return -1;
    }

    /**
     * Retrieves the first Entity/Member whose name matches {@code 'methodOrCtorName'}, 
     * and accepts {@code 'numParams'} parameters.
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ONLY_CALBL>
     * 
     * @param methodOrCtorName <EMBED CLASS='external-html' DATA-FILE-ID=ST_M_OR_C_NAME>
     * @throws IllegalArgumentException <EMBED CLASS='external-html' DATA-FILE-ID=ST_IAEX>
     * 
     * @return The index of the first HTML Table-Row that matches the provided specifications.  If
     * this Summary-Table does not have any Member-Signatures with that name and accepting the
     * specified number of parameters, then this method returns {@code -1}.
     */
    public int findFirst(String methodOrCtorName, int numParams)
    {
        CHECK_IS_CALLABLE();
        CHECK_NUM_PARAMS(numParams);

        for (int i=0; i < rowEntities.size(); i++)
        {
            final ENTITY e = rowEntities.elementAt(i);

            // After a sort, all Title-Rows have null Row-Entity elements
            // Make sure to skip any row completely if it is a Title-Row

            if (e == null) continue;

            if (e.name.equals(methodOrCtorName))
                if (((Callable) e).numParameters() == numParams)
                    return i;
        }

        return -1;
    }

    /**
     * Retrieves all Entities/Member Table-Row Indices whose name matches
     * {@code 'methodOrCtorName'}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ONLY_CALBL>
     * 
     * @param methodOrCtorName <EMBED CLASS='external-html' DATA-FILE-ID=ST_M_OR_C_NAME>
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=ST_FIND_ALL_RET>
     * 
     * <DIV CLASS=EXAMPLE>{@code
     * int[] tableRows = methodSummTable.findAll("someMethodName").toArray();
     * }</DIV>
     */
    public IntStream findAll(String methodOrCtorName)
    {
        CHECK_IS_CALLABLE();

        final IntStream.Builder b = IntStream.builder();

        ENTITY e = null;

        for (int i=0; i < rowEntities.size(); i++)

            // After a sort, all Title-Rows have null Row-Entity elements
            // Make sure to skip any row completely if it is a Title-Row

            if ((e = rowEntities.elementAt(i)) != null)
                if (e.name.equals(methodOrCtorName))
                    b.accept(i);

        return b.build();
    }

    /**
     * Retrieves the first Entity/Member Table-Row Index whose name matches
     * {@code 'methodOrCtorName'},  and accepts {@code 'numParams'} parameters.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=ST_ONLY_CALBL>
     * 
     * @param methodOrCtorName <EMBED CLASS='external-html' DATA-FILE-ID=ST_M_OR_C_NAME>
     * @param numParams <EMBED CLASS='external-html' DATA-FILE-ID=ST_NUM_PARAMS>
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=ST_FIND_ALL_RET>
     * 
     * <DIV CLASS=EXAMPLE>{@code
     * int[] tableRows = methodSummTable.findAll("someMethodName", 1).toArray();
     * }</DIV>
     * 
     * @throws IllegalArgumentException <EMBED CLASS='external-html' DATA-FILE-ID=ST_IAEX>
     */
    public IntStream findAll(String methodOrCtorName, int numParams)
    {
        CHECK_IS_CALLABLE();
        CHECK_NUM_PARAMS(numParams);

        final IntStream.Builder b = IntStream.builder();

        for (int i=0; i < rowEntities.size(); i++)
        {
            final ENTITY e = rowEntities.elementAt(i);

            // After a sort, all Title-Rows have null Row-Entity elements
            // Make sure to skip any row completely if it is a Title-Row

            if (e == null) continue;

            if (e.name.equals(methodOrCtorName))
                if (((Callable) e).numParameters() == numParams)
                    b.accept(i);
        }

        return b.build();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Package-Private Stuff
    // ********************************************************************************************
    // ********************************************************************************************


    // Package-Private: Only used in RearrangeEntitySummaries
    // EXPORTED BY THE EXPORT_PORTAL

    void setTableRows(Vector<Vector<HTMLNode>> tableRows, Vector<ENTITY> rowEntities)
    {
        this.tableRows      = tableRows;
        this.rowEntities    = rowEntities;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // REBUILD THE JAVADOC PAGE
    // ********************************************************************************************
    // ********************************************************************************************


    // Used in the method below
    private static final TextNode NEW_LINE = new TextNode("\n");

    // Method below too
    private static final Vector<Replaceable> EMPTY_VECTOR = new Vector<>();

    Vector<Replaceable> allReplaceables()
    {
        // There are summary-tables whose only contents are the "Inherited Entities".  When that
        // occurs, the 'tableOpen' and 'tableClose' NodeIndex-instances will be null.
        //
        // You still need to add the "Cinzel-H3" to the Banner that says "Method Summary" or
        // "Field Summary" (or whichever SummaryTable this is).  So, in this case, return a Vector
        // whose only contents are the TagNodeIndex Cinzel-H3 node.

        if (tableOpen == null)
        {
            Vector<Replaceable> cinzelOnlyVec = new Vector<>();
            cinzelOnlyVec.add(this.openingCinzelH3);
            return cinzelOnlyVec;
        }

        final Vector<HTMLNode>  newTable            = new Vector<>();
        final DotPair           oldTableLocation    = new DotPair(tableOpen.index, tableClose.index);

        newTable.add(tableOpen.n);
        newTable.add(NEW_LINE);
        newTable.addAll(headerRow);
        newTable.add(NEW_LINE);

        for (Vector<HTMLNode> row : tableRows)
        {
            newTable.addAll(row);
            newTable.add(NEW_LINE);
        }

        newTable.add(tableClose.n);
        newTable.add(NEW_LINE);

        final Vector<Replaceable> ret = new Vector<>();
        ret.add(openingCinzelH3);
        ret.add(Replaceable.create(oldTableLocation, newTable));

        return ret;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // 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()
    {
        // public final TagNodeIndex tableOpen;
        if (tableOpen != null) tableOpen.n = null;

        // public final TagNodeIndex tableClose;
        if (tableClose != null) tableClose.n = null;
    
        // final Vector<HTMLNode> headerRow;
        if (headerRow != null) headerRow.clear();

        // final TagNodeIndex openingCinzelH3;
        if (openingCinzelH3 != null) openingCinzelH3.n = null;
    
        // private Vector<Vector<HTMLNode>> tableRows = new Vector<>();
        if (tableRows != null)
        {
            for (Vector<HTMLNode> v : tableRows) if (v != null) v.clear();

            tableRows.clear();
            tableRows = null;
        }
    
        // private Vector<ENTITY> rowEntities = new Vector<>();
        if (rowEntities != null) { rowEntities.clear(); rowEntities = null; }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // DEBUG-PRINTING
    // ********************************************************************************************
    // ********************************************************************************************


    private static final String STARS =
        BYELLOW + "\n*****************************************\n" + RESET;

    /**
     * Prints an abbreviated-version of the contents of this instance, to a user-provided
     * {@code Appendable}.  If the HTML requires more than four lines of text, only the first four
     * lines are printed.
     * 
     * @param a This may be any Java Appendable.  If an {@code IOException} is thrown while writing
     * to this {@code Appendable}, it will be caught an wrapped in an
     * {@code IllegalArgumentException}, with the {@code IOException} set as the {@code cause}.
     * 
     * @throws IllegalArgumentException If {@code 'a'} throws an {@code IOException}
     * 
     * @see StrPrint#firstNLines(String, int)
     * @see Util#pageToString(Vector)
     * @see StrIndent#indent(String, int)
     */
    public void debugPrint(Appendable a)
    {
        try
        {
            if (tableType != null) a.append
                (BCYAN + "this.tableType: " + RESET + this.tableType.toString() + "\n");
            else
                a.append(BRED + "this.tableType is null" + RESET);

            if (tableOpen != null) a.append
                (BCYAN + "this.tableOpen: " + RESET + this.tableOpen.n.str + "\n");
            else
                a.append(BRED + "this.tableOpen is null" + RESET);

            if (tableClose != null) a.append
                (BCYAN + "this.tableClose: " + RESET + this.tableClose.n.str + "\n");
            else
                a.append(BRED + "this.tableClose is null" + RESET);

            if (openingCinzelH3 != null) a.append
                (BCYAN + "this.openingCinzelH3: " + RESET + this.openingCinzelH3.n.str + "\n");
            else
                a.append(BRED + "this.openingCinzelH3 is null" + RESET);

            if (headerRow != null) a.append(
                STARS + BCYAN + "this.headerRow:" + RESET + STARS +
                StrPrint.firstNLines(Util.pageToString(headerRow), 4) +
                '\n'
            );

            for (int i=0; i < tableRows.size(); i++)

                a.append(
                    BCYAN + "TABLE ROW " + (i+1) + RESET + '\n' +
                    BGREEN + "HTML:\n" + RESET +
                    StrIndent.indent
                        (Util.pageToString(tableRows.elementAt(i)).replace("\n", "\\n"), 4) +
                    '\n' +
                    BGREEN + "ENTITY:\n" + RESET +
                    StrIndent.indent
                        (rowEntities.elementAt(i).toString(PF.UNIX_COLORS | PF.JOW_INSTEAD), 4) +
                    '\n'
                );
        }

        catch (java.io.IOException ioe)
        {
            throw new IllegalArgumentException(
                ioe
            );
        }
    }

    
    /**
     * A really great way to view the contents of this class - <I>in just one page of text</I>.
     * 
     * @param numCharsWide The maximum line width to be printed to terminal.  This
     * number must be between 60 and 150, or else an exception shall throw.
     * 
     * @return The contents of this class-instance, as a {@code String}
     * 
     * @throws IllegalArgumentException If the parameter 'numCharsWide' was not passed a value 
     * within the aforementioned range.
     * 
     * @see StrPrint#printListAbbrev(Iterable, int, int, boolean, boolean, boolean)
     * @see StrPrint#printListAbbrev(Iterable, IntTFunction, int, int, boolean, boolean, boolean)
     */
    public String debugPrintDense(final int numCharsWide)
    {
        if ((numCharsWide < 60) || (numCharsWide > 150)) throw new IllegalArgumentException
            ("Parameter 'numCharsWide' wasn't passed a value between 60 and 150: " + numCharsWide);

        return
            "rowEntities.size(): " + rowEntities.size() + '\n' +
            "rowEntities Vector Contents:" + // '\n' is automatically added
                StrPrint.printListAbbrev(rowEntities, numCharsWide, 4, false, true, true) + '\n' +
            "tableRows.size(): " + tableRows.size() + '\n' +
            "tableRows Vector Contents:" + // '\n' is automatically added
                StrPrint.printListAbbrev(
                    tableRows,
                    (int i, Vector<HTMLNode> tableRow) -> Util.pageToString(tableRow),
                    numCharsWide, 4, false, true, true
                );
    }

    /**
     * Converts the contents of this class into a {@code String}
     * @return A Printable-{@code String}
     * @see #debugPrintDense(int)
     */
    public String toString()
    {
        final String oStr = (this.tableOpen == null)
            ? "null"
            : this.tableOpen.toString();

        final String cStr = (this.tableClose == null)
            ? "null"
            : this.tableClose.toString();

        final String hStr = (this.headerRow == null)
            ? "null"
            : StrPrint.abbrevEndRDSF(Util.pageToString(headerRow), 120, false);

        return
            "tableType:  " + tableType + '\n' +
            "tableOpen:  " + oStr + '\n' +
            "tableClose: " + cStr + '\n' +
            "headerRow:  " + hStr + '\n' +
            debugPrintDense(120);
    }
}