Class Callable

  • All Implemented Interfaces:
    java.io.Serializable
    Direct Known Subclasses:
    Constructor, Method
    public abstract class Callable
extends Declaration
implements java.io.Serializable
    Callable - Documentation.

    This class is abstract and is simply used to represent either a method, or a constructor - both of which can be 'called' by a line of java code. All Callable's have a few things in common, a parameter list, and exception throw list, and a name. Rather than re-write the code that can deal with / handle a list of parameters (their names and types), this abstract class has a few methods for handling these features, and then both class Constructor, and class Method may 're-use' the parameter-list handling code in their own definitions.

    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;

      • body

        public final java.lang.String body
        The body of the Callable. This is information that only the Java-Parser (library-JAR) can retrieve. The Java Reflection Library has no ability whatsoever to return information about the actual text that a programmer typed into his java source file. Generally, such information is not of much use; however, in order to implement an improvement on utilities such as this javadoc upgrader utility, this information can be invaluable.
        Code:
        Exact Field Declaration Expression:
        1
        public final String body;

      • parameterNames

        protected final java.lang.String[] parameterNames
        The names of all parameters to this Method or Constructor. This array must be considered as a parallel array to the other arrays, 'parameterTypes' and 'parameterTypesNoPackage'.
        Code:
        Exact Field Declaration Expression:
        1
        protected final String[] parameterNames;

      • parameterTypes

        protected final java.lang.String[] parameterTypes
        The types of all parameters to this Method or Constructor.

        NOTE: The parsed-types for a Method or Constructor signature often, but not always include the full-package name of the classes (and interfaces) for input-parameters that were not primitive-types. This abstract class 'DeclWithParameter' does not fill-out the full package name for a class/interface itself. The "full-package name" for an input parameter to a Method or Constructor is provided (sometimes, but not always) by the underlying Java-Parser mechanism. If the Java-Parser external JAR library does not provide full-package class-names, such information is just assumed unavailable.

        This array must be considered as a parallel array to the other arrays, 'parameterNames' and 'parameterTypesNoPackage'.
        Code:
        Exact Field Declaration Expression:
        1
        protected final String[] parameterTypes;

      • parameterTypesNoPackage

        protected final java.lang.String[] parameterTypesNoPackage
        The types of all parameters to this Method or Constructor. The parsed types of a signature often, but not always include the full-package name of the classes and interfaces for the type. This protected final String[] contains identical information as the protected final String[] 'parameterTypes', but differs in that - if any of the class or interface names included the java 'full package identifier' (for instance: java.lang.String, instead of just 'String') - then that package information will already have been "stripped out" of the String.

        ALSO: This array must be considered as a parallel array to the other arrays, 'parameterNames' and 'parameterTypes'.
        Code:
        Exact Field Declaration Expression:
        1
        protected final String[] parameterTypesNoPackage;

      • exceptions

        protected final java.lang.String[] exceptions
        The names of all Exception, Error and Throwable that may be thrown by this Constructor or Method.
        Code:
        Exact Field Declaration Expression:
        1
        protected final String[] exceptions;

    • Constructor Detail

      • Callable

        protected Callable​
            (java.lang.String[] modifiers,
             java.lang.String name,
             java.lang.String signature,
             java.lang.String jdComment,
             com.github.javaparser.ast.NodeList<com.github.javaparser.ast.body.Parameter> paramList,
             java.lang.String body,
             com.github.javaparser.ast.NodeList<com.github.javaparser.ast.type.ReferenceType> exceptions)
        Internally Used Constructor. Subclasses that inherit this abstract class use this.
        Code:
        Exact Constructor Body:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
         /*
     ************** SUPER-CLASS CONSTRUCTOR **************
     protected Declaration(
         String[] modifiers, String name, String signature,
         String jdComment
     )
     *****************************************************
 */
 super(modifiers, name, signature, jdComment);

 this.body                       = body;
 this.parameterNames             = new String[paramList.size()];
 this.parameterTypes             = new String[parameterNames.length];
 this.parameterTypesNoPackage    = new String[parameterNames.length];
 this.exceptions                 = new String[exceptions.size()];

 int i=0;
 for (Parameter p : paramList)
 {
     parameterNames[i]           = p.getName().toString();
     parameterTypes[i]           = p.getType().toString();
     parameterTypesNoPackage[i]  = REMOVE_PACKAGE_INFORMATION(parameterTypes[i]);
     i++;
 }

 i=0;
 for (ReferenceType r : exceptions) this.exceptions[i++] = r.toString();

      • Callable

        protected Callable​(java.lang.String[] modifiers,
                   java.lang.String name,
                   java.lang.String signature,
                   java.lang.String jdComment,
                   java.lang.String[] parameterNames,
                   java.lang.String[] parameterTypes,
                   java.lang.String[] parameterTypesNoPackage,
                   java.lang.String[] exceptions,
                   java.lang.String body)
        Internally Used. Useful for the clone() method
        Code:
        Exact Constructor Body:
        1
