Class JavaDocHTMLFile

  • All Implemented Interfaces:
    java.io.Serializable
    public final class JavaDocHTMLFile
extends ParsedFile
implements java.io.Serializable
    Optional-Extension Class of a Basic-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

    Alternatively:
    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:
    JavaSourceCodeFile, Serialized Form


    • Method Detail

      • allNonNullSummaryTables

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Iterator<SummaryTableHTML> allNonNullSummaryTables()
        An Iterator that iterates the Summary Tables defined on this page.
        Returns:
        An Instance of Iterator<SummaryTableHTML>.

        NOTE: There is a raw-type used by the Iterator that is returned. If this method is invoked, it will either generate compiler warnings, or the @SuppressWarnings("rawtypes") annotation will need to be applied (and, likely, the suppressing of "unchecked" warnings will also have to be applied eventually)
        Code:
        Exact Method Body:
         return new RemoveUnsupportedIterator<>(allNonNullSummaryTables.iterator());

      • allNonNullSummaryTablesStream

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.stream.Stream<SummaryTableHTML> allNonNullSummaryTablesStream
            ()
        An Stream of the Summary Tables defined on this page.
        Returns:
        An Instance of Stream<SummaryTableHTML>.

        NOTE: There is a raw-type used by the Stream that is returned. If this method is invoked, it will either generate compiler warnings, or the @SuppressWarnings("rawtypes") annotation will need to be applied (and, likely, the suppressing of "unchecked" warnings will also have to be applied eventually)
        Code:
        Exact Method Body:
         return allNonNullSummaryTables.stream();

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