JReflect (Java Reflection 2.0.0 API)

java.lang.Object
- org.bbottema.javareflection.JReflect

```
public final class JReflect
extends Object
```
This class utilizes functionality of the Java class java.lang.reflect. Specifically, this reflection tool is designed to perform advanced method or constructor lookups, using a combination of JReflect.LookupMode strategies.
Aside from that there are some nifty methods for things such as:
- finding out if a given string matches a package name (isPackage(String)),
- returning the widest number type that will fit a any number on a given list of numbers (widestNumberClass(Number...)),
- a method to autobox a given value to its counterpart (autobox(Class)),
- A couple of methods to resolve a direct property of a given object (though they may move to FieldUtils),
- Various handy methods for collecting information on a given Object, such as list of methods, properties or types
- An advanced Class lookup (locateClass(String, boolean, ExternalClassLoader)), that allows a full scan (to try all packages known) and an optional ExternalClassLoader instance that is able to actually compile a .java file on the fly and load its compile .class file
About the method / constructor lookup facility:
An expanded version of getConstructor is implemented that tries to find a constructor of a given datatype, with a given argument datatypelist, where types do not have to match formal types (auto-boxing, supertypes, implemented interfaces and type conversions are allowed as they are included in the lookup cycles). This expanded version tries a simple call first (exact match, which is provided natively by the Java) and when this fails, it generates a list of datatype arrays (signatures) with all possible versions of any type in the original list possible, and combinations thereof.
Observe the following (trivial) example:
```
        interface Foo {
                void foo(Double value, Fruit fruit, char c);
        }
        abstract class A implements Foo {
        }
        abstract class B extends A {
        }
 
        JReflect.findCompatibleJavaMethod(B.class, "foo", EnumSet.allOf(LookupMode.class), double.class, Pear.class, String.class)}
 
```
In the above example, the method foo will be found by finding all methods named "Foo" on the interfaces implemented by supertype A, and then foo's method signature will be matched using autoboxing on the double type, a cast to the Fruit supertype for the Pear type and finally by attempting a common conversion from String to char. This will give you a Java Method, but you won't be able to invoke it if it was found using a less strict lookup than one with a simple exact match. There are two ways to do this: use invokeCompatibleMethod(Object, Class, String, Object...) instead or perform the conversion yourself using ValueConverter.convert(Object[], Class[], boolean) prior to invoking the method. ValueConverter.convert(args, method.getParameterTypes()).
// TODO fix comment about switching the cache
Because this lookup is potentially very expensive, a cache is present to store lookup results. This cache is turned on/off using the constructor.
Types that are candidates for Autoboxing:
- boolean java.lang.Boolean
- char java.lang.Character
- byte java.lang.Byte
- short java.lang.Short
- int java.lang.Integer
- long java.lang.Long
- float java.lang.Float
- double java.lang.Double
For types that are candidates for common conversion, please see ValueConverter.
FIXME make JReflect cache optional
Author:

Benny Bottema

See Also:

ValueConverter, FieldUtils, ExternalClassLoader

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class JReflect.LookupMode
Defines lookup modes for matching Java methods and constructors.

