Class ReflHTML<ENTITY extends Declaration>

  • Type Parameters:
    ENTITY - This will take one of five type's: Method, Constructor, Field, EnumConstant, AnnotationElem. The html contained by this class must directly correspond to the HTMl contained by a detail section of one of these five entities.
    All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<ReflHTML>

    public class ReflHTML<ENTITY extends Declaration>
    extends java.lang.Object
    implements java.io.Serializable, java.lang.Comparable<ReflHTML>
    This class stores the HTML Detail-Descriptions retrieved from a Java Doc web-page 'Details Section', and simultaneously, holds the reflection-data extracted from the '.java' corresponding source-code files - facilitating all changes to a Java Doc Page deemed necessary.

    Reflection-HTML

    This class encapsulates the combination of Reflected Type Information, and the Java Doc HTML that was generated for that reflection. The type-parameter ENTITY should be one of the five NON-Abstract Reflection classes provided by this Upgrader A.P.I. These class can be retrieved from the class JavaDocHTMLFile, using one of it's getter methods.

    The way JavaDocHTMLFile can be retrieved is by registering a handler lambda-expression or method with the Upgrade class, using the method Upgrade.setExtraTasks. Registering a handler with class 'Upgrade' allows a user to make any type of customizations to any Java Doc page needed. It is neither imperative, nor mandatory to understand or use class 'ReflHTML' in order to do a basic Upgrade of a Java-Doc Generated HTML Documentation Directory. Instead, this class is provided for more advanced users who would like a finer-granularity of control in modifying Java Doc Web Pages.

    To begin writing proprietary customizations into Java Doc Web-Pages, an "Extra Tasks Handler" must be registered with the class Upgrade. This handler will be invoked once for each and every Java Doc Web-Page that is processed during the upgrade process. When your handler is called, it may request to change or update just about anything present on the page. The methods that make the Details about methods, fields, constructors on a Java Doc Web-Page are listed in the table below. They may be invoked on the JavaDocHTMLFile that is passed to your handler.

    Reflected Entity JavaDocHTMLFile 'Get' Method
    Methods allMethodDetails()
    Fields allFieldDetails()
    Constructors allConstructorDetails()
    Enum Constants allECDetails()
    Annotation Elements allAEDetails()

    NOTE: The above list is also visible via the "Method Summary Section" for class JavaDocHTMLFile.

    It should be of further interest to note that the actual parsed source code is available from each instance of ReflHTML as an Java Parser AST Tree Node. The entity field of this class contains one of the five Java Doc Upgrader Declaration classes. Each of these five classes exports the native Java Parser AST Node A.P.I. as apublic and final member field. The Java Parser AST Node Tree Fields are listed in the table below:

    Reflected Field Name Field Type
    Method.methodDeclaration com.github.javaparser.ast.body.
    MethodDeclaration
    Constructor.constructorDeclaration com.github.javaparser.ast.body.
    ConstructorDeclaration
    Field.variableDeclarator com.github.javaparser.ast.body.
    VariableDeclarator
    EnumConstant.enumConstantDeclaration com.github.javaparser.ast.body.
    EnumConstantDeclaration
    AnnotationElem.annotationMemberDeclaration com.github.javaparser.ast.body.
    AnnotationMemberDeclaration

    As an example, if the CIET were for class java.util.Vector<E>, and the Entity were Method 'get(int)', the HTML that would be contained by the internal 'html' field Vector<HTMLNode> would be exactly what can be seen in this location on the (Sun-Oracle) page:

    Vector.get(int)

    The Vectorized-HTML in private field 'html' would look as below (copied from the Sun-Oracle site):

    HTML Elements:
    <ul class="blockList">
    <li class="blockList">
    <h4>get</h4>
    <pre>public&nbsp;<a href="../../java/util/Vector.html" title="type parameter in Vector">E</a>&nbsp;get(int&nbsp;index)</pre>
    <div class="block">Returns the element at the specified position in this Vector.</div>
    <dl>
    <dt><span class="overrideSpecifyLabel">Specified by:</span></dt>
    <dd><code><a href="../../java/util/List.html#get-int-">get</a></code>&nbsp;in interface&nbsp;<code><a href="../../java/util/List.html" title="interface in java.util">List</a>&lt;<a href="../../java/util/Vector.html" title="type parameter in Vector">E</a>&gt;</code></dd>
    <dt><span class="overrideSpecifyLabel">Specified by:</span></dt>
    <dd><code><a href="../../java/util/AbstractList.html#get-int-">get</a></code>&nbsp;in class&nbsp;<code><a href="../../java/util/AbstractList.html" title="class in java.util">AbstractList</a>&lt;<a href="../../java/util/Vector.html" title="type parameter in Vector">E</a>&gt;</code></dd>
    <dt><span class="paramLabel">Parameters:</span></dt>
    <dd><code>index</code> - index of the element to return</dd>
    <dt><span class="returnLabel">Returns:</span></dt>
    <dd>object at the specified index</dd>
    <dt><span class="throwsLabel">Throws:</span></dt>
    <dd><code><a href="../../java/lang/ArrayIndexOutOfBoundsException.html" title="class in java.lang">ArrayIndexOutOfBoundsException</a></code> - if the index is out of range
                (<code>index &lt; 0 || index &gt;= size()</code>)</dd>
    <dt><span class="simpleTagLabel">Since:</span></dt>
    <dd>1.2</dd>
    </dl>
    </li>
    </ul>
    
    See Also:
    Serialized Form


    • Field Detail

      • serialVersionUID

        🡇    
        protected static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
        protected static final long serialVersionUID = 1;
        
      • openingUL

        🡅  🡇    
        public final TagNodeIndex openingUL
        This points to the opening <UL> tag for the detail. It's contents may be modified to include CSS classes or id's.
        Code:
        Exact Field Declaration Expression:
        public final TagNodeIndex openingUL;
        
      • entity

        🡅  🡇    
        public final ENTITY extends Declaration entity
        This is the actual type-reflection (type-mirror) of the Entity extracted from the Java Doc '.html' web-page file, and from the '.java' Source Code File.

        Since the type-parameter ENTITY must extend Declaration, this field will hold all of the information that was parsed & extracted by Java Parser. Depending on what type of instance of Declaration this represents, this will field will contain all of the parameter-names, parameter-types, modifiers, and exceptions that are associated with the entity.

        This will take one of five type's: Method, Constructor, Field, EnumConstant, AnnotationElem. This allows you to retrieve all reflected information, quickly and easily, associated with the Java Doc HTML "Detail Section" for a particular method, field, constructor etc...
        Code:
        Exact Field Declaration Expression:
        public final ENTITY entity;
        
      • entityAsEnum

        🡅  🡇    
        public final Entity entityAsEnum
        This is used as a 'faster-way' to retrieve what type of Entity this "Reference-HTML" detail-section is being represented here. This makes the code more readable than using Java's 'getClass()' reflection to identify whether this 'Detail Section HTML' holds the HTML for a Method, Field, Constructor, Enumeration, etc...

        The value in 'entityAsEnum' shall always be identical to the type of the entity. So for instance, if entity contained a Field instance, this field would be equal to Entity.FIELD. If this entity represented a Method HTML Detail-Section element, then this field would hold Entity.METHOD.
        Code:
        Exact Field Declaration Expression:
        public final Entity entityAsEnum;
        
      • htmlID

        🡅  🡇    
        public final java.lang.String htmlID
        Each Deteail Entity on a JavaDoc Page has a small and empty Anchor-Link, with an ID Attribute that allows the browser to redirect to the detail on a JavaDoc page using a relative URL to redirect to the details location on the web-page. If that detail element was found, it's will be stored in this field. (Otherwise, this field will contain null)

        Below is the <A ID=..> generated by Java Doc for a method that is named 'length'

        HTML Elements:
         <a id="length()">
         <!--   -->
         </a>
        
        Code:
        Exact Field Declaration Expression:
        public final String htmlID;
        
    • Constructor Detail

      • ReflHTML

        🡅  🡇    
        public ReflHTML​(ENTITY entity,
                        DotPair location,
                        java.util.Vector<HTMLNode> html,
                        Entity entityAsEnum,
                        java.lang.String htmlID)
        Constructs an instance of this class.
        Parameters:
        entity - This identifies which "Entity-Type" from which the HTML provided was derived. If the HTML-Vector passed to this constructor were taken from a "Method Detail" part of a Java Doc Web-Page, then this parameter would be passed Entity.METHOD
        location - The exact location on the Java Doc Web-Page from whence the HTML was extracted. It is important to note that this class facilitates changes, additions, and removal of HTML tags to a specific Detail-Segment of a CIET "Details Section".

        After the changes have been made, and all other HTML processors in this package have completed their updates, this HTML will need to replace the old-stuff in the page Vector. Keeping this location around makes this a simple replacement that has been optimized.

        Note that changing nodes in a Vector<HTMLNode>) can become profusely in-efficient if those changes are done in-place! By extracting small portions of the HTML-Vector, and only modifying small parts (all the while saving the original location of the HTMl) modifying HTML can be quickly and efficiently - even when not using DOM Tree like data-structures.
        entityAsEnum - If it is necessary to ask whether this "Reference HTML SubSection" is an HTML sub-section for a Method, Field or Constructor etc... Rather than using the getClass() on field entity, you may use this Enumeration, instead.
        html - The HTML of a Java Doc detail-section
        Throws:
        java.lang.IllegalArgumentException - If the parameter 'entity' and 'entityAsEnum' do not reference the same type of detail-section. This is a quick check that isn't costly. In the HTML file processors of this package, this won't ever be thrown.
        Code:
        Exact Constructor Body:
         // MESSAGER:
         //  1) EXPECTS:     FileName to be set
         //  2) SETS:        Nothing - only uses assertFailHTML
         //  3) INVOKES:     assertFailHTML only
         //  4) INVOKED-BY:  JavaDocHTMLFile *ONLY*
         //  5) THROWS:      only throws through assertFailHTML
         //  6) RETURNS:     This is a constructor, returns nothing
        
         this.entity         = entity;
         this.location       = location;
         this.entityAsEnum   = entityAsEnum;
         this.htmlID         = htmlID;
        
        
         // This will never happen.  ReflHTML's are constructed properly in JavaDocHTMLFile.
         // This switch statement is practically-free, so, this prevents possible errors later on.
        
         switch (entityAsEnum)
         {
             case METHOD:            if (! (entity instanceof Method))
                                         throw ENTITY_MATCH(entity, entityAsEnum);
                                     break;
        
             case FIELD:             if (! (entity instanceof Field))
                                         throw ENTITY_MATCH(entity, entityAsEnum);
                                     break;
        
             case CONSTRUCTOR:       if (! (entity instanceof Constructor))
                                         throw ENTITY_MATCH(entity, entityAsEnum);
                                     break;
        
             case ENUM_CONSTANT:     if (! (entity instanceof EnumConstant))
                                         throw ENTITY_MATCH(entity, entityAsEnum);
                                     break;
        
             case ANNOTATION_ELEM:   if (! (entity instanceof AnnotationElem))
                                         throw ENTITY_MATCH(entity, entityAsEnum);
                                     break;
         }
        
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // This is used over and over again, in every Messager.assertFailHTML
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         final String sig = this.entity.signature; // Makes for easier typing
        
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // Convenience Method's & Constructor's add a CSS Class to the first <UL>
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         TagNode tn = html.elementAt(location.start).ifTagNode();
        
         if (tn == null) Messager.assertFailHTML(
             "The first node in this detail is not a <UL>:\n" + detErrMsg(html, location),
             sig
         );
        
         this.openingUL = new TagNodeIndex(location.start, tn);
        
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // HiLitedDetails needs an insertion-point
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         // There is a <DL>...</DL> (HTML Definitions List) that Java Doc uses.  There should be one
         // at the end of the Detail-Section, which is where the HiLited Detail is placed.  If a
         // closing </DL> is not found, then an opening and closing <DL> ... </DL> needs to created
         // and inserted at the end
         // 
         // REMEMBER: 'hiLitedDetail' is wrapped in a <DD>...</DD><DT>...</DT>
        
         int insertionPoint = TagNodeFind.last
             (html, location.start, location.end, TC.ClosingTags, "dl");
        
         this.needToAddOpenCloseDLsForHiLitedDetails = insertionPoint == -1;
        
         // If a </DL> wasn't found, a new <DL> (Definition List), needs to be built.  Also a new
         // insertion point is needed.  The details section ends with a closing '</LI>' element,
         // which is where to insert the new <DL>...</DL>
         //
         // NOTE: **FIELDS** are the Detail-Elements that usually do not have a <DL>...</DL>, because
         //       there aren't many <SPAN> Label-Banners present in a field
        
         if (insertionPoint == -1)
         {
             insertionPoint = TagNodeFind.last
                 (html, location.start, location.end, TC.ClosingTags, "li");
        
             if (insertionPoint == -1) Messager.assertFailHTML
                 ("There is a detail with no ending </DL> and no ending </LI>", sig);
         }
        
         this.hiLitedCode = Replaceable.empty(insertionPoint);
        
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // Mandatory HTML Fields: name & signature
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         // One precaution is that this <H4> must be among the first 8 nodes in the sub-page,
         // Except for Annotation Elements, which have several HTML Nodes at the start of the detail
        
         this.name = TagNodePeekInclusive.first(
             html, location.start,
             ((this.entityAsEnum == Entity.ANNOTATION_ELEM) ? location.end : (location.start + 8)),
             "h4"
         );
        
         if (this.name == null)
        
             Messager.assertFailHTML(
                 "There was no name <H4> found in the detail:\n" +
                 // StrIndent.indent(Util.pageToString(html), 4),
                 detErrMsg(html, location),
                 sig
             );
        
         int sPos = this.name.location.end + 1;
        
         // Here, it is required that the <PRE> have a class that has the word "Signature"
         // Unfortunately, javadoc doesn't always insert the class...
        
         this.signature = TagNodePeekInclusive.first
             (html, sPos, location.end, "pre");
        
         if (this.signature == null)
        
             Messager.assertFailHTML(
                 "There was no signature <PRE> found in the detail:\n" +
                 // StrIndent.indent(Util.pageToString(html), 4),
                 detErrMsg(html, location),
                 sig
             );
        
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // Description HTML Field, it is not Mandatory
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         sPos = this.signature.location.end + 1;
        
         SubSection subSection = InnerTagPeekInclusive.first
             (html, sPos, location.end, "div", "class", TextComparitor.C, "block");
        
         if (subSection != null)
         {
             sPos = subSection.location.end + 1;
             subSections.put(DESCRIPTION_KEY, subSection);
         }
        
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // Annotations Have this little "Default" thing
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         //
         // <dt><SPAN CLASS=C21>Default:</SPAN></dt>
         // <dd>{}</dd>
        
         // NOTE: This is 'temp' variable that is reused over and over in this method
         DotPair dp = TagNodeFindInclusive.first(html, sPos, -1, "dl");
        
         if (dp != null)
         {
             int defPos = TextNodeFind.first
                 (html, dp.start, dp.end, s -> s.equals("Default:"));
        
             if (defPos != -1)
             {
                 dp = Surrounding.first(html, defPos, "dt");
                 subSections.put
                     (ANNOTATION_DEFAULT_KEY, new SubSection(dp, Util.cloneRange(html, dp)));
             }
         }
        
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // <DL> Labels: <DT><SPAN CLASS="someLabel">Some Label</SPAN></DT><DD>...</DD> Fields.  
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         final String[] spanClasses = {
             "paramLabel", "returnLabel", "seeLabel", "throwsLabel", "overrideSpecifyLabel",
             "simpleTagLabel"
         };
        
         int[] spans = InnerTagFind.all
             (html, sPos, location.end, "span", "class", TextComparitor.EQ, spanClasses);
        
         for (int spanPos : spans)
         {
             // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
             // Build the 'location' (DotPair) of the HTML that "surrounds" the SPAN (DT/DD's)
             // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
             //
             //  <DT><SPAN CLASS='someLabel'>Some Label</SPAN></DT>
             //  <DD> Some User Code Information </DD>
             //  <DD> For Parameters & Throws, there are multiple DD's </DD>
        
             // First ensure that there is an opening <DT> directly befofre the <SPAN CLASS=Label>
             // The 'tn' was declared at the top of this method, it is a re-usable temp variable
        
             tn = html.elementAt(spanPos - 1).openTag();
        
             if ((tn == null) || (! tn.tok.equals("dt"))) Messager.assertFailHTML(
                 "There is a " + C.BGREEN + html.elementAt(spanPos).str + C.RESET + "\n" +
                 "Not preceeded by an opening " + C.BGREEN + "<DT>" + C.RESET + "\n" +
                 "Instead there is a " + C.BGREEN + html.elementAt(spanPos - 1).str +
                 C.RESET,
                 sig
             );
        
             // Passed the above requirement/test, so this is the start of the SubSection
             int locStart = spanPos - 1;
        
             // The particular section we are observing ends as soon as another section begins, or
             // we encounter a </DL> element.  a <DT> element implies a new section is starting, and
             // a </DL> element means all of the labels have been handled
             //
             // Find the ending </DD> of the last <DD>...</DD> pair
        
             int locEnd = -1, len = html.size();
        
             // Find either a closing </DL> (meaning no more <SPAN CLASS='someLabel'> elements),
             // or an oopening <DT> - which is starting a new SPAN-LABEL
        
             INNER_FOR_LOOP:
             for (int i = (spanPos + 1); i < len; i++)
        
                 if ((tn = html.elementAt(i).ifTagNode()) != null)
        
                     if (    (tn.tok.equals("dl") &&  tn.isClosing)      // Closing </DL>
                         ||  (tn.tok.equals("dt") &&  (! tn.isClosing))  // Opening <DT>
                     )
                     {
                         locEnd = i;
                         break INNER_FOR_LOOP;
                     }
        
             // I still haven't found what I'm looking for...
             // There was not closing </DL>, nor an new, opening <DT>
        
             if (locEnd == -1) Messager.assertFailHTML(
                 "There is a " + C.BGREEN + html.elementAt(spanPos).str + C.RESET + ' ' +
                 "which isn't terminated by a new <DT> or a closing </DL>",
                 sig
             );
        
             // Back up through any TextNodes - which, usually, is just a '\n' newline character.
             while ((tn = html.elementAt(--locEnd).ifTagNode()) == null);
        
             // Finally, make sure there is a closing </DD> which is the end of the 
             // <DT>...</DT><DD>...</DD> Combination.  Remember, there may only be one <DT>..<DT>
             // (with a <SPAN CLASS='someLabel'), but that <DT> may be followed by more than one
             // <DD>...</DD> list.  Parameters and Throws Labels have severl <DD> pairs!
        
             if ((! tn.isClosing) || (! tn.tok.equals("dd"))) Messager.assertFailHTML(
                 "There is a " + C.BGREEN + html.elementAt(spanPos).str + C.RESET + ' ' +
                 "which is missing a <DD> definition",
                 sig
             );
        
        
             // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
             // Finished Searching. Build the "SubSection" instance, and start the switch-statement
             // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
             // 'dp' is a temp variable that was first used earlier
             dp = new DotPair(locStart, locEnd);
        
             // A 'SubSection' includes both the location, and the HTML put together in a
             // wrapper-class (SubSection is wrapper for Vector<HTMLNode> & DotPair)
        
             SubSection section = new SubSection(dp, Util.cloneRange(html, dp));
        
             // Temporary Variables for the switch statement
             String      kind;
             TextNode    txn;
        
             // In case you missed it, the six labels that were searched are:
             // "paramLabel", "returnLabel", "seeLabel", "throwsLabel", "overrideSpecifyLabel",
             // and "simpleTagLabel"
        
             CASE:
             switch (html.elementAt(spanPos).asTagNode().AV("class"))
             {
                 case "returnLabel" :
        
                     if (subSections.containsKey(RETURNS_KEY))
                         Messager.assertFailHTML("There is a second 'returnLabel", sig);
                     else
                         subSections.put(RETURNS_KEY, section);
        
                     break CASE;
        
                 case "seeLabel" :
        
                     if (subSections.containsKey(SEE_ALSO_KEY))
                         Messager.assertFailHTML("There is a second 'seeLabel", sig);
                     else
                         subSections.put(SEE_ALSO_KEY, section);
        
                     break CASE;
        
                 case "throwsLabel" :
        
                     if (subSections.containsKey(THROWS_KEY))
                         Messager.assertFailHTML("There is a second 'throwsLabel", sig);
                     else
                         subSections.put(THROWS_KEY, section);
        
                     break CASE;
        
        
                 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                 // There can be two kinds of "paramLabel" 
                 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                 //
                 // One is used for regular-parameters, which is the most common, while the second
                 // is for "Type-Parameters" (rare, but useful)
        
                 case "paramLabel" :
        
                     if ((txn = html.elementAt(spanPos + 1).ifTextNode()) == null)
                         Messager.assertFailHTML
                             ("There is a 'paramLabel' not followed by a TextNode", sig);
        
                     kind = txn.str;
        
                     if (kind.equals("Parameters:"))
                     {
                         if (subSections.containsKey(PARAMETERS_KEY))
                             Messager.assertFailHTML
                                 ("There is a second 'paramLabel' for parameters", sig);
                         else
                             subSections.put(PARAMETERS_KEY, section);
                     }
                     else if (kind.equals("Type Parameters:"))
                     {
                         if (subSections.containsKey(TYPE_PARAMETERS_KEY))
                             Messager.assertFailHTML
                                 ("There is a second 'paramLabel' for type-parameters", sig);
                         else
                             subSections.put(TYPE_PARAMETERS_KEY, section);
                     }
        
                     else Messager.assertFailHTML(
                         "Unknown Parameter Label Found:\n" +
                         StrIndent.indent(Util.pageToString(section.html), 4),
                         sig
                     );
        
                     break CASE;
        
        
                 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                 // There can be two kinds of "overrideSpecifyLabel"
                 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                 // (surprise, "override" and "specified by")
        
                 case "overrideSpecifyLabel" :
        
                     if ((txn = html.elementAt(spanPos + 1).ifTextNode()) == null)
                         Messager.assertFailHTML
                             ("There is a 'overrideSpecifyLabel' not followed by a TextNode", sig);
        
                     kind = txn.str;
        
                     if (kind.equals("Specified by:"))
                     {
                         if (subSections.containsKey(SPECIFIED_BY_KEY))
                         {
                             SubSection first = subSections.get(SPECIFIED_BY_KEY);
        
                             if ((dp.start - first.location.end) > 2)
        
                                 Messager.assertFailHTML(
                                     "There is a second 'overrideSpecifyLabel' for 'Specified " +
                                     "by:', and unfortunately it is not contiguous with the " +
                                     "previous one.",
                                     sig
                                 );
        
                             dp = new DotPair(first.location.start, dp.end);
                             section = new SubSection(dp, Util.cloneRange(html, dp));
                         }
        
                         subSections.put(SPECIFIED_BY_KEY, section);
                     }
        
                     else if (kind.equals("Overrides:"))
                     {
                         if (subSections.containsKey(OVERRIDES_KEY))
                             Messager.assertFailHTML
                                 ("There is a second 'Overrides' label", sig);
                         else
                             subSections.put(OVERRIDES_KEY, section);
                     }
        
                     else Messager.assertFailHTML(
                         "Unknown Overrides/Specified-By Label Found:\n" +
                         StrIndent.indent(Util.pageToString(section.html), 4),
                         sig
                     );
        
                     break CASE;
        
        
                 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                 // There can many kinds of "simpleTagLabel"
                 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
                 case "simpleTagLabel" :
        
                     if ((txn = html.elementAt(spanPos + 1).ifTextNode()) == null)
                         Messager.assertFailHTML
                             ("There is a 'simpleTagLabel' not followed by a TextNode", sig);
        
                     kind = txn.str;
        
                     if (kind.equals("Since:"))
                     {
                         if (subSections.containsKey(SINCE_KEY))
                             Messager.assertFailHTML
                                 ("There is a second 'simpleTagLabel' for 'since'", sig);
                         else
                             subSections.put(SINCE_KEY, section);
                     }
                     else
                     {
                         // 99% of the classes in JavaHTML do not have these, no need to build
                         // this array-list at construction-time, only build if used
        
                         if (miscSimpleTagLabels == null)
                             miscSimpleTagLabels = new ArrayList<>();
        
                         miscSimpleTagLabels.add
                             (new TagNodeIndex(spanPos, html.elementAt(spanPos).asTagNode()));
                     }
             }
         }
        
      • ReflHTML

        🡅  🡇    
        public ReflHTML​(ReflHTML<ENTITY> other)
        Clone Constructor.
        Parameters:
        other - Another instance of ReflHTML
        See Also:
        clone()
        Code:
        Exact Constructor Body:
         this.entity         = other.entity; /* not cloned, the reflected entity */
         this.entityAsEnum   = other.entityAsEnum;
         this.location       = other.location; /* immutable, no need to clone */
         //html           = ((Vector<HTMLNode>) other.html.clone());
         this.htmlID         = other.htmlID;
         this.openingUL      = other.openingUL;
         this.name           = other.name.clone();
         this.signature      = other.signature.clone();
        
         // The Code-HiLited Details "Special Additions"
         this.hiLitedCode = other.hiLitedCode;
         this.needToAddOpenCloseDLsForHiLitedDetails = other.needToAddOpenCloseDLsForHiLitedDetails;
        
         // Cannot 'clone' the other.subSections, it assigned a value at initialization (at the top
         // where it is declared). Use 'TreeMap.putAll' instead
        
         this.subSections.putAll(other.subSections);
        
         // This is not inialized unless there are actually 'simpleTagLabels' in the detail
         this.miscSimpleTagLabels = (other.miscSimpleTagLabels != null)
             ? ((ArrayList<TagNodeIndex>) other.miscSimpleTagLabels.clone())
             : null;
        
    • Method Detail

      • name

        🡅  🡇    
        public java.util.Vector<HTMLNodename()
        Returns an HTML-Vector of the HTML used to display the name of a detail element. This contains identical information to that which may be retrieved from a call to DetailsParts.name(Vector)

        This also contains the same information as in the field Declaration.name, which is reflected (using Java Parer) from the associated 'java' source-code file. The HTML for this segment is listed, here below:

        HTML Elements:
         <h4> [Name] </h4>
        


        This returned result of this method is HTML, and it may be modified in any way that the programmer sees fit. Any changes that are made to this HTML will be incorporated into the final version of the Java Doc Page for the detail element HTML.
        Returns:
        An HTML-Vector of the Java Doc name segment of this detail. This method will never return null, as all detail-elements have a name.
        See Also:
        DetailsParts.name(Vector), Declaration.name
        Code:
        Exact Method Body:
         return name.html;
        
      • signature

        🡅  🡇    
        public java.util.Vector<HTMLNodesignature()
        Returns an HTML-Vector of the HTML used to display the signature of a detail element. This contains identical information to that which may be retrieved from a call to DetailsParts.signature(Vector)

        This also contains the same information as in the field Declaration.signature, which is reflected (using Java Parer) from the associated 'java' source-code file. In the HTML below it is the text that appears between the @lt;PRE> tags. Note that the HTML 'class' attribute (present, below) will not always be included in every detail element.

        HTML Elements:
         <h4> [Name] </h4>
         <pre class="Signature"> ... </pre>
        


        This returned result of this method is HTML, and it may be modified in any way that the programmer sees fit. Any changes that are made to this HTML will be incorporated into the final version of the Java Doc Page for the detail element HTML.
        Returns:
        An HTML-Vector of the Java Doc signature segment of this detail. This method will never return null, as all detail-elements have a signature.
        See Also:
        DetailsParts.signature(Vector), Declaration.signature
        Code:
        Exact Method Body:
         return signature.html;
        
      • description

        🡅  🡇    
        public final java.util.Vector<HTMLNodedescription()
        Returns an HTML-Vector of the HTML used to display the description of a detail element. This contains identical information to that which may be retrieved from a call to DetailsParts.description(Vector)

        This HTML is generated by the Java Doc Tool using the text provided by a programmer in his Java Doc Comments directly above the code in a '.java' file. In a Java Doc '.html' file, the description is always surrounded by an HTML divider ('<DIV>') element, as appears below:

        HTML Elements:
         <div class="block"> ... [Text-Description of Method, Field, etc...] ... </div>
        


        This returned result of this method is HTML, and it may be modified in any way that the programmer sees fit. Any changes that are made to this HTML will be incorporated into the final version of the Java Doc Page for the detail element HTML.
        Returns:
        An HTML-Vector of the Java Doc description segment of this detail. Since a description is not mandatory, and it is not an auto-generated segment of a detail element, this method will return null if a programmer has not written or included a description for this particular detail element in his source-code for this detail element.
        See Also:
        DetailsParts.description(Vector)
        Code:
        Exact Method Body:
         SubSection s = subSections.get(DESCRIPTION_KEY);
         return (s!= null) ? s.html : null;
        
      • annotationDefault

        🡅  🡇    
        public java.util.Vector<HTMLNodeannotationDefault()
        Returns an HTML-Vector of the HTML used to display the Default Annotation Element Value of an Annotation-Detail element. This contains identical information to that which may be retrieved from a call to DetailsParts.defaultLabel(Vector)

        This also contains the same information as in the field AnnotationElem.defaultValue, which is reflected (using Java Parer) from the associated 'java' source-code file. The HTML for this segment is listed, here below:

        HTML Elements:
         <dl>
         <dt>Default:</dt>
         <dd> [ some values possibly inserted here ]</dd>
         </dl>
        


        This returned result of this method is HTML, and it may be modified in any way that the programmer sees fit. Any changes that are made to this HTML will be incorporated into the final version of the Java Doc Page for the detail element HTML.

        Unless this detail is an "Annotation Detail", calling this method will generate an exception-throw.
        Returns:
        An HTML-Vector of an annotation detail element's Default Value. If the annotation does not have a default value assigned, or it is not present on the Java Doc Page, this method will return null.
        Throws:
        DetailsException - If the ReflHTML instance on which this method is being invoked is not for an Annotation Detail, the invocation will generate a DetailsException
        See Also:
        DetailsParts.defaultLabel(Vector), AnnotationElem.defaultValue
        Code:
        Exact Method Body:
         if (entityAsEnum != Entity.ANNOTATION_ELEM)
        
             throw new DetailsException(
                 "This ReflHTML is a Reflection of a(n) " + entityAsEnum.toString() + " details, " +
                 "however only Annotations may have Annotation-Element Default Values."
             );
        
         SubSection s = subSections.get(ANNOTATION_DEFAULT_KEY);
         return (s!= null) ? s.html : null;
        
      • returns

        🡅  🡇    
        public java.util.Vector<HTMLNodereturns()
        Returns an HTML-Vector of the HTML used to display the Returns: segment of a Method Detail element. This contains identical information to that which may be retrieved from a call to DetailsParts.returns(Vector)

        This also contains some of the information present in the field Method.returnType, which is reflected (using Java Parer) from the associated 'java' source-code file.

        This HTML is auto-generated by Java Doc using the @return taglet's, which may be provided by a programmer in his '.java' source-code file. The HTML output generated by Java Doc is as below:

        HTML Elements:
         <dt><span class="returnLabel">Returns:</span></dt>
         <dd> [User-Provided Return-Value Information, as HTML, Here] </dd>
        


        This returned result of this method is HTML, and it may be modified in any way that the programmer sees fit. Any changes that are made to this HTML will be incorporated into the final version of the Java Doc Page for the detail element HTML.

        Only methods may have return-values. Furthermore, only methods for which the programmer has provided a @return taglet entry will the result of this method be non-null.
        Returns:
        An HTML-Vector of a method detail element's Returns: label. If the method does not have such a label, because the programmer did not provide a @return taglet, this method will return null.
        Throws:
        DetailsException - If the ReflHTML instance on which this method is being invoked is not for an Method Detail, the invocation will generate a DetailsException
        See Also:
        DetailsParts.returns(Vector), Method.returnType
        Code:
        Exact Method Body:
         if (entityAsEnum != Entity.METHOD)
        
             throw new DetailsException(
                 "This ReflHTML is a Reflection of a(n) " + entityAsEnum.toString() + " details, " +
                 "however only Methods may have Return-Values."
             );
        
         SubSection s = subSections.get(RETURNS_KEY);
         return (s!= null) ? s.html : null;
        
      • seeAlso

        🡅  🡇    
        public java.util.Vector<HTMLNodeseeAlso()
        Returns an HTML-Vector of the HTML used to display the See Also: segment of any detail element. This contains identical information to that which may be retrieved from a call to DetailsParts.see(Vector)

        This HTML is auto-generated by Java Doc using the @see taglet's, which may be provided by a programmer in his '.java' source-code file. The HTML output generated by Java Doc is as below:

        HTML Elements:
         <dt><span class="seeLabel">See Also:</span></dt>
         <dd><a href="#someMethod()"><code>someMethod()</code></a></dd>
        


        This returned result of this method is HTML, and it may be modified in any way that the programmer sees fit. Any changes that are made to this HTML will be incorporated into the final version of the Java Doc Page for the detail element HTML.

        Only detail elements for which the programmer has provided at least one @see taglet entry will the result of this method be non-null.
        Returns:
        An HTML-Vector of a method detail element's See Also: label. If the method does not have such a label, because the programmer did not provide any @see taglet, this method will return null.
        See Also:
        DetailsParts.see(Vector)
        Code:
        Exact Method Body:
         SubSection s = subSections.get(SEE_ALSO_KEY);
         return (s!= null) ? s.html : null;
        
      • throwing

        🡅  🡇    
        public java.util.Vector<HTMLNodethrowing()
        Returns an HTML-Vector of the HTML used to display the Throws: segment of a Method or Constructor Detail element. This contains identical information to that which may be retrieved from a call to DetailsParts.throwing(Vector)

        This also contains some of the information present in the field Callable.exceptions, which is reflected (using Java Parer) from the associated 'java' source-code file.

        This HTML is auto-generated by Java Doc using the @throws taglet's, which may be provided by a programmer in his '.java' source-code file. If a method or constructor is throwing checked exceptions, Java Doc will auto-create a 'Throws:' label / segment. The HTML output generated by Java Doc is as below:

        HTML Elements:
         <dt><span class="throwsLabel">Throws:</span></dt>
         <dd> [Text explaining thrown exceptions by a method or constructor]</dd>
        


        This returned result of this method is HTML, and it may be modified in any way that the programmer sees fit. Any changes that are made to this HTML will be incorporated into the final version of the Java Doc Page for the detail element HTML.

        Only methods and constructors are capable of throwing exceptions. Furthermore, only details for which the programmer has provided a @throws taglet entry (or which throw checked-exceptions) will the result of this method be non-null.
        Returns:
        An HTML-Vector of a method or constructor detail element's Throws: label. If the detail does not have such a label, this method will return null.
        Throws:
        DetailsException - If the ReflHTML instance on which this method is being invoked is neither a Method Detail nor a Constructor Detail, the invocation will generate a DetailsException
        See Also:
        DetailsParts.description(Vector), Callable.exceptions
        Code:
        Exact Method Body:
         if ((entityAsEnum != Entity.METHOD) && (entityAsEnum != Entity.CONSTRUCTOR))
        
             throw new DetailsException(
                 "This ReflHTML is a Reflection of a(n) " + entityAsEnum.toString() + " details, " +
                 "however only Methods and Constructors may throw Exceptions."
             );
        
         SubSection s = subSections.get(THROWS_KEY);
         return (s!= null) ? s.html : null;
        
      • parameters

        🡅  🡇    
        public java.util.Vector<HTMLNodeparameters()
        Returns an HTML-Vector of the HTML used to display the Parmeters: segment of a Method or Constructor Detail element. This contains identical information to that which may be retrieved from a call to DetailsParts.parameters(Vector)

        This also contains some of the information present in the fields Callable.parameterNames and Callable.parameterTypes, which is reflected (using Java Parer) from the associated 'java' source-code file.

        This HTML is auto-generated by Java Doc using the @param taglet's, which may be provided by a programmer in his '.java' source-code file. The HTML output generated by Java Doc is as below:

        HTML Elements:
         <dt><span class="paramLabel">Parameters:</span></dt>
         <dd><code>[Parameter Name]</code> - [Some Parameter Description]</dd>
        


        This returned result of this method is HTML, and it may be modified in any way that the programmer sees fit. Any changes that are made to this HTML will be incorporated into the final version of the Java Doc Page for the detail element HTML.

        Only methods and constructors may accept input parameters. Furthermore, only details for which the programmer has provided a @param taglet entry will there be parameter descriptive-text on a Java Doc Page. The result of this method will be non-null, only in cases where such descriptions have been included in their JavaDoc commenting.
        Returns:
        An HTML-Vector of a method or constructor detail element's Parameters: label. If the detail does not have such a label, this method will return null.
        Throws:
        DetailsException - If the ReflHTML instance on which this method is being invoked is neither a Method Detail nor a Constructor Detail, the invocation will generate a DetailsException
        See Also:
        DetailsParts.parameters(Vector), Callable.parameterNames, Callable.parameterTypes
        Code:
        Exact Method Body:
         if ((entityAsEnum != Entity.METHOD) && (entityAsEnum != Entity.CONSTRUCTOR))
        
             throw new DetailsException(
                 "This ReflHTML is a Reflection of a " + entityAsEnum.toString() + " details, " +
                 "however only Methods and Constructors may have Parameters."
             );
        
         SubSection s = subSections.get(PARAMETERS_KEY);
         return (s!= null) ? s.html : null;
        
      • typeParameters

        🡅  🡇    
        public java.util.Vector<HTMLNodetypeParameters()
        Returns an HTML-Vector of the HTML used to display the Type Parmeters: segment of a Method or Constructor Detail element. This contains identical information to that which may be retrieved from a call to DetailsParts.typeParameters(Vector)

        This HTML is auto-generated by Java Doc using the @param <T> taglet's, which may be provided by a programmer in his '.java' source-code file. The HTML output generated by Java Doc is as below:

        HTML Elements:
         <dt><span class="paramLabel">Type Parameters:</span></dt>
         <dd><code>[Type Parameter <T>]</code> - [Some Type Parameter Description]</dd>
        


        This returned result of this method is HTML, and it may be modified in any way that the programmer sees fit. Any changes that are made to this HTML will be incorporated into the final version of the Java Doc Page for the detail element HTML.

        Only methods and constructors will allow type-parameters. Furthermore, only details for which the programmer has provided a @param <T> taglet entry will there be parameter descriptive-text on a Java Doc Page. The result of this method will be non-null, only in cases where such descriptions have been included in their JavaDoc commenting.
        Returns:
        An HTML-Vector of a method or constructor detail element's Type Parameters: label. If the detail does not have such a label, this method will return null.
        Throws:
        DetailsException - If the ReflHTML instance on which this method is being invoked is neither a Method Detail nor a Constructor Detail, the invocation will generate a DetailsException
        See Also:
        DetailsParts.typeParameters(Vector)
        Code:
        Exact Method Body:
         if ((entityAsEnum != Entity.METHOD) && (entityAsEnum != Entity.CONSTRUCTOR))
        
             throw new DetailsException(
                 "This ReflHTML is a Reflection of a(n) " + entityAsEnum.toString() + " details, " +
                 "however only Methods and Constructors may have Type-Parameters."
             );
        
         SubSection s = subSections.get(TYPE_PARAMETERS_KEY);
         return (s!= null) ? s.html : null;
        
      • overrides

        🡅  🡇    
        public java.util.Vector<HTMLNodeoverrides()
        Returns an HTML-Vector of the HTML used to display the Overrides: segment of a Method Detail element. This contains identical information to that which may be retrieved from a call to DetailsParts.overrideSpecify(Vector)

        This HTML is auto-generated by Java Doc, for methods which override a parent class or interface. The HTML output generated by Java Doc is as below:

        HTML Elements:
         <dt><span class="overrideSpecifyLabel">Overrides:</span></dt>
         <dd><code> [ Some Name ]</code>&nbsp;in interface&nbsp;<code> [Interface Name] </code></dd>
        


        This returned result of this method is HTML, and it may be modified in any way that the programmer sees fit. Any changes that are made to this HTML will be incorporated into the final version of the Java Doc Page for the detail element HTML.

        Only methods may override other methods. The result of this method will be non-null, only in cases where the Method Detail on which this invocation was made is actually an overrided method.
        Returns:
        An HTML-Vector of a method detail element's Overrides: label. If the detail does not have such a label, this method will return null.
        Throws:
        DetailsException - If the ReflHTML detail instance on which this method is being invoked is not a Method Detail, then a DetailsException will throw.
        See Also:
        DetailsParts.overrideSpecify(Vector)
        Code:
        Exact Method Body:
         if (entityAsEnum != Entity.METHOD)
        
             throw new DetailsException(
                 "This ReflHTML is a Reflection of a(n) " + entityAsEnum.toString() + " details, " +
                 "however only Methods may have \"Overrides:\" Labels."
             );
        
         SubSection s = subSections.get(OVERRIDES_KEY);
         return (s!= null) ? s.html : null;
        
      • specifiedBy

        🡅  🡇    
        public java.util.Vector<HTMLNodespecifiedBy()
        Returns an HTML-Vector of the HTML used to display the Specified by: segment of a Method Detail element. This contains indentical information to that which may be retrieved from a call to DetailsParts.overrideSpecify(Vector)

        This HTML is auto-generated by Java Doc, for methods which implement another method that was specified by an interface which the type implements, or a method specified by an abstract parent super-class. The HTML output generated by Java Doc is as below:

        HTML Elements:
         <dt><span class="overrideSpecifyLabel">Specified by:</span></dt>
         <dd><code> [ Some Name ]</code>&nbsp;in interface&nbsp;<code> [Interface Name] </code></dd>
        


        This returned result of this method is HTML, and it may be modified in any way that the programmer sees fit. Any changes that are made to this HTML will be incorporated into the final version of the Java Doc Page for the detail element HTML.

        Only methods may implement a "specified-method" (obviously!) The result of this method will be non-null - only in cases where the Method Detail on which this invocation was made actually implements another abstract method declaration.
        Returns:
        An HTML-Vector of a method detail element's Specified by: label. If the detail does not have such a label, this method will return null.
        Throws:
        DetailsException - If the ReflHTML detail instance on which this method is being invoked is not a Method Detail, then a DetailsException will throw.
        See Also:
        DetailsParts.overrideSpecify(Vector)
        Code:
        Exact Method Body:
         if (entityAsEnum != Entity.METHOD)
        
             throw new DetailsException(
                 "This ReflHTML is a Reflection of a(n) " + entityAsEnum.toString() + " details, " +
                 "however only Methods may have \"Specified-By:\" Labels."
             );
        
         SubSection s = subSections.get(SPECIFIED_BY_KEY);
         return (s!= null) ? s.html : null;
        
      • author

        🡅  🡇    
        public java.util.Vector<HTMLNodeauthor()
        This will be implented at a later date. For now, this throws an exception.
        Code:
        Exact Method Body:
         if (1 == 1) throw new Torello.Java.ToDoException("Not Tested Yet");
        
         SubSection s = subSections.get(AUTHOR_KEY);
         return (s!= null) ? s.html : null;
        
      • since

        🡅  🡇    
        public java.util.Vector<HTMLNodesince()
        Returns an HTML-Vector of the HTML used to display the Specified by: segment of a Method Detail element.

        HTML Elements:
         <dt><span class="simpleTagLabel">Since:</span></dt>
         <dd> [ Version Number Information ]</dd>
        


        This returned result of this method is HTML, and it may be modified in any way that the programmer sees fit. Any changes that are made to this HTML will be incorporated into the final version of the Java Doc Page for the detail element HTML.

        Only details for which the programmer has provided a @since <T> taglet entry will there be 'since' descriptive-text on a Java Doc Page. The result of this method will be non-null, only in cases where such version-information has been included in their JavaDoc commenting.
        Returns:
        An HTML-Vector of a method detail element's Since: label. If the detail does not have such a label, this method will return null.
        Code:
        Exact Method Body:
         SubSection s = subSections.get(SINCE_KEY);
         return (s!= null) ? s.html : null;
        
      • clone

        🡅  🡇    
        public ReflHTML<ENTITYclone()
        Java's interface Cloneable requirements. This provides a "Deep Clone", where all internal Vector's and SubSection's are also cloned, rather than a "Shallow Clone", having identical references. See the clone-constructor ReflHTML(ReflHTML)
        Overrides:
        clone in class java.lang.Object
        Returns:
        A new ReflHTML whose internal fields are identical to this one.
        See Also:
        ReflHTML(Torello.HTML.Tools.JavaDoc.ReflHTML<ENTITY>)
        Code:
        Exact Method Body:
         return new ReflHTML<>(this);
        
      • compareTo

        🡅    
        public final int compareTo​(ReflHTML other)
        Java's interface Comparable<T> requirements. This does a very simple comparison using the location field.

        FINAL METHOD: This method is declared final, and cannot be modified by sub-classes.
        Specified by:
        compareTo in interface java.lang.Comparable<ENTITY extends Declaration>
        Parameters:
        other - Any other ReflHTML to be compared to 'this' ReflHTML
        Returns:
        An integer that fulfils Java's interface Comparable<T> public boolean compareTo(T t) method requirements.
        See Also:
        DotPair.compareTo(DotPair)
        Code:
        Exact Method Body:
         return this.location.compareTo(other.location);