net.sf.jguiraffe.di
Class ReflectionUtils

java.lang.Object
  net.sf.jguiraffe.di.ReflectionUtils

public class ReflectionUtils
extends java.lang.Object

An utility class that provides some functionality related to reflection and dependency injection.

This class implements some basic functionality that is needed by other parts of the dependency injection package. It especially deals with row reflection calls and exception handling. It is not intended to be used directly by applications using this framework. It will be called under the hood.

Version:

$Id: ReflectionUtils.java 156 2009-03-03 21:04:47Z oheger $

Author:

Oliver Heger

Method Summary

static <T> T	convert(java.lang.Class<T> targetClass, java.lang.Object value) Performs a type conversion if required.
static <T> java.lang.reflect.Constructor<T>	findConstructorByParamTypes(java.lang.Class<T> targetClass, java.lang.Class<?>... types) Finds a constructor in the specified target class when all parameter types are known.
static <T> java.lang.reflect.Constructor<T>	findConstructorByParamValues(java.lang.Class<T> targetClass, java.lang.Class<?>[] types, java.lang.Object... values) Finds a constructor if not all parameter types are exactly known.
static java.lang.reflect.Method	findMethodByParamTypes(java.lang.Class<?> targetClass, java.lang.String methodName, java.lang.Class<?>... types) Finds a method in the specified target class when all parameter types are known.
static java.lang.reflect.Method	findMethodByParamValues(java.lang.Class<?> targetClass, java.lang.String methodName, java.lang.Class<?>[] types, java.lang.Object... values) Finds a method if not all parameter types are exactly known.
static java.lang.Object	getProperty(java.lang.Object bean, java.lang.String name) Returns the value of the specified property from the given bean.
static <T> T	invokeConstructor(java.lang.reflect.Constructor<T> ctor, java.lang.Object... args) Creates an object by invoking the specified constructor with the given arguments.
static <T> T	invokeConstructorByParamTypes(java.lang.Class<T> targetClass, java.lang.Class<?>[] paramTypes, java.lang.Object... paramValues) Finds a constructor and invokes it when the exact signature is known.
static <T> T	invokeConstructorByParamValues(java.lang.Class<T> targetClass, java.lang.Class<?>[] paramTypes, java.lang.Object... paramValues) Finds a constructor and invokes it when the signature is only partly known.
static java.lang.Object	invokeMethod(java.lang.reflect.Method method, java.lang.Object target, java.lang.Object... args) Helper method for invoking a method using reflection.
static java.lang.Object	invokeMethodByParamTypes(java.lang.Class<?> targetClass, java.lang.String methodName, java.lang.Object target, java.lang.Class<?>[] paramTypes, java.lang.Object... paramValues) Finds a method and invokes it when all its parameter types are known.
static java.lang.Object	invokeMethodByParamTypes(java.lang.String methodName, java.lang.Object target, java.lang.Class<?>[] paramTypes, java.lang.Object... paramValues) Finds a method and invokes it on the specified target object when all its parameter types are known.
static java.lang.Object	invokeMethodByParamValues(java.lang.Class<?> targetClass, java.lang.String methodName, java.lang.Object target, java.lang.Class<?>[] paramTypes, java.lang.Object... paramValues) Finds a method and invokes it when the parameter types are only partly known.
static java.lang.Object	invokeMethodByParamValues(java.lang.String methodName, java.lang.Object target, java.lang.Class<?>[] paramTypes, java.lang.Object... paramValues) Finds a method and invokes it on the specified target object when the parameter types are only partly known.
static java.lang.Class<?>	loadClass(java.lang.String className, java.lang.ClassLoader loader) Loads the class with the specified name using the given class loader.
static void	setProperty(java.lang.Object bean, java.lang.String name, java.lang.Object value) Sets the value of a property for the specified bean.
static void	setPropertyWithConversion(java.lang.Object bean, java.lang.String name, java.lang.Object value) Sets the value of a property for the specified bean applying type conversions if necessary.

Methods inherited from class java.lang.Object

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

Method Detail

loadClass

public static java.lang.Class<?> loadClass(java.lang.String className,
                                           java.lang.ClassLoader loader)

