org.modeshape.common.util

## Class Reflection

- java.lang.Object
- - org.modeshape.common.util.Reflection

-     @Immutable
      public class Reflection
      extends Object

  Utility class for working reflectively with objects.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Reflection.Property` A representation of a property on a Java object.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static Inflector` | `INFLECTOR`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Reflection(Class<?> targetClass)` Construct a Reflection instance that cache's some information about the target class.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Class<?>[]` | `buildArgumentClasses(Object... arguments)` Build the list of classes that correspond to the list of argument objects.
    `static List<Class<?>>` | `buildArgumentClassList(Object... arguments)` Build the list of classes that correspond to the list of argument objects.
    `static List<Class<?>>` | `convertArgumentClassesToPrimitives(Class<?>... arguments)` Convert any argument classes to primitives.
    `Iterable<Method>` | `findAllMethods(Pattern methodNamePattern)` Finds the methods on the target class that match the supplied method name.
    `Iterable<Method>` | `findAllMethods(String methodName, boolean caseSensitive)` Finds the methods on the target class that match the supplied method name.
    `Method` | `findBestMethodOnTarget(String methodName, Object... arguments)` Find the best method on the target class that matches the signature specified with the specified name and the list of arguments.
    `Method` | `findBestMethodWithSignature(String methodName, boolean caseSensitive, Class<?>... argumentsClasses)` Find the best method on the target class that matches the signature specified with the specified name and the list of argument classes.
    `Method` | `findBestMethodWithSignature(String methodName, Class<?>... argumentsClasses)` Find the best method on the target class that matches the signature specified with the specified name and the list of argument classes.
    `Method` | `findFirstMethod(Pattern methodNamePattern)` Find the method on the target class that matches the supplied method name.
    `Method` | `findFirstMethod(String methodName, boolean caseSensitive)` Find the method on the target class that matches the supplied method name.
    `Method[]` | `findGetterMethods()` Find the getter methods on the target class that begin with "get" or "is", that have no parameters, and that return something other than void.
    `String[]` | `findGetterPropertyNames()` Find the property names with getter methods on the target class.
    `protected String[]` | `findMethodNames(String methodName)`
    `Method[]` | `findMethods(Pattern methodNamePattern)` Find the methods on the target class that matches the supplied method name.
    `Method[]` | `findMethods(String methodName, boolean caseSensitive)` Find the method on the target class that matches the supplied method name.
    `Map<String,Reflection.Property>` | `getAllPropertiesByNameOn(Object target)` Get representations for all of the Java properties on the supplied object.
    `List<Reflection.Property>` | `getAllPropertiesOn(Object target)` Get representations for all of the Java properties on the supplied object.
    `protected static <AnnotationType extends Annotation> AnnotationType` | `getAnnotation(Class<AnnotationType> annotationType, Field field, Method[] getters, Method[] setters)`
    `static String` | `getClassName(Class<?> clazz)` Returns the name of the class.
    `protected Field` | `getField(Class<?> targetClass, String propertyName)` Get a Field intance for a given class and property.
    `Object` | `getProperty(Object target, Reflection.Property property)` Get current value for the property on the supplied target object.
    `Reflection.Property` | `getProperty(Object target, String propertyName)` Get the representation of the named property on the target object.
    `Reflection.Property` | `getProperty(Object target, String propertyName, String description)` Get the representation of the named property (with the supplied description) on the target object.
    `Reflection.Property` | `getProperty(Object target, String propertyName, String label, String category, String description, Object... allowedValues)` Get the representation of the named property (with the supplied labe, category, description, and allowed values) on the target object.
    `String` | `getPropertyAsString(Object target, Reflection.Property property)` Get current value represented as a string for the property on the supplied target object.
    `Class<?>` | `getTargetClass()` Return the class that is the target for the reflection methods.
    `Object` | `invokeBestMethodOnTarget(String[] methodNames, Object target, Object... arguments)` Find and execute the best method on the target class that matches the signature specified with one of the specified names and the list of arguments.
    `Object` | `invokeGetterMethodOnTarget(String javaPropertyName, Object target)` Find and execute the getter method on the target class for the supplied property name.
    `Object` | `invokeSetterMethodOnTarget(String javaPropertyName, Object target, Object argument)` Find and execute the best setter method on the target class for the supplied property name and the supplied list of arguments.
    `protected static String` | `localizedString(Class<?> i18nClass, String id)`
    `void` | `setProperty(Object target, Reflection.Property property, Object value)` Set the property on the supplied target object to the specified value.
    `protected void` | `writeObjectAsString(Object obj, StringBuilder sb, boolean wrapWithBrackets)`

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

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

