Package Torello.JavaDoc

Class AnnotationElem

java.lang.Object

Torello.JavaDoc.Declaration

Torello.JavaDoc.AnnotationElem

All Implemented Interfaces:

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

public class AnnotationElem
extends Declaration
implements java.io.Serializable, java.lang.Comparable<AnnotationElem>, 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' Annotation (@interface) Source-Files about all Elements 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 class AnnotationElem allows for storing the name, definition, default-value, etc... of an Annotation Element. Note that an 'Annotation Element' is not the same as a Java 'Annotation' (@interface). An 'Annotation Element' is merely the (optional) element / parameter which may (if used) help specify the contents of a Java Annotation.

For Instance: With the commonly-used annotation named @SuppressWarnings(...), the Value-Parameters that are passed inside the parenthesis are the 'value' Annotation-Element. This 'value' may be assigned several Java String's such as: 'rawtypes', 'unchecked', etc...


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.

O'Rielly Note:
COPIED VERBATIM FROM: O'Rielly Publishing, Java in a Nutshell (5^th Edition, by David Flanagan)

Defining Annotation Types: An annotation type is an interface, but it is not a normal one. An annotation type differs from a normal interface in the following ways:

• An annotation type is defined with the keyword @interface rather than with interface. An @interface declaration implicitly extends the interface java.lang.annotation.Annotation and may not have an explicit extends clause of its own.
  
  
• The methods of an annotation type must be declared with no arguments and may not throw exceptions. These methods define annotation members: the method name becomes the member name, and the method return type becomes the member type.
  
  
• The return value of annotation methods may be a primitive type, a String, a Class, an enumerated type, another annotation type, or a single-dimensional array of one of those types.
  
  
• Any method of an annotation type may be followed by the keyword default and a value compatible with the return type of the method. This strange new syntax specifies the default value of the annotation member that corresponds to the method. The syntax for default values is the same as the syntax used to specify member values when writing an annotation. null is never a legal default value.
  
  
• Annotation types and their methods may not have type parameters—annotation types and members cannot be made generic. The only valid use of generics in annotation types is for methods whose return type is Class. These methods may use a bounded wildcard to specify a constraint on the returned class.

See Also:

Serialized Form

Hi-Lited Source-Code:

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

File Size: 13,537 Bytes Line Count: 303 '\n' Characters Found

Field Summary

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

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
AnnotationElem(MethodTree mt, TreeUtils util)
AnnotationElem(AnnotationElem aeFromSourceParser, String jdTypeStr)

Method Summary

Methods: interface java.lang.Comparable
Modifier and Type	Method
int	compareTo(AnnotationElem ae)
Methods: class java.lang.Object
Modifier and Type	Method
boolean	equals(AnnotationElem 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

🡇 ⇈ ⮫ 🗕 🗗 🗖

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;

type

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final java.lang.String type

An Annotation-Element may only assume one of several types, as per the Java Sun / Oracle Documentation. The type must be one of the following, or a compile-time error occurs:

• a primitive type
• String
• Class or an invocation of Class
• An enum type
• An annotation type
• An (1 dimensional) array type whose component type is one of the preceding types

typeJOW

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final java.lang.String typeJOW

JOW: Just One Word

The Just One Word convention in the upgrader tool elminates package-name information from type-String's.

defaultValue

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final java.lang.String defaultValue

The default value assigned to this element. This may be null if there is no assigned default value.

methodTree

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final transient com.sun.source.tree.MethodTree methodTree

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 MethodTree instance that was used to build this Constructor instance, it may be retrieved from this transient field.

NOTE: The package com.sun.source.tree "reuses" or "overloads" the MethodTree object such that it may represent either a Method, or an Annotation Element (or even a Constructor).

Since Java Annotations do not actually have methods or constructors, when a MethodTree instance is one of the Members of a Class-Tree, it should always be treated as an Annotation-Element (rather than a method or constructor),

Method Detail

toString

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public java.lang.String toString()

Generates a String of this Annotation Element, with all information included.

Overrides:

toString in class Declaration

Returns:

A printable string of this AnnotationElem.

See Also:

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

Code:

Exact Method Body:

 String def = (defaultValue != null)
     ? ("Default:      [" + StrPrint.abbrevEndRDSF(defaultValue, MAX_STR_LEN, true) +
         "]\n") 
     : "";
    
 return
     "Name:         [" + name + "]\n" +
     "Declaration:  [" + StrPrint.abbrevEndRDSF(signature, MAX_STR_LEN, true) + "]\n" +
     "Type:         [" + typeJOW + "]\n" +
     "Modifiers:    [" + StrCSV.toCSV(modifiers, true, true, null) + "]\n" +
     def +

     // 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 Annotation Element, with all information included. This will also included any content requested by the 'flags' parameter. For this class (class AnnotationElem), 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 AnnotationElem.

See Also:

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

Code:

Exact Method Body:

 boolean color = (flags & UNIX_COLORS) > 0;

 return
     printedName("Element", 14, color) + 
     printedDeclaration(14, color) +
     "Type-JOW:     [" + typeJOW + "]\n" + 
     printedModifiers(14) +
     printedLocation(14, color, (flags & BRIEF_LOCATION) > 0) +

     // The previous method does not add a '\n' end to the end of the returned string
     // These are both optional, they add a '\n' AT THE BEGINNING if one of them is included

     printedDefault(color) +
     printedComments(14, color, (flags & JAVADOC_COMMENTS) > 0);

compareTo

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public int compareTo(AnnotationElem ae)

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

Specified by:

compareTo in interface java.lang.Comparable<AnnotationElem>

Parameters:

ae - Any other AnnotationElem to be compared to 'this' AnnotationElem

Returns:

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

Code:

Exact Method Body:

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

equals

🡅 ⇈ ⮫ 🗕 🗗 🗖

public boolean equals(AnnotationElem 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 element defined. The presumption here is that the definition of an 'element' only has meaning - at all - inside the context of an Annotation where that element has been defined. Since inside any '.java' Annotation, there may only be one element with a given name, this method shall return TRUE whenever the element being compared also has the same name.

Parameters:

other - This may be any other Annotation-Element. It is strongly suggested that 'other' be an element defined in the same '.java' source-code file as 'this' element.

Returns:

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

Code:

Exact Method Body:

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