MethodUtils (Griffon 0.9.5-rc2)
Date: 2012-03-09

Overview | Package | Class | Deprecated | Index | Help
| Griffon 0.9.5-rc2
| FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## griffon.util
[Java] Class MethodUtils

    java.lang.Object
      griffon.util.MethodUtils

    public class MethodUtils
    extends Object

Utility reflection methods focussed on methods in general rather than properties in particular.

Copied from commons-beanutils, removed dependencies to commons-logging

### Known Limitations

#### Accessing Public Methods In A Default Access Superclass

There is an issue when invoking public methods contained in a default access superclass. Reflection locates these methods fine and correctly assigns them as public. However, an `IllegalAccessException` is thrown if the method is invoked.

`MethodUtils` contains a workaround for this situation. It will attempt to call `setAccessible` on this method. If this call succeeds, then the method can be invoked as normal. This call will only succeed when the application has sufficient security privilages.

Authors:
  Craig R. McClanahan
  Ralph Schaer
  Chris Audley
  Rey François
  Gregor Raýman
  Jan Sorensen
  Robert Burrell Donkin

Nested Class Summary
`private static class` | `MethodUtils.MethodDescriptor` Represents the key to looking up a Method by reflection.

Field Summary
`private static boolean` | `CACHE_METHODS` Indicates whether methods should be cached for improved performance.
`private static Class[]` | `EMPTY_CLASS_PARAMETERS` An empty class array
`private static Object[]` | `EMPTY_OBJECT_ARRAY` An empty object array
`private static Map` | `cache` Stores a cache of MethodDescriptor -> Method in a WeakHashMap.

Constructor Summary
`MethodUtils()`

Method Summary
`private static void` | `cacheMethod(MethodUtils.MethodDescriptor md, Method method)` Add a method to the cache.
`static int` | `clearCache()` Clear the method cache.
`static Method` | `getAccessibleMethod(Class clazz, String methodName, Class parameterType)`
`static Method` | `getAccessibleMethod(Class clazz, String methodName, Class[] parameterTypes)`
`static Method` | `getAccessibleMethod(Method method)`
`static Method` | `getAccessibleMethod(Class clazz, Method method)`
`private static Method` | `getAccessibleMethodFromInterfaceNest(Class clazz, String methodName, Class[] parameterTypes)`
`private static Method` | `getAccessibleMethodFromSuperclass(Class clazz, String methodName, Class[] parameterTypes)`
`private static Method` | `getCachedMethod(MethodUtils.MethodDescriptor md)` Return the method from the cache, if present.
`static Method` | `getMatchingAccessibleMethod(Class clazz, String methodName, Class[] parameterTypes)`
`private static float` | `getObjectTransformationCost(Class srcClass, Class destClass)` Gets the number of steps required needed to turn the source class into the destination class.
`static Class` | `getPrimitiveType(Class wrapperType)` Gets the class for the primitive type corresponding to the primitive wrapper class given.
`static Class` | `getPrimitiveWrapper(Class primitiveType)` Gets the wrapper object class for the given primitive type class.
`private static float` | `getTotalTransformationCost(Class[] srcArgs, Class[] destArgs)` Returns the sum of the object transformation cost for each class in the source argument list.
`static Object` | `invokeExactMethod(Object object, String methodName, Object arg)`
`static Object` | `invokeExactMethod(Object object, String methodName, Object[] args)`
`static Object` | `invokeExactMethod(Object object, String methodName, Object[] args, Class[] parameterTypes)`
`static Object` | `invokeExactStaticMethod(Class objectClass, String methodName, Object[] args, Class[] parameterTypes)`
`static Object` | `invokeExactStaticMethod(Class objectClass, String methodName, Object arg)`
`static Object` | `invokeExactStaticMethod(Class objectClass, String methodName, Object[] args)`
`static Object` | `invokeMethod(Object object, String methodName, Object arg)`
`static Object` | `invokeMethod(Object object, String methodName, Object[] args)`
`static Object` | `invokeMethod(Object object, String methodName, Object[] args, Class[] parameterTypes)`
`static Object` | `invokeStaticMethod(Class objectClass, String methodName, Object arg)`
`static Object` | `invokeStaticMethod(Class objectClass, String methodName, Object[] args)`
`static Object` | `invokeStaticMethod(Class objectClass, String methodName, Object[] args, Class[] parameterTypes)`
`static boolean` | `isAssignmentCompatible(Class parameterType, Class parameterization)`
`static void` | `setCacheMethods(boolean cacheMethods)` Set whether methods should be cached for greater performance or not, default is `true`.
`private static void` | `setMethodAccessible(Method method)` Try to make the method accessible
`static Class` | `toNonPrimitiveClass(Class clazz)` Find a non primitive representation for given primitive class.

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

