com.github.aliteralmind.codelet.simplesig

Class SimpleMethodSignature

java.lang.Object

com.github.aliteralmind.codelet.simplesig.SimpleMethodSignature

public class SimpleMethodSignature
extends Object

The pieces that represent a method, containing its return-type, containing-class, function-name, and a comma-delimited, and strictly-formatted string-list of its parameters--parameters which may only be of a primitive type or strings. This class is unrelated to SimpleParamNameSignature. Also contains utilities for creating this object from a "string signature" in the format:

"fully.qualified.package.ClassName#functionName(\"all\", true, \"parameters\", (byte)-112)"

There are two alternative formats, one in which the package name is not provided:

"ClassName#functionName(\"all\", true, \"parameters\", (byte)-112)"

and another in which only the function is provided:

"functionName(\"all\", true, \"parameters\", (byte)-112)"

In the two alternative signatures, default package or class values must be specified. If there are no parameters following the function name, it defaults to "()".

Example: No defaults

A string signature where everything (the package, class, and function name) is provided.

Source code

   import  com.github.xbn.lang.reflect.InvokeMethodWithRtx;
   import  java.lang.reflect.Method;
   import  com.github.aliteralmind.codelet.simplesig.SimpleMethodSignature;
public class SimpleMethodSigNoDefaults  {
   public static final void main(String[] ignored)  {

      String strSig = "com.github.aliteralmind.codelet.examples.simplesig." +
         "SimpleMethodSigNoDefaults#getStringForBoolInt(false, 3)";

      SimpleMethodSignature simpleSig = null;
      try  {
         simpleSig = SimpleMethodSignature.newFromStringAndDefaults(
            String.class, strSig, null, null,
            null);         //debug (on=System.out, off=null)
      }  catch(ClassNotFoundException cnfx)  {
         throw  new RuntimeException(cnfx);
      }

      Method m = null;
      try  {
         m = simpleSig.getMethod();
      }  catch(NoSuchMethodException nsmx)  {
         throw  new RuntimeException(nsmx);
      }

      m.setAccessible(true);

      Object returnValue = new InvokeMethodWithRtx(m).sstatic().
         parameters(simpleSig.getParamValueObjectList().toArray()).invokeGetReturnValue();

      System.out.println(returnValue);
   }
   public static final String getStringForBoolInt(Boolean b, Integer i)  {
      return  "b=" + b + ", i=" + i;
   }
}

Output:

b=false, i=3

Example: Default classes

This demonstrates a string signature in which the (package and) class name is not specified. The potential classes, one in which the function must exist, are provided directly.

Source code

   import  com.github.xbn.lang.reflect.InvokeMethodWithRtx;
   import  java.lang.reflect.Method;
   import  com.github.aliteralmind.codelet.simplesig.SimpleMethodSignature;
public class SimpleMethodSigWithClassDefaults  {
   public static final void main(String[] ignored)  {

      String strSig = "getStringForBoolInt(false, 3)";

      SimpleMethodSignature simpleSig = null;
      try  {
         simpleSig = SimpleMethodSignature.newFromStringAndDefaults(
            String.class, strSig, null,
            new Class[]{Object.class, SimpleMethodSigWithClassDefaults.class, SimpleMethodSignature.class},
            null);         //debug (on=System.out, off=null)
      }  catch(ClassNotFoundException cnfx)  {
         throw  new RuntimeException(cnfx);
      }

      Method m = null;
      try  {
         m = simpleSig.getMethod();
      }  catch(NoSuchMethodException nsmx)  {
         throw  new RuntimeException(nsmx);
      }

      m.setAccessible(true);

      Object returnValue = new InvokeMethodWithRtx(m).sstatic().
         parameters(simpleSig.getParamValueObjectList().toArray()).invokeGetReturnValue();

      System.out.println(returnValue);
   }
   public static final String getStringForBoolInt(Boolean b, Integer i)  {
      return  "b=" + b + ", i=" + i;
   }
}

Output:

b=false, i=3

Since:

0.1.0

Author:

Copyright (C) 2014, Jeff Epstein (aliteralmind __DASH__ github __AT__ yahoo __DOT__ com), dual-licensed under the LGPL (version 3.0 or later) or the ASL (version 2.0). See source code for details. http://codelet.aliteralmind.com, https://github.com/aliteralmind/codelet

Field Summary

Fields

Modifier and Type	Field and Description
static String	STRING_SIGNATURE_REGEX Matches a validly formatted string-signature, as required by newFromStringAndDefaults.

Constructor Summary

Constructors

Constructor and Description
SimpleMethodSignature(Class<?> return_typeCls, Class<?>[] containsFuncClasses_inOrder, String func_name, String param_strList, Appendable debugDest_ifNonNull) YYY

Method Summary

Methods

