Class Declaration

  • All Implemented Interfaces:
    java.io.Serializable
    Direct Known Subclasses:
    Callable, Field

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

    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.
    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:
        1
        public static final long serialVersionUID = 1;
        
      • name

        public final java.lang.String name
        The name of the java Field, Method or Constructor. This String will not include any return-type related String's, nor parameter or modifier String's. Note that the name of a Constructor (for-example) is always just the name of the class.
        Code:
        Exact Field Declaration Expression:
        1
        public final String name;
        
      • signature

        public final java.lang.String signature
        The complete declared signature, as a String. This is the Method or Constructor "Signature" if 'this' instance of Declaration is being inherited / instantiated by a Method or Constructor. If 'this' instance of Declaration is for a Field, then 'signature' will be the exact line in the original source file as it was declared.
        Code:
        Exact Field Declaration Expression:
        1
        public final String signature;
        
      • modifiers

        protected final java.lang.String[] modifiers
        The 'modifiers' for this field. This includes String's such as public, static, final etc... This is kept protected to prevent unwarranted changes. It's contents may be retrieved by the getter methods provided.
        Code:
        Exact Field Declaration Expression:
        1
        protected final String[] modifiers;
        
      • jdComment

        public final java.lang.String jdComment
        The java-doc comment portion of this Field, Method or Constructor as a String - if one exists. This is defined directly above the Declaration. If this Field, Method or Constructor did not have a JavaDoc Comment, then this Declaration's 'jdComment' will be null.
        Code:
        Exact Field Declaration Expression:
        1
        public final String jdComment;
        
    • Constructor Detail

      • Declaration

        protected Declaration​(java.lang.String[] modifiers,
                              java.lang.String name,
                              java.lang.String signature,
                              java.lang.String jdComment)
        Creates a Declaration with the given name, signature, modifiers and comment.
        Parameters:
        modifiers - This should be the complete list of modifiers including, but-not-limited-to: public, private, protected, etc...
        name - This should be the name of the Field, Method or Constructor. Note, a Constructor's name is always the name of the class.
        signature - This is how the Declaration reads in a java source file.
        jdComment - This is the JavaDoc comment which may-or-may-not accompany a Declaration of a Field, Method or Constructor.
        Code:
        Exact Constructor Body:
        1
        2
        3
        4
        5
        6
        7
        8
        9
         this.name           = name;
         this.signature      = signature;
         this.jdComment      = jdComment;
        
         // The modifiers may need to be trimmed, build an array
         this.modifiers = new String[modifiers.length];
        
         // Trim them of the ridiculous space-character at the end of them.
         for (int i=0; i < modifiers.length; i++) this.modifiers[i] = modifiers[i].trim();
        
    • 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 or Method, and include (for-example): public, private, protected, final etc...
        Returns:
        An instance of String[] that employs the clone() method of the internal data-structure, protecting its contents.
        Code:
        Exact Method Body:
        1
         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 or Method, and include (for-example): public, private, protected, final etc...
        Parameters:
        acceptModifiersAsStringConsumer - This should be any java.util.function.Consumer<String> takes a String, and inserts it into the data-structure.

        • decl.getModifiers(ts::add) - Inserts the list of 'modifiers' into a 'TreeSet', assuming variable 'ts' was of type TreeSet<String>

        • decl.getModifiers(v::add) - Inserts the list of 'modifiers' into a 'Vector', assuming the variable 'v' was of type Vector<String>
        Code:
        Exact Method Body:
        1
         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.
        Code:
        Exact Method Body:
        1
         for (String m : modifiers) if (m.equals(modifier)) return true; return false;
        
      • REMOVE_PACKAGE_INFORMATION

        public static java.lang.String[] REMOVE_PACKAGE_INFORMATION​
                    (java.lang.String[] types)
        
        This removes the package information from a String[] array of class-names or interface-names.
        Parameters:
        types - This input String[] array should be a list of the input-parameter 'types' to a method or constructor. It may be any list of class/interface String's.
        Returns:
        This will return a parallel array that contains the same classes or interfaces, but any of the input String's that contained full-package names will have had the package part of the name stripped out. For parameter-types in the original array that did not have package-information the original String will be returned.
        Code:
        Exact Method Body:
        1
        2
        3
        4
        5
        6
        7
        8
         String[] ret = new String[types.length];
        
         for (int i=0; i < types.length; i++)
             ret[i] = types[i].contains(".")
                         ? StringParse.PACKAGE_NAME.matcher(types[i]).replaceAll("")
                         : types[i];
        
         return ret;
        
      • REMOVE_PACKAGE_INFORMATION

        public static java.lang.String REMOVE_PACKAGE_INFORMATION​
                    (java.lang.String type)
        
        This removes the package information from a single class or interface name.
        Parameters:
        type - This lone input String-parameter should contain a single class or interface name that includes the full package name.
        Returns:
        This will return a single String that is identical to the input-type, but has had the full package-name removed - if it had full-package details in the first place. If there were no package-name String's as substrings of the input, the original String will be returned.
        Code:
        Exact Method Body:
        1
         return type.contains(".") ? StringParse.PACKAGE_NAME.matcher(type).replaceAll("") : type;
        
      • MODIFIERS_LIST

        public static java.lang.String[] MODIFIERS_LIST​
                    (com.github.javaparser.ast.NodeList<com.github.javaparser.ast.Modifier> modifiersList)
        
        Converts a list of 'modifiers' from a Java-Parser NodeList<Modifier> to a String[]-Array.
        Parameters:
        modifiersList - This is the JavaParser Type that contains the modifiers for a Field, Method or Constructor etc.
        Returns:
        A String-Array format of the modifiers (words like: public, protected, final, etc...) that are at the start of every Field, Method and Constructor declaration.
        Code:
        Exact Method Body:
        1
        2
        3
        4
        5
        6
         String[]    modifiers   = new String[modifiersList.size()];
         int         i           =   0;
        
         for (Modifier modifier : modifiersList) modifiers[i++] = modifier.toString();
        
         return modifiers;