Class JavaDocHTMLFile

  • All Implemented Interfaces:
    java.io.Serializable

    public final class JavaDocHTMLFile
    extends ParsedFile
    implements java.io.Serializable
    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 and ReflHTML.
    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


    • 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 java.lang.String 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 String dotDots;
        
      • 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

      • pageTop

        🡅  🡇    
        public java.util.Vector<HTMLNodepageTop()
        Retrievs the Header and top-portion of a Java Doc Generatd Web-Page. This may be modified and the changes will be committed to disk before the upgrader exits.
        Returns:
        Vectorized-HTML of all nodes in a Java Doc Web-Page starting at vector-index '0' and ending at the node directly previous to the opening summary-node: .
        Code:
        Exact Method Body:
         return pageTop.html;
        
      • allNonNullSummaryTables

        🡅  🡇    
        public java.util.Iterator<SummaryTableHTMLallNonNullSummaryTables()
        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<SummaryTableHTMLallNonNullSummaryTablesStream
                    ()
        
        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();
        
      • pageTail

        🡅  🡇    
        public java.util.Vector<HTMLNodepageTail()
        Retrieves the Footer of a Java Doc Generated Web-Page. This may be modified and the changes will be incorporated back into the page before the page is comitted to disk.
        Returns:
        Vectorized-HTML of all nodes in a Java Doc Web-Page starting at the vector-index just after the closing-</DIV> of the "Details Section"
        Code:
        Exact Method Body:
         return pageTail.html;
        
      • allFieldDetails

        🡅  🡇    
        public java.util.stream.Stream<ReflHTML<Field>> allFieldDetails()
        This creates a stream of all of the Field's Details Sections on this Java Doc Web-Page. The ReflHTML<Field> instances hold all of the HTML for the 'Field' that was placed on the page by Java Doc.

        IMPORTANT: The use of retrieving these lists is that is that they may be used in conjunction with an an 'Extra-Tasks' Visitor/Handler to modify the HTML on a Java Doc Web-Page, in any way deemed necessary. Just register a handler with the Upgrade.extraTask configuration method. The method you write will be able to change, programmatically, the contents of Field "Details Sections" on the web-page.
        Returns:
        A stream of all Field Details
        Code:
        Exact Method Body:
         return allFieldDetails.stream();
        
      • allConstructorDetails

        🡅  🡇    
        public java.util.stream.Stream<ReflHTML<Constructor>> allConstructorDetails
                    ()
        
        This creates a stream of all of the Constructor's Details Sections on this Java Doc Web-Page. The ReflHTML<Constructor> instances hold all of the HTML for the 'Constructor' that was placed on the page by Java Doc.

        IMPORTANT: The use of retrieving these lists is that is that they may be used in conjunction with an an 'Extra-Tasks' Visitor/Handler to modify the HTML on a Java Doc Web-Page, in any way deemed necessary. Just register a handler with the Upgrade.extraTask configuration method. The method you write will be able to change, programmatically, the contents of Constructor "Details Sections" on the web-page.
        Returns:
        A stream of all Constructor Details
        Code:
        Exact Method Body:
         return allConstructorDetails.stream();
        
      • allMethodDetails

        🡅  🡇    
        public java.util.stream.Stream<ReflHTML<Method>> allMethodDetails()
        This creates a stream of all of the Method's Details Sections on this Java Doc Web-Page. The ReflHTML<Method> instances hold all of the HTML for the 'Method' that was placed on the page by Java Doc.

        IMPORTANT: The use of retrieving these lists is that is that they may be used in conjunction with an an 'Extra-Tasks' Visitor/Handler to modify the HTML on a Java Doc Web-Page, in any way deemed necessary. Just register a handler with the Upgrade.extraTask configuration method. The method you write will be able to change, programmatically, the contents of Method "Details Sections" on the web-page.
        Returns:
        A stream of all Method Details
        Code:
        Exact Method Body:
         return allMethodDetails.stream();
        
      • allECDetails

        🡅  🡇    
        public java.util.stream.Stream<ReflHTML<EnumConstant>> allECDetails()
        This creates a stream of all of the Enumeration Constant's Details Sections on this Java Doc Web-Page. The ReflHTML<Enumeration Constant> instances hold all of the HTML for the 'Enumeration Constant' that was placed on the page by Java Doc.

        IMPORTANT: The use of retrieving these lists is that is that they may be used in conjunction with an an 'Extra-Tasks' Visitor/Handler to modify the HTML on a Java Doc Web-Page, in any way deemed necessary. Just register a handler with the Upgrade.extraTask configuration method. The method you write will be able to change, programmatically, the contents of Enumeration Constant "Details Sections" on the web-page.
        Returns:
        A stream of all Enumeration-Constant Details
        Throws:
        UpgradeException - If invoked on a Java Doc Web-Page that isn't an 'enum'
        Code:
        Exact Method Body:
         if (this.ciet != CIET.ENUM) throw new UpgradeException(
             "This Java Doc Web-Page is for a(n) [" + ciet.toString() + "], but only Java " +
             "enum's may define Enum-Constants."
         );
        
         return allECDetails.stream();
        
      • allAEDetails

        🡅  🡇    
        public java.util.stream.Stream<ReflHTML<AnnotationElem>> allAEDetails()
        This creates a stream of all of the Anotation Element's Details Sections on this Java Doc Web-Page. The ReflHTML<Anotation Element> instances hold all of the HTML for the 'Anotation Element' that was placed on the page by Java Doc.

        IMPORTANT: The use of retrieving these lists is that is that they may be used in conjunction with an an 'Extra-Tasks' Visitor/Handler to modify the HTML on a Java Doc Web-Page, in any way deemed necessary. Just register a handler with the Upgrade.extraTask configuration method. The method you write will be able to change, programmatically, the contents of Anotation Element "Details Sections" on the web-page.
        Returns:
        A stream of all Annotation-Element Details
        Throws:
        UpgradeException - If invoked on a Java Doc Web-Page that isn't an Annotation
        Code:
        Exact Method Body:
         if (this.ciet != CIET.ANNOTATION) throw new UpgradeException(
             "This Java Doc Web-Page is for a(n) [" + ciet.toString() + "], but only Java " +
             "Annotations may define Annotation-Elements."
         );
        
         return allAEDetails.stream();
        
      • fieldDetailsIterator

        🡅  🡇    
        public java.util.Iterator<ReflHTML<Field>> fieldDetailsIterator()
        This creates an Iterator that will iterate on the Detail's Section for Field's. The contents of the Iterator are SubSection, which, themselves, contain the HTML describing the 'Field' - and the location where that HTML is on the main Java Doc web-page, as a DotPair
        Returns:
        An Iterator<ReflHTML<Field>> for each "Field Details" entry
        See Also:
        RemoveUnsupportedIterator
        Code:
        Exact Method Body:
         return new RemoveUnsupportedIterator<>(allFieldDetails.iterator());
        
      • constructorDetailsIterator

        🡅  🡇    
        public java.util.Iterator<ReflHTML<Constructor>> constructorDetailsIterator
                    ()
        
        This creates an Iterator that will iterate on the Detail's Section for Constructor's. The contents of the Iterator are SubSection, which, themselves, contain the HTML describing the 'Constructor' - and the location where that HTML is on the main Java Doc web-page, as a DotPair
        Returns:
        An Iterator<ReflHTML<Constructor>> for each "Constructor Details" entry
        See Also:
        RemoveUnsupportedIterator
        Code:
        Exact Method Body:
         return new RemoveUnsupportedIterator<>(allConstructorDetails.iterator());
        
      • methodDetailsIterator

        🡅  🡇    
        public java.util.Iterator<ReflHTML<Method>> methodDetailsIterator()
        This creates an Iterator that will iterate on the Detail's Section for Method's. The contents of the Iterator are SubSection, which, themselves, contain the HTML describing the 'Method' - and the location where that HTML is on the main Java Doc web-page, as a DotPair
        Returns:
        An Iterator<ReflHTML<Method>> for each "Method Details" entry
        See Also:
        RemoveUnsupportedIterator
        Code:
        Exact Method Body:
         return new RemoveUnsupportedIterator<>(allMethodDetails.iterator());
        
      • ecDetailsIterator

        🡅  🡇    
        public java.util.Iterator<ReflHTML<EnumConstant>> ecDetailsIterator()
        This creates an Iterator that will iterate on the Detail's Section for Enumeration Constant's. The contents of the Iterator are SubSection, which, themselves, contain the HTML describing the 'Enumeration Constant' - and the location where that HTML is on the main Java Doc web-page, as a DotPair
        Returns:
        An Iterator<ReflHTML<EnumConstant>> for each "Enumeration Constant Details" entry
        Throws:
        UpgradeException - If invoked on a Java Doc Web-Page that isn't an 'enum'
        See Also:
        RemoveUnsupportedIterator
        Code:
        Exact Method Body:
         if (this.ciet != CIET.ENUM) throw new UpgradeException(
             "This Java Doc Web-Page is for a(n) [" + ciet.toString() + "], but only Java " +
             "enum's may define Enum-Constants."
         );
        
         return new RemoveUnsupportedIterator<>(allECDetails.iterator());
        
      • aeDetailsIterator

        🡅  🡇    
        public java.util.Iterator<ReflHTML<AnnotationElem>> aeDetailsIterator()
        This creates an Iterator that will iterate on the Detail's Section for Annotation Element's. The contents of the Iterator are SubSection, which, themselves, contain the HTML describing the 'Annotation Element' - and the location where that HTML is on the main Java Doc web-page, as a DotPair
        Returns:
        An Iterator<ReflHTML<AnnotationElem>> for each "Annotation Element Details" entry
        Throws:
        UpgradeException - If invoked on a Java Doc Web-Page that isn't an Annotation.
        See Also:
        RemoveUnsupportedIterator
        Code:
        Exact Method Body:
         if (this.ciet != CIET.ANNOTATION) throw new UpgradeException(
             "This Java Doc Web-Page is for a(n) [" + ciet.toString() + "], but only Java " +
             "Annotations may define Annotation-Elements."
         );
        
         return new RemoveUnsupportedIterator<>(allAEDetails.iterator());
        
      • findMethodHTML

        🡅  🡇    
        public java.util.stream.Stream<ReflHTML<Method>> findMethodHTML​
                    (java.util.function.Predicate<Method> finder)
        
        Returns a list as a java.util.stream.Stream of all Reflected-HTML-Method instances that match a user-specified finder-predicate
        Parameters:
        finder - Any Predicate<Method>
        Returns:
        A Java Stream containing all Method-ReflHTML instances that were accepted by the finder's test() method.
        See Also:
        findMethodHTML(String)
        Code:
        Exact Method Body:
         Stream.Builder<ReflHTML<Method>> b = Stream.builder();
         for (ReflHTML<Method> m : allMethodDetails) if (finder.test(m.entity)) b.accept(m);
         return b.build();
        
      • findConstructorHTML

        🡅  🡇    
        public java.util.stream.Stream<ReflHTML<Constructor>> findConstructorHTML​
                    (java.util.function.Predicate<Constructor> finder)
        
        Returns a list as a java.util.stream.Stream of all Reflected-HTML-Constructor instances that match a user-specified finder-predicate
        Parameters:
        finder - Any Predicate<Constructor>
        Returns:
        A Java Stream containing all Constructor-ReflHTML instances that were accepted by the finder's test() method.
        See Also:
        findConstructorHTML(int)
        Code:
        Exact Method Body:
         Stream.Builder<ReflHTML<Constructor>> b = Stream.builder();
         for (ReflHTML<Constructor> c : allConstructorDetails) if (finder.test(c.entity)) b.accept(c);
         return b.build();
        
      • findFieldHTML

        🡅  🡇    
        public java.util.stream.Stream<ReflHTML<Field>> findFieldHTML​
                    (java.util.function.Predicate<Field> finder)
        
        Returns a list as a java.util.stream.Stream of all Reflected-HTML-Method instances that match a user-specified finder-predicate
        Parameters:
        finder - Any Predicate<Field>
        Returns:
        A Java Stream containing all Field-ReflHTML instances that were accepted by the finder's test() method
        Code:
        Exact Method Body:
         Stream.Builder<ReflHTML<Field>> b = Stream.builder();
         for (ReflHTML<Field> f : allFieldDetails) if (finder.test(f.entity)) b.accept(f);
         return b.build();
        
      • findECHTML

        🡅  🡇    
        public java.util.stream.Stream<ReflHTML<EnumConstant>> findECHTML​
                    (java.util.function.Predicate<EnumConstant> finder)
        
        Returns a list as a java.util.stream.Stream of all Reflected-HTML-EnumConstant instances that match a user-specified finder-predicate
        Parameters:
        finder - Any Predicate<EnumConstant>
        Returns:
        A Java Stream containing all EnumConstant-ReflHTML instances that were accepted by the finder's test() method
        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() + "]"
         );
        
         Stream.Builder<ReflHTML<EnumConstant>> b = Stream.builder();
         for (ReflHTML<EnumConstant> ec : allECDetails) if (finder.test(ec.entity)) b.accept(ec);
         return b.build();
        
      • findAEHTML

        🡅  🡇    
        public java.util.stream.Stream<ReflHTML<AnnotationElem>> findAEHTML​
                    (java.util.function.Predicate<AnnotationElem> finder)
        
        Returns a list as a java.util.stream.Stream of all Reflected-HTML-AnnotationElem instances that match a user-specified finder-predicate
        Parameters:
        finder - Any Predicate<AnnotationElem>
        Returns:
        A Java Stream containing all AnnotationElem-ReflHTML instances that were accepted by the finder's test() method
        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.ENUM) 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() + "]"
         );
        
         Stream.Builder<ReflHTML<AnnotationElem>> b = Stream.builder();
         for (ReflHTML<AnnotationElem> ae : allAEDetails) if (finder.test(ae.entity)) b.accept(ae);
         return b.build();
        
      • findFieldHTML

        🡅  🡇    
        public ReflHTML<FieldfindFieldHTML​(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<EnumConstantfindECHTML​
                    (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<AnnotationElemfindAEHTML​
                    (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;