Nested Classes
Modifier and Type	Class and Description
`static class`	`JReflect.LookupMode` Defines lookup modes for matching Java methods and constructors.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static Object`	`assignToField(Object o, String property, Object value)` Assigns a value to a field `id` on the given object `o`.
`static Class<?>`	`autobox(Class<?> c)` Emulates Java's Autoboxing feature; tries to convert a type to its (un)wrapped counter version.
`static Set<String>`	`collectMethods(Object subject, boolean publicOnly)` Returns a list of names that represent the methods on an `Object`
`static Collection<String>`	`collectProperties(Object subject)` Returns a list of names that represent the fields on an `Object`.
`static Class<?>[]`	`collectTypes(Object[] objects)` Creates a new array of class objects harvested from an array of objects.
`static <T> Constructor<T>`	`findCompatibleConstructor(Class<T> datatype, EnumSet<JReflect.LookupMode> lookupMode, Class<?>... types)` Tries to find a `Constructor` of a given type, with a given typelist, where types do not match due to formal types simple types.
`static Method`	`findCompatibleMethod(Class<?> datatype, String methodName, EnumSet<JReflect.LookupMode> lookupMode, Class<?>... signature)` Same as `getConstructor()`, except for getting a `Method` of a classtype, using the name to indicate which method should be located.
`static Method`	`findSimpleCompatibleMethod(Class<?> datatype, String methodName, Class<?>... signature)` Delegates to `findCompatibleMethod(Class, String, EnumSet, Class...)`, using strict lookupmode (no autoboxing, casting etc.) and optional signature parameters.
`static Method`	`getMethod(Class<?> datatype, String name, Class<?>... signature)` Searches a specific class object for a `Method` using java reflect using a specific signature.
`static <T> T`	`invokeCompatibleConstructor(Class<T> datatype, Object... args)` Locates and invokes a `Constructor`using `invokeConstructor(Class, Class[], Object[])`
`static <T> T`	`invokeCompatibleMethod(Object context, Class<?> datatype, String identifier, Object... args)` Locates a method on an Object using serveral searchmodes for optimization.
`static <T> T`	`invokeConstructor(Class<T> datatype, Class<?>[] signature, Object[] args)` Locates and invokes a `Constructor`, using a customized typelist.
`static boolean`	`isPackage(String name)` Validates whether a string represents a valid package.
`static Class<?>`	`locateClass(String className, boolean fullscan, ExternalClassLoader classLoader)` Delegates to `locateClass(String, ExternalClassLoader)`, using default cache.
`static Class<?>`	`locateClass(String className, boolean fullscan, ExternalClassLoader classLoader, boolean useCache)` Searches the JVM and optionally all of its packages
`static Class<?>`	`locateClass(String fullClassName, ExternalClassLoader classLoader)` This function dynamically tries to locate a class.
`static <T> T`	`newInstanceSimple(Class<T> _class)` Simply calls `Class.newInstance()` and hides the exception handling boilerplate code.
`static <T> T[]`	`replaceInArray(T[] array, int index, T value)` Shortcut helper method that replaces an item in an array and returns the array itself.
`static void`	`resetCaches()`
`static Field`	`solveField(Object o, String fieldName)` Returns a field from the given object that goes by the name of `fieldName`.
`static Class<?>`	`widestNumberClass(Number... numbers)` Returns the smallest class that can hold all of the specified numbers.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - resetCaches
```
public static void resetCaches()
```
  - locateClass
```
@Nullable
public static Class<?> locateClass(String className,
                                              boolean fullscan,
                                              ExternalClassLoader classLoader)
```
    Delegates to locateClass(String, ExternalClassLoader), using default cache.
  - locateClass
```
@Nullable
public static Class<?> locateClass(String className,
                                              boolean fullscan,
                                              ExternalClassLoader classLoader,
                                              boolean useCache)
```
    Searches the JVM and optionally all of its packages
    
    Parameters:
    
    className - The name of the class to locate.
    
    fullscan - Whether a full scan through all available java packages is required.
    
    classLoader - Optional user-provided classloader.
    
    Returns:
    
    The Class reference if found or null otherwise.
  - locateClass
```
@Nullable
public static Class<?> locateClass(String fullClassName,
                                              ExternalClassLoader classLoader)