Field Detail

### CACHE_METHODS

    private static boolean CACHE_METHODS

  Indicates whether methods should be cached for improved performance.

  Note that when this class is deployed via a shared classloader in a container, this will affect all webapps. However making this configurable per webapp would mean having a map keyed by context classloader which may introduce memory-leak problems.

### EMPTY_CLASS_PARAMETERS

    private static final Class[] EMPTY_CLASS_PARAMETERS

  An empty class array

### EMPTY_OBJECT_ARRAY

    private static final Object[] EMPTY_OBJECT_ARRAY

  An empty object array

### cache

    private static final Map cache

  Stores a cache of MethodDescriptor -> Method in a WeakHashMap.

  The keys into this map only ever exist as temporary variables within methods of this class, and are never exposed to users of this class. This means that the WeakHashMap is used only as a mechanism for limiting the size of the cache, ie a way to tell the garbage collector that the contents of the cache can be completely garbage-collected whenever it needs the memory. Whether this is a good approach to this problem is doubtful; something like the commons-collections LRUMap may be more appropriate (though of course selecting an appropriate size is an issue).

  This static variable is safe even when this code is deployed via a shared classloader because it is keyed via a MethodDescriptor object which has a Class as one of its members and that member is used in the MethodDescriptor.equals method. So two components that load the same class via different classloaders will generate non-equal MethodDescriptor objects and hence end up with different entries in the map.

Constructor Detail

### MethodUtils

    MethodUtils()

Method Detail

### cacheMethod

    private static void cacheMethod(MethodUtils.MethodDescriptor md, Method method)

  Add a method to the cache.
  Parameters:
    `md` - The method descriptor
    `method` - The method to cache

### clearCache

    public static int clearCache()

  Clear the method cache.
  Returns:
    the number of cached methods cleared
  Since:
    1.8.0

### getAccessibleMethod

    public static Method getAccessibleMethod(Class clazz, String methodName, Class parameterType)

  Return an accessible method (that is, one that can be invoked via reflection) with given name and a single parameter. If no such method can be found, return `null`. Basically, a convenience wrapper that constructs a `Class` array for you.

  Parameters:
    `clazz` - get method from this class
    `methodName` - get method with this name
    `parameterType` - taking this type of parameter
  Returns:
    The accessible method

### getAccessibleMethod

    public static Method getAccessibleMethod(Class clazz, String methodName, Class[] parameterTypes)

  Return an accessible method (that is, one that can be invoked via reflection) with given name and parameters. If no such method can be found, return `null`. This is just a convenient wrapper for getAccessibleMethod(Method method).

  Parameters:
    `clazz` - get method from this class
    `methodName` - get method with this name
    `parameterTypes` - with these parameters types
  Returns:
    The accessible method

### getAccessibleMethod

    public static Method getAccessibleMethod(Method method)

  Return an accessible method (that is, one that can be invoked via reflection) that implements the specified Method. If no such method can be found, return `null`.

  Parameters:
    `method` - The method that we wish to call
  Returns:
    The accessible method

### getAccessibleMethod

    public static Method getAccessibleMethod(Class clazz, Method method)

  Return an accessible method (that is, one that can be invoked via reflection) that implements the specified Method. If no such method can be found, return `null`.

  Parameters:
    `clazz` - The class of the object
    `method` - The method that we wish to call
  Returns:
    The accessible method
  Since:
    1.8.0

### getAccessibleMethodFromInterfaceNest

    private static Method getAccessibleMethodFromInterfaceNest(Class clazz, String methodName, Class[] parameterTypes)

  Return an accessible method (that is, one that can be invoked via reflection) that implements the specified method, by scanning through all implemented interfaces and subinterfaces. If no such method can be found, return `null`.

  There isn't any good reason why this method must be private. It is because there doesn't seem any reason why other classes should call this rather than the higher level methods.

  Parameters:
    `clazz` - Parent class for the interfaces to be checked
    `methodName` - Method name of the method we wish to call
    `parameterTypes` - The parameter type signatures

### getAccessibleMethodFromSuperclass

    private static Method getAccessibleMethodFromSuperclass(Class clazz, String methodName, Class[] parameterTypes)

  Return an accessible method (that is, one that can be invoked via reflection) by scanning through the superclasses. If no such method can be found, return `null`.

  Parameters:
    `clazz` - Class to be checked
    `methodName` - Method name of the method we wish to call
    `parameterTypes` - The parameter type signatures

