java.lang.Object
- Torello.JavaDoc.Declaration

All Implemented Interfaces:: java.io.Serializable

Direct Known Subclasses:: AnnotationElem, Callable, EnumConstant, Field, NestedType

public abstract class Declaration
extends java.lang.Object
implements java.io.Serializable

Abstract Superclass:
This class is the super-class for all Reflection-Extension Classes in this package.

Java Parser Bridge: Common-Root Ancestor Class of all Bridge Data-Classes.

This class has three different descendants in this package,

Method,
Field

and Constructor. All three of these types of java declarations share a few things in common. They all have a public String 'name' part, and a modifier 'public' 'static' 'volatile' etc... part, among other attributes. For the things that these share (things they have in common), this class facilitates code re-use for such parts of a parser object.

There is a Java-Parser Library that is required to use this Package. The Java Doc Upgrader Package / Tool will not work without this '.jar'file being placed in your CLASSPATH environment-variable. That '.jar'is available here:

http://developer.torello.directory/ralphsReference/jars/javaparser-core-3.16.2.jar

There is a book available and an internet "Gitter" support web-site chat-room with some of the people involved in writing this library. There are quite a number of available jars in the "Master Jar Distribution" - but the core library jar is fully sufficient for running the tasks needed by this Java-Doc Upgrade Tool's logic.

Reflection-Classes Inheritance-Diagram

IMPORTANT:
All reflection classes above, also contain an additional (transient, non-Serializable) field that hooks into the native Java-Parser Library classes, providing an option for a more in-depth or complete analysis using that Library's features & extensive utilities.

See Also:: Serialized Form

Hi-Lited Source-Code:

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

File Size: 35,602 Bytes Line Count: 832 '\n' Characters Found

Field Summary

Serializable ID

Modifier and Type	Field
`static long`	`serialVersionUID`

SubClass Identifier
Modifier and Type	Field
`Entity`	`entity`

Reflection & Inspection final-Strings
Modifier and Type	Field
`String`	`body`
`String`	`jdComment`
`String`	`name`
`String`	`signature`

Line Number & Location Information
Modifier and Type	Field
`Location`	`location`

Reflection & Inspection, Protected, String Arrays
Modifier and Type	Field
`protected String[]`	`annotations`
`protected String[]`	`modifiers`

Internally Used ID
Modifier and Type	Field
`int`	`id`

Method Summary

Methods - Reflection: Annotations

Modifier and Type	Method
`String[]`	`getAnnotations()`
`void`	`getAnnotations(Consumer<String> acceptAnnotationsAsStringConsumer)`
`boolean`	`hasAnnotations()`
`int`	`numAnnotations()`

Methods - Reflection: Modifiers
Modifier and Type	Method
`String[]`	`getModifiers()`
`void`	`getModifiers(Consumer<String> acceptModifiersAsStringConsumer)`
`boolean`	`hasModifier(String modifier)`
`boolean`	`hasModifiers()`
`int`	`numModifiers()`

