Class TopDescription


  • public class TopDescription
    extends java.lang.Object
    TopDescription - Documentation.

    This class is used to manipulate the class, interface, or enumerated-type description at the top. For instance, these words you are reading right now are located in the "Top Description" for class TopDescription .

    Static (Functional) API: The methods in this class are all (100%) defined with the Java Key-Word / Key-Concept 'static'. Furthermore, there is no way to obtain an instance of this class, because there are no public (nor private) constructors. Java's Spring-Boot, MVC feature is *not* utilized because it flies directly in the face of the light-weight data-classes philosophy. This has many advantages over the rather ornate Component Annotations (@Component, @Service, @AutoWired, etc... 'Java Beans') syntax:

    • The methods here use the key-word 'static' which means (by implication) that there is no internal-state. Without any 'internal state' there is no need for constructors in the first place! (This is often the complaint by MVC Programmers).
    • A 'Static' (Functional-Programming) API expects to use fewer data-classes, and light-weight data-classes, making it easier to understand and to program.
    • The Vectorized HTML data-model allows more user-control over HTML parse, search, update & scrape. Also, memory management, memory leakage, and the Java Garbage Collector ought to be intelligible through the 'reuse' of the standard JDK class Vector for storing HTML Web-Page data.

    The power that object-oriented programming extends to a user is (mostly) limited to data-representation. Thinking of "Services" as "Objects" (Spring-MVC, 'Java Beans') is somewhat 'over-applying' the Object Oriented Programming Model. Like most classes in the Java-HTML JAR Library, this class backtracks to a more C-Styled Functional Programming Model (no Objects) - by re-using (quite profusely) the key-word static with all of its methods, and by sticking to Java's well-understood class Vector

    Internal-State: A user may click on this class' source code (see link below) to view any and all internally defined fields class. A cursory inspection of the code would prove that this class has precisely zero internally defined global fields (Spaghetti). All variables used by the methods in this class are local fields only, and therefore this class ought to be though of as 'state-less'.



    • Method Detail

      • descriptionAtTop

        public static DotPair descriptionAtTop​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        This will return the "class or interface (or enumerated-type 'enum')" that is always printed at the very top of any JavaDoc generated documentation file. The example included in this method description shall be the javadoc generated "description" for class 'Torello.Java.FileRW'

        HTML Elements:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        25
        26
        27
        28
        29
        30
        31
        32
        33
        34
        35
        36
        37
        38
        39
        40
        41
        42
        43
        44
        45
        46
        47
        48
        49
        <!-- The following HTML was just copied/lifted from the documentation of the FileRW class on June 1st, 2019 -->
        <!-- It may have changed since then, but unlikely -->
        
        </a></div>
        <!-- ========= END OF TOP NAVBAR ========= -->
        <!-- ======== START OF CLASS DATA ======== -->
        <div class="header">
        <div class="subTitle">Torello.Java</div>
        <h2 title="Class FileRW" class="title">Class FileRW</h2>
        </div>
        <div class="contentContainer">
        <ul class="inheritance">
        <li>java.lang.Object</li>
        <li>
        <ul class="inheritance">
        <li>Torello.Java.FileRW</li>
        </ul>
        </li>
        </ul>
        <div class="description"> <!-- THIS RIGHT HERE IS THE HTML 'DIVIDER' whose 'innerHTML' CONTENTS HOLD THE CLASS DESCRIPTION. -->
        <ul class="blockList">
        <li class="blockList">
        <hr>
        <br>
        <pre>public class <a href="../../src-html/Torello/Java/FileRW.html#line.25">FileRW</a>
        extends java.lang.Object</pre>
        <div class="block">The purpose of this class is to simplify quite a few of the standard java.io.* file operations.  The operations that Java provides are
        mostly "pretty useful" - however, if one is <i>not concerned with the optimization of read's or write's</i>, what this package provides
        is many orders of <b>code simplification.</b>  Many of the append and write operations instantiate a <code>java.io.File and
        java.io.OutputStream</code>, and open and close those objects/classes in the same method/function body.
        
        <BR /><BR />
        <b>FileRW.append()</b> for instance, opens the File-Pointer, writes the String, and then closes it immediately.  However, the 4 or 5
        lines of code that each of these methods/functions eliminate make text-processing code and language-translation code a lot easier to read.
        With text-processing and language-translation, I find myself writing file data once a day, and never for very long.  A few milliseconds is
        expended by opening and closing these file-pointers, but the code that I have written is world's easier to read.
        
        <BR /><BR />
        <b>FileRW.writeObjectToFile()</b> for instance, allows a user who is writing Vector<String> <i>(which for all intents-and-purposes is
        Java's way of saying "data-file" (object-serialization))</i>, to write the Vector-Class to a file in a single line of code.  This utilizes Java's
        object-serialization code, compression code, and file-io code in a single method, efficiently.</div>
        </li>
        </ul>
        </div>
        <div class="summary">
        <ul class="blockList">
        <li class="blockList">
        <!-- ======== CONSTRUCTOR SUMMARY ======== -->
        <ul class="blockList">
        
        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        Returns:
        A 'DotPair' pointer that holds pointers to the starting-position and ending-position in a vectorized-html web-page, in this case an HTML page generated by Java's 'javadoc' executable utility for generating code-documentation, ... to the class-description section at the top of the page.

        NOTE: If any insertion of HTML is going to happen, it is usually better to insert such elements inside of an <LI>...</LI> pair inside the HTML Un-Ordered List - which is the only element inside the HTML DIV element in a javadoc generated HTML class-description page.
        See Also:
        dividerInsideDescriptionAtTop(Vector), InnerTagFindInclusive, TextComparitor
        Code:
        Exact Method Body:
        1
        2
         return InnerTagFindInclusive.first
             (javaDocHTMLCIETPage, "div", "class", TextComparitor.C, "description");
        
      • dividerInsideDescriptionAtTop

        public static DotPair dividerInsideDescriptionAtTop​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        It becomes difficult to explain, but the "Description Divider" (at the top of a javadoc created HTML class-file) actually just, sort-of, 'wraps' and another HTML "divider" (<DIV ...> </DIV>) element. If, by some chance, a programmer has decided to insert HTML into the top of an HTML java-doc class-description file, and he / she would like to preserve / utilize the CSS-Styling that is (automatically) assigned by JavaDoc to the rest of content in that page, then inserting at the beginning or end of the HTML "Description Divider" - rather than the internal "block" divider will produce a situation where the inserted HTML is not formatted the same way, using the same fonts as the rest of the text in the class-description

        SUMMARY: If a programmer wants to 'borrow' or 'inherit' the style & font assignments that are assigned by the CSS definition to the HTML text being inserted, use method:

        Java Method Signature:
        1
        2
         public static DotPair dividerInsideDescriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage)
         
        

        Rather than the method:

        Java Method Signature:
        1
        2
         public static DotPair descriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage)
         
        
        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        Returns:
        A 'DotPair' pointer that holds pointers to the starting-position and ending-position in a vectorized-html web-page, in this case an HTML page generated by Java's 'javadoc' executable utility for generating code-documentation, ... to the HTML <DIV CLASS='block'>...</DIV> class-description section at the top of the page.
        See Also:
        descriptionAtTop(Vector), InnerTagFindInclusive, TextComparitor
        Code:
        Exact Method Body:
        1
        2
        3
        4
        5
        6
         DotPair dp = descriptionAtTop(javaDocHTMLCIETPage);
        
         if (dp == null) return null;
        
         return InnerTagFindInclusive.first
             (javaDocHTMLCIETPage, dp.start, dp.end + 1, "div", "class", TextComparitor.C, "block");
        
      • title

        public static DotPair title​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        This returns a DotPair (start & end integer vector-index pointers) to the HTML "title" element that contains the "Class, Interface, or Enumerated-Type Name" that is at the top of all Java-Doc Generated Web-Page. What the HTML actually looks like is included in the HTML-Snippet below:

        HTML Elements:
        1
        2
        3
         <!-- In any Java-Doc Generated HTML-Description Web-Page, the "Title" HTML looks like this: -->
         <h2 title="Class HTMLNode" class="title">Class HTMLNode</h2>
         
        
        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        Returns:
        A 'DotPair' pointer that holds pointers to the starting-position and ending-position in a vectorized-html web-page of the "title" (<h2 title="Class HTMLNode" class="title"> ... title ...</h2>) for any class, interface or enumerated-type JavaDoc Generated Web-Page.
        See Also:
        CommentNodeFind, InnerTagFindInclusive, TextComparitor
        Code:
        Exact Method Body:
        1
        2
        3
        4
        5
        6
        7
         int pos = CommentNodeFind.first
             (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");
        
         if (pos == -1) return null;
        
         return InnerTagFindInclusive.first
             (javaDocHTMLCIETPage, "h2", "class", TextComparitor.C, "title");
        
      • titleAsString

        public static java.lang.String titleAsString​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        This returns the Title of this JavaDoc HTML Documentation Page as a String. This String will have the "Class, Interface, or Enumerated-Type Name" that is at the top of all Java-Doc Generated Web-Pages. What the HTML actually looks like is included in the HTML-Snippet below:

        HTML Elements:
        1
        2
        3
         <!-- In any Java-Doc Generated HTML-Description Web-Page, the "Title" HTML looks like this: -->
         <h2 title="Class HTMLNode" class="title">Class HTMLNode</h2>
         
        
        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        Returns:
        A 'DotPair' pointer that holds pointers to the starting-position and ending-position in a vectorized-html web-page of the "title" (<h2 title="Class HTMLNode" class="title"> ... title ...</h2>) for any class, interface or enumerated-type JavaDoc Generated Web-Page.
        See Also:
        Util.textNodesString(Vector), CommentNodeFind, InnerTagFindInclusive, TextComparitor
        Code:
        Exact Method Body:
        1
        2
        3
        4
        5
        6
        7
        8
        9
         int pos = CommentNodeFind.first
             (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");
        
         if (pos == -1) return null;
        
         Vector<HTMLNode> v = InnerTagGetInclusive.first
             (javaDocHTMLCIETPage, "h2", "class", TextComparitor.C, "title");
        
         return Escape.replace(Util.textNodesString(v));
        
      • inheritance

        public static java.util.Vector<SubSectioninheritance​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        This returns a DotPair (start & end integer vector-index pointers) to the HTML "Unordered List" element that contains the "Class or Interface Inheritance Specification" which is at the top of all Java-Doc Generated Class or Interface Description Web-Pages. What the HTML actually looks like is included in the hilited code below:

        HTML Elements:
        1
        2
        3
        4
        5
        6
         <!-- In Java-Doc Generated HTML-Description Web-Pages, the "Inheritance List" HTML looks like: -->
         <!-- In this particular case, "class CommentNode" (which inherits from HTMLNode) is used -->
         <ul class="inheritance">
         <li>Torello.HTML.HTMLNode</li>
         </ul>
         
        
        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        Returns:
        A 'DotPair' pointer that holds pointers to the starting-position and ending-position in a vectorized-html web-page of the "inheritance Unordered List" (<ul class="inheritance"> ... </ul>) for any class or interface JavaDoc Generated Web-Page. If this web-page is not a javaDoc generated web-page, or is a part of a web-page that does not contain the information, then this method will return null, gracefully. No Exceptions will be thrown.
        See Also:
        CommentNodeFind, InnerTagPeekInclusive, TextComparitor
        Code:
        Exact Method Body:
        1
        2
        3
        4
        5
        6
        7
         int pos = CommentNodeFind.first
             (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");
        
         if (pos == -1) return null;
        
         return InnerTagPeekInclusive.all
             (javaDocHTMLCIETPage, pos, -1, "ul", "class", TextComparitor.C, "inheritance");
        
      • packageInfo

        public static DotPair packageInfo​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        This returns a DotPair (start & end integer vector-index pointers) to the HTML Divider-Element ("<DIV ...>") that contains the "Package Name" in which this class, interface, or enumerated-type is located. The package information is located at the top of all Java-Doc Generated Class or Interface Description Web-Pages. What the HTML actually looks like is included in the hilited code below:

        HTML Elements:
        1
        2
        3
         <!-- In Java-Doc Generated HTML-Description Web-Pages, the "Containing Package" HTML looks like: -->
         <div class="subTitle">Torello.HTML</div>
         
        
        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        Returns:
        A 'DotPair' pointer that holds pointers to the starting-position and ending-position in a vectorized-html web-page of the "Package Information" (<div class="subTitle"> ... </div>) for any class, interface, or enumerated-type JavaDoc Generated Web-Page. If this web-page is not a javaDoc generated web-page, or is a part of a web-page that does not contain the information, then this method will return null, gracefully; and no exceptions will be thrown.
        See Also:
        CommentNodeFind, InnerTagFindInclusive, TextComparitor
        Code:
        Exact Method Body:
        1
        2
        3
        4
        5
        6
        7
         int pos = CommentNodeFind.first
             (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");
        
         if (pos == -1) return null;
        
         return InnerTagFindInclusive.first
             (javaDocHTMLCIETPage, pos, -1, "div", "class", TextComparitor.C, "subTitle");
        
      • packageInfoAsString

        public static java.lang.String packageInfoAsString​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        Rather than returning an vectorized-html sublist - which is what method 'package(Vector<HTMLNode>)' does - this method finds the "Package Name" itself and returns that as a regular java-string. This operation can be performed on a class, interface, or enumerated-type. This package-information is located at the top of all Java-Doc Description Web-Pages. What the HTML actually looks like is included in the hilited code below:

        HTML Elements:
        1
        2
        3
         <!-- In Java-Doc Generated HTML-Description Web-Pages, the "Containing Package" HTML looks like:
         <div class="subTitle">Torello.HTML</div>
         
        
        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        Returns:
        A string that contains "Package Information" for any class, interface, or enumerated-type JavaDoc Generated Web-Page. If this web-page is not a javaDoc generated web-page, or is a part of a web-page that does not contain the information, then this method will return null, gracefully; and no exceptions will throw.
        See Also:
        Util.textNodesString(Vector), CommentNodeFind, InnerTagGetInclusive, TextComparitor
        Code:
        Exact Method Body:
        1
        2
        3
        4
        5
        6
        7
        8
        9
         int pos = CommentNodeFind.first
             (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");
        
         if (pos == -1) return null;
        
         Vector<HTMLNode> v = InnerTagGetInclusive.first
             (javaDocHTMLCIETPage, pos, -1, "class", TextComparitor.C, "subTitle");
        
         return Escape.replace(Util.textNodesString(v));
        
      • allTopDLs

        public static java.util.Vector<DotPairallTopDLs​
                    (java.util.Vector<HTMLNode> javaDocHTMLCIETPage)
        
        Returns all of the HTML Element "<DL> ... </DL>" sublists at the top of a CIET (Class, Interface, or Enumerated-Type) java web-page. This contains a plethora of variants, depending on whether the particular documentation page is for a class, an interface, a function-interface, a static-inner-class, an enumerated type, etc. Below is an example piece of HTML for the class "CommentNode." There are many other versions for this sub-list, and it would be best to run this method-operation on different HTML Documentation Pages to see all the possible versions of <DD> and <DT> definitions that are possible in this <DL> ... </DL> sublist occurring in the "Description-at-Top" of a javadoc web-pge.

        HTML Elements:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
         <!-- In Java-Doc Generated HTML-Description Web-Pages, the top "DL" HTML Element looks like: -->
         <dl>
         <dt>All Implemented Interfaces:</dt>
         <dd>java.io.Serializable, java.lang.CharSequence, java.lang.Cloneable</dd>
         </dl>
         <dl>
         <dt>Direct Known Subclasses:</dt>
         <dd><a href="../../Torello/HTML/CommentNode.html" title="class in Torello.HTML">CommentNode</a>, <a href="../../Torello/HTML/TagNode.html" title="class in Torello.HTML">TagNode</a>, <a href="../../Torello/HTML/TextNode.html" title="class in Torello.HTML">TextNode</a></dd>
         </dl>
         
        
        Parameters:
        javaDocHTMLCIETPage - This should be a vectorized-HTML Java-Doc Generated Documentation Page for a CIET (Class, Interface, or Enumerated-Type). Load a Vector of HTMLNode for JavaDoc generated page the exact same way that any other HTML Page is vectorized into TagNode, TextNode, and CommentNode.
        See Also:
        CommentNodeFind, TagNodeFindInclusive, TextComparitor
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
         int sPos = CommentNodeFind.first
             (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");
        
         if (sPos == -1) return null;
        
         int ePos = TagNodeFind.first(javaDocHTMLCIETPage, sPos, -1, TC.OpeningTags, "hr");
        
         if (ePos == -1) return null;
        
         return TagNodeFindInclusive.all(javaDocHTMLCIETPage, sPos, ePos, "dl");