2
3
4
5
6
7
         super(modifiers, name, signature, jdComment);

 this.body                       = body;
 this.parameterNames             = parameterNames.clone();
 this.parameterTypes             = parameterTypes.clone();
 this.parameterTypesNoPackage    = parameterTypesNoPackage.clone();
 this.exceptions                 = exceptions.clone();

    • Method Detail

      • getParameterNames

        public java.lang.String[] getParameterNames()
        Retrieves the list of parameterNames as a String[] array clone
        Returns:
        An instance of String[] that employs the clone() method of the internal data-structure, protecting its contents.
        Code:
        Exact Method Body:
        1
         return parameterNames.clone();

      • getParameterNames

        public void getParameterNames​
            (java.util.function.Consumer<java.lang.String> acceptParamNameAsStringConsumer)
        Retrieves the list of parameterNames using a 'java.util.function.Consumer<String>', so that any data-structure needed can be used to retrieve these parameters.
        Parameters:
        acceptParamNameAsStringConsumer - This java.util.function.Consumer should accept type String, and be used to fill a data-structure of whatever type is needed with the parameterNames associated with 'this' Method or Constructor

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

        • decl.getParameterNames(v::add); - Inserts the list of parameterNames into a 'Vector', assuming the variable 'v' was of type Vector<String>

        Code:
        Exact Method Body:
        1
2
         for (String parameterName : parameterNames)
     acceptParamNameAsStringConsumer.accept(parameterName);

      • hasParameterNamed

        public boolean hasParameterNamed​(java.lang.String name)
        Check whether a particular 'name' has the same name as one of the parameters in the signature of this Callable.
        Parameters:
        name - Any parameter name
        Returns:
        This method will return TRUE if any of the parameters defined in this instance of Callable match the provided 'name'.
        Code:
        Exact Method Body:
        1
2
         for (String parameterName : parameterNames) if (name.equals(parameterName)) return true;
 return false;

      • getParameterTypes

        public java.lang.String[] getParameterTypes()
        Retrieves the list of parameterTypes as a String[] array.
        Returns:
        An instance of String[] that employs the clone() method of the internal data-structure, protecting its contents
        Code:
        Exact Method Body:
        1
         return parameterTypes.clone();

      • getParameterTypes

        public void getParameterTypes​
            (java.util.function.Consumer<java.lang.String> acceptParamTypeAsStringConsumer)
        Retrieves the list of parameterTypes using a 'java.util.function.Consumer<String>', so that any data-structure needed can be used to retrieve this parameters.
        Parameters:
        acceptParamTypeAsStringConsumer - This java.util.function.Consumer should accept type String, and be used to fill a data-structure of whatever type is needed with the parameter-types associated with 'this' Method or Constructor.

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

        • decl.getParameterTypes(v::add) - Inserts the list of parameterTypes into a 'Vector', assuming the variable 'v' was of type Vector<String>
        Code:
        Exact Method Body:
        1
2
         for (String parameterType : parameterTypes)
     acceptParamTypeAsStringConsumer.accept(parameterType);

      • hasParameterTyped

        public boolean hasParameterTyped​(java.lang.String type)
        Check whether a particular 'type' has the same String-value as one of the parameters in the signature of this Callable.

        IMPORTANT: This class does not retrieve the fully-qualified package names for the parameters. The contents of the internal 'parameterTypes' array may or may not be specified by there fully-qualified type. This is wholly dependent on what the Java Doc HTML File looks like (in the case of JavaDoc Parsed Files).

        You should print the 'parameterTypes' array to check, or use the method that leaves out package-information from the 'type' String.
        Parameters:
        type - Any parameter type as a java.lang.String
        Returns:
        This method will return TRUE if any of the parameters defined in this instance of Callable have a type that matches the provided 'type'.
        Code:
        Exact Method Body:
        1