Methods: class java.lang.Object
Modifier and Type	Method
`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;
  - id
    
    🡅 🡇 ⇈ ⮫
```
public final int id
```
    For the purposes of passing these around to different parts of the code, every one of of these are given a unique ID. This id is unique for a method, whether it was parsed from a detail or a summary section. This id is (probably) not useful outside of the HTML Processor Classes.
    
    NOTE: If a subclass of Declaration is cloned, then this id field is also cloned / copied.
    Code:
    
    Exact Field Declaration Expression:
    
    public final int id;
  - name
    
    🡅 🡇 ⇈ ⮫
```
public final java.lang.String name
```
    The Name of the java Field, Method, Constructor, EnumConstant or AnnotationElem. This will be a simple, standard 'Java Identifier'.
    
    Note that the name of a Constructor (for-example) is always just the name of the class.
    
    This field will never be null.
    Code:
    
    Exact Field Declaration Expression:
    
    public final String name;
  - signature
    
    🡅 🡇 ⇈ ⮫
```
public final java.lang.String signature
```
    The complete, declared Signature (as a String) of the Method, Field, Constructor, EnumConstant or AnnotationElem.
    
    This field would never be null.
    Code:
    
    Exact Field Declaration Expression:
    
    public final String signature;
  - jdComment
    
    🡅 🡇 ⇈ ⮫
```
public final java.lang.String jdComment
```
    The Java Doc Comment of this 'Entity' (Field, Method, Constructor, EnumConstant, AnnotationElem or NestedType) as a String - if one exists. The Java Doc Comment is the one defined directly above the Declaration.
    
    If this Entity / Member (Field, Method, Constructor etc...) did not have a Java Doc Comment placed on it, then this field 'jdComment' will be null.
    Code:
    
    Exact Field Declaration Expression:
    
    public final String jdComment;
  - body
    
    🡅 🡇 ⇈ ⮫
```
public final java.lang.String body
```
    The Body of this 'Entity' (Field, Method, Constructor, EnumConstant, AnnotationElem or NestedType) as a String - if one exists.
    
    If this Entity / Member (Field, Method, Constructor etc...) did not have a body, then this field 'body' will be null.
    
    The 'body' of a Method or Constructor is exactly the code that comprises it. If the method is abstract, then the method will not have a body, and in such cases this field will be null. If this member / entity is a Field then the body is the initializer of the Field. Again, if there were no initializer for the field, then 'body' would also be null.
    Code:
    
    Exact Field Declaration Expression:
    
    public final String body;
  - entity
    
    🡅 🡇 ⇈ ⮫
```
public final Entity entity
```
    This just stores the type of Entity this is. For sub-classes instances of Declaration which are Method, this field will be equal to Entity.METHOD. For instances of the Field sub-class, this will equal Entity.FIELD, and so on and so forth.
    
    Mostly, this makes code easier to read when used along-side if-statements or switch-statements than something akin to Declaration.getClass() (when retrieving the specific Declaration sub-class type).
    
    NOTE: Both this class, and sub-class Callable are declared abstract, and only instances of Method, Field, Constructor, etc... can be instantiated.
    Code:
    
    Exact Field Declaration Expression:
    
    public final Entity entity;
  - location
    
    🡅 🡇 ⇈ ⮫
```
public final Location location
```
    Location instance that contains character-locations within the original Java Source-File
    Code:
    
    Exact Field Declaration Expression:
    
    public final Location location;
  - modifiers
    
    🡅 🡇 ⇈ ⮫
```
protected final java.lang.String[] modifiers
```
    The 'modifiers' placed on this Declaration. This includes String's such as: public, static, final etc...
    
    NOTE: Access to the internal-arrays is restricted as 'protected' to prevent any accidental or intentional changing of the values. This is to ensure that the contents of this class are always consistent with the source-code '.java' file on disk.
    
    ALSO: If this Declaration instance has not had any annotations placed on it, then this field will be a non-null, zero-length String[]-Array.
    See Also:
    
    getModifiers(), getModifiers(Consumer), hasModifier(String), hasModifiers(), numModifiers()
    
    Code:
    
    Exact Field Declaration Expression:
    
    protected final String[] modifiers;
  - annotations
    
    🡅 🡇 ⇈ ⮫
```
protected final java.lang.String[] annotations
```
    The 'annotations' that decorate this declaration. It is important to keep in mind that the vast majority of Method's, Field's, Constructor's and EnumConstant's inside of any CIET will not have any 'annotations' that adorn them - at all. For many Declaration's this String-array will just be a zero-length array.
    
    NOTE: Though an annotation, itself, can have annotations applied to it, an Annotation Element cannot. An AnnotationElem is like a field, but for an annotation. It's the expression in parenthesis after the annotation name - if the programmer has, indeed, written an annotation that accepts parameters. Remember that It isn't mandatory to accept parameters into annotation-elements when writing an annotation - nor is it even always mandatory for the end user to provide values to those annotation-elements in the case that they are present.
    
    IMPORTANT: The String's contained here will be the un-parsed raw text that was used in the '.java' source code. What that means is that when a Method, Field, EnumConstant etc... is annotated using an annotation (starting with the '@'-symbol), whatever text-String the programmer actually typed next to that Method, Field, Constructor or EnumConstant - is what will be present in this String-array. This means that if the annotation itself has elements/parameters, they are not parsed, but they are included in the String.
    
    SPECIFICALLY: If @SuppressWarnings({"unchecked", "rawtypes"}) were attached to a method (for example), that exact String would be one of the elements of this String-array. Retrieving the 'value' element array contents "unchecked" and "rawtypes" is left as a parsing exercise to the programmer.
    
    NOTE: Access to the internal-arrays is restricted as 'protected' to prevent any accidental or intentional changing of the values. This is to ensure that the contents of this class are always consistent with the source-code '.java' file on disk.
    
    ALSO: If this Declaration instance has not had any annotations placed on it, then this field will be a non-null, zero-length String[]-Array.
    See Also:
    
    getAnnotations(), getAnnotations(Consumer), hasAnnotations(), numAnnotations()
    
    Code:
    
    Exact Field Declaration Expression:
    
    protected final String[] annotations;
- Method Detail
  - getModifiers
    
    🡅 🡇 ⇈ ⮫
```
public java.lang.String[] getModifiers()
```
    Retrieves the list of 'modifiers' as String-array. The modifiers are just the words that come before a Field, Constructor, Method, EnumConstant or AnnotationElem such as: public, private, protected, final - among others.
    
    NOTE: Access to the internal-arrays is restricted as 'protected' to prevent any accidental or intentional changing of the values. This is to ensure that the contents of this class are always consistent with the source-code '.java' file on disk.
    Returns:
    
    An instance of String[], which was built using Java's clone() method, thereby protecting its contents.
    
    See Also:
    
    modifiers
    
    Code:
    
    Exact Method Body:
    
    return modifiers.clone();
  - getModifiers
    
    🡅 🡇 ⇈ ⮫
```
public void getModifiers
            (java.util.function.Consumer<java.lang.String> acceptModifiersAsStringConsumer)
