net.sf.jguiraffe.di

Class InvocationHelper

java.lang.Object

net.sf.jguiraffe.di.InvocationHelper

public class InvocationHelper
extends Object

A helper class providing some more complex functionality related to reflection.

This class builds on top of ReflectionUtils which implements low-level utility methods for various operations related to reflection. InvocationHelper in contrast focuses on some more advanced operations. It deals with stuff like finding suitable methods and constructors to be invoked, getting and setting properties, and data type conversions (this is delegated to an instance of ConversionHelper which is maintained by this class).

Implementation note: This class is thread-safe.

Version:

$Id: InvocationHelper.java 205 2012-01-29 18:29:57Z oheger $

Author:

Oliver Heger

Constructor Summary

Constructors

Constructor and Description
InvocationHelper() Creates a new instance of InvocationHelper.
InvocationHelper(ConversionHelper convHlp) Creates a new instance of InvocationHelper and initializes it with the given ConversionHelper instance.

Method Summary

Modifier and Type	Method and Description
protected Object[]	convertArguments(Class<?>[] parameterTypes, Object[] args) Performs necessary type conversions before invoking a method.
<T> Constructor<T>	findUniqueConstructor(Class<T> targetClass, Class<?>[] parameterTypes, Object[] args) Tries to match a single constructor of the specified target class given the parameter types and the call arguments.
Method	findUniqueMethod(Class<?> targetClass, String methodName, Class<?>[] parameterTypes, Object[] args) Determines the method to be called given the name, the parameter types, and the arguments.
ConversionHelper	getConversionHelper() Returns the ConversionHelper instance associated with this object.
<T> T	invokeConstructor(Class<T> targetClass, Class<?>[] parameterTypes, Object[] args) Invokes a constructor.
Object	invokeInstanceMethod(Object instance, String methodName, Class<?>[] parameterTypes, Object[] args) Invokes a method on the specified object.
Object	invokeMethod(Class<?> targetClass, Object instance, String methodName, Class<?>[] parameterTypes, Object[] args) Invokes a method.
Object	invokeStaticMethod(Class<?> targetClass, String methodName, Class<?>[] parameterTypes, Object[] args) Invokes the specified static method and returns its result.
void	setProperty(Object bean, String property, Object value) Sets a property of the given bean.

Methods inherited from class java.lang.Object

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

Constructor Detail

InvocationHelper

public InvocationHelper()

Creates a new instance of InvocationHelper. A default ConversionHelper instance is set.

InvocationHelper

public InvocationHelper(ConversionHelper convHlp)

Creates a new instance of InvocationHelper and initializes it with the given ConversionHelper instance. If no helper object is provided, a new default instance is created.

Parameters:

convHlp - the ConversionHelper

Method Detail

getConversionHelper

public ConversionHelper getConversionHelper()

Returns the ConversionHelper instance associated with this object.

Returns:

the ConversionHelper

findUniqueMethod

public Method findUniqueMethod(Class<?> targetClass,
                               String methodName,
                               Class<?>[] parameterTypes,
                               Object[] args)

Determines the method to be called given the name, the parameter types, and the arguments. This method delegates to ReflectionUtils.findMethods(Class, String, Class[], boolean) to find a single method that matches the specified method signature. It also takes the specified method arguments into account in order to find a unique match. If this is not possible, an exception is thrown.

Parameters:

targetClass - the class on which to invoke the method

methodName - the name of the method to be invoked

parameterTypes - an array with the known parameter types (may be null or contain null entries representing wild cards)

args - an array with the method arguments

Returns:

the method to be invoked

Throws:

InjectionException - if the method cannot be determined

IllegalArgumentException - if the target class is null

findUniqueConstructor

public <T> Constructor<T> findUniqueConstructor(Class<T> targetClass,
                                                Class<?>[] parameterTypes,
                                                Object[] args)

Tries to match a single constructor of the specified target class given the parameter types and the call arguments. This method works analogously to findUniqueMethod(Class, String, Class[], Object[]), but it searches for a matching constructor.

Type Parameters:

T - the type of the target class

Parameters:

targetClass - the class on which to invoke the method

parameterTypes - an array with the known parameter types (may be null or contain null entries representing wild cards)

args - an array with the call arguments

Returns:

the unique constructor matching the specified criteria

Throws:

InjectionException - if no unique constructor can be determined

IllegalArgumentException - if the target class is null

invokeStaticMethod

