Package org.apache.commons.beanutils2

# Class BeanUtilsBean

java.lang.Object
org.apache.commons.beanutils2.BeanUtilsBean

Direct Known Subclasses:
  `LocaleBeanUtilsBean`

public class BeanUtilsBean extends Object
TODO docs

2.0

`BeanUtilsBean` implementation that creates a `ConvertUtilsBean` and delegates conversion to `ConvertUtilsBean.convert(Object, Class)`.

To configure this implementation for the current context ClassLoader invoke `BeanUtilsBean.setInstance(new BeanUtilsBean2());`

BeanUtils 1.7.0 delegated all conversion to String to the converter registered for the `String.class`. One of the improvements in BeanUtils 1.8.0 was to upgrade the `Converter` implementations so that they could handle conversion to String for their type (for example IntegerConverter now handles conversion from an Integer to a String as well as String to Integer).

In order to take advantage of these improvements BeanUtils needs to change how it gets the appropriate `Converter`. This functionality has been implemented in the new `ConvertUtilsBean.lookup(Class, Class)` and `ConvertUtilsBean.convert(Object, Class)` methods. However changing `BeanUtilsBean` to use these methods could create compatibility issues for existing users. In order to avoid that, this new `BeanUtilsBean` implementation has been created (and the associated `ConvertUtilsBean`).

Pre-2.0

JavaBean property population methods.

This class provides implementations for the utility methods in `BeanUtils`. Different instances can be used to isolate caches between class loaders and to vary the value converters registered.

Since:
  1.7
See Also:
  - `BeanUtils`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BeanUtilsBean()`
  Constructs an instance using new property and conversion instances.
  `BeanUtilsBean(ConvertUtilsBean todoRemove)`
  Constructs an instance using given conversion instances and new `PropertyUtilsBean` instance.
  `BeanUtilsBean(ConvertUtilsBean convertUtilsBean, PropertyUtilsBean propertyUtilsBean)`
  Constructs an instance using given property and conversion instances.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Object`
  `cloneBean(Object bean)`
  Clone a bean based on the available property getters and setters, even if the bean class itself does not implement Cloneable.
  `protected <R> Object`
  `convert(Object value, Class<R> type)`
  Converts the value to an object of the specified class (if possible).
  `void`
  `copyProperties(Object dest, Object orig)`
  Copy property values from the origin bean to the destination bean for all cases where the property names are the same.
  `void`
  `copyProperty(Object bean, String name, Object value)`
  Copy the specified property value to the specified destination bean, performing any type conversion that is required.
  `Map<String,String>`
  `describe(Object bean)`
  Return the entire set of properties for which the specified bean provides a read method.
  `String[]`
  `getArrayProperty(Object bean, String name)`
  Gets the value of the specified array property of the specified bean, as a String array.
  `ConvertUtilsBean`
  `getConvertUtils()`
  Gets the `ConvertUtilsBean` instance used to perform the conversions.
  `String`
  `getIndexedProperty(Object bean, String name)`
  Gets the value of the specified indexed property of the specified bean, as a String.
  `String`
  `getIndexedProperty(Object bean, String name, int index)`
  Gets the value of the specified indexed property of the specified bean, as a String.
  `static BeanUtilsBean`
  `getInstance()`
  Gets the instance which provides the functionality for `BeanUtils`.
  `String`
  `getMappedProperty(Object bean, String name)`
  Gets the value of the specified indexed property of the specified bean, as a String.
  `String`
  `getMappedProperty(Object bean, String name, String key)`
  Gets the value of the specified mapped property of the specified bean, as a String.
  `String`
  `getNestedProperty(Object bean, String name)`
  Gets the value of the (possibly nested) property of the specified name, for the specified bean, as a String.
  `String`
  `getProperty(Object bean, String name)`
  Gets the value of the specified property of the specified bean, no matter which property reference format is used, as a String.
  `PropertyUtilsBean`
  `getPropertyUtils()`
  Gets the `PropertyUtilsBean` instance used to access properties.
  `String`
  `getSimpleProperty(Object bean, String name)`
  Gets the value of the specified simple property of the specified bean, converted to a String.
  `void`
  `populate(Object bean, Map<String,? extends Object> properties)`
  Populate the JavaBeans properties of the specified bean, based on the specified name/value pairs.
  `static void`
  `setInstance(BeanUtilsBean newInstance)`
  Sets the instance which provides the functionality for `BeanUtils`.
  `void`
  `setProperty(Object bean, String name, Object value)`
  Set the specified property value, performing type conversions as required to conform to the type of the destination property.

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

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