Modifier and Type	Method and Description
StringBuilder	appendStringSig_ret_class_func_params(StringBuilder to_appendTo, boolean doInclude_returnType, boolean doInclude_class, boolean doInclude_funcName, boolean doInclude_params)
StringBuilder	appendToString(StringBuilder to_appendTo)
TextAppenter	getDbgAptr()
static SimpleMethodSignature	getForMainFromStringSig(Object class_funcParamStringSignature, Appendable debugDest_ifNonNull) Splits a string-signature into its parts, for the classes main function (or any non-returning void function), and where the fully-qualified class is explicitely specified in the string (no defaults are used).
String	getFunctionName()
Class<?>	getMayContainFuncClass(int index)
int	getMayContainFuncClassCount()
Method	getMethod()
Method	getMethodFromParamTypes(Class<?>[] paramClasses_nullForSigDefault) Get the method as specified in the SimpleMethodSignature, which must exist in one of the may-contain classes.
Method	getMethodFromParamValueList(List<Object> paramValues_nullForSigDefault)
static Object	getObjectFromString(String var_asString) Get the object represented by a single string-representation of a single parameter.
static List<Object>	getObjectListFromCommaSepParamString(String commaSep_varList) Get the objects from the string-representation of a function's parameter list.
String	getParamStringList()
List<Object>	getParamValueObjectList()
Class<?>	getReturnType()
String	getStringSig_ret_class_func_params(boolean doInclude_returnType, boolean doInclude_class, boolean doInclude_funcName, boolean doInclude_params)
String	invokeGetMainOutputNoExtraParams(String app_descriptionNotClassName) Execute the classes main function and get its console output.
void	invokeMainNoExtraParams() Execute the classes main function.
static SimpleMethodSignature	newFromStringAndDefaults(Class<?> return_typeCls, Object class_funcParamStringSignature, String default_package, Class<?>[] default_classesInOrder, Appendable debugDest_ifNonNull) Splits a string-signature into its parts.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

STRING_SIGNATURE_REGEX

public static final String STRING_SIGNATURE_REGEX

Matches a validly formatted string-signature, as required by newFromStringAndDefaults. View the source-code for more documentation.

Five named capture-groups:

• package: The fully-qualified package-name, ending with a dot. When non-null, this is always followed by className1.
• className1: The name of the class that exists in package. When package is null, this is as well.
• className2: The class name existing in package default_package (parameter in newFromStringAndDefaults). When non-null, default_package must be null. When both this and className1 are null, default_classesInOrder must be non-null.
• funcName: Always non-null.
• params: Always non-null, but may be the empty-string.

See Also:

JavaRegexes#IDENTIFIER, JavaRegexes#PACKAGE_NAME, Constant Field Values

Constructor Detail

SimpleMethodSignature

public SimpleMethodSignature(Class<?> return_typeCls,
                     Class<?>[] containsFuncClasses_inOrder,
                     String func_name,
                     String param_strList,
                     Appendable debugDest_ifNonNull)

YYY

Method Detail

getDbgAptr

public TextAppenter getDbgAptr()

getReturnType

public Class<?> getReturnType()

getParamValueObjectList

public List<Object> getParamValueObjectList()

getMayContainFuncClass

public Class<?> getMayContainFuncClass(int index)

invokeMainNoExtraParams

public void invokeMainNoExtraParams()
                             throws NoSuchMethodException

Execute the classes main function. This requires the main function to exist in getMayContainFuncClass(0).

Throws:

NoSuchMethodException

See Also:

invokeGetMainOutputNoExtraParams(String)

invokeGetMainOutputNoExtraParams

public String invokeGetMainOutputNoExtraParams(String app_descriptionNotClassName)

Execute the classes main function and get its console output. This requires the main function to exist in getMayContainFuncClass(0).

See Also:

invokeMainNoExtraParams()

getMethod

public Method getMethod()
                 throws NoSuchMethodException

Throws:

NoSuchMethodException

getMethodFromParamValueList

public Method getMethodFromParamValueList(List<Object> paramValues_nullForSigDefault)
                                   throws NoSuchMethodException

Throws:

NoSuchMethodException

getMethodFromParamTypes

public Method getMethodFromParamTypes(Class<?>[] paramClasses_nullForSigDefault)
                               throws NoSuchMethodException

Get the method as specified in the SimpleMethodSignature, which must exist in one of the may-contain classes.

Throws:

NoSuchMethodException

See Also:

getMayContainFuncClass(int), http://stackoverflow.com/questions/22876120/how-to-test-if-a-private-static-function-exists-in-a-class-without-having-to-ca

getMayContainFuncClassCount

public int getMayContainFuncClassCount()

getFunctionName

public String getFunctionName()

getParamStringList

public String getParamStringList()

toString

public String toString()

Overrides:

toString in class Object

appendToString

public StringBuilder appendToString(StringBuilder to_appendTo)

getStringSig_ret_class_func_params

public String getStringSig_ret_class_func_params(boolean doInclude_returnType,
                                        boolean doInclude_class,
                                        boolean doInclude_funcName,
                                        boolean doInclude_params)

appendStringSig_ret_class_func_params

public StringBuilder appendStringSig_ret_class_func_params(StringBuilder to_appendTo,
                                                  boolean doInclude_returnType,
                                                  boolean doInclude_class,
                                                  boolean doInclude_funcName,
                                                  boolean doInclude_params)

