Class 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
    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.

    Class Inheritance Diagram for Reflection Classes


    Class Declaration
     
    intid
    Entityentity
     
    Stringname
    Stringsignature
    StringjdComment
     
    String[]modifiers
    String[]annotations
     
    intsignatureLineNumber
    intjdStartLineNumber
    intjdEndLineNumber
     
     
     
     
     
    Class Callable
     
    Stringbody
     
    String[]parameterNames
    String[]parameterTypes
    String[]parameterTypesJOW
    String[][]parameterAnnotations
     
    String[]exceptions
     
     
     
     
     
    Class Method
     
    StringreturnType
    StringreturnTypeJOW
     
     
     
     
     
    Class Constructor
    Inherits Class Callable
    No Additional Fields
    Java Parser Bridge
    Inheritance Diagram


    Class Field
     
    Stringdefinition
    Stringtype
    StringtypeJOW
     
     
     
     
     
    Class EnumConstant
     
    String[]paramExpressions
     
     
     
     
     
    Class AnnotationElem
     
    StringdefaultValue
    Stringtype
    StringtypeJOW
     
     
     
     
     
    Class NestedType
     
    CIETciet
    intnumFields
    intnumMethods
     
    StringfullyQualifiedName
    StringnameWithContainer
    StringpackageName
     
    String[]extendedTypesJOW
    String[]implementedTypesJOW
    String[]genericTypeParameters
     
     
     
     
     




    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


    • 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;
        
      • jdComment

        🡅  🡇    
        public final java.lang.String jdComment
        The Java Doc Comment of this Field, Method, Constructor, EnumConstant or AnnotationElem as a String - if one exists. The Java Doc Comment is the one defined directly above the Declaration.

        If this 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;
        
      • entity

        🡅  🡇    
        public final Entity entity
        This just stores the type of Entity this is. For sub-classes instances of 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;
        
      • signatureLineNumber

        🡅  🡇    
        public final int signatureLineNumber
        This contains the source-code file line-number where the signature for this Declaration.
        Code:
        Exact Field Declaration Expression:
        public final int signatureLineNumber;
        
      • jdStartLineNumber

        🡅  🡇    
        public final int jdStartLineNumber
        This contains the source-code file line-number for the last line of the Java Doc Comment, if present. If there were no JavaDoc Comment, this shall contain -1.
        Code:
        Exact Field Declaration Expression:
        public final int jdStartLineNumber;
        
      • jdEndLineNumber

        🡅  🡇    
        public final int jdEndLineNumber
        This contains the source-code file line-number for the last line of the Java Doc Comment, if present. If there were no JavaDoc Comment, this shall contain -1.
        Code:
        Exact Field Declaration Expression:
        public final int jdEndLineNumber;
        
      • modifiers

        🡅  🡇    
        protected final java.lang.String[] modifiers
        The 'modifiers' placed on this Declaration. This includes String's such as: public, static, final etc... Note that this field is kept protected so that it cannot be changed, but it's contents can be retrieved with the getter methods provided, below.

        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.
        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.

        BTW: 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 the expression (which is not mandatory) if a programmer has written an annotation that accepts parameters.

        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.
        See Also:
        getAnnotations(), getAnnotations(Consumer), hasAnnotations(), numAnnotations()
        Code:
        Exact Field Declaration Expression:
        protected final String[] annotations;
        
    • Method Detail

      • codeHiLiteString

        🡅  🡇    
        public java.lang.String codeHiLiteString()
        This returns the String to send to the Syntax HiLiter. This is what is inserted into the HiLited Code Portion of a Details Entry (Method Details, Field Declaration, etc...).

        NOTE: This will overloaded by the class Callable.

        Returns:
        The String that is ultimately sent to the Syntax HiLiter, and inserted into a Java Doc page.
        Code:
        Exact Method Body:
         return signature;
        
      • 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;