```
    This function dynamically tries to locate a class. First it searches the class-cache list, then it tries to get it from the Virtual Machine using Class.forName(String).
    
    Parameters:
    
    fullClassName - The Class that needs to be found.
    
    classLoader - Optional user-provided classloader.
    
    Returns:
    
    The Class object found from cache or VM.
  - newInstanceSimple
```
@Nonnull
public static <T> T newInstanceSimple(Class<T> _class)
```
    Simply calls Class.newInstance() and hides the exception handling boilerplate code.
    
    Type Parameters:
    
    T - Type used to parameterize the return instance.
    
    Parameters:
    
    _class - The datatype for which we need to create a new instance of.
    
    Returns:
    
    A new parameterized instance of the given type.
  - invokeCompatibleMethod
```
@Nullable
public static <T> T invokeCompatibleMethod(Object context,
                                                      Class<?> datatype,
                                                      String identifier,
                                                      Object... args)
                                               throws NoSuchMethodException,
                                                      IllegalArgumentException,
                                                      IllegalAccessException,
                                                      InvocationTargetException
```
    Locates a method on an Object using serveral searchmodes for optimization. First of all a Method cache is being maintained to quickly fetch heavily used methods. If not cached before and if a simple search (autoboxing and supertype casts) fails a more complex search is done where all interfaces are searched for the method as well. If this fails as well, this method will try to autoconvert the types of the arguments and find a matching signature that way.
    
    Parameters:
    
    context - The object to call the method from (can be null).
    
    datatype - The class to find the method on.
    
    identifier - The name of the method to locate.
    
    args - A list of [non-formal] arguments.
    
    Returns:
    
    The return value of the invoke method, if successful.
    
    Throws:
    
    NoSuchMethodException - Thrown by findCompatibleMethod(Class, String, EnumSet, Class...).
    
    IllegalArgumentException - Thrown by Method.invoke(Object, Object...).
    
    IllegalAccessException - Thrown by Method.invoke(Object, Object...).
    
    InvocationTargetException - Thrown by Method.invoke(Object, Object...).
  - invokeCompatibleConstructor
```
@Nonnull
public static <T> T invokeCompatibleConstructor(Class<T> datatype,
                                                          Object... args)
                                                   throws NoSuchMethodException,
                                                          IllegalAccessException,
                                                          InvocationTargetException,
                                                          InstantiationException
```
    Locates and invokes a Constructorusing invokeConstructor(Class, Class[], Object[])
    
    Type Parameters:
    
    T - Used to parameterize the returned object so that the caller doesn't need to cast.
    
    Parameters:
    
    datatype - The class to find the constructor for.
    
    args - A list of [non-formal] arguments.
    
    Returns:
    
    The instantiated object of class datatype.
    
    Throws:
    
    IllegalAccessException - Thrown by invokeConstructor(Class, Class[], Object[]).
    
    InvocationTargetException - Thrown by invokeConstructor(Class, Class[], Object[]).
    
    InstantiationException - Thrown by invokeConstructor(Class, Class[], Object[]).
    
    NoSuchMethodException - Thrown by invokeConstructor(Class, Class[], Object[]).
    
    See Also:
    
    Constructor.newInstance(Object[])
  - invokeConstructor
```
@Nonnull
public static <T> T invokeConstructor(Class<T> datatype,
                                                Class<?>[] signature,
                                                Object[] args)
                                         throws NoSuchMethodException,
                                                IllegalAccessException,
                                                InvocationTargetException,
                                                InstantiationException
