Package Torello.JavaDoc

Class Field

java.lang.Object

Torello.JavaDoc.Declaration

Torello.JavaDoc.Field

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<Field>

public class Field
extends Declaration
implements java.io.Serializable, java.lang.Comparable<Field>, java.lang.Cloneable

Similar to java.lang.reflect
This class is heavily used internally, and can be used (if needed) to modify Java Doc Web-Pages, programmatically.

HTML Processors that sort the Web-Page "Summary-Tables" will provide instances of this class to your Summary-Sorter Handler methods. Summary-Sorter handlers usually implement the SummarySorterHelper interface; please review that class for more about sorting Java-Doc Page Summary Tables.

The HTML Processors that upgrade Web-Page "Detail Elements" also rely heavily on this class. Please review the class: ReflHTML for more information about Java-Doc Web-Page Detail Sections.

Reflection Class: Holds all information extracted from '.java' Source-Files about Field's identified in that file.

Instances of this Class are Obtained From: ReflHTML & SummaryTableHTML

Use of the Reflection-HTML API is *NOT REQUIRED* to perform a standard Java Doc HTML File Upgrade. This "extra API" allows for programmatic modification of Java Doc HTML. This class contains quite a bit of reflected information, and furthermore, here there is a hook to the Native Java Parser Reflection Class.
Class Field allows for storing the name, definition and modifiers list of a Field.


Reflection-Classes Inheritance-Diagram

Native JDK API Hook:
All reflection classes above, also contain an additional (transient, non-Serializable) field that hooks into the native Java Tree-Parser Tools available in JDK Package com.sun.source.tree.*

If a more in-depth Code-Analysis is needed, the JDK's AST's have full and complete Parses of your Source-Code that can facilitate almost any analysis.

See Also:

Serialized Form

Hi-Lited Source-Code:

• View Here: Torello/JavaDoc/Field.java
• Open New Browser-Tab: Torello/JavaDoc/Field.java

File Size: 13,003 Bytes Line Count: 301 '\n' Characters Found

Field Summary

Serializable ID
Modifier and Type	Field
protected static long	serialVersionUID
Reflection & Inspection final-String(s)
Modifier and Type	Field
String	definition
String	type
String	typeJOW
Source-Parser Library-Hook References (Transient / Not Serializable)
Modifier and Type	Field
VariableTree	variableTree

Fields inherited from class Torello.JavaDoc.Declaration

annotations, body, entity, id, jdComment, location, modifiers, name, signature

Constructor Summary

Public Constructors that are Intended for Internal-Use, Only
Constructor
Field(VariableTree vt, TreeUtils util)
Field(Field fFromSourceParser, Field fFromHTMLParser)

Method Summary

Methods: interface java.lang.Comparable
Modifier and Type	Method
int	compareTo(Field f)
Methods: class java.lang.Object
Modifier and Type	Method
boolean	equals(Field other)
String	toString()
String	toString(int flags)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

serialVersionUID

🡇 ⇈ ⮫ 🗕 🗗 🗖

protected 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:

 protected static final long serialVersionUID = 1;

definition

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final java.lang.String definition

The definition of this field, as a String.

type

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final java.lang.String type

The type / class of this field, as a String.

typeJOW

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final java.lang.String typeJOW

The type / class of this field, as a String.

JOW: Just One Word

If the String's in a type-as-String contain complicated or intricate detailed information, and all you need is a simple identifier, the JOW-String stores the type-as-String with all package-name and generic-parameters (if they were present / included) stripped from the String. Furthermore, if the type was originally an inner-class, even the containing class-name is removed from the JOW-String.

If a parameter to a Method, or the type of a Field had the (fully-qualified) type-name: java.util.stream.Stream.Builder<String>, the JOW-String would simply have the word "Builder".

NOTE: If the type, itself, is an array of any kind, the array-brackets will be included in this String-name.

Output Single-Word, Type-String	Input Type
"Entry"	"java.util.Map.Entry<K, V>"
"Vector"	"java.util.Vector<E>"
"Vector"	"Vector<TagNode>"
"Vector"	"Vector<Vector<TagNode>>"
"Vector"	"java.util.Vector<Vector<TagNode>>"
"String"	"String"
"String"	"java.lang.String"
"String[]"	"java.lang.String[]"
"Integer"	"Integer"
"Integer[]"	"java.lang.Integer[]"
"String[]"	"String..."
"String[]"	"java.lang.String..."