getForMainFromStringSig

public static final SimpleMethodSignature getForMainFromStringSig(Object class_funcParamStringSignature,
                                            Appendable debugDest_ifNonNull)
                                                           throws ClassNotFoundException,
                                                                  SimpleMethodSigFormatException

Splits a string-signature into its parts, for the classes main function (or any non-returning void function), and where the fully-qualified class is explicitely specified in the string (no defaults are used).

Returns:

newFromStringAndDefaults(Void.class, class_funcParamStringSignature, null, null, debugDest_ifNonNull)

Throws:

ClassNotFoundException

SimpleMethodSigFormatException

newFromStringAndDefaults

public static final SimpleMethodSignature newFromStringAndDefaults(Class<?> return_typeCls,
                                             Object class_funcParamStringSignature,
                                             String default_package,
                                             Class<?>[] default_classesInOrder,
                                             Appendable debugDest_ifNonNull)
                                                            throws ClassNotFoundException

Splits a string-signature into its parts. An example string-signature is
"ClassName#functionName(\"parameter\", \"list\", 1, (byte)-3, true)"

Format requirements

"functionName()"

A function with no parameters that exists in the default class. In all cases, when there are no parameters, the empty parentheses may be omitted: "functionName".

"MyClass#functionName()"

A function that exists in MyClass, which is in the default package.

"com.something.me.MyClass#functionName()"

A function that exists in a specific class.

"com.something.me.MyClass#functionName(true, 1, \"hello\", ...)"

A function that exists in a specific class, with a particular set of parameters.

Parameters:

class_funcParamStringSignature - The string-signature. May not be null or empty, and must be formatted as specified above. Specifically, it must be matched by STRING_SIGNATURE_REGEX.

default_package - The default package to use when the string-signature specifies a class-name but does not specify a package. When the string-signature does not contain a package, and no default class is specified, this must be non-null and non-empty, must end with a dot ('.'), and must be the package in which the specified class as specified in the string-signature exists (default_classesInOrder must be null). The class must exist in a package.

default_classesInOrder - The ordered set of classes to use when no class is specified in the string-signature. The function must exist in one of these classes. The search order is left-to-right (starting with element zero). When the class is specified in the string-signature, default_classesInOrder must be null. Otherwise, must be non-null, non-empty, and elements may not be null, and should be unique. When non-null, default_package must be null.

Returns:

A non-null SimpleMethodSigFormatException.

Throws:

ClassNotFoundException - If the class name, but not its package, is in the string-signature, and the class does not exist in the default package.

SimpleMethodSigFormatException - If class_funcParamStringSignature is invalidly-formatted.

IllegalArgumentStateException - If either

• There is no package specified in the string-signature and default_package is null.
• There is no class name specified in the string-signature and default_classesInOrder is null.

See Also:

getForMainFromStringSig(Object, Appendable)

getObjectListFromCommaSepParamString

public static final List<Object> getObjectListFromCommaSepParamString(String commaSep_varList)

Get the objects from the string-representation of a function's parameter list.

Parameters:

commaSep_varList - May not be null, each element must be separated by a comma-space (", "), and each element must be formatted as required by getObjectFromString(s). Example value:
"\"parameter\", \"list\", 1, (byte)-3, true"

Returns:

A list of objects, where each element is the object represented by the corresponding element in commaSep_varList, in the same order as the exist in the string.

Throws:

IllegalArgumentException - If commaSep_varList is invalidly-formatted.

See Also:

getClassArrayFromObjects, newFromStringAndDefaults(cls,s,s,cls[])

getObjectFromString

public static final Object getObjectFromString(String var_asString)

Get the object represented by a single string-representation of a single parameter. The only available types are the eight primitives and non-null strings (null is not possible).

Parameters:

var_asString - May not be null or empty, and must conform to the following:

Type	Examples	Notes
Boolean	true or false
Character	'x'	Must start and end with a single quote, and contain exactly one character between it. For the single-quote, use three single quotes: "'''" (do not escape it).
Byte	(byte)3	Must contain the explicit cast and be an appropriate value for a byte. The plus-sign, indicating a positive number, is not allowed for any numeric type.
Short	(short)-15	Must contain the explicit cast and be an appropriate value for a short
Integer	-15	Must be an appropriate value for an int
Long	3300012L	Must be followed by a capital 'L' and be an appropriate value for an long
Float	0.003f	Must be followed by a lowercase 'f', contain at least one digit on both sides of the decimal, and be an appropriate value for an float. For both float and double, only digits (as matched by the regular expression "\d") are allowed. Hex numbers, exponenents, and special values such as NaN or Infinity are not allowed.
Double	-3.8d	Must be followed by a lowercase 'd', contain at least one digit on both sides of the decimal, and be an appropriate value for an double
String	"Hello there!"	Must be non-null, surrounded by double-quotes, and may not contain a comma (','), double-quote ('"'), or ampersand ('&'). When these characters are needed, use their respective html entity codes: ",", "&quot", and "&".