Class JavaDocHTMLFile

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

    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.

    Below is the Inheritance Diagram for the two File-Parser Classes. Both of these classes (in the diagram) parse into an identical set of class-fields. The parsers, themselves, though achieve this through two very different means. One class is derived from a '.html' file, and the other a '.java' file.

    Parsed File Inheritance

    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:
        1
        public static final long serialVersionUID = 1;

    • Constructor Detail

      • JavaDocHTMLFile

        public JavaDocHTMLFile​(java.util.Vector<HTMLNode> fileVec,
                       java.lang.String jdHTMLFileName,
                       StorageWriter sw)
                throws java.io.IOException
        Constructs an instance of this class using a vectorized-HTML Java-Doc File.
        Parameters:
        fileVec - This is the vectorized-html for any javadoc generated HTML documentation page.
        jdHTMLFileName - This is the name of the '.html' file that was used to generate/produce the vectorized-html that is passed via the first parameter. The file-name as-a-String is requested by this constructor only for the purpose of better exception reporting. If an exception throws while iterating the methods, constructors and fields of the HTML, including the file-name in the exception message can be beneficial.
        sw - This will send information to the log.
        Throws:
        java.io.IOException

    • Method Detail

      • parseMethod

        protected static Method parseMethod​(java.lang.String methodSig,
                                    java.lang.String fileName,
                                    java.util.Vector<java.lang.String> gps)
        Parses the contents of an vectorized-html section containing one 'Method Details.' The method-details sections of java-doc generated HTML documentation pages contain the text for the method's description, signature, parameters-list, throwing-exceptions, etc.
        Parameters:
        methodSig - This is the 'Signature' part of a 'Method Details' section for a single Method in a JavaDoc Generated HTML web-documentation page.
        fileName - This is the name from which the signature is returned. It is needed because this method is actually declared 'static'. It is 'static' because it is also used elsewhere
        Returns:
        An instance of Method that has been parsed from the JavaDoc '.html' file.
        Throws:
        JavaDocHTMLParseException - If there are errors in the '.html' parse.
        Code:
        Exact Method Body:
         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
         String jpReadySig = null;

 try {
     // Append a semi-colon to the end of the method.
     jpReadySig  = VEC_TO_STRING_FOR_JP(methodSig, true, gps);

     return new Method(StaticJavaParser.parseMethodDeclaration(jpReadySig), true);
 }
 catch (Exception e)
 {
     throw new JavaDocHTMLParseException(
         "There was an error parsing the HTML from a Java-Doc Web-page.  One of the " +
         "declared methods from the page could not be parsed by the JavaParser Bridge " +
         "Classes, or that method's signature was not properly retrieved from the " +
         "JavaDoc Page.  The method that failed may be viewed by inspecting the " +
         "exception-field 'e.signature'.  Also, if an underlying-exception has been " +
         "thrown, e.getCause() will produce that cause-chain exception.",
         e, fileName,
         ((jpReadySig != null) 
             ? jpReadySig 
             : ((methodSig != null) 
                 ? methodSig 
                 : "METHOD-SIGNATURE NOT OBTAINED FROM HTML FILE AT TIME OF EXCEPTION THROW"))
     );
 }

      • parseConstructor

        protected static Constructor parseConstructor​
            (java.lang.String constructorSig,
             java.lang.String fileName,
             java.util.Vector<java.lang.String> gps)
        Parses the contents of an vectorized-html section containing one 'Constructor Details.' The constructor-details sections of java-doc generated HTML documentation pages contain the text for the constructor's description, signature, parameters-list, throwing-exceptions, etc.
        Parameters:
        constructorSig - This is the 'Signature' part of a 'Constructor Details' section for a single Constructor in a JavaDoc Generated HTML web-documentation page.
        fileName - This is the name from which the signature is returned. It is needed because this method is actually declared 'static'. It is 'static' because it is also used elsewhere
        Returns:
        An instance of Constructor that has been parsed from a JavaDoc '.html' file.
        Throws:
        JavaDocHTMLParseException - If there are errors in the '.html' parse.
        Code:
        Exact Method Body:
         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
         String jpReadySig = null;

 try {
     // false -> DOES NOT need semi-colon (this is for a constructor)
     jpReadySig = VEC_TO_STRING_FOR_JP(constructorSig, false, gps);

     // It needs an ending "{ }" instead!
     BodyDeclaration<?>  bd  = StaticJavaParser.parseBodyDeclaration(jpReadySig + "{ }");

     Constructor c = (bd == null)
                         ? null
                         : (bd.isConstructorDeclaration() 
                             ? new Constructor((ConstructorDeclaration) bd, true) 
                             : null);

     if (c != null) return c;

     throw new JavaDocHTMLParseException(
         "There was an error parsing the HTML from a Java-Doc Web-page.  One of the " +
         "declared constructors from the page could not be parsed by the JavaParser " +
         "Bridge Classes.  The constructor that failed may be viewed by inspecting the " +
         "exception-field 'e.signature'.",
         fileName,
         ((jpReadySig != null)
             ? jpReadySig
             : ((constructorSig != null) 
                 ? constructorSig
                 : "CONSTRUCTOR-SIGNATURE NOT OBTAINED FROM HTML FILE AT TIME OF EXCEPTION THROW"))
     );
 }
 catch (Exception e)
 {
     if (e instanceof JavaDocHTMLParseException) throw e;

     throw new JavaDocHTMLParseException(
         "There was an error parsing the HTML from a Java-Doc Web-page.  One of the " +
         "declared constructors from the page could not be parsed by the JavaParser " +
         "Bridge Classes, or that constructor's signature was not properly retrieved " +
         "from the JavaDoc Page.  The constructor that failed may be viewed by inspecting " +
         "the exception-field 'e.signature'.  Also, if an underlying-exception has been " +
         "thrown, e.getCause() will produce that cause-chain exception.",
         e, fileName,
         ((jpReadySig != null)
             ? jpReadySig
             : ((constructorSig != null)
                 ? constructorSig
                 : "CONSTRUCTOR-SIGNATURE NOT OBTAINED FROM HTML FILE AT TIME OF EXCEPTION THROW"))
     );
 }

      • parseField

        protected static Field parseField​(java.lang.String fieldSig,
                                  java.lang.String fileName,
                                  java.util.Vector<java.lang.String> gps)
        Parses the contents of an vectorized-html section containing one "Field Details." The field-details sections of java-doc generated HTML documentation pages contain the text for the field's description, signature, parameters-list, throwing-exceptions, etc.
        Parameters:
        fieldSig - This is the 'Signature' part of a 'Field Details' section for a single Field in a JavaDoc Generated HTML web-documentation page.
        fileName - This is the name from which the signature is returned. It is needed because this method is actually declared 'static'. It is 'static' because it is also used elsewhere
        Returns:
        An instance of Field that has been parsed from the JavaDoc '.html' file.
        Throws:
        JavaDocHTMLParseException - If there are errors in the '.html' file-parse.
        Code:
        Exact Method Body:
         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
