Class Callable

  • All Implemented Interfaces:
    java.io.Serializable
    Direct Known Subclasses:
    Constructor, Method
    public abstract class Callable
extends Declaration
implements java.io.Serializable
    Abstract Superclass:
    This class is the super-class for the classes Constructor and Method
    Reflection Class:
    Common-Root Ancestor Class of both Method and Constructor.

    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.

    This abstract class has Method'ss for handling these features. Both Constructor and Method inherit this class, and allow for 're-using' the Reflection-Stuff about Parameter-Lists, Parameter-Types and Throw-Clauses.
    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;

      • parameterTypes

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<java.lang.String> parameterTypes
        This contains the types of the parameters, stored as String's. The contents of these String's do include: package-name, containing classes (if inner-classes), and generic-parameter expressions (if generic-types). These names are as fully-qualified as the AST Parser allows.

        JOW Alternative:
        The ReadOnlyList parameterTypesJOW reduces these types (as String's) to a single-word. If a Method or a Constructor that accepts a paremeter such as java.util.Iterable<Integer>, and it seems 'difficult to work with' - the entry in parameterTypesJOW at the same array-location would contain, simply, the Java String 'Iterable'.

        Parallel List:
        This list must be considered a parallel list to the other parameter-related list: parameterNames, parameterTypesJOW and parameterAnnotations

      • parameterTypesJOW

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<java.lang.String> parameterTypesJOW
        JOW: Just One Word
        The Just One Word convention used by the JDU Tool elminates BOTH Package-Name Information AND (for Inner-Types / Nested-Types) any & all Container-Class Information from the Type-String's.

        The Java-Doc Upgrader does not perform a Compiler-Styled "Linking Pass" on the Java-Doc Web-Pages it parses, and must suffice with the unlinked Type-Names provided by the Oracle AST-Parser and Java-Doc '.html' Output Pages.

        As an example of this, If a parameter to a Method, or the type of a Field inside of a class had the fully qualified type-name:

        java.util.stream.Stream.Builder<String>

        the JOW-String for that type would simply be the word "Builder"

        For Arrays:
        If the type, itself, is an array of any kind, any & all Array-Brackets will be included in this String-Name. Please review the Example Table, below:
        Output JOW-StringInput Type
        "Entry" "java.util.Map.Entry<K, V>"
        "Vector" "java.util.Vector<E>"
        "Vector" "Vector<TagNode>"
        "Vector" "Vector<Vector<TagNode>>"
        "Vector" "java.util.Vector<Vector<TagNode>>"
        "String" "String"
        "String" "java.lang.String"
        "String[]" "java.lang.String[]"
        "Integer" "Integer"
        "Integer[]" "java.lang.Integer[]"
        "String[]" "String..."
        "String[]" "java.lang.String..."


        Parallel List:
        This list must be considered a parallel list to the other parameter-related list: parameterNames, parameterTypes and parameterAnnotations

      • parameterAnnotations

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<ReadOnlyList<java.lang.String>> parameterAnnotations
        Any parameters that are annotated will have the exact text-String of the annotations that were used in the source-code for that parameter stored in this two-dimensional String[][] array.

        This list will retrieve and contain the actual character data that may be found in the source-code file for an element in a com.sun.source 'AST' (Abstract Syntax Tree). The list of annotations on a parameter (if any) will each be saved as a java.lang.String.

        Null Warning:
        Unlike the other lists in class Callable, when there are no parameters for a Callabe, or when there are parameters, but none of them have been annotated, for the purposes of efficiency and better memory management, this field will simply be assigned null.

        In almost all cases (particularly in the Java HTML Library), this two-dimensional list, itself, really will be null - since parameter annotations are quite uncommon. Perhaps, some users make use of them from time to time.

        Parallel List:
        This list must be considered a parallel list to the other parameter-related list: parameterNames, parameterTypes and parameterTypesJOW

      • exceptions

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final ReadOnlyList<java.lang.String> exceptions
        The names of all Exception, Error and Throwable that may be thrown by this Constructor or Method.

        NOTE: Only exceptions which are included in the actual Declaration.signature, inside the original '.java' source-file for this Callable will be listed in this array.

    • Method Detail

      • getParameterType

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String getParameterType​(java.lang.String parameterName)
        This will retrieve the type of the parameter (as a String) that has the name 'parameterName'. This method will simply return null, gracefully, if this Method or Constructor does not have a parameter with that name. This method will not throw an exception in such cases.
        Parameters:
        parameterName - The name of the parameter whose type you are requesting.
        Returns:
        The fully-qualified type of the parameter, as a String having the name 'parameterName', or null if no such type exists.
        See Also:
        parameterTypes, parameterNames
        Code:
        Exact Method Body:
         for (int i=0; i < parameterNames.size(); i++)
     if (parameterNames.get(i).equals(parameterName))
         return parameterTypes.get(i);

 return null;

      • getParameterTypeJOW

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String getParameterTypeJOW​
            (java.lang.String parameterName)
        This will retrieve the type of the parameter (as a String) that has the name 'parameterName'. This method will simply return null, gracefully, if this Method or Constructor does not have a parameter with that name. This method will not throw an exception in such cases.

        JOW: Just One Word - The types in the String[] array field parameterTypesJOW are simplified to just a single 'Java Identifier' part. All outer-class, package, and generic type-parameter information are stripped from these array entries. Please see the detailed-description of parameterTypesJOW for a better explanation.
        Parameters:
        parameterName - The name of the parameter whose type you are requesting.
        Returns:
        The type of the parameter, as a one-word String having the name 'parameterName'.
        See Also:
        parameterTypesJOW, parameterTypes, parameterNames
        Code:
        Exact Method Body:
         if (parameterNames != null)
     for (int i=0; i < parameterNames.size(); i++)
         if (parameterNames.get(i).equals(parameterName))
             return parameterTypesJOW.get(i);

 return null;

      • getParameterAnnotations

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyList<java.lang.String> getParameterAnnotations​
            (java.lang.String parameterName)
        This will retrieve the annotations-list that may (or may not) adorn the parameter which uses the name 'parameterName'.

        This method will simply return null, gracefully, if this Method or Constructor does not have a parameter with that name. This method will not throw an exception in such cases.

        NOTE:This method will also return null even if a parameter having the provided name is found, but that parameter wasn't annotated with anything. If a null is returned, distinguishing between the case where 'parameterName' just wasn't found, and the case where that parameter wasn't annotated - isn't possible here.
        Parameters:
        parameterName - The name of the parameter whose annotation-list you are requesting.
        Returns:
        The type of the parameter having the name 'parameterName'.
        See Also:
        parameterAnnotations, parameterNames
        Code:
        Exact Method Body:
         if (parameterAnnotations == null) return null;

 for (int i=0; i < parameterNames.size(); i++)

     if (parameterNames.get(i).equals(parameterName))
         return parameterAnnotations.get(i);
             // In the line above, if a parameter isnt annotated, that location in the 
             // array will have a 'null'

 return null;

      • hasAnnotatedParameters

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean hasAnnotatedParameters()
        This will look at each parmeter's annotation array to see if there are any parameters in this Callable's invocation parameter-list that were annotated with anything.
        Returns:
        TRUE if there are any parameters that were annotated with something, and false if every parameter in the parameter-list had a 'null' String array of parameter-annotations.

        If this instance of Callable is one which does not accept any parameters, this methhod will return FALSE immediately.

        NOTE: The internal 'parameterAnnotations' field for class Callable is implemented as a two-dimensional String-array. There may be any number of parameters that are passed to a Method or Constructor, and each of those parameters may have any number of annotations that were attached to them.

        SANITY-CHECK Likely 99.99% of the parameters in the Java HTML library do not have any parameter's that are annotated.
        See Also:
        parameterAnnotations
        Code:
        Exact Method Body:
         return parameterAnnotations != null;

      • numAnnotatedParameters

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int numAnnotatedParameters()
        Reports how many of the parameters in the internal list of parameters that had annotations attached to them.

        SANITY-CHECK Likely 99.99% of the parameters in the Java HTML library do not have any parameter's that are annotated.
        Returns:
        This will count how many parameters which are used by this Callable (either Method or Field) that have annotations that were attached to the parameter.
        See Also:
        parameterAnnotations
        Code:
        Exact Method Body:
         int count = 0;

 if (parameterAnnotations == null) return 0;

 // NOTE: each parameter has an "Annotation List" stored in a 2-D array.  This is why
 //       this for-loop is using 'String[]', rather than 'String' ...
 //       A parameter may be annotated with zero annotations, one, or many annotations.

 for (ReadOnlyList<String> paList : parameterAnnotations)
     if (paList.size() > 0) count++;

 return count;

      • nearlyEqualsCallableSig

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean nearlyEqualsCallableSig​
            (Torello.JDUInternal.Parse.HTML.Other.CallableSignature cSig)
        An internally used utility that is accessed from outside this package. This method allows a user to check whether 'this' method has an identical signature to the input instance of 'CallableSignature'.

        Because this Upgrader does not execute an actual Compiler Linking-Pass, only the 'JOW' (Just One Word) of the input Parameter Types are checked.
        Parameters:
        cSig - The Type Signature for any Method or Constructor.
        Returns:
        TRUE if the Parameter-Names fpr 'this' Callable are all equal to the names in 'cSig' AND the "Just One Word" types match those in 'cSig'.

        If either pf these two tests fail, then FALSE is returned.
        Code:
        Exact Method Body:
         // This works for Methods and Constructors.  This method used to be in the actual 'Method'
 // and 'Constructor' sub-class due to this one-line optimization.  (This is an un-necessary
 // check for Constructors, but not for methods).

 if (this.numParameters() != cSig.parameterNames.size()) return false;

 // If there are no parameters (for either of them), then return true immediately
 if (this.numParameters() == 0) return true;

 // If any of the parameter-names are different, break immediately and return false;
 for (int i=0; i < this.parameterNames.size(); i++)
     if (! this.parameterNames.get(i).equals(cSig.parameterNames.get(i)))
         return false;

 // If the parameter-types listed by the javadoc '.html' file differ from parameter-types
 // listed in the original '.java' source-code file, then break immediately.
 //
 // NOTE: The "package-information" for the FULL CLASS OR INTERFACE NAME is not always
 // available.

 for (int i=0; i < this.parameterTypes.size(); i++)
     if (! this.parameterTypesJOW.get(i).equals(cSig.parameterTypesJOW.get(i)))
         return false;

 // ALL TESTS PASSED
 return true;