```
    Retrieves the list of 'modifiers'. User provides an insertion function of their choice. The 'modifiers' are just the words that come before a Field, Constructor, Method, etc... - including (for-example): public, private, protected, final, volatile (of which there are quite a few).
    
    NOTE: Access to the internal-arrays is restricted as 'protected' to prevent any accidental or intentional changing of the values. This is to ensure that the contents of this class are always consistent with the source-code '.java' file on disk.
    Parameters:
    
    acceptModifiersAsStringConsumer - This should be any java.util.function.Consumer that will accept a reference from the getModifiers array, and perform whatever operations needed.
    
    See Also:
    
    modifiers
    
    Code:
    
    Exact Method Body:
    
    for (String modifier : modifiers) acceptModifiersAsStringConsumer.accept(modifier);
  - hasModifier
    
    🡅 🡇 ⇈ ⮫
```
public boolean hasModifier(java.lang.String modifier)
```
    The user may pass any of the standard Java Modifiers for Declarations to ask whether this Declaration was defined using that modifier.
    Parameters:
    
    modifier - a (lower-case) String such as: 'public', 'static', 'final' etc...
    
    Returns:
    
    TRUE if the provided 'modifier' is, actually, one of the modifiers listed within this Declaration's internal 'modifiers' array.
    
    See Also:
    
    modifiers
    
    Code:
    
    Exact Method Body:
    
    for (String m : modifiers) if (m.equals(modifier)) return true; return false;
  - hasModifiers
    
    🡅 🡇 ⇈ ⮫
```
public boolean hasModifiers()
```
    Reports whether this instance of Declaration has any modifiers attached to it. It simply returns whether or not the internal 'modifiers' array has length bigger than zero.
    Returns:
    
    Returns TRUE if there were any modifiers - public, static, final etc... - that were specified in this declaration.
    
    See Also:
    
    modifiers
    
    Code:
    
    Exact Method Body:
    
    return modifiers.length > 0;
  - numModifiers
    
    🡅 🡇 ⇈ ⮫
```
public int numModifiers()
```
    Returns the number of 'modifiers' - public, static, final etc... - that were specified by 'this' Declaration
    Returns:
    
    Returns the length of the protected (internal) 'modifiers' array.
    
    See Also:
    
    modifiers
    
    Code:
    
    Exact Method Body:
    
    return modifiers.length;
  - getAnnotations
    
    🡅 🡇 ⇈ ⮫
```
public java.lang.String[] getAnnotations()
```
    Retrieves the list of 'annotations' as String-array. The annotations are the String's that begin with the '@' symbol, and are, occasionally, placed before a Method, Constructor, Field, EnumConstant or AnnotationElem.
    
    NOTE: Access to the internal-arrays is restricted as 'protected' to prevent any accidental or intentional changing of the values. This is to ensure that the contents of this class are always consistent with the source-code '.java' file on disk.
    Returns:
    
    An instance of String[], which was built using Java's clone() method, thereby protecting its contents.
    
    See Also:
    
    annotations
    
    Code:
    
    Exact Method Body:
    
    return annotations.clone();
  - getAnnotations
    
    🡅 🡇 ⇈ ⮫
```
public void getAnnotations
            (java.util.function.Consumer<java.lang.String> acceptAnnotationsAsStringConsumer)
