Package Torello.JavaDoc
Class JavaDocHTMLFile
- java.lang.Object
-
- Torello.JavaDoc.ParsedFile
-
- Torello.JavaDoc.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 classUpgrade
, and executing itsupgrade()
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 classUpgrade
, specifically calling:
Upgrade.setExtraTasks(Consumer<JavaDocHTMLFile> handler)
... with a handler (ajava.util.function.Consumer
instance) that receives aJavaDocHTMLFile
instance.
ClassJavaDocHTMLFile
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 theUpgrader
, make the necessary improvements, and they will be incorporated into the final-output HTML-Page.
Again, classJavaDocHTMLFile
has getters for:HeaderFooterHTML
,SummaryTableHTML
andReflHTML
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 classUpgrade
by callingUpgrade.setExtraTasks(Consumer)
.This Class May be Used to Programmatically Modify JavaDoc HTML
Modifying JavaDoc HTML can be done using:JavaDocHTMLFile
,SummaryTableHTML
,ReflHTML
andHeaderFooterHTML
.
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 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.
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/JavaDoc/JavaDocHTMLFile.java
- Open New Browser-Tab: Torello/JavaDoc/JavaDocHTMLFile.java
File Size: 35,880 Bytes Line Count: 821 '\n' Characters Found
-
-
Field Summary
-
Fields inherited from class Torello.JavaDoc.ParsedFile
annotationElems, ciet, constructors, containerClasses, endLineNumber, enumConstants, fields, fileName, fullNameNoGenerics, genericParameters, isGeneric, isInner, javaSrcFileAsStr, jdEndLineNumber, jdStartLineNumber, methods, nestedTypes, packageName, simpleNameWithContainersAndGenerics, simpleNameWithPossibleContainers, startLineNumber, typeAnnotationMirrors, typeLineCount, typeNameJOW, typeSizeChars
-
-
Constructor Summary
Constructors Constructor Description JavaDocHTMLFile(Torello.JDUInternal.ClassUpgradeData.UpgradePredicates predicates, Torello.JDUInternal.ClassUpgradeData.PathsAndTypes pathsTypes, String jdHTMLFileName, Torello.JDUInternal.Parse.Java.JSCF.JavaSourceCodeFile jscf, RelativePathStr dotDots, String simpleNameWithContainersAndGenerics, String packageName, CIET ciet, ReadOnlyList<String> genericParameters, String cietFullNameNoGenerics, Vector<HTMLNode> fileVec, Torello.JDUInternal.Parse.HTML.JDHF.D3_JDHFMembers jdhfMembers, String srcAsHTMLFileURL, Torello.JDUInternal.Parse.HTML.JDHF.D2_RemovedDetails removedDetails)
-
Method Summary
Get all Reflection-HTML ID's, and their associated HREF Links Modifier and Type Method Ret2<TreeSet<String>,
TreeSet<String>>allIDsAndHREFs()
Find specific Reflected-HTML ( ReflHTML
) instancesModifier and Type Method ReflHTML<AnnotationElem>
findAEHTML(String annotationElemName)
Stream<ReflHTML<Constructor>>
findConstructorHTML(int numParameters)
ReflHTML<EnumConstant>
findECHTML(String enumConstantName)
ReflHTML<Field>
findFieldHTML(String fieldName)
Stream<ReflHTML<Method>>
findMethodHTML(int numParameters)
Stream<ReflHTML<Method>>
findMethodHTML(String methodName)
<ENTITY extends Declaration>
ReflHTML<ENTITY>findReflHTML(int declarationID, Class<ENTITY> c)
-
Methods inherited from class Torello.JavaDoc.ParsedFile
abbreviatedSummary, findAnnotationElem, findConstructor, findConstructors, findEnumConstant, findField, findMethod, findMethods, findNestedType, quickSummary, 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:
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.
-
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.
-
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.
-
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, thisString
begins with the text"/hilite-files/"
, followed by the type-name, and ending with the extension".java.html"
-
allConstructorDetails
public final ReadOnlyList<ReflHTML<Constructor>> allConstructorDetails
This is the list of all constructors in the "Constructor Details", stored as Reflection-HTML instances
-
allFieldDetails
public final ReadOnlyList<ReflHTML<Field>> allFieldDetails
This is the list of all fields in the "Field Details", stored as Reflection-HTML instances
-
allMethodDetails
public final ReadOnlyList<ReflHTML<Method>> allMethodDetails
This is the list of all methods in the "Method Details", stored as Reflection-HTML instances
-
allECDetails
public final ReadOnlyList<ReflHTML<EnumConstant>> allECDetails
This is the list of all constants in the "Enumerated Constant Details", stored as Reflection-HTML instances
-
allAEDetails
public final ReadOnlyList<ReflHTML<AnnotationElem>> allAEDetails
This is the list of all elements in the "Annotation Element Details", stored as Reflection-HTML instances
-
methodSummaryTable
public final SummaryTableHTML<Method> methodSummaryTable
The HTML for a Method Summary
-
fieldSummaryTable
public final SummaryTableHTML<Field> fieldSummaryTable
The HTML for a Field Summary Table
-
constructorSummaryTable
public final SummaryTableHTML<Constructor> constructorSummaryTable
The HTML for a Constructor Summary Table
-
ecSummaryTable
public final SummaryTableHTML<EnumConstant> ecSummaryTable
The HTML for an Enum-Constant Summary Table
-
oaeSummaryTable
public final SummaryTableHTML<AnnotationElem> oaeSummaryTable
The HTML for an Optional Annotation Element Summary Table
-
raeSummaryTable
public final SummaryTableHTML<AnnotationElem> raeSummaryTable
The HTML for a Required Annotation Element Summary Table
-
ntSummaryTable
public final SummaryTableHTML<NestedType> ntSummaryTable
The HTML for a Nested-Class (Inner-Class) Summary Table
-
allNonNullSummaryTables
public final ReadOnlyList<SummaryTableHTML> allNonNullSummaryTables
all non-nullSummaryTableHTML
instances
-
methodDetailsRemoved
public final boolean methodDetailsRemoved
Identifies if this Java Doc HTML Page has had it's Method Details Removed
-
constructorDetailsRemoved
public final boolean constructorDetailsRemoved
Identifies if this Java Doc HTML Page has had it's Constructor Details Removed
-
fieldDetailsRemoved
public final boolean fieldDetailsRemoved
Identifies if this Java Doc HTML Page has had it's Field Details Removed
-
ecDetailsRemoved
public final boolean ecDetailsRemoved
Identifies if this Java Doc HTML Page has had it's Enumeration Constant Details Removed
-
aeDetailsRemoved
public final boolean aeDetailsRemoved
Identifies if this Java Doc HTML Page has had it's Annotation-Element Details Removed
-
-
Method Detail
-
findMethodHTML
public java.util.stream.Stream<ReflHTML<Method>> findMethodHTML (java.lang.String methodName)
Returns a list as ajava.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 ajava.util.stream.Stream
of all Reflected-HTML-Method
instances that have the specified number of parameters.- Parameters:
numParameters
- The number of parameters contained by theMethod
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 ajava.util.stream.Stream
of all Reflected-HTML-Constructor
instances that have the specified number of parameters.- Parameters:
numParameters
- The number of parameters contained by theConstructor
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 matchesfieldName
, 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 matchesenumConstantName
, or null it wasn't found. - Throws:
UpgradeException
- Only a JavaCIET
/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 anenum
.- 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 matchesannotationElemName
, or null it wasn't found. - Throws:
UpgradeException
- Only a JavaCIET
/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 matchingReflHTML
instance whose internal'entity'
field has an ID number that matches input-parameter'declarationID'
.- Parameters:
declarationID
- Whenever any instance of a sub-class ofDeclaration
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 Javajava.lang.Class
from one of the following:Constructor
,Method
,Field
,EnumConstant
orAnnotationElem
.
NOTE: This class is very easily obtained by simple using the'enum'
fieldEntity.upgraderReflectionClass
. To pass the appropriate class for a method, simply passEntity.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 instanceMethod.class
. If you were searching for aReflHTML<Field>
, you would passField.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 ()
-
-