### getCachedMethod

    private static Method getCachedMethod(MethodUtils.MethodDescriptor md)

  Return the method from the cache, if present.
  Parameters:
    `md` - The method descriptor
  Returns:
    The cached method

### getMatchingAccessibleMethod

    public static Method getMatchingAccessibleMethod(Class clazz, String methodName, Class[] parameterTypes)

  Find an accessible method that matches the given name and has compatible parameters. Compatible parameters mean that every method parameter is assignable from the given parameters. In other words, it finds a method with the given name that will take the parameters given.

  This method is slightly undeterminstic since it loops through methods names and return the first matching method.

  This method is used by invokeMethod(Object object, String methodName, Object [] args, Class[] parameterTypes).

  This method can match primitive parameter by passing in wrapper classes. For example, a `Boolean` will match a primitive `boolean` parameter.

  Parameters:
    `clazz` - find method in this class
    `methodName` - find method with this name
    `parameterTypes` - find method with compatible parameters
  Returns:
    The accessible method

### getObjectTransformationCost

    private static float getObjectTransformationCost(Class srcClass, Class destClass)

  Gets the number of steps required needed to turn the source class into the destination class. This represents the number of steps in the object hierarchy graph.
  Parameters:
    `srcClass` - The source class
    `destClass` - The destination class
  Returns:
    The cost of transforming an object

### getPrimitiveType

    public static Class getPrimitiveType(Class wrapperType)

  Gets the class for the primitive type corresponding to the primitive wrapper class given. For example, an instance of `Boolean.class` returns a `boolean.class`.
  Parameters:
    `wrapperType` - the
  Returns:
    the primitive type class corresponding to the given wrapper class, null if no match is found

### getPrimitiveWrapper

    public static Class getPrimitiveWrapper(Class primitiveType)

  Gets the wrapper object class for the given primitive type class. For example, passing `boolean.class` returns `Boolean.class`
  Parameters:
    `primitiveType` - the primitive type class for which a match is to be found
  Returns:
    the wrapper type associated with the given primitive or null if no match is found

### getTotalTransformationCost

    private static float getTotalTransformationCost(Class[] srcArgs, Class[] destArgs)

  Returns the sum of the object transformation cost for each class in the source argument list.
  Parameters:
    `srcArgs` - The source arguments
    `destArgs` - The destination arguments
  Returns:
    The total transformation cost

### invokeExactMethod

    public static Object invokeExactMethod(Object object, String methodName, Object arg)

  Invoke a method whose parameter type matches exactly the object type.

  This is a convenient wrapper for invokeExactMethod(Object object, String methodName, Object [] args).

  throws:
    NoSuchMethodException if there is no such accessible method
  throws:
    InvocationTargetException wraps an exception thrown by the method invoked
  throws:
    IllegalAccessException if the requested method is not accessible via reflection
  Parameters:
    `object` - invoke method on this object
    `methodName` - get method with this name
    `arg` - use this argument
  Returns:
    The value returned by the invoked method

### invokeExactMethod

    public static Object invokeExactMethod(Object object, String methodName, Object[] args)

  Invoke a method whose parameter types match exactly the object types.

  This uses reflection to invoke the method obtained from a call to `getAccessibleMethod()`.

  throws:
    NoSuchMethodException if there is no such accessible method
  throws:
    InvocationTargetException wraps an exception thrown by the method invoked
  throws:
    IllegalAccessException if the requested method is not accessible via reflection
  Parameters:
    `object` - invoke method on this object
    `methodName` - get method with this name
    `args` - use these arguments - treat null as empty array
  Returns:
    The value returned by the invoked method

### invokeExactMethod

    public static Object invokeExactMethod(Object object, String methodName, Object[] args, Class[] parameterTypes)

  Invoke a method whose parameter types match exactly the parameter types given.

  This uses reflection to invoke the method obtained from a call to `getAccessibleMethod()`.

  throws:
    NoSuchMethodException if there is no such accessible method
  throws:
    InvocationTargetException wraps an exception thrown by the method invoked
  throws:
    IllegalAccessException if the requested method is not accessible via reflection
  Parameters:
    `object` - invoke method on this object
    `methodName` - get method with this name
    `args` - use these arguments - treat null as empty array
    `parameterTypes` - match these parameters - treat null as empty array
  Returns:
    The value returned by the invoked method