Loads the class with the specified name using the given class loader. This is a thin wrapper over the Class.forName() method. ClassNotFoundException exceptions are caught and re-thrown as InjectionException exceptions.

Parameters:

className - the name of the class to be loaded

loader - the class loader to use

Returns:

the loaded class

Throws:

java.lang.IllegalArgumentException - if the class name or the class loader is undefined

InjectionException - if the class cannot be resolved

invokeMethod

public static java.lang.Object invokeMethod(java.lang.reflect.Method method,
                                            java.lang.Object target,
                                            java.lang.Object... args)

Helper method for invoking a method using reflection. This method catches the variety of possible exceptions and re-throws them as runtime exceptions.

Parameters:

method - the method to be invoked

target - the target object

args - the arguments of the method

Returns:

the return value of the method

Throws:

InjectionException - if invoking the method causes an error

java.lang.IllegalArgumentException - if the method object is null

invokeConstructor

public static <T> T invokeConstructor(java.lang.reflect.Constructor<T> ctor,
                                      java.lang.Object... args)

Creates an object by invoking the specified constructor with the given arguments. Like invokeMethod(), this is a helper method that deals with all possible exceptions and redirects them as InjectionExceptions.

Parameters:

ctor - the constructor to be invoked (must not be null)

args - the arguments to be passed to the constructor

Returns:

the newly created instance

Throws:

InjectionException - if construction of the object fails

java.lang.IllegalArgumentException - if the constructor object is null

findMethodByParamTypes

public static java.lang.reflect.Method findMethodByParamTypes(java.lang.Class<?> targetClass,
                                                              java.lang.String methodName,
                                                              java.lang.Class<?>... types)

Finds a method in the specified target class when all parameter types are known.

Parameters:

targetClass - the target class

methodName - the name of the searched method

types - an array with the types of all parameters

Returns:

the found method

Throws:

InjectionException - if the method cannot be found

java.lang.IllegalArgumentException - if the method name is null or the target class is null

findMethodByParamValues

public static java.lang.reflect.Method findMethodByParamValues(java.lang.Class<?> targetClass,
                                                               java.lang.String methodName,
                                                               java.lang.Class<?>[] types,
                                                               java.lang.Object... values)

Finds a method if not all parameter types are exactly known.

This method can be used if a method is to be invoked and only the current parameter values (and maybe some of the exact parameter types) are known. In this case the signature of the method cannot directly be derived from the values of the parameter objects because calling the method could involve some legal type conversions like unboxing or widening conversions (see The Java Language Specification). So each parameter value has to be checked for compatibility with the type defined in the method signature.

This method expects two arrays as arguments: The 2nd array holds the parameter values to be passed to the method. The first array contains the known types of the signature. Its number of elements must equal the number of elements of the 2nd array. If the signature of the method to be called is partly known, the elements with the corresponding parameter indices can contain the exact parameter class. Otherwise they must be set to null. This implementation will iterate over the two arrays. If the current element of the first array is not null, the corresponding parameter type of the currently tested method is checked for equality. Otherwise it is checked for compatibility with the current element of the parameter values array.

Parameters:

targetClass - the class, on which to find the method (must not be null)

methodName - the name of the method to invoke (must not be null)

types - an array with the partly known exact parameter types of the searched method (unknown parameter types are represented by null values in this array)

values - an array with the current parameter values

Returns:

the found method

Throws:

InjectionException - if no compatible method can be found

java.lang.IllegalArgumentException - if either the target class is null or the method name is null or the number of elements in the arrays differ

findConstructorByParamTypes

public static <T> java.lang.reflect.Constructor<T> findConstructorByParamTypes(java.lang.Class<T> targetClass,
                                                                               java.lang.Class<?>... types)

Finds a constructor in the specified target class when all parameter types are known.

Parameters:

targetClass - the target class

types - an array with the types of all parameters

Returns:

the found constructor

Throws:

InjectionException - if the constructor cannot be found

findConstructorByParamValues

public static <T> java.lang.reflect.Constructor<T> findConstructorByParamValues(java.lang.Class<T> targetClass,
                                                                                java.lang.Class<?>[] types,
                                                                                java.lang.Object... values)