```
    Locates and invokes a Constructor, using a customized typelist. Avoids dynamically trying to find correct parameter type list. Can also be used to force up/down casting (ie. passing a specific type of List into a generic type)
    
    Type Parameters:
    
    T - Used to parameterize the returned object so that the caller doesn't need to cast.
    
    Parameters:
    
    datatype - The class to find the constructor for.
    
    signature - The typelist used to find correct constructor.
    
    args - A list of [non-formal] arguments.
    
    Returns:
    
    The instantiated object of class datatype.
    
    Throws:
    
    IllegalAccessException - Thrown by Constructor.newInstance(Object...).
    
    InvocationTargetException - Thrown by Constructor.newInstance(Object...).
    
    InstantiationException - Thrown by Constructor.newInstance(Object...).
    
    NoSuchMethodException - Thrown by findCompatibleConstructor(Class, EnumSet, Class...).
    
    See Also:
    
    Constructor.newInstance(Object[])
  - collectTypes
```
@Nonnull
public static Class<?>[] collectTypes(Object[] objects)
```
    Creates a new array of class objects harvested from an array of objects.
    NOTE: this method will never return primitive classes (such as double.class, as you can't put primitive values into an array of Objects (they will be autoboxes by the JVM).
    
    Parameters:
    
    objects - The array of objects to harvest classtypes from.
    
    Returns:
    
    The array with the harvested classtypes.
  - findCompatibleConstructor
```
@Nonnull
public static <T> Constructor<T> findCompatibleConstructor(Class<T> datatype,
                                                                     EnumSet<JReflect.LookupMode> lookupMode,
                                                                     Class<?>... types)
                                                              throws NoSuchMethodException
```
    Tries to find a Constructor of a given type, with a given typelist, where types do not match due to formal types simple types. This expanded version tries a simple call first and when it fails, it generates a list of type arrays with all possible (un)wraps of any type in the original list possible, and combinations thereof.
    
    Type Parameters:
    
    T - Used to parameterize the returned constructor.
    
    Parameters:
    
    datatype - The class to get the constructor from.
    
    lookupMode - Flag indicating the search steps that need to be done.
    
    types - The list of types as specified by the user.
    
    Returns:
    
    The constructor if found, otherwise exception is thrown.
    
    Throws:
    
    NoSuchMethodException - Thrown when the Constructor could not be found on the data type, even after performing optional conversions.
  - findSimpleCompatibleMethod
```
@Nullable
public static Method findSimpleCompatibleMethod(Class<?> datatype,
                                                           String methodName,
                                                           Class<?>... signature)
```
    Delegates to findCompatibleMethod(Class, String, EnumSet, Class...), using strict lookupmode (no autoboxing, casting etc.) and optional signature parameters.
    
    Parameters:
    
    datatype - The class to get the constructor from.
    
    methodName - The name of the method to retrieve from the class.
    
    signature - The list of types as specified by the user.
    
    Returns:
    
    null in case of a NoSuchMethodException exception.
    
    See Also:
    
    findCompatibleMethod(Class, String, EnumSet, Class...)
  - findCompatibleMethod
```
@Nonnull
public static Method findCompatibleMethod(Class<?> datatype,
                                                    String methodName,
                                                    EnumSet<JReflect.LookupMode> lookupMode,
                                                    Class<?>... signature)
                                             throws NoSuchMethodException
```
    Same as getConstructor(), except for getting a Method of a classtype, using the name to indicate which method should be located.
    
    Parameters:
    
    datatype - The class to get the constructor from.
    
    methodName - The name of the method to retrieve from the class.
    
    lookupMode - Flag indicating the search steps that need to be done.
    
    signature - The list of types as specified by the user.
    
    Returns:
    
    The method if found, otherwise exception is thrown.
    
    Throws:
    
    NoSuchMethodException - Thrown when the Method could not be found on the data type, even after performing optional conversions.
  - getMethod
```
@Nonnull
public static Method getMethod(Class<?> datatype,
                                         String name,
                                         Class<?>... signature)
                                  throws NoSuchMethodException
```
    Searches a specific class object for a Method using java reflect using a specific signature. This method will first search all implemented interfaces for the method to avoid visibility problems.
    
    An example of such a problem is the Iterator as implemented by the ArrayList. The Iterator is implemented as a private innerclass and as such not accessible by java reflect (even though the implemented methods are declared public), unlike the interface's definition.
    
    Parameters:
    
    datatype - The class reference to locate the method on.
    
    name - The name of the method to find.
    
    signature - The signature the method should match.
    
    Returns:
    
    The Method found on the data type that matched the specified signature.
    
    Throws:
    
    NoSuchMethodException - Thrown when the Method could not be found on the interfaces implemented by the given data type.
    
    See Also:
    
    Class.getMethod(String, Class[])
  - autobox
```
@Nullable
public static Class<?> autobox(Class<?> c)
```
    Emulates Java's Autoboxing feature; tries to convert a type to its (un)wrapped counter version.
    
    Parameters:
    
    c - The datatype to convert (autobox).
    
    Returns:
    
    The converted version of the specified type, or null.
  - solveField
```
@Nullable
public static Field solveField(Object o,
                                          String fieldName)