### invokeExactStaticMethod

    public static Object invokeExactStaticMethod(Class objectClass, String methodName, Object[] args, Class[] parameterTypes)

  Invoke a static method whose parameter types match exactly the parameter types given.

  This uses reflection to invoke the method obtained from a call to getAccessibleMethod(Class, String, Class[]).

  throws:
    NoSuchMethodException if there is no such accessible method
  throws:
    InvocationTargetException wraps an exception thrown by the method invoked
  throws:
    IllegalAccessException if the requested method is not accessible via reflection
  Parameters:
    `objectClass` - invoke static method on this class
    `methodName` - get method with this name
    `args` - use these arguments - treat null as empty array
    `parameterTypes` - match these parameters - treat null as empty array
  Returns:
    The value returned by the invoked method
  Since:
    1.8.0

### invokeExactStaticMethod

    public static Object invokeExactStaticMethod(Class objectClass, String methodName, Object arg)

  Invoke a static method whose parameter type matches exactly the object type.

  This is a convenient wrapper for invokeExactStaticMethod(Class objectClass, String methodName, Object [] args).

  throws:
    NoSuchMethodException if there is no such accessible method
  throws:
    InvocationTargetException wraps an exception thrown by the method invoked
  throws:
    IllegalAccessException if the requested method is not accessible via reflection
  Parameters:
    `objectClass` - invoke static method on this class
    `methodName` - get method with this name
    `arg` - use this argument
  Returns:
    The value returned by the invoked method
  Since:
    1.8.0

### invokeExactStaticMethod

    public static Object invokeExactStaticMethod(Class objectClass, String methodName, Object[] args)

  Invoke a static method whose parameter types match exactly the object types.

  This uses reflection to invoke the method obtained from a call to getAccessibleMethod(Class, String, Class[]).

  throws:
    NoSuchMethodException if there is no such accessible method
  throws:
    InvocationTargetException wraps an exception thrown by the method invoked
  throws:
    IllegalAccessException if the requested method is not accessible via reflection
  Parameters:
    `objectClass` - invoke static method on this class
    `methodName` - get method with this name
    `args` - use these arguments - treat null as empty array
  Returns:
    The value returned by the invoked method
  Since:
    1.8.0

### invokeMethod

    public static Object invokeMethod(Object object, String methodName, Object arg)

  Invoke a named method whose parameter type matches the object type.

  The behaviour of this method is less deterministic than `invokeExactMethod()`. It loops through all methods with names that match and then executes the first it finds with compatable parameters.

  This method supports calls to methods taking primitive parameters via passing in wrapping classes. So, for example, a `Boolean` class would match a `boolean` primitive.

  This is a convenient wrapper for invokeMethod(Object object, String methodName, Object [] args).

  throws:
    NoSuchMethodException if there is no such accessible method
  throws:
    InvocationTargetException wraps an exception thrown by the method invoked
  throws:
    IllegalAccessException if the requested method is not accessible via reflection
  Parameters:
    `object` - invoke method on this object
    `methodName` - get method with this name
    `arg` - use this argument
  Returns:
    The value returned by the invoked method

### invokeMethod

    public static Object invokeMethod(Object object, String methodName, Object[] args)

  Invoke a named method whose parameter type matches the object type.

  The behaviour of this method is less deterministic than invokeExactMethod(Object object, String methodName, Object [] args). It loops through all methods with names that match and then executes the first it finds with compatable parameters.

  This method supports calls to methods taking primitive parameters via passing in wrapping classes. So, for example, a `Boolean` class would match a `boolean` primitive.

  This is a convenient wrapper for invokeMethod(Object object, String methodName, Object [] args, Class[] parameterTypes).

  throws:
    NoSuchMethodException if there is no such accessible method
  throws:
    InvocationTargetException wraps an exception thrown by the method invoked
  throws:
    IllegalAccessException if the requested method is not accessible via reflection
  Parameters:
    `object` - invoke method on this object
    `methodName` - get method with this name
    `args` - use these arguments - treat null as empty array
  Returns:
    The value returned by the invoked method

### invokeMethod

    public static Object invokeMethod(Object object, String methodName, Object[] args, Class[] parameterTypes)

  Invoke a named method whose parameter type matches the object type.

  The behaviour of this method is less deterministic than invokeExactMethod(Object object, String methodName, Object [] args, Class[] parameterTypes). It loops through all methods with names that match and then executes the first it finds with compatable parameters.

  This method supports calls to methods taking primitive parameters via passing in wrapping classes. So, for example, a `Boolean` class would match a `boolean` primitive.

  throws:
    NoSuchMethodException if there is no such accessible method
  throws:
    InvocationTargetException wraps an exception thrown by the method invoked
  throws:
    IllegalAccessException if the requested method is not accessible via reflection
  Parameters:
    `object` - invoke method on this object
    `methodName` - get method with this name
    `args` - use these arguments - treat null as empty array
    `parameterTypes` - match these parameters - treat null as empty array
  Returns:
    The value returned by the invoked method