Finds a constructor if not all parameter types are exactly known. This method works like findMethodByParamValues(), but searches for a compatible constructor rather than a method.

Parameters:

targetClass - the class, on which to find the method (must not be null)

types - an array with the partly known exact parameter types of the searched method (unknown parameter types are represented by null values in this array)

values - an array with the current parameter values

Returns:

the found method

Throws:

InjectionException - if no compatible constructor can be found

java.lang.IllegalArgumentException - if either the target class is null or the number of elements in the arrays differ

invokeMethodByParamTypes

public static java.lang.Object invokeMethodByParamTypes(java.lang.Class<?> targetClass,
                                                        java.lang.String methodName,
                                                        java.lang.Object target,
                                                        java.lang.Class<?>[] paramTypes,
                                                        java.lang.Object... paramValues)

Finds a method and invokes it when all its parameter types are known. This is a convenience method that combines method lookup and invocation. First findMethodByParamTypes() is called for retrieving the method to be called. Then it is actually invoked passing in the specified parameters.

Parameters:

targetClass - the target class the method belongs to

methodName - the name of the method to invoke

target - the target object, on which to invoke the method

paramTypes - the classes of the parameters; specifies the signature of the method to invoke

paramValues - the actual values to be passed to the method

Returns:

the return value of the method

Throws:

InjectionException - if an error occurs during method invocation

java.lang.IllegalArgumentException - if invalid arguments are passed in

See Also:

findMethodByParamTypes(Class, String, Class[]), invokeMethod(Method, Object, Object...)

invokeMethodByParamTypes

public static java.lang.Object invokeMethodByParamTypes(java.lang.String methodName,
                                                        java.lang.Object target,
                                                        java.lang.Class<?>[] paramTypes,
                                                        java.lang.Object... paramValues)

Finds a method and invokes it on the specified target object when all its parameter types are known. This overloaded version derives the target class from the passed in target object (so this object must not be null); this may be more convenient when dealing with non-static methods.

Parameters:

methodName - the name of the method to invoke

target - the target object, on which to invoke the method

paramTypes - the classes of the parameters; specifies the signature of the method to invoke

paramValues - the actual values to be passed to the method

Returns:

the return value of the method

Throws:

InjectionException - if an error occurs during method invocation

java.lang.IllegalArgumentException - if invalid arguments are passed in

invokeMethodByParamValues

public static java.lang.Object invokeMethodByParamValues(java.lang.Class<?> targetClass,
                                                         java.lang.String methodName,
                                                         java.lang.Object target,
                                                         java.lang.Class<?>[] paramTypes,
                                                         java.lang.Object... paramValues)

Finds a method and invokes it when the parameter types are only partly known. This is a convenience method that combines method lookup and invocation. First findMethodByParamValues() is called for retrieving the method to be called. Then it is actually invoked passing in the specified parameters.

Parameters:

targetClass - the target class the method belongs to

methodName - the name of the method to invoke

target - the target object, on which to invoke the method

paramTypes - the classes of the parameters; specifies the signature of the method to invoke; array elements that represent unknown parameter types must be set to null

paramValues - the actual values to be passed to the method

Returns:

the return value of the method

Throws:

InjectionException - if an error occurs during method invocation

java.lang.IllegalArgumentException - if invalid arguments are passed in

See Also:

findMethodByParamValues(Class, String, Class[], Object[]), invokeMethod(Method, Object, Object...)

invokeMethodByParamValues

public static java.lang.Object invokeMethodByParamValues(java.lang.String methodName,
                                                         java.lang.Object target,
                                                         java.lang.Class<?>[] paramTypes,
                                                         java.lang.Object... paramValues)

Finds a method and invokes it on the specified target object when the parameter types are only partly known. This overloaded version derives the target class from the passed in target object (so this object must not be null); this may be more convenient when dealing with non-static methods.

Parameters:

methodName - the name of the method to invoke

target - the target object, on which to invoke the method

paramTypes - the classes of the parameters; specifies the signature of the method to invoke; array elements that represent unknown parameter types must be set to null