2
         for (String parameterType : parameterTypes) if (type.equals(parameterType)) return true;
 return false;

      • getParameterTypesWithoutPackageInfo

        public java.lang.String[] getParameterTypesWithoutPackageInfo()
        Retrieves the list of parameterTypes as a String[] array. The String's that are returned from this method are the ones stored internally to the String-array 'parameterTypesNoPackage'. They do not retain the package information (if they even had that information in the first place).
        Returns:
        An instance of String[] that employs the clone() method of the internal data-structure, protecting its contents
        Code:
        Exact Method Body:
        1
         return parameterTypesNoPackage.clone();

      • getParameterTypesWithoutPackageInfo

        public void getParameterTypesWithoutPackageInfo​
            (java.util.function.Consumer<java.lang.String> acceptParamTypeAsStringConsumer)
        Retrieves the list of parameterTypes using a 'java.util.function.Consumer<String>', so that any data-structure needed can be used to retrieve this parameters. The String's that are sent to the Consumer are the ones stored internally to the String-array 'parameterTypesNoPackage'. They do not retain the package-information (if they even had that information in the first place).
        Parameters:
        acceptParamTypeAsStringConsumer - This java.util.function.Consumer should accept type String, and be used to fill a data-structure of whatever type is needed with the parameter-types associated with 'this' Method or Constructor.

        • decl.getParameterTypesWithoutPackageInfo(ts::add); - Inserts the list of parameter-no-package-types into a 'TreeSet', assuming variable 'ts' was of type TreeSet<String>

        • decl.getParameterTypesWithoutPackageInfo(v::add); - Inserts the list of parameter-no-package-types into a 'Vector', assuming the variable 'v' was of type Vector<String>
        Code:
        Exact Method Body:
        1
2
         for (String parameterTypeNoPackage : parameterTypesNoPackage)
     acceptParamTypeAsStringConsumer.accept(parameterTypeNoPackage);

      • hasParameterTypedWithoutPackage

        public boolean hasParameterTypedWithoutPackage​(java.lang.String type)
        Check whether a particular 'type' has the same type as one of the parameters in the signature of this Callable. The check absconds regarding fully-qualified package-information checking issue.
        Parameters:
        type - Any parameter type, as a java.lang.String, without package-name details included in the String.
        Returns:
        This method will return TRUE if any of the parameters defined in this instance of Callable have a type that matches the provided 'type'.
        Code:
        Exact Method Body:
        1
2
3
4
         for (String parameterType : parameterTypesNoPackage)
     if (type.equals(parameterType)) return true;

 return false;

      • getExceptions

        public java.lang.String[] getExceptions()
        Retrieves the list of Exception's as a String[] array. The String's that are returned from this method are the ones stored internally to the String-array 'exceptions'.
        Returns:
        An instance of String[] that employs the clone() method of the internal data-structure, protecting its contents.
        Code:
        Exact Method Body:
        1
         return exceptions.clone();

      • getExceptions

        public void getExceptions​
            (java.util.function.Consumer<java.lang.String> acceptExceptionsAsStringConsumer)
        Retrieves the list of exceptions using a 'java.util.function.Consumer<String>', so that any data-structure needed can be used to retrieve these Exception's. The String's that are sent to the Consumer are the ones stored internally to the String-array 'exceptions'.
        Parameters:
        acceptExceptionsAsStringConsumer - This java.util.function.Consumer should accept type String, and be used to fill a data-structure of whatever type is needed with the Exception's associated with 'this' Method or Constructor.

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

        • decl.getParameterTypesWithoutPackageInfo(v::add); Inserts the list of exceptions into a 'Vector', assuming the variable 'v' was of type Vector<String>
        Code:
        Exact Method Body:
        1
2
         for (String exception : exceptions)
     acceptExceptionsAsStringConsumer.accept(exception);

      • hasException

        public boolean hasException​(java.lang.String exception)
        Check whether a particular 'exception' (or other 'Throwable') is thrown, according to the declared-signature of this Callable.
        Parameters:
        exception - Any Exception, Error or Throwable name, as a java.lang.String
        Returns:
        This method will return TRUE if any of the Throwables listed in this instance of Callable match the provided 'exception'.

        NOTE: The exceptions listed in this class are only the ones that are included in the Method or Constructor Signature. This should be similar to (but not identical to) the list of Checked-Exceptions. No in-depth code-analysis is performed, as it is a nearly impossible problem to solve. Instead, when a parse is performed, the exceptions listed in the 'throws' clause of the Method or Constructor being parsed placed into this class 'exceptions' array.

        FURTHERMORE: The exception-name as String may or may not contain the fully-qualified package-name of the exception.
        Code:
        Exact Method Body:
        1
2
         for (String e : exceptions) if (e.equals(exception)) return true;
 return false;

      • numParameters

        public int numParameters()
        Returns the array-length of the internal parameterNames array.
        Returns:
        The number of parameters in the signature of this Callable
        Code:
        Exact Method Body:
        1
         return parameterNames.length;

      • numExceptions

        public int numExceptions()
        Returns the array-length of the internal exceptions array.
        Returns:
        The number of excepions in the signature of this Callable
        Code:
        Exact Method Body:
        1
         return exceptions.length;