Package Torello.HTML.Tools.JavaDoc
Class JavaDocHTMLFile
- java.lang.Object
-
- Torello.HTML.Tools.JavaDoc.ParsedFile
-
- Torello.HTML.Tools.JavaDoc.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 theclass 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:class JavaSourceCodeFile
- Parses'.java'
Source-Code Filesclass 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 ofString'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.
In order to retrieve JavaMethod
andConstructor
bodies asString'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
Hi-Lited Source-Code:
- View Here: Torello/HTML/Tools/JavaDoc/JavaDocHTMLFile.java
- Open New Browser-Tab: Torello/HTML/Tools/JavaDoc/JavaDocHTMLFile.java
-
-
Field Summary
Fields Modifier and Type Field static long
serialVersionUID
-
Fields inherited from class Torello.HTML.Tools.JavaDoc.ParsedFile
ciet, constructors, fields, fileName, genericParameters, methods, name, packageName
-
-
Constructor Summary
Constructors Constructor JavaDocHTMLFile(Vector<HTMLNode> fileVec, String jdHTMLFileName, StorageWriter sw)
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method protected static Constructor
parseConstructor(String constructorSig, String fileName, Vector<String> gps)
protected static Field
parseField(String fieldSig, String fileName, Vector<String> gps)
protected static Method
parseMethod(String methodSig, String fileName, Vector<String> gps)
-
Methods inherited from class Torello.HTML.Tools.JavaDoc.ParsedFile
addConstructor, addField, addMethod, findConstructor, findField, findMethod, getConstructor, getConstructors, getConstructors, getField, getFields, getFields, getGenericParameters, getMethod, getMethods, getMethods, numConstructors, numFields, numMethods, toString, toString
-
-
-
-
Field Detail
-
serialVersionUID
public static final long serialVersionUID
This fulfils the SerialVersion UID requirement for all classes that implement Java'sinterface java.io.Serializable
. Using theSerializable
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 singleMethod
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 singleConstructor
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 singleField
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")) ); }
-
-