org.apache.commons.beanutils

Class BeanUtilsBean

Known Direct Subclasses:
LocaleBeanUtilsBean

public class BeanUtilsBean
extends java.lang.Object

JavaBean property population methods.

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

Version:
$Revision: 1.16 $ $Date: 2004/02/28 13:18:33 $
Authors:
Craig R. McClanahan
Ralph Schaer
Chris Audley
Rey Fran?ois
Gregor Ra?man
Since:
1.7
See Also:
BeanUtils

Field Summary

private static ContextClassLoaderLocal
beansByClassLoader
Contains BeanUtilsBean instances indexed by context classloader.
private ConvertUtilsBean
convertUtilsBean
Used to perform conversions between object types when setting properties
private Log
log
Logging for this instance
private PropertyUtilsBean
propertyUtilsBean
Used to access properties

Constructor Summary

BeanUtilsBean()
Constructs an instance using new property and conversion instances.
BeanUtilsBean(ConvertUtilsBean convertUtilsBean, PropertyUtilsBean propertyUtilsBean)
Constructs an instance using given property and conversion instances.

Method Summary

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.
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
describe(Object bean)
Return the entire set of properties for which the specified bean provides a read method.
private int
findLastNestedIndex(String expression)
String[]
getArrayProperty(Object bean, String name)
Return 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)
Return the value of the specified indexed property of the specified bean, as a String.
String
getIndexedProperty(Object bean, String name, int index)
Return 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)
Return the value of the specified indexed property of the specified bean, as a String.
String
getMappedProperty(Object bean, String name, String key)
Return the value of the specified mapped property of the specified bean, as a String.
String
getNestedProperty(Object bean, String name)
Return the value of the (possibly nested) property of the specified name, for the specified bean, as a String.
String
getProperty(Object bean, String name)
Return 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)
Return the value of the specified simple property of the specified bean, converted to a String.
void
populate(Object bean, Map 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.

Field Details

beansByClassLoader

private static final ContextClassLoaderLocal beansByClassLoader
Contains BeanUtilsBean instances indexed by context classloader.

convertUtilsBean

private ConvertUtilsBean convertUtilsBean
Used to perform conversions between object types when setting properties

log

private Log log
Logging for this instance

propertyUtilsBean

private PropertyUtilsBean propertyUtilsBean
Used to access properties

Constructor Details

BeanUtilsBean

public BeanUtilsBean()
Constructs an instance using new property and conversion instances.

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

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

copyProperties

public void copyProperties(Object dest,
                           Object orig)
            throws IllegalAccessException,
                   InvocationTargetException
Parameters:
dest - Destination bean whose properties are modified
orig - Origin bean whose properties are retrieved

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 Converters 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

describe

public Map 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 reconsitute the same set of properties, modulo differences for read-only and write-only properties, but only if there are no indexed properties.

Parameters:
bean - Bean whose properties are to be extracted

findLastNestedIndex

private int findLastNestedIndex(String expression)

getArrayProperty

public String[] getArrayProperty(Object bean,
                                 String name)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Return 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

getConvertUtils

public ConvertUtilsBean getConvertUtils()
Gets the ConvertUtilsBean instance used to perform the conversions.

getIndexedProperty

public String getIndexedProperty(Object bean,
                                 String name)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Return 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

getIndexedProperty

public String getIndexedProperty(Object bean,
                                 String name,
                                 int index)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Return 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

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.

getMappedProperty

public String getMappedProperty(Object bean,
                                String name)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Return 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

getMappedProperty

public String getMappedProperty(Object bean,
                                String name,
                                String key)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Return 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

getNestedProperty

public String getNestedProperty(Object bean,
                                String name)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Return 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

getProperty

public String getProperty(Object bean,
                          String name)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Return 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

getPropertyUtils

public PropertyUtilsBean getPropertyUtils()
Gets the PropertyUtilsBean instance used to access properties.

getSimpleProperty

public String getSimpleProperty(Object bean,
                                String name)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Return 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

populate

public void populate(Object bean,
                     Map 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, 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

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.

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

Copyright (c) 2001-2004 - Apache Software Foundation