### invokeStaticMethod

    public static Object invokeStaticMethod(Class objectClass, String methodName, Object arg)

  Invoke a named static method whose parameter type matches the object type.

  The behaviour of this method is less deterministic than invokeExactMethod(Object, String, Object[], Class[]). It loops through all methods with names that match and then executes the first it finds with compatable parameters.

  This method supports calls to methods taking primitive parameters via passing in wrapping classes. So, for example, a `Boolean` class would match a `boolean` primitive.

  This is a convenient wrapper for invokeStaticMethod(Class objectClass, String methodName, Object [] args).

  throws:
    NoSuchMethodException if there is no such accessible method
  throws:
    InvocationTargetException wraps an exception thrown by the method invoked
  throws:
    IllegalAccessException if the requested method is not accessible via reflection
  Parameters:
    `objectClass` - invoke static method on this class
    `methodName` - get method with this name
    `arg` - use this argument
  Returns:
    The value returned by the invoked method
  Since:
    1.8.0

### invokeStaticMethod

    public static Object invokeStaticMethod(Class objectClass, String methodName, Object[] args)

  Invoke a named static method whose parameter type matches the object type.

  The behaviour of this method is less deterministic than invokeExactMethod(Object object, String methodName, Object [] args). It loops through all methods with names that match and then executes the first it finds with compatable parameters.

  This method supports calls to methods taking primitive parameters via passing in wrapping classes. So, for example, a `Boolean` class would match a `boolean` primitive.

  This is a convenient wrapper for invokeStaticMethod(Class objectClass, String methodName, Object [] args, Class[] parameterTypes).

  throws:
    NoSuchMethodException if there is no such accessible method
  throws:
    InvocationTargetException wraps an exception thrown by the method invoked
  throws:
    IllegalAccessException if the requested method is not accessible via reflection
  Parameters:
    `objectClass` - invoke static method on this class
    `methodName` - get method with this name
    `args` - use these arguments - treat null as empty array
  Returns:
    The value returned by the invoked method
  Since:
    1.8.0

### invokeStaticMethod

    public static Object invokeStaticMethod(Class objectClass, String methodName, Object[] args, Class[] parameterTypes)

  Invoke a named static method whose parameter type matches the object type.

  The behaviour of this method is less deterministic than invokeExactStaticMethod(Class objectClass, String methodName, Object [] args, Class[] parameterTypes). It loops through all methods with names that match and then executes the first it finds with compatable parameters.

  This method supports calls to methods taking primitive parameters via passing in wrapping classes. So, for example, a `Boolean` class would match a `boolean` primitive.

  throws:
    NoSuchMethodException if there is no such accessible method
  throws:
    InvocationTargetException wraps an exception thrown by the method invoked
  throws:
    IllegalAccessException if the requested method is not accessible via reflection
  Parameters:
    `objectClass` - invoke static method on this class
    `methodName` - get method with this name
    `args` - use these arguments - treat null as empty array
    `parameterTypes` - match these parameters - treat null as empty array
  Returns:
    The value returned by the invoked method
  Since:
    1.8.0

### isAssignmentCompatible

    public static final boolean isAssignmentCompatible(Class parameterType, Class parameterization)

  Determine whether a type can be used as a parameter in a method invocation. This method handles primitive conversions correctly.

  In order words, it will match a `Boolean` to a `boolean`, a `Long` to a `long`, a `Float` to a `float`, a `Integer` to a `int`, and a `Double` to a `double`. Now logic widening matches are allowed. For example, a `Long` will not match a `int`.

  Parameters:
    `parameterType` - the type of parameter accepted by the method
    `parameterization` - the type of parameter being tested
  Returns:
    true if the assignement is compatible.

### setCacheMethods

    public static void setCacheMethods(boolean cacheMethods)

  Set whether methods should be cached for greater performance or not, default is `true`.
  Parameters:
    `cacheMethods` - `true` if methods should be cached for greater performance, otherwise `false`
  Since:
    1.8.0

### setMethodAccessible

    private static void setMethodAccessible(Method method)

  Try to make the method accessible
  Parameters:
    `method` - The source arguments

### toNonPrimitiveClass

    public static Class toNonPrimitiveClass(Class clazz)

  Find a non primitive representation for given primitive class.
  Parameters:
    `clazz` - the class to find a representation for, not null
  Returns:
    the original class if it not a primitive. Otherwise the wrapper class. Not null

Groovy Documentation