public Object invokeStaticMethod(Class<?> targetClass,
                                 String methodName,
                                 Class<?>[] parameterTypes,
                                 Object[] args)

Invokes the specified static method and returns its result.

Parameters:

targetClass - the target class on which to invoke the method (must not be null)

methodName - the name of the method

parameterTypes - an array with the known parameter types (may be null or contain null entries representing wild cards)

args - an array with the method arguments

Returns:

the result returned by the method

Throws:

InjectionException - if an exception occurs

IllegalArgumentException - if the target class is undefined

invokeInstanceMethod

public Object invokeInstanceMethod(Object instance,
                                   String methodName,
                                   Class<?>[] parameterTypes,
                                   Object[] args)

Invokes a method on the specified object. The object must not be null because the target class is obtained from it. Then this implementation delegates to invokeMethod(Class, Object, String, Class[], Object[]).

Parameters:

instance - the instance on which to invoke the method

methodName - the name of the method to be invoked

parameterTypes - an array with the known parameter types (may be null or contain null entries representing wild cards)

args - an array with the method arguments

Returns:

the result returned by the method

Throws:

InjectionException - if an exception occurs

IllegalArgumentException - if the instance is undefined

invokeMethod

public Object invokeMethod(Class<?> targetClass,
                           Object instance,
                           String methodName,
                           Class<?>[] parameterTypes,
                           Object[] args)

Invokes a method. This is the most generic form of invoking a method. It works with both static and instance methods. This method delegates to findUniqueMethod(Class, String, Class[], Object[]) to find the method to be invoked. Then it performs necessary type conversions of the parameters. Eventually, it invokes the method. Using this method it is possible to invoke a specific method in a given class, even if the parameter types are not or only partly known. All possible exceptions (e.g. no unique method is found, the parameters cannot be converted, reflection-related exceptions) are thrown as InjectionException exceptions.

Parameters:

targetClass - the target class on which to invoke the method (may be null if an object instance is provided)

instance - the instance on which to invoke the method (may be null for static methods)

methodName - the name of the method to be invoked

parameterTypes - an array with the known parameter types (may be null or contain null entries representing wild cards)

args - an array with the method arguments

Returns:

the result returned by the method

Throws:

InjectionException - if an exception occurs

IllegalArgumentException - if a required parameter is missing or the specification of the method to be called is invalid

invokeConstructor

public <T> T invokeConstructor(Class<T> targetClass,
                               Class<?>[] parameterTypes,
                               Object[] args)

Invokes a constructor. This method delegates to findUniqueConstructor(Class, Class[], Object[]) to obtain the constructor to be invoked. Then it performs necessary type conversions of the parameters. Eventually, it invokes the constructor and returns the newly created instance. Using this method it is possible to invoke a specific constructor of a given class, even if the parameter types are not or only partly known. All possible exceptions (e.g. no unique method is found, the parameters cannot be converted, reflection-related exceptions) are thrown as InjectionException exceptions.

Type Parameters:

T - the type of the target class

Parameters:

targetClass - the target class on which the constructor is to be invoked

parameterTypes - an array with the known parameter types (may be null or contain null entries representing wild cards)

args - an array with the method arguments

Returns:

the newly created instance

Throws:

InjectionException - if an exception occurs

IllegalArgumentException - if the specification of the constructor is invalid

setProperty

public void setProperty(Object bean,
                        String property,
                        Object value)

Sets a property of the given bean. This method obtains the set method for the property in question. If necessary, type conversion is performed. Then the set method is invoked so that the new value of the property is written. Occurring exceptions are redirected either as InjectionException (if they are related to reflection operations) or as IllegalArgumentException if they are related to the parameters passed to this method.

Parameters:

bean - the bean on which to set the property

property - the name of the property to be set

value - the value of the property

Throws:

InjectionException - if an error occurs related to reflection

IllegalArgumentException - if invalid arguments are passed in

convertArguments

protected Object[] convertArguments(Class<?>[] parameterTypes,
                                    Object[] args)

Performs necessary type conversions before invoking a method. This method is called before a method or a constructor is invoked. The passed in parameter types are the actual parameters of the method to be invoked, the arguments are the ones passed by the caller. They may require a type conversion. This implementation performs this conversion if necessary.

Parameters:

parameterTypes - the array with the parameter types

args - the array with the call arguments

Returns:

an array with the converted arguments

Throws:

InjectionException - if a conversion fails