ReflectionUtils (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.util

## Class ReflectionUtils

- java.lang.Object
- - org.springframework.util.ReflectionUtils

-     public abstract class ReflectionUtils
      extends Object

  Simple utility class for working with the reflection API and handling reflection exceptions.

  Only intended for internal use.

  Since:
    1.2.2
  Author:
    Juergen Hoeller, Rob Harrop, Rod Johnson, Costin Leau, Sam Brannen, Chris Beams

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `ReflectionUtils.FieldCallback` Callback interface invoked on each field in the hierarchy.
    `static interface` | `ReflectionUtils.FieldFilter` Callback optionally used to filter fields to be operated on by a field callback.
    `static interface` | `ReflectionUtils.MethodCallback` Action to take on each method.
    `static interface` | `ReflectionUtils.MethodFilter` Callback optionally used to filter methods to be operated on by a method callback.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static ReflectionUtils.FieldFilter` | `COPYABLE_FIELDS` Pre-built FieldFilter that matches all non-static, non-final fields.
    `static ReflectionUtils.MethodFilter` | `NON_BRIDGED_METHODS` Pre-built MethodFilter that matches all non-bridge methods.
    `static ReflectionUtils.MethodFilter` | `USER_DECLARED_METHODS` Pre-built MethodFilter that matches all non-bridge methods which are not declared on `java.lang.Object`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ReflectionUtils()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `declaresException(Method method, Class<?> exceptionType)` Determine whether the given method explicitly declares the given exception or one of its superclasses, which means that an exception of that type can be propagated as-is within a reflective invocation.
    `static void` | `doWithFields(Class<?> clazz, ReflectionUtils.FieldCallback fc)` Invoke the given callback on all fields in the target class, going up the class hierarchy to get all declared fields.
    `static void` | `doWithFields(Class<?> clazz, ReflectionUtils.FieldCallback fc, ReflectionUtils.FieldFilter ff)` Invoke the given callback on all fields in the target class, going up the class hierarchy to get all declared fields.
    `static void` | `doWithMethods(Class<?> clazz, ReflectionUtils.MethodCallback mc)` Perform the given callback operation on all matching methods of the given class and superclasses.
    `static void` | `doWithMethods(Class<?> clazz, ReflectionUtils.MethodCallback mc, ReflectionUtils.MethodFilter mf)` Perform the given callback operation on all matching methods of the given class and superclasses (or given interface and super-interfaces).
    `static Field` | `findField(Class<?> clazz, String name)` Attempt to find a `field` on the supplied `Class` with the supplied `name`.
    `static Field` | `findField(Class<?> clazz, String name, Class<?> type)` Attempt to find a `field` on the supplied `Class` with the supplied `name` and/or `type`.
    `static Method` | `findMethod(Class<?> clazz, String name)` Attempt to find a `Method` on the supplied class with the supplied name and no parameters.
    `static Method` | `findMethod(Class<?> clazz, String name, Class<?>... paramTypes)` Attempt to find a `Method` on the supplied class with the supplied name and parameter types.
    `static Method[]` | `getAllDeclaredMethods(Class<?> leafClass)` Get all declared methods on the leaf class and all superclasses.
    `static Object` | `getField(Field field, Object target)` Get the field represented by the supplied `field object` on the specified `target object`.
    `static Method[]` | `getUniqueDeclaredMethods(Class<?> leafClass)` Get the unique set of declared methods on the leaf class and all superclasses.
    `static void` | `handleInvocationTargetException(InvocationTargetException ex)` Handle the given invocation target exception.
    `static void` | `handleReflectionException(Exception ex)` Handle the given reflection exception.
    `static Object` | `invokeJdbcMethod(Method method, Object target)` Invoke the specified JDBC API `Method` against the supplied target object with no arguments.
    `static Object` | `invokeJdbcMethod(Method method, Object target, Object... args)` Invoke the specified JDBC API `Method` against the supplied target object with the supplied arguments.
    `static Object` | `invokeMethod(Method method, Object target)` Invoke the specified `Method` against the supplied target object with no arguments.
    `static Object` | `invokeMethod(Method method, Object target, Object... args)` Invoke the specified `Method` against the supplied target object with the supplied arguments.
    `static boolean` | `isCglibRenamedMethod(Method renamedMethod)` Determine whether the given method is a CGLIB 'renamed' method, following the pattern "CGLIB$methodName$0".
    `static boolean` | `isEqualsMethod(Method method)` Determine whether the given method is an "equals" method.
    `static boolean` | `isHashCodeMethod(Method method)` Determine whether the given method is a "hashCode" method.
    `static boolean` | `isObjectMethod(Method method)` Determine whether the given method is originally declared by `Object`.
    `static boolean` | `isPublicStaticFinal(Field field)` Determine whether the given field is a "public static final" constant.
    `static boolean` | `isToStringMethod(Method method)` Determine whether the given method is a "toString" method.
    `static void` | `makeAccessible(Constructor<?> ctor)` Make the given constructor accessible, explicitly setting it accessible if necessary.
    `static void` | `makeAccessible(Field field)` Make the given field accessible, explicitly setting it accessible if necessary.
    `static void` | `makeAccessible(Method method)` Make the given method accessible, explicitly setting it accessible if necessary.
    `static void` | `rethrowException(Throwable ex)` Rethrow the given `exception`, which is presumably the target exception of an `InvocationTargetException`.
    `static void` | `rethrowRuntimeException(Throwable ex)` Rethrow the given `exception`, which is presumably the target exception of an `InvocationTargetException`.
    `static void` | `setField(Field field, Object target, Object value)` Set the field represented by the supplied `field object` on the specified `target object` to the specified `value`.
    `static void` | `shallowCopyFieldState(Object src, Object dest)` Given the source object and the destination, which must be the same class or a subclass, copy all fields, including inherited fields.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### COPYABLE_FIELDS

          public static ReflectionUtils.FieldFilter COPYABLE_FIELDS

      Pre-built FieldFilter that matches all non-static, non-final fields.

    - #### NON_BRIDGED_METHODS

          public static ReflectionUtils.MethodFilter NON_BRIDGED_METHODS

      Pre-built MethodFilter that matches all non-bridge methods.

    - #### USER_DECLARED_METHODS

          public static ReflectionUtils.MethodFilter USER_DECLARED_METHODS

      Pre-built MethodFilter that matches all non-bridge methods which are not declared on `java.lang.Object`.

  - ### Constructor Detail

    - #### ReflectionUtils

          public ReflectionUtils()

  - ### Method Detail

    - #### findField

          public static Field findField(Class<?> clazz,
                        String name)

      Attempt to find a `field` on the supplied `Class` with the supplied `name`. Searches all superclasses up to `Object`.
      Parameters:
        `clazz` - the class to introspect
        `name` - the name of the field
      Returns:
        the corresponding Field object, or `null` if not found

    - #### findField

          public static Field findField(Class<?> clazz,
                        String name,
                        Class<?> type)

      Attempt to find a `field` on the supplied `Class` with the supplied `name` and/or `type`. Searches all superclasses up to `Object`.
      Parameters:
        `clazz` - the class to introspect
        `name` - the name of the field (may be `null` if type is specified)
        `type` - the type of the field (may be `null` if name is specified)
      Returns:
        the corresponding Field object, or `null` if not found

    - #### setField

          public static void setField(Field field,
                      Object target,
                      Object value)

      Set the field represented by the supplied `field object` on the specified `target object` to the specified `value`. In accordance with `Field.set(Object, Object)` semantics, the new value is automatically unwrapped if the underlying field has a primitive type.

      Thrown exceptions are handled via a call to `handleReflectionException(Exception)`.

      Parameters:
        `field` - the field to set
        `target` - the target object on which to set the field
        `value` - the value to set; may be `null`

    - #### getField

          public static Object getField(Field field,
                        Object target)

      Get the field represented by the supplied `field object` on the specified `target object`. In accordance with `Field.get(Object)` semantics, the returned value is automatically wrapped if the underlying field has a primitive type.

      Thrown exceptions are handled via a call to `handleReflectionException(Exception)`.

      Parameters:
        `field` - the field to get
        `target` - the target object from which to get the field
      Returns:
        the field's current value

    - #### findMethod

          public static Method findMethod(Class<?> clazz,
                          String name)

      Attempt to find a `Method` on the supplied class with the supplied name and no parameters. Searches all superclasses up to `Object`.

      Returns `null` if no `Method` can be found.

      Parameters:
        `clazz` - the class to introspect
        `name` - the name of the method
      Returns:
        the Method object, or `null` if none found

    - #### findMethod

          public static Method findMethod(Class<?> clazz,
                          String name,
                          Class<?>... paramTypes)

      Attempt to find a `Method` on the supplied class with the supplied name and parameter types. Searches all superclasses up to `Object`.

      Returns `null` if no `Method` can be found.

      Parameters:
        `clazz` - the class to introspect
        `name` - the name of the method
        `paramTypes` - the parameter types of the method (may be `null` to indicate any signature)
      Returns:
        the Method object, or `null` if none found

    - #### invokeMethod

          public static Object invokeMethod(Method method,
                            Object target)

      Invoke the specified `Method` against the supplied target object with no arguments. The target object can be `null` when invoking a static `Method`.

      Thrown exceptions are handled via a call to `handleReflectionException(java.lang.Exception)`.

      Parameters:
        `method` - the method to invoke
        `target` - the target object to invoke the method on
      Returns:
        the invocation result, if any
      See Also:
        `invokeMethod(java.lang.reflect.Method, Object, Object[])`

    - #### invokeMethod

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

      Invoke the specified `Method` against the supplied target object with the supplied arguments. The target object can be `null` when invoking a static `Method`.

      Thrown exceptions are handled via a call to `handleReflectionException(java.lang.Exception)`.

      Parameters:
        `method` - the method to invoke
        `target` - the target object to invoke the method on
        `args` - the invocation arguments (may be `null`)
      Returns:
        the invocation result, if any

    - #### invokeJdbcMethod

          public static Object invokeJdbcMethod(Method method,
                                Object target)
                                         throws SQLException

      Invoke the specified JDBC API `Method` against the supplied target object with no arguments.
      Parameters:
        `method` - the method to invoke
        `target` - the target object to invoke the method on
      Returns:
        the invocation result, if any
      Throws:
        `SQLException` - the JDBC API SQLException to rethrow (if any)
      See Also:
        `invokeJdbcMethod(java.lang.reflect.Method, Object, Object[])`

    - #### invokeJdbcMethod

          public static Object invokeJdbcMethod(Method method,
                                Object target,
                                Object... args)
                                         throws SQLException

      Invoke the specified JDBC API `Method` against the supplied target object with the supplied arguments.
      Parameters:
        `method` - the method to invoke
        `target` - the target object to invoke the method on
        `args` - the invocation arguments (may be `null`)
      Returns:
        the invocation result, if any
      Throws:
        `SQLException` - the JDBC API SQLException to rethrow (if any)
      See Also:
        `invokeMethod(java.lang.reflect.Method, Object, Object[])`

    - #### handleReflectionException

          public static void handleReflectionException(Exception ex)

      Handle the given reflection exception. Should only be called if no checked exception is expected to be thrown by the target method.

      Throws the underlying RuntimeException or Error in case of an InvocationTargetException with such a root cause. Throws an IllegalStateException with an appropriate message else.

      Parameters:
        `ex` - the reflection exception to handle

    - #### handleInvocationTargetException

          public static void handleInvocationTargetException(InvocationTargetException ex)

      Handle the given invocation target exception. Should only be called if no checked exception is expected to be thrown by the target method.

      Throws the underlying RuntimeException or Error in case of such a root cause. Throws an IllegalStateException else.

      Parameters:
        `ex` - the invocation target exception to handle

    - #### rethrowRuntimeException

          public static void rethrowRuntimeException(Throwable ex)

      Rethrow the given `exception`, which is presumably the target exception of an `InvocationTargetException`. Should only be called if no checked exception is expected to be thrown by the target method.

      Rethrows the underlying exception cast to an `RuntimeException` or `Error` if appropriate; otherwise, throws an `IllegalStateException`.

      Parameters:
        `ex` - the exception to rethrow
      Throws:
        `RuntimeException` - the rethrown exception

    - #### rethrowException

          public static void rethrowException(Throwable ex)
                                       throws Exception

      Rethrow the given `exception`, which is presumably the target exception of an `InvocationTargetException`. Should only be called if no checked exception is expected to be thrown by the target method.

      Rethrows the underlying exception cast to an `Exception` or `Error` if appropriate; otherwise, throws an `IllegalStateException`.

      Parameters:
        `ex` - the exception to rethrow
      Throws:
        `Exception` - the rethrown exception (in case of a checked exception)

    - #### declaresException

          public static boolean declaresException(Method method,
                                  Class<?> exceptionType)

      Determine whether the given method explicitly declares the given exception or one of its superclasses, which means that an exception of that type can be propagated as-is within a reflective invocation.
      Parameters:
        `method` - the declaring method
        `exceptionType` - the exception to throw
      Returns:
        `true` if the exception can be thrown as-is; `false` if it needs to be wrapped

    - #### isPublicStaticFinal

          public static boolean isPublicStaticFinal(Field field)

      Determine whether the given field is a "public static final" constant.
      Parameters:
        `field` - the field to check

    - #### isEqualsMethod

          public static boolean isEqualsMethod(Method method)

      Determine whether the given method is an "equals" method.
      See Also:
        `Object.equals(Object)`

    - #### isHashCodeMethod

          public static boolean isHashCodeMethod(Method method)

      Determine whether the given method is a "hashCode" method.
      See Also:
        `Object.hashCode()`

    - #### isToStringMethod

          public static boolean isToStringMethod(Method method)

      Determine whether the given method is a "toString" method.
      See Also:
        `Object.toString()`

    - #### isObjectMethod

          public static boolean isObjectMethod(Method method)

      Determine whether the given method is originally declared by `Object`.

    - #### isCglibRenamedMethod

          public static boolean isCglibRenamedMethod(Method renamedMethod)

      Determine whether the given method is a CGLIB 'renamed' method, following the pattern "CGLIB$methodName$0".
      Parameters:
        `renamedMethod` - the method to check
      See Also:
        `Enhancer.rename(org.springframework.cglib.core.Signature, int)`

    - #### makeAccessible

          public static void makeAccessible(Field field)

      Make the given field accessible, explicitly setting it accessible if necessary. The `setAccessible(true)` method is only called when actually necessary, to avoid unnecessary conflicts with a JVM SecurityManager (if active).
      Parameters:
        `field` - the field to make accessible
      See Also:
        `AccessibleObject.setAccessible(java.lang.reflect.AccessibleObject[], boolean)`

    - #### makeAccessible

          public static void makeAccessible(Method method)

      Make the given method accessible, explicitly setting it accessible if necessary. The `setAccessible(true)` method is only called when actually necessary, to avoid unnecessary conflicts with a JVM SecurityManager (if active).
      Parameters:
        `method` - the method to make accessible
      See Also:
        `AccessibleObject.setAccessible(java.lang.reflect.AccessibleObject[], boolean)`

    - #### makeAccessible

          public static void makeAccessible(Constructor<?> ctor)

      Make the given constructor accessible, explicitly setting it accessible if necessary. The `setAccessible(true)` method is only called when actually necessary, to avoid unnecessary conflicts with a JVM SecurityManager (if active).
      Parameters:
        `ctor` - the constructor to make accessible
      See Also:
        `AccessibleObject.setAccessible(java.lang.reflect.AccessibleObject[], boolean)`

    - #### doWithMethods

          public static void doWithMethods(Class<?> clazz,
                           ReflectionUtils.MethodCallback mc)
                                    throws IllegalArgumentException

      Perform the given callback operation on all matching methods of the given class and superclasses.

      The same named method occurring on subclass and superclass will appear twice, unless excluded by a `ReflectionUtils.MethodFilter`.

      Parameters:
        `clazz` - class to start looking at
        `mc` - the callback to invoke for each method
      Throws:
        `IllegalArgumentException`
      See Also:
        `doWithMethods(Class, MethodCallback, MethodFilter)`

    - #### doWithMethods

          public static void doWithMethods(Class<?> clazz,
                           ReflectionUtils.MethodCallback mc,
                           ReflectionUtils.MethodFilter mf)
                                    throws IllegalArgumentException

      Perform the given callback operation on all matching methods of the given class and superclasses (or given interface and super-interfaces).

      The same named method occurring on subclass and superclass will appear twice, unless excluded by the specified `ReflectionUtils.MethodFilter`.

      Parameters:
        `clazz` - class to start looking at
        `mc` - the callback to invoke for each method
        `mf` - the filter that determines the methods to apply the callback to
      Throws:
        `IllegalArgumentException`

    - #### getAllDeclaredMethods

          public static Method[] getAllDeclaredMethods(Class<?> leafClass)
                                                throws IllegalArgumentException

      Get all declared methods on the leaf class and all superclasses. Leaf class methods are included first.
      Throws:
        `IllegalArgumentException`

    - #### getUniqueDeclaredMethods

          public static Method[] getUniqueDeclaredMethods(Class<?> leafClass)
                                                   throws IllegalArgumentException

      Get the unique set of declared methods on the leaf class and all superclasses. Leaf class methods are included first and while traversing the superclass hierarchy any methods found with signatures matching a method already included are filtered out.
      Throws:
        `IllegalArgumentException`

    - #### doWithFields

          public static void doWithFields(Class<?> clazz,
                          ReflectionUtils.FieldCallback fc)
                                   throws IllegalArgumentException

      Invoke the given callback on all fields in the target class, going up the class hierarchy to get all declared fields.
      Parameters:
        `clazz` - the target class to analyze
        `fc` - the callback to invoke for each field
      Throws:
        `IllegalArgumentException`

    - #### doWithFields

          public static void doWithFields(Class<?> clazz,
                          ReflectionUtils.FieldCallback fc,
                          ReflectionUtils.FieldFilter ff)
                                   throws IllegalArgumentException

      Invoke the given callback on all fields in the target class, going up the class hierarchy to get all declared fields.
      Parameters:
        `clazz` - the target class to analyze
        `fc` - the callback to invoke for each field
        `ff` - the filter that determines the fields to apply the callback to
      Throws:
        `IllegalArgumentException`

    - #### shallowCopyFieldState

          public static void shallowCopyFieldState(Object src,
                                   Object dest)
                                            throws IllegalArgumentException

      Given the source object and the destination, which must be the same class or a subclass, copy all fields, including inherited fields. Designed to work on objects with public no-arg constructors.
      Throws:
        `IllegalArgumentException` - if the arguments are incompatible