Class JavaDocHTMLFile

  • All Implemented Interfaces:
    java.io.Serializable
    public final class JavaDocHTMLFile
extends ParsedFile
implements java.io.Serializable

    Optional-Extension Class of a Simple-Upgrade:

    Running a Standard-Upgrade on a Java-Doc Web-Page Directory-Tree only requires building an instance of class Upgrade, and executing its upgrade() method!

    The Standard-Upgrade Process will insert CSS-Tags, Hi-Lite Properly-Marked Code-Snippet <DIV>'s, Hi-Lite all Method-Bodies & Field-Declarations, and even create Navigation-Menu Links. If more fine-grained control is needed, this class provides direct access to the Java Doc Web-Page HTML.

    Accessing this Class:
    This class may be accessed by utilizing a configuration method in class Upgrade, specifically calling:

    Upgrade.setExtraTasks(Consumer<JavaDocHTMLFile> handler)

    ... with a handler (a java.util.function.Consumer instance) that receives a JavaDocHTMLFile instance.

    Class JavaDocHTMLFile provides access to every HTML Component on a Java-Doc Web-Page. If programmatic changes to a Java-Doc Web-Page are needed, these Reflection-API classes make it easy to change, update, remove & add-to the HTML on these pages. Simply registering a handler with the Upgrader, make the necessary improvements, and they will be incorporated into the final-output HTML-Page.

    Again, class JavaDocHTMLFile has getters for: HeaderFooterHTML, SummaryTableHTML and ReflHTML


    Access Alternative:
    Creating an instance of one of the two offered "User-Processor" classes - both of which have several listener/handler methods - is also a great way to access the Reflection-HTML API. These two Java Interfaces are:

    Retains all information parsed from a '.html' Java-Doc web-page, and borrows any missing information that was found in the '.java' source-code file; note that an instance-reference of this class may be rerieved, and used, to further change a Java Doc page by registering a visitor-handler with the configuration class Upgrade by calling Upgrade.setExtraTasks(Consumer).

    This Class May be Used to Programmatically Modify JavaDoc HTML

    Modifying JavaDoc HTML can be done using: JavaDocHTMLFile, SummaryTableHTML, ReflHTML and HeaderFooterHTML.

    To get instances of these classes, just register a listener with the Upgrader using: Upgrade.setExtraTasks
    This is optional, as the Standard Upgrader-Features do not necessitate use of this class.
    This class is used to "Parse" an already vectorized-html web-page that is, specifically, a page that was generated by the Java-Doc HTML code-documentation page-generator tool. This class works in tandem with the class JavaSourceCodeFile which uses the more advanced 'Java Parser' tool to parse '.java' source-code files into lists of method, constructor and field definitions. The features of both of these classes is similar to the features that Java's "Reflection A.P.I." offers:

    1. class JavaSourceCodeFile - Parses '.java' Source-Code Files
    2. class JavaDocHTMLFile - Extracts Method, Constructor & Field Info from '.html' javadoc files.

    This class, which is the second listed in the above list, simply retrieves the method names, constructor names and method-types (and constructor-types, etc...). With this information encapsulated in string-format, the internal JavaDoc Upgrader can find additional information that the original javadoc tool (written in the 1990's) does not include in the output documentation web-pages. The primary point to remember about this class, though, is that in order to "insert / update" more information into the output '.html' web-page files, the information which comes from the '.java' source-code files needs to do some work to be able to "automatically map" a method, constructor, or field definition on a documentation page with the same method, constructor or field defined in the source-code file. In order to do this, both files need to have their lists of these things parsed and converted into something simple and manageable. This class parses the "web-page .html files." The other class - 'JavaSourceCodeFile' - parses '.java' files and builds the exact same lists of String's so that both files may be matched.

    In order to retrieve Java Method and Constructor bodies as String's - and perform the syntax hiliting needed to insert them into the JavaDoc Web-Pages, both of these parsers are needed to do an upgrade.
    See Also:
    Serialized Form


    • Field Detail

      • serialVersionUID

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public 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:
         public static final long serialVersionUID = 1;

      • dotDots

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final RelativePathStr dotDots
        This provides the relative path-String from 'this' Java Doc generated '.html' File to the root Java Doc Directory.
        Code:
        Exact Field Declaration Expression:
         public final RelativePathStr dotDots;

      • javaDocPackageDirName

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String javaDocPackageDirName
        Directory-Name of the Java-Doc Sub-Directory that contains this Java-Doc '.html'-File. This sub-directory should just be the name of the Root Java-Doc Directory, with this class' Full Package-Name appended to it.

        If the JPMS (Java Platform Module System) has been used by a User-Project that contains multiple Java-Modules, then this directory shall also be pre-fixed with the relevant module containing this directory.
        Code:
        Exact Field Declaration Expression:
         public final String javaDocPackageDirName;

      • javaDocPkgHiLitedSrcCodeDirName

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String javaDocPkgHiLitedSrcCodeDirName
        Directory-Name of the Java-Doc Sub-Directory that contains the Hi-Lited Source-Code '.html'-Files for the Java-Classes which are included in the Java-Package to which this particular Java-Class belongs.

        Unless instructed otherwise, the JDU spends effort to provide Syntax-HiLited '.html'-Files for each and every one of the Classes in a User's Java-Project. These files are each saved in the Hi-Lite Directory that is germaine / relevant for the given Java-Package to which the given Java-Class belongs.
        Code:
        Exact Field Declaration Expression:
         public final String javaDocPkgHiLitedSrcCodeDirName;

      • headerFooter

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final HeaderFooterHTML headerFooter
        The HTML that occurs directly above the Summary-Tables is the header. The HTML that is located below the Detail-Entries is the footer.
        Code:
        Exact Field Declaration Expression:
         public final HeaderFooterHTML headerFooter;

      • srcAsHTMLFileURL

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String srcAsHTMLFileURL
        This is the File-URL to use if a need to link to the corresponding "/src-html/" file is necessary.

        This is a relative-URL that contains the requisite number of 'dot-dots' to reach the file from the location where this Java Doc HTML File is located.
        Code:
        Exact Field Declaration Expression:
         public final String srcAsHTMLFileURL;

      • hiLitedSrcFileURL

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final java.lang.String hiLitedSrcFileURL
        This is the File-URL to use if a need to link to the corresponding "/hilite-files/" file is necessary.

        This is a relative-URL that is relative to the file from the location where this Java Doc HTML File is located. Specifically, this String begins with the text "/hilite-files/", followed by the type-name, and ending with the extension ".java.html"
        Code:
        Exact Field Declaration Expression:
         public final String hiLitedSrcFileURL;

      • pkgSummaryHTML

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final PackageSummaryHTML pkgSummaryHTML
        This is a reference to the parsed, 'package-summary.html' File for the Project's 'Java-Package' to which this class belongs.
        Code:
        Exact Field Declaration Expression:
         public final PackageSummaryHTML pkgSummaryHTML;

      • methodDetailsRemoved

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean methodDetailsRemoved
        Identifies if this Java Doc HTML Page has had it's Method Details Removed
        Code:
        Exact Field Declaration Expression:
         public final boolean methodDetailsRemoved;

      • constructorDetailsRemoved

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean constructorDetailsRemoved
        Identifies if this Java Doc HTML Page has had it's Constructor Details Removed
        Code:
        Exact Field Declaration Expression:
         public final boolean constructorDetailsRemoved;

      • fieldDetailsRemoved

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean fieldDetailsRemoved
        Identifies if this Java Doc HTML Page has had it's Field Details Removed
        Code:
        Exact Field Declaration Expression:
         public final boolean fieldDetailsRemoved;

      • ecDetailsRemoved

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean ecDetailsRemoved
        Identifies if this Java Doc HTML Page has had it's Enumeration Constant Details Removed
        Code:
        Exact Field Declaration Expression:
         public final boolean ecDetailsRemoved;

      • aeDetailsRemoved

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final boolean aeDetailsRemoved
        Identifies if this Java Doc HTML Page has had it's Annotation-Element Details Removed
        Code:
        Exact Field Declaration Expression:
         public final boolean aeDetailsRemoved;

    • Method Detail

      • findMethodHTML

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.stream.Stream<ReflHTML<Method>> findMethodHTML​
            (java.lang.String methodName)
        Returns a list as a java.util.stream.Stream of all Reflected-HTML-Method instances that have a name equal to 'methodName'.
        Parameters:
        methodName - The name of the method being searched for.
        Returns:
        A Java Stream containing all Method-ReflHTML instances that match the provided 'methodName' criteria.
        Code:
        Exact Method Body:
         return allMethodDetails
     .stream()
     .filter((ReflHTML<Method> refl) -> refl.entity.name.equals(methodName));

      • findMethodHTML

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.stream.Stream<ReflHTML<Method>> findMethodHTML​
            (int numParameters)
        Returns a list as a java.util.stream.Stream of all Reflected-HTML-Method instances that have the specified number of parameters.
        Parameters:
        numParameters - The number of parameters contained by the Method being searched for.
        Returns:
        A Java Stream containing all Method-ReflHTML instances that match the provided 'numParameters' criteria.
        Code:
        Exact Method Body:
         return allMethodDetails
     .stream()
     .filter((ReflHTML<Method> refl) -> refl.entity.numParameters() == numParameters);

      • findConstructorHTML

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.stream.Stream<ReflHTML<Constructor>> findConstructorHTML​
            (int numParameters)
        Returns a list as a java.util.stream.Stream of all Reflected-HTML-Constructor instances that have the specified number of parameters.
        Parameters:
        numParameters - The number of parameters contained by the Constructor being searched for.
        Returns:
        A Java Stream containing all Constructor-ReflHTML instances that match the provided 'numParameters' specifier.
        Code:
        Exact Method Body:
         return allConstructorDetails
     .stream()
     .filter((ReflHTML<Constructor> refl) -> refl.entity.numParameters() == numParameters);

      • findFieldHTML

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReflHTML<Field> findFieldHTML​(java.lang.String fieldName)
        The Reflected-HTML Field having the specified name, or null if no such field exists
        Parameters:
        fieldName - The name of the field being searched
        Returns:
        The ReflHTML<Field> instance, from 'this' Java Doc Page, whose name matches fieldName, or null it wasn't found.
        Code:
        Exact Method Body:
         for (ReflHTML<Field> f : allFieldDetails) if (f.entity.name.equals(fieldName)) return f;
 return null;

      • findECHTML

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReflHTML<EnumConstant> findECHTML​
            (java.lang.String enumConstantName)
        The Reflected-HTML Enum-Constant having the specified name, or null if no such constant exists
        Parameters:
        enumConstantName - The name of the constant being searched
        Returns:
        The ReflHTML<EnumConstant> instance, from 'this' Java Doc Page, whose name matches enumConstantName, or null it wasn't found.
        Throws:
        UpgradeException - Only a Java CIET/Type 'enum' is allowed to declare Enum-Constants, and therefore this exception throws when this method is invoked on a Java Doc HTML File that doesn't represent an enum.
        Code:
        Exact Method Body:
         if (this.ciet != CIET.ENUM) throw new UpgradeException(
     "Finding Enumeration-Constants is only possible with HTML Files for Java 'enum' " +
     "Type's.  This file is of type [" + this.ciet.toString() + "]"
 );

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

 return null;

      • findAEHTML

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReflHTML<AnnotationElem> findAEHTML​
            (java.lang.String annotationElemName)
        The Reflected-HTML Annotation-Element having the specified name, or null if no such element exists
        Parameters:
        annotationElemName - The name of the constant being searched
        Returns:
        The ReflHTML<EnumConstant> instance, from 'this' Java Doc Page, whose name matches annotationElemName, or null it wasn't found.
        Throws:
        UpgradeException - Only a Java CIET/Type '@interface' is allowed to declare Annotation-Elements, and therefore this exception throws when this method is invoked on a Java Doc HTML File that doesn't represent an annotation.
        Code:
        Exact Method Body:
         if (this.ciet != CIET.ANNOTATION) throw new UpgradeException(
     "Finding Annotation-Elements is only possible with HTML Files for Java '@interface' " +
     "(Annotation) Type's.  This file is of type [" + this.ciet.toString() + "]"
 );

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

 return null;

      • findReflHTML

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public <ENTITY extends Declaration> ReflHTML<ENTITY> findReflHTML​
            (int declarationID,
             java.lang.Class<ENTITY> c)
        Finds a matching ReflHTML instance whose internal 'entity' field has an ID number that matches input-parameter 'declarationID'.
        Parameters:
        declarationID - Whenever any instance of a sub-class of Declaration is created, it is given a unique id that uniquely identifies it across the entire life-cycle of the JVM that is currently running.
        c - This must be a Java java.lang.Class from one of the following: Constructor, Method, Field, EnumConstant or AnnotationElem.

        NOTE: This class is very easily obtained by simple using the 'enum' field Entity.upgraderReflectionClass. To pass the appropriate class for a method, simply pass Entity.METHOD.upgraderReflectionClass to this parameter.

        ALSO: Even more easy (if you know the member/entity type), you can hard-code / hand-type the class yourself - for instance Method.class. If you were searching for a ReflHTML<Field>, you would pass Field.class to this parameter.
        Returns:
        The ReflHTML instance whose HTML describes the Method, Field, or Constructor etc... whose actual Reflected-class has an ID that matches 'declarationID'. Note that the second parameter 'c' is primarily used to "speed up" the search process.

        Example:
         // Note the 'Method' being passed is Torello.JavaDoc.Method (not java.lang.reflect.Method)
 ReflHTML<Method> refl = jdhf.findEntity(someEntityID, Method.class);
        Throws:
        java.lang.IllegalArgumentException - If the value passed to 'declarationID' is negative.
        Code:
        Exact Method Body:
         if (declarationID < 0) throw new IllegalArgumentException
     ("You have passed a negative declarationID: " + declarationID);

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

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

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

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

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

 return null;

      • allIDsAndHREFs

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public Ret2<java.util.TreeSet<java.lang.String>,​java.util.TreeSet<java.lang.String>> allIDsAndHREFs
            ()
        Code:
        Exact Method Body:
         TreeSet<String> allIDs      = new TreeSet<>();
 TreeSet<String> allHREFs    = new TreeSet<>();
 TagNode         tn          = null;

 for (HTMLNode n : updatedFileVec)

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

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

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

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

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

 return new Ret2<>(allIDs, allHREFs);