JReflect (Java Reflection 3.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 ValueConversionHelper.convert(Object[], Class[], boolean) prior to invoking the method. ValueConverter.convert(args, method.getParameterTypes()).
A reverse lookup is also possible: given an ordered list of possible types, is a given Method compatible?
Because this lookup is potentially very expensive, a cache is present to store lookup results.
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 ValueConversionHelper.
Author:

Benny Bottema

See Also:

ValueConversionHelper, 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.

Constructor Summary

Constructors
Constructor and Description

JReflect()

Constructors
Constructor and Description
`JReflect()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static @Nullable Object`	`assignToField(Object o, String property, Object value)` Assigns a value to a field `id` on the given object `o`.
`static @Nullable Class<?>`	`autobox(Class<?> c)` Emulates Java's Autoboxing feature; tries to convert a type to its (un)wrapped counter version.
`static @NotNull Set<String>`	`collectMethods(Object subject, boolean publicOnly)` Returns a list of names that represent the methods on an `Object`
`static @NotNull Collection<String>`	`collectProperties(Object subject)` Returns a list of names that represent the fields on an `Object`.
`static @NotNull Class<?>[]`	`collectTypes(Object[] objects)` Creates a new array of class objects harvested from an array of objects.
`static <T> @NotNull 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 @NotNull 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 @Nullable 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 @NotNull List<Class<?>[]>`	`generateCompatibleSignatures(EnumSet<JReflect.LookupMode> lookupMode, Class<?>... signature)` Initializes the list with type-arrays and starts generating beginning from index 0.
`static @NotNull 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(@Nullable 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`	`isMethodCompatible(Method method, EnumSet<JReflect.LookupMode> lookupMode, Class<?>... signature)`
`static boolean`	`isPackage(String name)` Validates whether a string represents a valid package.
`static boolean`	`isSignatureCompatible(Class<?>[] signature, Class<?>[] exactTargetSignature, EnumSet<JReflect.LookupMode> lookupMode)`
`static @Nullable Class<?>`	`locateClass(String className, boolean fullscan, @Nullable ExternalClassLoader classLoader)` Searches the JVM and optionally all of its packages
`static @Nullable Class<?>`	`locateClass(String fullClassName, @Nullable 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 @Nullable Field`	`solveField(Object o, String fieldName)` Returns a field from the given object that goes by the name of `fieldName`.
`static @NotNull 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

- Constructor Detail
  - JReflect
```
public JReflect()
```
- Method Detail
  - resetCaches
```
public static void resetCaches()
```
  - locateClass
```
@Nullable
public static @Nullable Class<?> locateClass(String className,
                                                        boolean fullscan,
                                                        @Nullable
                                                        @Nullable ExternalClassLoader classLoader)
```
    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 @Nullable Class<?> locateClass(String fullClassName,
                                                        @Nullable
                                                        @Nullable 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
```
@NotNull
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(@Nullable
                                                      @Nullable 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
```
@NotNull
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
```
@NotNull
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
```
@NotNull
public static @NotNull 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
```
@NotNull
public static <T> @NotNull 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 @Nullable 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
```
@NotNull
public static @NotNull 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
```
@NotNull
public static @NotNull 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[])
  - isMethodCompatible
```
public static boolean isMethodCompatible(Method method,
                                         EnumSet<JReflect.LookupMode> lookupMode,
                                         Class<?>... signature)
```
  - isSignatureCompatible
```
public static boolean isSignatureCompatible(Class<?>[] signature,
                                            Class<?>[] exactTargetSignature,
                                            EnumSet<JReflect.LookupMode> lookupMode)
```
  - generateCompatibleSignatures
```
@NotNull
public static @NotNull List<Class<?>[]> generateCompatibleSignatures(EnumSet<JReflect.LookupMode> lookupMode,
                                                                               Class<?>... signature)
```
    Initializes the list with type-arrays and starts generating beginning from index 0. This method is used for (un)wrapping.
    
    Parameters:
    
    lookupMode - Flag indicating the search steps that need to be done.
    
    signature - The list with original user specified types.
    
    Returns:
    
    The list with converted type-arrays.
  - autobox
```
@Nullable
public static @Nullable 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 @Nullable 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 @Nullable 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:
    
    ValueConversionHelper.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
```
@NotNull
public static @NotNull 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
```
@NotNull
public static @NotNull 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
```
@NotNull
public static @NotNull 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
```
@NotNull
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

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

JReflect

Method Detail

resetCaches

locateClass

locateClass

newInstanceSimple

invokeCompatibleMethod

invokeCompatibleConstructor

invokeConstructor

collectTypes

findCompatibleConstructor

findSimpleCompatibleMethod

findCompatibleMethod

getMethod

isMethodCompatible

isSignatureCompatible

generateCompatibleSignatures

autobox

solveField

assignToField

isPackage

widestNumberClass

collectProperties

collectMethods

replaceInArray