paramValues - the actual values to be passed to the method

Returns:

the return value of the method

Throws:

InjectionException - if an error occurs during method invocation

java.lang.IllegalArgumentException - if invalid arguments are passed in

invokeConstructorByParamTypes

public static <T> T invokeConstructorByParamTypes(java.lang.Class<T> targetClass,
                                                  java.lang.Class<?>[] paramTypes,
                                                  java.lang.Object... paramValues)

Finds a constructor and invokes it when the exact signature is known. This is a convenience method that combines lookup of the constructor with its invocation. First findConstructorByParamTypes() will be called. Then the found Constructor object is passed to invokeConstructor().

Parameters:

targetClass - the target class, to which the constructor belongs

paramTypes - an array with the parameter types of the constructor

paramValues - the current parameter values to be passed to the constructor

Returns:

the newly created instance

Throws:

InjectionException - if invocation of the constructor causes an error

java.lang.IllegalArgumentException - if invalid parameters are passed in

See Also:

findConstructorByParamTypes(Class, Class...), invokeConstructor(Constructor, Object...)

invokeConstructorByParamValues

public static <T> T invokeConstructorByParamValues(java.lang.Class<T> targetClass,
                                                   java.lang.Class<?>[] paramTypes,
                                                   java.lang.Object... paramValues)

Finds a constructor and invokes it when the signature is only partly known. This is a convenience method that combines lookup of the constructor with its invocation. First findConstructorByParamValues() will be called. Then the found Constructor object is passed to invokeConstructor().

Parameters:

targetClass - the target class, to which the constructor belongs

paramTypes - an array with the parameter types of the constructor (unknown types are represented by null elements)

paramValues - the current parameter values to be passed to the constructor

Returns:

the newly created instance

Throws:

InjectionException - if invocation of the constructor causes an error

java.lang.IllegalArgumentException - if invalid parameters are passed in

See Also:

findConstructorByParamValues(Class, Class[], Object...), invokeConstructor(Constructor, Object...)

getProperty

public static java.lang.Object getProperty(java.lang.Object bean,
                                           java.lang.String name)

Returns the value of the specified property from the given bean.

Parameters:

bean - the bean

name - the name of the property to retrieve

Returns:

the value of this property

Throws:

InjectionException - if accessing the property fails

java.lang.IllegalArgumentException - if invalid parameters are specified

setProperty

public static void setProperty(java.lang.Object bean,
                               java.lang.String name,
                               java.lang.Object value)

Sets the value of a property for the specified bean. The given value will be directly written into the property, without performing any type conversions. Occurring exceptions will be re-thrown as InjectionExceptions.

Parameters:

bean - the bean, on which to set the property

name - the name of the property to be set

value - the new value of the property

Throws:

InjectionException - if an error occurs when setting the property

java.lang.IllegalArgumentException - if invalid parameters are passed in

setPropertyWithConversion

public static void setPropertyWithConversion(java.lang.Object bean,
                                             java.lang.String name,
                                             java.lang.Object value)

Sets the value of a property for the specified bean applying type conversions if necessary. Note: This implementation is a thin wrapper over the BeanUtils.copyProperty() method from Apache Commons Beanutils. Type conversions are handled by this library; especially specific converters can be registered for custom data types.

Parameters:

bean - the bean, on which to set the property

name - the name of the property to be set

value - the new value of the property

Throws:

InjectionException - if an error occurs when setting the property

java.lang.IllegalArgumentException - if invalid parameters are passed in

convert

public static <T> T convert(java.lang.Class<T> targetClass,
                            java.lang.Object value)

Performs a type conversion if required. This method tries to convert the specified object into an object of the given target class. If the object can be casted to the target class already or if it is null, it is directly returned. Otherwise a type conversion is tried, and the result is returned (provided it was successful). Under the hood Apache Commons Beanutils is used for performing the conversion.

Type Parameters:

T - the type of the resulting object

Parameters:

targetClass - the target class to convert to (if null, no conversion will be performed)

value - the object to be converted

Returns:

the converted object

Throws:

java.lang.IllegalArgumentException - if conversion fails