```
    Retrieves the list of 'annotations'. User provides an insertion function of their choice.
    
    NOTE: Access to the internal-arrays is restricted as 'protected' to prevent any accidental or intentional changing of the values. This is to ensure that the contents of this class are always consistent with the source-code '.java' file on disk.
    Parameters:
    
    acceptAnnotationsAsStringConsumer - This should be any java.util.function.Consumer that will accept a reference from the getAnnotations array, and perform whatever operations needed.
    
    See Also:
    
    annotations
    
    Code:
    
    Exact Method Body:
    
    for (String annotation : annotations) acceptAnnotationsAsStringConsumer.accept(annotation);
  - hasAnnotations
    
    🡅 🡇 ⇈ ⮫
```
public boolean hasAnnotations()
```
    Reports whether this instance of Declaration has any annotations attached to it. It simply returns whether or not the internal 'modifiers' array has length bigger than zero.
    Returns:
    
    Returns TRUE if there were any modifiers - public, static, final etc... - that were specified in this declaration.
    
    See Also:
    
    annotations
    
    Code:
    
    Exact Method Body:
    
    return annotations.length > 0;
  - numAnnotations
    
    🡅 🡇 ⇈ ⮫
```
public int numAnnotations()
```
    This returns the number of 'annotations' that may or may not have placed on 'this' Declaration. If this Method, Constructor, Field, EnumConstant or AnnotationElem was not annotated with anything, then the return-value of this method is, simply, zero.
    Returns:
    
    Returns the length of the protected (internal) 'annotations' array.
    
    See Also:
    
    annotations
    
    Code:
    
    Exact Method Body:
    
    return annotations.length;
  - toString
    
    🡅 🡇 ⇈ ⮫
```
public java.lang.String toString()
```
    Dummy Method. Overriden by Concrete Sub-Classes.
    Overrides:
    
    toString in class java.lang.Object
    
    See Also:
    
    Method.toString(), Field.toString(), Constructor.toString()
    
    Code:
    
    Exact Method Body:
    
    return "Declaration is Abstract, all Concrete Sub-Classes Override this method.";
  - toString
    
    🡅 ⇈ ⮫
```
public java.lang.String toString(int flags)
```
    Dummy Method. Overriden by Concrete Sub-Classes.
    See Also:
    
    Method.toString(int), Field.toString(int), Constructor.toString(int)
    
    Code:
    
    Exact Method Body:
    
    return "Declaration is Abstract, all Concrete Sub-Classes Override this method.";

Class Declaration

int	id
Entity	entity
Location	location

String	name
String	signature
String	jdComment
String	body

String[]	modifiers
String[]	annotations






Class Callable

String[]	parameterNames
String[]	parameterTypes
String[]	parameterTypesJOW
String[][]	parameterAnnotations

String[]	exceptions






Class Method

String	returnType
String	returnTypeJOW





Class Constructor
Also Inherits Class Callable No Additional Fields

Class Field

String	definition
String	type
String	typeJOW





Class EnumConstant

String[]	paramExpressions





Class AnnotationElem

String	defaultValue
String	type
String	typeJOW





Class NestedType

CIET	ciet
int	numFields
int	numMethods

String	fullyQualifiedName
String	nameWithContainer
String	packageName

String[]	extendedTypesJOW
String[]	implementedTypesJOW
String[]	genericTypeParameters

Class Declaration

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

serialVersionUID

id

name

signature

jdComment

body

entity

location

modifiers

annotations

Method Detail

getModifiers

getModifiers

hasModifier

hasModifiers

numModifiers

getAnnotations

getAnnotations

hasAnnotations

numAnnotations

toString

toString