- - ### Field Detail

    - #### INFLECTOR

          protected static final Inflector INFLECTOR

  - ### Constructor Detail

    - #### Reflection

          public Reflection(Class<?> targetClass)

      Construct a Reflection instance that cache's some information about the target class. The target class is the Class object upon which the methods will be found.
      Parameters:
        `targetClass` - the target class
      Throws:
        `IllegalArgumentException` - if the target class is null

  - ### Method Detail

    - #### buildArgumentClasses

          public static Class<?>[] buildArgumentClasses(Object... arguments)

      Build the list of classes that correspond to the list of argument objects.
      Parameters:
        `arguments` - the list of argument objects.
      Returns:
        the list of Class instances that correspond to the list of argument objects; the resulting list will contain a null element for each null argument.

    - #### buildArgumentClassList

          public static List<Class<?>> buildArgumentClassList(Object... arguments)

      Build the list of classes that correspond to the list of argument objects.
      Parameters:
        `arguments` - the list of argument objects.
      Returns:
        the list of Class instances that correspond to the list of argument objects; the resulting list will contain a null element for each null argument.

    - #### convertArgumentClassesToPrimitives

          public static List<Class<?>> convertArgumentClassesToPrimitives(Class<?>... arguments)

      Convert any argument classes to primitives.
      Parameters:
        `arguments` - the list of argument classes.
      Returns:
        the list of Class instances in which any classes that could be represented by primitives (e.g., Boolean) were replaced with the primitive classes (e.g., Boolean.TYPE).

    - #### getClassName

          public static String getClassName(Class<?> clazz)

      Returns the name of the class. The result will be the fully-qualified class name, or the readable form for arrays and primitive types.
      Parameters:
        `clazz` - the class for which the class name is to be returned.
      Returns:
        the readable name of the class.

    - #### getTargetClass

          public Class<?> getTargetClass()

      Return the class that is the target for the reflection methods.
      Returns:
        the target class

    - #### findMethods

          public Method[] findMethods(String methodName,
                             boolean caseSensitive)

      Find the method on the target class that matches the supplied method name.
      Parameters:
        `methodName` - the name of the method that is to be found.
        `caseSensitive` - true if the method name supplied should match case-sensitively, or false if case does not matter
      Returns:
        the Method objects that have a matching name, or an empty array if there are no methods that have a matching name.

    - #### findMethods

          public Method[] findMethods(Pattern methodNamePattern)

      Find the methods on the target class that matches the supplied method name.
      Parameters:
        `methodNamePattern` - the regular expression pattern for the name of the method that is to be found.
      Returns:
        the Method objects that have a matching name, or an empty array if there are no methods that have a matching name.

    - #### findGetterMethods

          public Method[] findGetterMethods()

      Find the getter methods on the target class that begin with "get" or "is", that have no parameters, and that return something other than void. This method skips the `Object.getClass()` method.
      Returns:
        the Method objects for the getters; never null but possibly empty

    - #### findGetterPropertyNames

          public String[] findGetterPropertyNames()

      Find the property names with getter methods on the target class. This method returns the property names for the methods returned by `findGetterMethods()`.
      Returns:
        the Java Bean property names for the getters; never null but possibly empty

    - #### findFirstMethod

          public Method findFirstMethod(String methodName,
                               boolean caseSensitive)

      Find the method on the target class that matches the supplied method name.
      Parameters:
        `methodName` - the name of the method that is to be found.
        `caseSensitive` - true if the method name supplied should match case-sensitively, or false if case does not matter
      Returns:
        the first Method object found that has a matching name, or null if there are no methods that have a matching name.

    - #### findFirstMethod

          public Method findFirstMethod(Pattern methodNamePattern)

      Find the method on the target class that matches the supplied method name.
      Parameters:
        `methodNamePattern` - the regular expression pattern for the name of the method that is to be found.
      Returns:
        the first Method object found that has a matching name, or null if there are no methods that have a matching name.

    - #### findAllMethods

          public Iterable<Method> findAllMethods(String methodName,
                                        boolean caseSensitive)

      Finds the methods on the target class that match the supplied method name.
      Parameters:
        `methodName` - the name of the method that is to be found.
        `caseSensitive` - true if the method name supplied should match case-sensitively, or false if case does not matter
      Returns:
        the Method objects that have a matching name, or empty if there are no methods that have a matching name.

    - #### findAllMethods

          public Iterable<Method> findAllMethods(Pattern methodNamePattern)

      Finds the methods on the target class that match the supplied method name.
      Parameters:
        `methodNamePattern` - the regular expression pattern for the name of the method that is to be found.
      Returns:
        the Method objects that have a matching name, or empty if there are no methods that have a matching name.

    - #### invokeBestMethodOnTarget

          public Object invokeBestMethodOnTarget(String[] methodNames,
                                        Object target,
                                        Object... arguments)
                                          throws NoSuchMethodException,
                                                 SecurityException,
                                                 IllegalArgumentException,
                                                 IllegalAccessException,
                                                 InvocationTargetException

      Find and execute the best method on the target class that matches the signature specified with one of the specified names and the list of arguments. If no such method is found, a NoSuchMethodException is thrown.

      This method is unable to find methods with signatures that include both primitive arguments and arguments that are instances of `Number` or its subclasses.

      Parameters:
        `methodNames` - the names of the methods that are to be invoked, in the order they are to be tried
        `target` - the object on which the method is to be invoked
        `arguments` - the array of Object instances that correspond to the arguments passed to the method.
      Returns:
        the Method object that references the method that satisfies the requirements, or null if no satisfactory method could be found.
      Throws:
        `NoSuchMethodException` - if a matching method is not found.
        `SecurityException` - if access to the information is denied.
        `InvocationTargetException`
        `IllegalAccessException`
        `IllegalArgumentException`

    - #### invokeSetterMethodOnTarget

          public Object invokeSetterMethodOnTarget(String javaPropertyName,
                                          Object target,
                                          Object argument)
                                            throws NoSuchMethodException,
                                                   SecurityException,
                                                   IllegalArgumentException,
                                                   IllegalAccessException,
                                                   InvocationTargetException

      Find and execute the best setter method on the target class for the supplied property name and the supplied list of arguments. If no such method is found, a NoSuchMethodException is thrown.

      This method is unable to find methods with signatures that include both primitive arguments and arguments that are instances of `Number` or its subclasses.

      Parameters:
        `javaPropertyName` - the name of the property whose setter is to be invoked, in the order they are to be tried
        `target` - the object on which the method is to be invoked
        `argument` - the new value for the property
      Returns:
        the result of the setter method, which is typically null (void)
      Throws:
        `NoSuchMethodException` - if a matching method is not found.
        `SecurityException` - if access to the information is denied.
        `InvocationTargetException`
        `IllegalAccessException`
        `IllegalArgumentException`

    - #### invokeGetterMethodOnTarget

          public Object invokeGetterMethodOnTarget(String javaPropertyName,
                                          Object target)
                                            throws NoSuchMethodException,
                                                   SecurityException,
                                                   IllegalArgumentException,
                                                   IllegalAccessException,
                                                   InvocationTargetException

      Find and execute the getter method on the target class for the supplied property name. If no such method is found, a NoSuchMethodException is thrown.
      Parameters:
        `javaPropertyName` - the name of the property whose getter is to be invoked, in the order they are to be tried
        `target` - the object on which the method is to be invoked
      Returns:
        the property value (the result of the getter method call)
      Throws:
        `NoSuchMethodException` - if a matching method is not found.
        `SecurityException` - if access to the information is denied.
        `InvocationTargetException`
        `IllegalAccessException`
        `IllegalArgumentException`

    - #### findMethodNames

          protected String[] findMethodNames(String methodName)

    - #### findBestMethodOnTarget

          public Method findBestMethodOnTarget(String methodName,
                                      Object... arguments)
                                        throws NoSuchMethodException,
                                               SecurityException

      Find the best method on the target class that matches the signature specified with the specified name and the list of arguments. This method first attempts to find the method with the specified arguments; if no such method is found, a NoSuchMethodException is thrown.

      This method is unable to find methods with signatures that include both primitive arguments and arguments that are instances of `Number` or its subclasses.

      Parameters:
        `methodName` - the name of the method that is to be invoked.
        `arguments` - the array of Object instances that correspond to the arguments passed to the method.
      Returns:
        the Method object that references the method that satisfies the requirements, or null if no satisfactory method could be found.
      Throws:
        `NoSuchMethodException` - if a matching method is not found.
        `SecurityException` - if access to the information is denied.

    - #### findBestMethodWithSignature

          public Method findBestMethodWithSignature(String methodName,
                                           Class<?>... argumentsClasses)
                                             throws NoSuchMethodException,
                                                    SecurityException

      Find the best method on the target class that matches the signature specified with the specified name and the list of argument classes. This method first attempts to find the method with the specified argument classes; if no such method is found, a NoSuchMethodException is thrown.
      Parameters:
        `methodName` - the name of the method that is to be invoked.
        `argumentsClasses` - the list of Class instances that correspond to the classes for each argument passed to the method.
      Returns:
        the Method object that references the method that satisfies the requirements, or null if no satisfactory method could be found.
      Throws:
        `NoSuchMethodException` - if a matching method is not found.
        `SecurityException` - if access to the information is denied.

    - #### findBestMethodWithSignature

          public Method findBestMethodWithSignature(String methodName,
                                           boolean caseSensitive,
                                           Class<?>... argumentsClasses)
                                             throws NoSuchMethodException,
                                                    SecurityException

      Find the best method on the target class that matches the signature specified with the specified name and the list of argument classes. This method first attempts to find the method with the specified argument classes; if no such method is found, a NoSuchMethodException is thrown.
      Parameters:
        `methodName` - the name of the method that is to be invoked.
        `caseSensitive` - true if the method name supplied should match case-sensitively, or false if case does not matter
        `argumentsClasses` - the list of Class instances that correspond to the classes for each argument passed to the method.
      Returns:
        the Method object that references the method that satisfies the requirements, or null if no satisfactory method could be found.
      Throws:
        `NoSuchMethodException` - if a matching method is not found.
        `SecurityException` - if access to the information is denied.

    - #### getProperty

          public Reflection.Property getProperty(Object target,
                                        String propertyName,
                                        String label,
                                        String category,
                                        String description,
                                        Object... allowedValues)
                                          throws SecurityException,
                                                 IllegalArgumentException,
                                                 NoSuchMethodException,
                                                 IllegalAccessException,
                                                 InvocationTargetException

      Get the representation of the named property (with the supplied labe, category, description, and allowed values) on the target object.

      If the label is not provided, this method looks for the `Label` annotation on the property's field and sets the label to the annotation's literal value, or if the `Label.i18n()` class is referenced, the localized value of the referenced `I18n`.

      If the description is not provided, this method looks for the `Description` annotation on the property's field and sets the label to the annotation's literal value, or if the `Description.i18n()` class is referenced, the localized value of the referenced `I18n`.

      And if the category is not provided, this method looks for the `Category` annotation on the property's field and sets the label to the annotation's literal value, or if the `Category.i18n()` class is referenced, the localized value of the referenced `I18n`.

      Parameters:
        `target` - the target on which the setter is to be called; may not be null
        `propertyName` - the name of the Java object property; may not be null
        `label` - the new label for the property; may be null
        `category` - the category for this property; may be null
        `description` - the description for the property; may be null if this is not known
        `allowedValues` - the of allowed values, or null or empty if the values are not constrained
      Returns:
        the representation of the Java property; never null
      Throws:
        `NoSuchMethodException` - if a matching method is not found.
        `SecurityException` - if access to the information is denied.
        `IllegalAccessException` - if the setter method could not be accessed
        `InvocationTargetException` - if there was an error invoking the setter method on the target
        `IllegalArgumentException` - if 'target' is null, or if 'propertyName' is null or empty

    - #### getField

          protected Field getField(Class<?> targetClass,
                       String propertyName)
                            throws NoSuchFieldException

      Get a Field intance for a given class and property. Iterate over super classes of a class when a <@link NoSuchFieldException> occurs until no more super classes are found then re-throw the <@link NoSuchFieldException>.
      Parameters:
        `targetClass` -
        `propertyName` -
      Returns:
        Field
      Throws:
        `NoSuchFieldException`

    - #### getAnnotation

          protected static <AnnotationType extends Annotation> AnnotationType getAnnotation(Class<AnnotationType> annotationType,
                                                                         Field field,
                                                                         Method[] getters,
                                                                         Method[] setters)

    - #### localizedString

          protected static String localizedString(Class<?> i18nClass,
                               String id)

    - #### getProperty

          public Reflection.Property getProperty(Object target,
                                        String propertyName,
                                        String description)
                                          throws SecurityException,
                                                 IllegalArgumentException,
                                                 NoSuchMethodException,
                                                 IllegalAccessException,
                                                 InvocationTargetException

      Get the representation of the named property (with the supplied description) on the target object.
      Parameters:
        `target` - the target on which the setter is to be called; may not be null
        `propertyName` - the name of the Java object property; may not be null
        `description` - the description for the property; may be null if this is not known
      Returns:
        the representation of the Java property; never null
      Throws:
        `NoSuchMethodException` - if a matching method is not found.
        `SecurityException` - if access to the information is denied.
        `IllegalAccessException` - if the setter method could not be accessed
        `InvocationTargetException` - if there was an error invoking the setter method on the target
        `IllegalArgumentException` - if 'target' is null, or if 'propertyName' is null or empty

    - #### getProperty

          public Reflection.Property getProperty(Object target,
                                        String propertyName)
                                          throws SecurityException,
                                                 IllegalArgumentException,
                                                 NoSuchMethodException,
                                                 IllegalAccessException,
                                                 InvocationTargetException

      Get the representation of the named property on the target object.
      Parameters:
        `target` - the target on which the setter is to be called; may not be null
        `propertyName` - the name of the Java object property; may not be null
      Returns:
        the representation of the Java property; never null
      Throws:
        `NoSuchMethodException` - if a matching method is not found.
        `SecurityException` - if access to the information is denied.
        `IllegalAccessException` - if the setter method could not be accessed
        `InvocationTargetException` - if there was an error invoking the setter method on the target
        `IllegalArgumentException` - if 'target' is null, or if 'propertyName' is null or empty

    - #### getAllPropertiesOn

          public List<Reflection.Property> getAllPropertiesOn(Object target)
                                                       throws SecurityException,
                                                              IllegalArgumentException,
                                                              NoSuchMethodException,
                                                              IllegalAccessException,
                                                              InvocationTargetException

      Get representations for all of the Java properties on the supplied object.
      Parameters:
        `target` - the target on which the setter is to be called; may not be null
      Returns:
        the list of all properties; never null
      Throws:
        `NoSuchMethodException` - if a matching method is not found.
        `SecurityException` - if access to the information is denied.
        `IllegalAccessException` - if the setter method could not be accessed
        `InvocationTargetException` - if there was an error invoking the setter method on the target
        `IllegalArgumentException` - if 'target' is null, or if 'propertyName' is null or empty

    - #### getAllPropertiesByNameOn

          public Map<String,Reflection.Property> getAllPropertiesByNameOn(Object target)
                                                                   throws SecurityException,
                                                                          IllegalArgumentException,
                                                                          NoSuchMethodException,
                                                                          IllegalAccessException,
                                                                          InvocationTargetException

      Get representations for all of the Java properties on the supplied object.
      Parameters:
        `target` - the target on which the setter is to be called; may not be null
      Returns:
        the map of all properties keyed by their name; never null
      Throws:
        `NoSuchMethodException` - if a matching method is not found.
        `SecurityException` - if access to the information is denied.
        `IllegalAccessException` - if the setter method could not be accessed
        `InvocationTargetException` - if there was an error invoking the setter method on the target
        `IllegalArgumentException` - if 'target' is null, or if 'propertyName' is null or empty

    - #### setProperty

          public void setProperty(Object target,
                         Reflection.Property property,
                         Object value)
                           throws SecurityException,
                                  IllegalArgumentException,
                                  NoSuchMethodException,
                                  IllegalAccessException,
                                  InvocationTargetException

      Set the property on the supplied target object to the specified value.
      Parameters:
        `target` - the target on which the setter is to be called; may not be null
        `property` - the property that is to be set on the target
        `value` - the new value for the property
      Throws:
        `NoSuchMethodException` - if a matching method is not found.
        `SecurityException` - if access to the information is denied.
        `IllegalAccessException` - if the setter method could not be accessed
        `InvocationTargetException` - if there was an error invoking the setter method on the target
        `IllegalArgumentException` - if 'target' is null, 'property' is null, or 'property.getName()' is null

    - #### getProperty

          public Object getProperty(Object target,
                           Reflection.Property property)
                             throws SecurityException,
                                    IllegalArgumentException,
                                    NoSuchMethodException,
                                    IllegalAccessException,
                                    InvocationTargetException

      Get current value for the property on the supplied target object.
      Parameters:
        `target` - the target on which the setter is to be called; may not be null
        `property` - the property that is to be set on the target
      Returns:
        the current value for the property; may be null
      Throws:
        `NoSuchMethodException` - if a matching method is not found.
        `SecurityException` - if access to the information is denied.
        `IllegalAccessException` - if the setter method could not be accessed
        `InvocationTargetException` - if there was an error invoking the setter method on the target
        `IllegalArgumentException` - if 'target' is null, 'property' is null, or 'property.getName()' is null

    - #### getPropertyAsString

          public String getPropertyAsString(Object target,
                                   Reflection.Property property)
                                     throws SecurityException,
                                            IllegalArgumentException,
                                            NoSuchMethodException,
                                            IllegalAccessException,
                                            InvocationTargetException

      Get current value represented as a string for the property on the supplied target object.
      Parameters:
        `target` - the target on which the setter is to be called; may not be null
        `property` - the property that is to be set on the target
      Returns:
        the current value for the property; may be null
      Throws:
        `NoSuchMethodException` - if a matching method is not found.
        `SecurityException` - if access to the information is denied.
        `IllegalAccessException` - if the setter method could not be accessed
        `InvocationTargetException` - if there was an error invoking the setter method on the target
        `IllegalArgumentException` - if 'target' is null, 'property' is null, or 'property.getName()' is null

    - #### writeObjectAsString

          protected void writeObjectAsString(Object obj,
                                 StringBuilder sb,
                                 boolean wrapWithBrackets)

Copyright © 2008-2014 JBoss, a division of Red Hat. All Rights Reserved.