```
    Returns a field from the given object that goes by the name of fieldName. If o is a Class object, a static field will be returned.
    
    Parameters:
    
    o - The reference to the object to fetch the property value from.
    
    fieldName - The identifier or name of the member field/property.
    
    Returns:
    
    The value of the Field.
  - assignToField
```
@Nullable
public static Object assignToField(Object o,
                                              String property,
                                              Object value)
                                       throws IllegalAccessException,
                                              NoSuchFieldException
```
    Assigns a value to a field id on the given object o. If a simple assignment fails, a common conversion will be attempted.
    
    Parameters:
    
    o - The object to find the field on.
    
    property - The name of the field we're assigning the value to.
    
    value - The value to assign to the field, may be converted to the field's type through common conversion.
    
    Returns:
    
    The actual value that was assigned (the original or the converted value).
    
    Throws:
    
    IllegalAccessException - Thrown by Field.set(Object, Object)
    
    NoSuchFieldException - Thrown if the Field could not be found, even after trying to convert the value to the target type.
    
    See Also:
    
    ValueConverter.convert(Object, Class)
  - isPackage
```
public static boolean isPackage(String name)
```
    Validates whether a string represents a valid package.
    
    Parameters:
    
    name - The string representing a list of packages.
    
    Returns:
    
    A boolean indicating whether name represents a valid package.
  - widestNumberClass
```
@Nonnull
public static Class<?> widestNumberClass(Number... numbers)
```
    Returns the smallest class that can hold all of the specified numbers.
    
    Parameters:
    
    numbers - The list with numbers that all should fit in the Number container.
    
    Returns:
    
    The Number container that is just large enough for all specified numbers.
  - collectProperties
```
@Nonnull
public static Collection<String> collectProperties(Object subject)
```
    Returns a list of names that represent the fields on an Object.
    
    Parameters:
    
    subject - The Object who's properties/fields need to be reflected.
    
    Returns:
    
    A list of names that represent the fields on the given Object.
  - collectMethods
```
@Nonnull
public static Set<String> collectMethods(Object subject,
                                                   boolean publicOnly)
```
    Returns a list of names that represent the methods on an Object
    
    Parameters:
    
    subject - The Object who's methods need to be reflected.
    
    publicOnly - Indicates whether only public (albeit inherited) members should be returned. Else also private and protected methods will be included
    
    Returns:
    
    Returns a list with methods, either Methods.
  - replaceInArray
```
@Nonnull
public static <T> T[] replaceInArray(T[] array,
                                               int index,
                                               T value)
```
    Shortcut helper method that replaces an item in an array and returns the array itself.
    
    Type Parameters:
    
    T - The type of object that goes into the array.
    
    Parameters:
    
    array - The array that needs an item replaced.
    
    index - The index at which the new value should be inserted.
    
    value - The value to insert at the specified index in the specified array.
    
    Returns:
    
    The specified array with the item replaced at specified index.

Class JReflect

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

resetCaches

locateClass

locateClass

locateClass

newInstanceSimple

invokeCompatibleMethod

invokeCompatibleConstructor

invokeConstructor

collectTypes

findCompatibleConstructor

findSimpleCompatibleMethod

findCompatibleMethod

getMethod

autobox

solveField

assignToField

isPackage

widestNumberClass

collectProperties

collectMethods

replaceInArray