NOTE: You may view the StringParse class' methods removeGeneric, and typeToJavaIdentifier for more information.

variableTree

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final transient com.sun.source.tree.VariableTree variableTree

Hook Reference to Sun/Oracle Parser-Refletion Class

Though this class offers a streamlined set of reflection features, the Native Oracle Library Reflection-Classes offer a detailed AST interface into the standard Java Compiler. If you would like to use these Tree's to provide further code analysis on your Java-Doc Pages, this field is provided as a convenience for such purposes.
If a user decides to make use of the native Sun/Oracle VariableTree instance that was used to build this Field instance, it may be retrieved from this transient field.

Method Detail

toString

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public java.lang.String toString()

Generates a String of this field, with all information included.

Overrides:

toString in class Declaration

Returns:

A printable String of this field.

See Also:

StrCSV.toCSV(String[], boolean, boolean, Integer), toString(int)

Code:

Exact Method Body:

 String defStr = (definition == null)
     ? "null" 
     : StrPrint.abbrevEndRDSF(definition, MAX_STR_LEN, true);

 return
     "Name:         [" + name + "]\n" +
     "Declaration:  [" + StrPrint.abbrevEndRDSF(signature, MAX_STR_LEN, true) + "]\n" +
     "Type:         [" + type + "]\n" + 
     "Definition:   [" + defStr + "]\n" +
     "Modifiers:    [" + StrCSV.toCSV(modifiers, true, true, null) + "]\n" +

     // This will **NEVER** be null - unless 'this' instance was built from an HTML File,
     // rather than a source-code file.  Instances like that are only used temporarily, and
     // are garbage collected instantly.  Do this check anyway (just in case).

     "Location:     " + ((this.location == null)
         ? "null" 
         : ('[' + this.location.quickSummary() + ']'));

toString

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public java.lang.String toString(int flags)

Generates a String of this field, with all information included. This will also included any content requested by the 'flags' parameter. For this class (class Field), the only additional information printed by this 'toString' method is the Java-Doc Comment String.

This String may also have UNIX color codes added.

Overrides:

toString in class Declaration

Parameters:

flags - These are the toString(...) flags from class PF ("Print Flags"). View available flags listed in class PF.

Returns:

A printable String of this Field.

See Also:

PF, StrCSV.toCSV(String[], boolean, boolean, Integer), toString()

Code:

Exact Method Body:

 boolean color = (flags & UNIX_COLORS) > 0;

 return
     printedName("Field", 15, color) + 
     printedDeclaration(15, color) +
     printedType(jowFlags(flags)) +
     printedDefinition(color) +
     printedModifiers(15) +
     printedLocation(15, color, (flags & BRIEF_LOCATION) > 0) +

     // The previous method does not add a '\n' end to the end of the returned string
     // This is optional, it adds a '\n' AT THE BEGINNING if it is included

     printedComments(15, color, (flags & JAVADOC_COMMENTS) > 0);

compareTo

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public int compareTo(Field f)

Java's interface Comparable<T> requirements. This does a very simple comparison using the two field's 'name' field.

Specified by:

compareTo in interface java.lang.Comparable<Field>

Parameters:

f - Any other Field to be compared to 'this' Field

Returns:

An integer that fulfills Java's interface Comparable<Field> public boolean compareTo(Field f) method requirements.

Code:

Exact Method Body:

 return (this == f) ? 0 : this.name.compareTo(f.name);

equals

🡅 ⇈ ⮫ 🗕 🗗 🗖

public boolean equals(Field other)

This should be called an "atypical version" of the usual equals(Object other) method. This version of equals merely compares the name of the field defined. The presumption here is that the definition of a 'field' only has meaning - at all - inside the context of a class, interface, or enumerated-type where that field is defined. Since inside any '.java' source-code file, there may only be one field with a given name, this method shall return TRUE whenever the field being compared also has the same name.

Parameters:

other - This may be any other field. It is strongly suggested that 'other' be a field defined in the same '.java' source-code file as 'this' field.

Returns:

This method returns TRUE when 'this' instance of Field has the same 'name' as the name-field of input-parameter 'other'

Code:

Exact Method Body:

 return this.name.equals(other.name);