50
51
52
         String jpReadySig = null;

 try {
     jpReadySig = VEC_TO_STRING_FOR_JP(fieldSig, true, gps);

     String fieldName = FIELD_NAME(fieldSig);

     BodyDeclaration<?>          bd  = StaticJavaParser.parseBodyDeclaration(jpReadySig);

     Optional<FieldDeclaration>  ofd = (bd == null) ? null : bd.toFieldDeclaration();

     FieldDeclaration            fd  = (ofd == null)
                                         ? null
                                         : (ofd.isPresent() ? ofd.get() : null);
                            
     Field                       f   = (fd == null) ? null : new Field(fd, fieldName);

     if (f != null) return f;

     throw new JavaDocHTMLParseException(
         "There was an error parsing the HTML from a Java-Doc Web-page.  One of the " +
         "declared constructors from the page could not be parsed by the JavaParser " +
         "Bridge Classes.  The constructor that failed may be viewed by inspecting the " +
         "exception-field 'e.signature'.",
         fileName,
         ((jpReadySig != null)
             ? jpReadySig
             : ((fieldSig != null)
                 ? fieldSig 
                 : "CONSTRUCTOR-SIGNATURE NOT OBTAINED FROM HTML FILE AT TIME OF EXCEPTION THROW"))
     );
 }
 catch (Exception e)
 {
     if (e instanceof JavaDocHTMLParseException) throw e;

     // DEBUG: System.out.println("fieldSig:" + fieldSig + "\njpReadySig: " + jpReadySig);
     throw new JavaDocHTMLParseException(
         "There was an error parsing the HTML from a Java-Doc Web-page.  One of the " +
         "declared fields from the page could not be parsed by the JavaParser Bridge " +
         "Classes, or that fields's signature was not properly retrieved from the " +
         "JavaDoc Page.  The field that failed may be viewed by inspecting the " +
         "exception-field 'e.signature'. Also, if an underlying-exception has been "+
         "thrown, e.getCause() will produce that cause-chain exception.",
         e, fileName,
         ((jpReadySig != null) 
             ? jpReadySig
             : ((fieldSig != null)
                 ? fieldSig
                 : "CONSTRUCTOR-SIGNATURE NOT OBTAINED FROM HTML FILE AT TIME OF EXCEPTION THROW"))
     );
 }