- ## Constructor Details

  - ### BeanUtilsBean

    public BeanUtilsBean()

    Constructs an instance using new property and conversion instances.

  - ### BeanUtilsBean

    public BeanUtilsBean(ConvertUtilsBean todoRemove)

    Constructs an instance using given conversion instances and new `PropertyUtilsBean` instance.

    Parameters:
      `todoRemove` - use this `ConvertUtilsBean` to perform conversions from one object to another
    Since:
      1.8.0

  - ### BeanUtilsBean

    public BeanUtilsBean(ConvertUtilsBean convertUtilsBean, PropertyUtilsBean propertyUtilsBean)

    Constructs an instance using given property and conversion instances.

    Parameters:
      `convertUtilsBean` - use this `ConvertUtilsBean` to perform conversions from one object to another
      `propertyUtilsBean` - use this `PropertyUtilsBean` to access properties

- ## Method Details

  - ### getInstance

    public static BeanUtilsBean getInstance()
    Gets the instance which provides the functionality for `BeanUtils`. This is a pseudo-singleton - an single instance is provided per (thread) context classloader. This mechanism provides isolation for web apps deployed in the same container.
    Returns:
      The (pseudo-singleton) BeanUtils bean instance

  - ### setInstance

    public static void setInstance(BeanUtilsBean newInstance)
    Sets the instance which provides the functionality for `BeanUtils`. This is a pseudo-singleton - an single instance is provided per (thread) context classloader. This mechanism provides isolation for web apps deployed in the same container.
    Parameters:
      `newInstance` - The (pseudo-singleton) BeanUtils bean instance

  - ### cloneBean

    public Object cloneBean(Object bean) throws IllegalAccessException, InstantiationException, InvocationTargetException, NoSuchMethodException

    Clone a bean based on the available property getters and setters, even if the bean class itself does not implement Cloneable.

    Note: this method creates a shallow clone. In other words, any objects referred to by the bean are shared with the clone rather than being cloned in turn.

    Parameters:
      `bean` - Bean to be cloned
    Returns:
      the cloned bean
    Throws:
      `IllegalAccessException` - if the caller does not have access to the property accessor method
      `InstantiationException` - if a new instance of the bean's class cannot be instantiated
      `InvocationTargetException` - if the property accessor method throws an exception
      `NoSuchMethodException` - if an accessor method for this property cannot be found

  - ### convert

    protected <R> Object convert(Object value, Class<R> type)

    Converts the value to an object of the specified class (if possible).

    Type Parameters:
      `R` - the type of the class for the return value.
    Parameters:
      `value` - Value to be converted (may be null)
      `type` - Class of the value to be converted to
    Returns:
      The converted value

  - ### copyProperties

    public void copyProperties(Object dest, Object orig) throws IllegalAccessException, InvocationTargetException

    Copy property values from the origin bean to the destination bean for all cases where the property names are the same. For each property, a conversion is attempted as necessary. All combinations of standard JavaBeans and DynaBeans as origin and destination are supported. Properties that exist in the origin bean, but do not exist in the destination bean (or are read-only in the destination bean) are silently ignored.

    If the origin "bean" is actually a `Map`, it is assumed to contain String-valued simple property names as the keys, pointing at the corresponding property values that will be converted (if necessary) and set in the destination bean. Note that this method is intended to perform a "shallow copy" of the properties and so complex properties (for example, nested ones) will not be copied.

    This method differs from `populate()`, which was primarily designed for populating JavaBeans from the map of request parameters retrieved on an HTTP request, is that no scalar->indexed or indexed->scalar manipulations are performed. If the origin property is indexed, the destination property must be also.

    If you know that no type conversions are required, the `copyProperties()` method in `PropertyUtils` will execute faster than this method.

    FIXME - Indexed and mapped properties that do not have getter and setter methods for the underlying array or Map are not copied by this method.

    Parameters:
      `dest` - Destination bean whose properties are modified
      `orig` - Origin bean whose properties are retrieved
    Throws:
      `IllegalAccessException` - if the caller does not have access to the property accessor method
      `IllegalArgumentException` - if the `dest` or `orig</code> argument is null or if the <code>dest` property type is different from the source type and the relevant converter has not been registered.
      `InvocationTargetException` - if the property accessor method throws an exception

  - ### copyProperty

    public void copyProperty(Object bean, String name, Object value) throws IllegalAccessException, InvocationTargetException

    Copy the specified property value to the specified destination bean, performing any type conversion that is required. If the specified bean does not have a property of the specified name, or the property is read only on the destination bean, return without doing anything. If you have custom destination property types, register `Converter`s for them by calling the `register()` method of `ConvertUtils`.

    IMPLEMENTATION RESTRICTIONS:

    - Does not support destination properties that are indexed, but only an indexed setter (as opposed to an array setter) is available.
    - Does not support destination properties that are mapped, but only a keyed setter (as opposed to a Map setter) is available.
    - The desired property type of a mapped setter cannot be determined (since Maps support any data type), so no conversion will be performed.
    Parameters:
      `bean` - Bean on which setting is to be performed
      `name` - Property name (can be nested/indexed/mapped/combo)
      `value` - Value to be set
    Throws:
      `IllegalAccessException` - if the caller does not have access to the property accessor method
      `InvocationTargetException` - if the property accessor method throws an exception

  - ### describe

    public Map<String,String> describe(Object bean) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException

    Return the entire set of properties for which the specified bean provides a read method. This map contains the to `String` converted property values for all properties for which a read method is provided (i.e. where the getReadMethod() returns non-null).

    This map can be fed back to a call to `BeanUtils.populate()` to re-constitute the same set of properties, modulo differences for read-only and write-only properties, but only if there are no indexed properties.

    Warning: if any of the bean property implementations contain (directly or indirectly) a call to this method then a stack overflow may result. For example:

         class MyBean
         {
            public Map getParameterMap()
            {
                 BeanUtils.describe(this);
            }
         }

    will result in an infinite regression when `getParametersMap` is called. It is recommended that such methods are given alternative names (for example, `parametersMap`).

    Parameters:
      `bean` - Bean whose properties are to be extracted
    Returns:
      Map of property descriptors
    Throws:
      `IllegalAccessException` - if the caller does not have access to the property accessor method
      `InvocationTargetException` - if the property accessor method throws an exception
      `NoSuchMethodException` - if an accessor method for this property cannot be found

  - ### getArrayProperty

    public String[] getArrayProperty(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException
    Gets the value of the specified array property of the specified bean, as a String array.
    Parameters:
      `bean` - Bean whose property is to be extracted
      `name` - Name of the property to be extracted
    Returns:
      The array property value
    Throws:
      `IllegalAccessException` - if the caller does not have access to the property accessor method
      `InvocationTargetException` - if the property accessor method throws an exception
      `NoSuchMethodException` - if an accessor method for this property cannot be found

  - ### getConvertUtils

    public ConvertUtilsBean getConvertUtils()
    Gets the `ConvertUtilsBean` instance used to perform the conversions.
    Returns:
      The ConvertUtils bean instance

  - ### getIndexedProperty

    public String getIndexedProperty(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException
    Gets the value of the specified indexed property of the specified bean, as a String. The zero-relative index of the required value must be included (in square brackets) as a suffix to the property name, or `IllegalArgumentException` will be thrown.
    Parameters:
      `bean` - Bean whose property is to be extracted
      `name` - `propertyname[index]` of the property value to be extracted
    Returns:
      The indexed property's value, converted to a String
    Throws:
      `IllegalAccessException` - if the caller does not have access to the property accessor method
      `InvocationTargetException` - if the property accessor method throws an exception
      `NoSuchMethodException` - if an accessor method for this property cannot be found

  - ### getIndexedProperty

    public String getIndexedProperty(Object bean, String name, int index) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException
    Gets the value of the specified indexed property of the specified bean, as a String. The index is specified as a method parameter and must *not* be included in the property name expression
    Parameters:
      `bean` - Bean whose property is to be extracted
      `name` - Simple property name of the property value to be extracted
      `index` - Index of the property value to be extracted
    Returns:
      The indexed property's value, converted to a String
    Throws:
      `IllegalAccessException` - if the caller does not have access to the property accessor method
      `InvocationTargetException` - if the property accessor method throws an exception
      `NoSuchMethodException` - if an accessor method for this property cannot be found

  - ### getMappedProperty

    public String getMappedProperty(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException
    Gets the value of the specified indexed property of the specified bean, as a String. The String-valued key of the required value must be included (in parentheses) as a suffix to the property name, or `IllegalArgumentException` will be thrown.
    Parameters:
      `bean` - Bean whose property is to be extracted
      `name` - `propertyname(index)` of the property value to be extracted
    Returns:
      The mapped property's value, converted to a String
    Throws:
      `IllegalAccessException` - if the caller does not have access to the property accessor method
      `InvocationTargetException` - if the property accessor method throws an exception
      `NoSuchMethodException` - if an accessor method for this property cannot be found

  - ### getMappedProperty

    public String getMappedProperty(Object bean, String name, String key) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException
    Gets the value of the specified mapped property of the specified bean, as a String. The key is specified as a method parameter and must *not* be included in the property name expression
    Parameters:
      `bean` - Bean whose property is to be extracted
      `name` - Simple property name of the property value to be extracted
      `key` - Lookup key of the property value to be extracted
    Returns:
      The mapped property's value, converted to a String
    Throws:
      `IllegalAccessException` - if the caller does not have access to the property accessor method
      `InvocationTargetException` - if the property accessor method throws an exception
      `NoSuchMethodException` - if an accessor method for this property cannot be found

  - ### getNestedProperty

    public String getNestedProperty(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException
    Gets the value of the (possibly nested) property of the specified name, for the specified bean, as a String.
    Parameters:
      `bean` - Bean whose property is to be extracted
      `name` - Possibly nested name of the property to be extracted
    Returns:
      The nested property's value, converted to a String
    Throws:
      `IllegalAccessException` - if the caller does not have access to the property accessor method
      `IllegalArgumentException` - if a nested reference to a property returns null
      `InvocationTargetException` - if the property accessor method throws an exception
      `NoSuchMethodException` - if an accessor method for this property cannot be found

  - ### getProperty

    public String getProperty(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException
    Gets the value of the specified property of the specified bean, no matter which property reference format is used, as a String.
    Parameters:
      `bean` - Bean whose property is to be extracted
      `name` - Possibly indexed and/or nested name of the property to be extracted
    Returns:
      The property's value, converted to a String
    Throws:
      `IllegalAccessException` - if the caller does not have access to the property accessor method
      `InvocationTargetException` - if the property accessor method throws an exception
      `NoSuchMethodException` - if an accessor method for this property cannot be found

  - ### getPropertyUtils

    public PropertyUtilsBean getPropertyUtils()
    Gets the `PropertyUtilsBean` instance used to access properties.
    Returns:
      The ConvertUtils bean instance

  - ### getSimpleProperty

    public String getSimpleProperty(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException
    Gets the value of the specified simple property of the specified bean, converted to a String.
    Parameters:
      `bean` - Bean whose property is to be extracted
      `name` - Name of the property to be extracted
    Returns:
      The property's value, converted to a String
    Throws:
      `IllegalAccessException` - if the caller does not have access to the property accessor method
      `InvocationTargetException` - if the property accessor method throws an exception
      `NoSuchMethodException` - if an accessor method for this property cannot be found

  - ### populate

    public void populate(Object bean, Map<String,? extends Object> properties) throws IllegalAccessException, InvocationTargetException

    Populate the JavaBeans properties of the specified bean, based on the specified name/value pairs. This method uses Java reflection APIs to identify corresponding "property setter" method names, and deals with setter arguments of type `String</code>, <code>boolean`, `int`, `long`, `float`, and `double`. In addition, array setters for these types (or the corresponding primitive types) can also be identified.

    The particular setter method to be called for each property is determined using the usual JavaBeans introspection mechanisms. Thus, you may identify custom setter methods using a BeanInfo class that is associated with the class of the bean itself. If no such BeanInfo class is available, the standard method name conversion ("set" plus the capitalized name of the property in question) is used.

    NOTE: It is contrary to the JavaBeans Specification to have more than one setter method (with different argument signatures) for the same property.

    WARNING - The logic of this method is customized for extracting String-based request parameters from an HTTP request. It is probably not what you want for general property copying with type conversion. For that purpose, check out the `copyProperties()` method instead.

    Parameters:
      `bean` - JavaBean whose properties are being populated
      `properties` - Map keyed by property name, with the corresponding (String or String[]) value(s) to be set
    Throws:
      `IllegalAccessException` - if the caller does not have access to the property accessor method
      `InvocationTargetException` - if the property accessor method throws an exception

  - ### setProperty

    public void setProperty(Object bean, String name, Object value) throws IllegalAccessException, InvocationTargetException

    Set the specified property value, performing type conversions as required to conform to the type of the destination property.

    If the property is read only then the method returns without throwing an exception.

    If `null` is passed into a property expecting a primitive value, then this will be converted as if it were a `null` string.

    WARNING - The logic of this method is customized to meet the needs of `populate()`, and is probably not what you want for general property copying with type conversion. For that purpose, check out the `copyProperty()` method instead.

    WARNING - PLEASE do not modify the behavior of this method without consulting with the Struts developer community. There are some subtleties to its functionality that are not documented in the Javadoc description above, yet are vital to the way that Struts utilizes this method.

    Parameters:
      `bean` - Bean on which setting is to be performed
      `name` - Property name (can be nested/indexed/mapped/combo)
      `value` - Value to be set
    Throws:
      `IllegalAccessException` - if the caller does not have access to the property accessor method
      `InvocationTargetException` - if the property accessor method throws an exception