org.apache.commons.beanutils

Class PropertyUtilsBean


public class PropertyUtilsBean
extends java.lang.Object

Utility methods for using Java Reflection APIs to facilitate generic property getter and setter operations on Java objects. Much of this code was originally included in BeanUtils, but has been separated because of the volume of code involved.

In general, the objects that are examined and modified using these methods are expected to conform to the property getter and setter method naming conventions described in the JavaBeans Specification (Version 1.0.1). No data type conversions are performed, and there are no usage of any PropertyEditor classes that have been registered, although a convenient way to access the registered classes themselves is included.

For the purposes of this class, five formats for referencing a particular property value of a bean are defined, with the default layout of an identifying String in parentheses. However the notation for these formats and how they are resolved is now (since BeanUtils 1.8.0) controlled by the configured Resolver implementation:

Version:
$Revision: 557008 $ $Date: 2007-07-17 19:27:26 +0100 (Tue, 17 Jul 2007) $
Authors:
Craig R. McClanahan
Ralph Schaer
Chris Audley
Rey Francois
Gregor Rayman
Jan Sorensen
Scott Sanders
Erik Meade
Since:
1.7
See Also:
Resolver, PropertyUtils

Field Summary

private static Class[]
EMPTY_CLASS_PARAMETERS
private static Class[]
LIST_CLASS_PARAMETER
private FastHashMap
descriptorsCache
The cache of PropertyDescriptor arrays for beans we have already introspected, keyed by the java.lang.Class of this object.
private Log
log
Log instance
private FastHashMap
mappedDescriptorsCache
private Resolver
resolver

Constructor Summary

PropertyUtilsBean()
Base constructor

Method Summary

void
clearDescriptors()
Clear any cached property descriptors information for all classes loaded by any class loaders.
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 (even though the actual getter and setter methods might have been customized via BeanInfo classes).
Map
describe(Object bean)
Return the entire set of properties for which the specified bean provides a read method.
Object
getIndexedProperty(Object bean, String name)
Return the value of the specified indexed property of the specified bean, with no type conversions.
Object
getIndexedProperty(Object bean, String name, int index)
Return the value of the specified indexed property of the specified bean, with no type conversions.
protected static PropertyUtilsBean
getInstance()
Return the PropertyUtils bean instance.
Object
getMappedProperty(Object bean, String name)
Return the value of the specified mapped property of the specified bean, with no type conversions.
Object
getMappedProperty(Object bean, String name, String key)
Return the value of the specified mapped property of the specified bean, with no type conversions.
FastHashMap
getMappedPropertyDescriptors(Class beanClass)
Deprecated. This method should not be exposed
FastHashMap
getMappedPropertyDescriptors(Object bean)
Deprecated. This method should not be exposed
Object
getNestedProperty(Object bean, String name)
Return the value of the (possibly nested) property of the specified name, for the specified bean, with no type conversions.
Object
getProperty(Object bean, String name)
Return the value of the specified property of the specified bean, no matter which property reference format is used, with no type conversions.
PropertyDescriptor
getPropertyDescriptor(Object bean, String name)
Retrieve the property descriptor for the specified property of the specified bean, or return null if there is no such descriptor.
PropertyDescriptor[]
getPropertyDescriptors(Class beanClass)
Retrieve the property descriptors for the specified class, introspecting and caching them the first time a particular bean class is encountered.
PropertyDescriptor[]
getPropertyDescriptors(Object bean)
Retrieve the property descriptors for the specified bean, introspecting and caching them the first time a particular bean class is encountered.
Class
getPropertyEditorClass(Object bean, String name)
Return the Java Class repesenting the property editor class that has been registered for this property (if any).
protected Object
getPropertyOfMapBean(Map bean, String propertyName)
This method is called by getNestedProperty and setNestedProperty to define what it means to get a property from an object which implements Map.
Class
getPropertyType(Object bean, String name)
Return the Java Class representing the property type of the specified property, or null if there is no such property for the specified bean.
Method
getReadMethod(PropertyDescriptor descriptor)
Return an accessible property getter method for this property, if there is one; otherwise return null.
Resolver
getResolver()
Return the configured Resolver implementation used by BeanUtils.
Object
getSimpleProperty(Object bean, String name)
Return the value of the specified simple property of the specified bean, with no type conversions.
Method
getWriteMethod(PropertyDescriptor descriptor)
Return an accessible property setter method for this property, if there is one; otherwise return null.
private Object
invokeMethod(Method method, Object bean, Object[] values)
This just catches and wraps IllegalArgumentException.
boolean
isReadable(Object bean, String name)
Return true if the specified property name identifies a readable property on the specified bean; otherwise, return false.
boolean
isWriteable(Object bean, String name)
Return true if the specified property name identifies a writeable property on the specified bean; otherwise, return false.
void
setIndexedProperty(Object bean, String name, Object value)
Set the value of the specified indexed property of the specified bean, with no type conversions.
void
setIndexedProperty(Object bean, String name, int index, Object value)
Set the value of the specified indexed property of the specified bean, with no type conversions.
void
setMappedProperty(Object bean, String name, Object value)
Set the value of the specified mapped property of the specified bean, with no type conversions.
void
setMappedProperty(Object bean, String name, String key, Object value)
Set the value of the specified mapped property of the specified bean, with no type conversions.
void
setNestedProperty(Object bean, String name, Object value)
Set the value of the (possibly nested) property of the specified name, for the specified bean, with no type conversions.
void
setProperty(Object bean, String name, Object value)
Set the value of the specified property of the specified bean, no matter which property reference format is used, with no type conversions.
protected void
setPropertyOfMapBean(Map bean, String propertyName, Object value)
This method is called by method setNestedProperty when the current bean is found to be a Map object, and defines how to deal with setting a property on a Map.
void
setResolver(Resolver resolver)
Configure the Resolver implementation used by BeanUtils.
void
setSimpleProperty(Object bean, String name, Object value)
Set the value of the specified simple property of the specified bean, with no type conversions.

Field Details

EMPTY_CLASS_PARAMETERS

private static final Class[] EMPTY_CLASS_PARAMETERS

LIST_CLASS_PARAMETER

private static final Class[] LIST_CLASS_PARAMETER

descriptorsCache

private FastHashMap descriptorsCache
The cache of PropertyDescriptor arrays for beans we have already introspected, keyed by the java.lang.Class of this object.

log

private Log log
Log instance

mappedDescriptorsCache

private FastHashMap mappedDescriptorsCache

resolver

private Resolver resolver

Constructor Details

PropertyUtilsBean

public PropertyUtilsBean()
Base constructor

Method Details

clearDescriptors

public void clearDescriptors()
Clear any cached property descriptors information for all classes loaded by any class loaders. This is useful in cases where class loaders are thrown away to implement class reloading.

copyProperties

public void copyProperties(Object dest,
                           Object orig)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Copy property values from the "origin" bean to the "destination" bean for all cases where the property names are the same (even though the actual getter and setter methods might have been customized via BeanInfo classes). No conversions are performed on the actual property values -- it is assumed that the values retrieved from the origin bean are assignment-compatible with the types expected by the destination bean.

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

Note, that this method will not copy a List to a List, or an Object[] to an Object[]. It's specifically for copying JavaBean properties.

Parameters:
dest - Destination bean whose properties are modified
orig - Origin bean whose properties are retrieved

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 unconverted property values for all properties for which a read method is provided (i.e. where the getReadMethod() returns non-null).

FIXME - Does not account for mapped properties.

Parameters:
bean - Bean whose properties are to be extracted
Returns:
The set of properties for the bean

getIndexedProperty

public Object getIndexedProperty(Object bean,
                                 String name)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Return the value of the specified indexed property of the specified bean, with no type conversions. 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. In addition to supporting the JavaBeans specification, this method has been extended to support List objects as well.
Parameters:
bean - Bean whose property is to be extracted
name - propertyname[index] of the property value to be extracted
Returns:
the indexed property value

getIndexedProperty

public Object getIndexedProperty(Object bean,
                                 String name,
                                 int index)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Return the value of the specified indexed property of the specified bean, with no type conversions. In addition to supporting the JavaBeans specification, this method has been extended to support List objects as well.
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 value

getInstance

protected static PropertyUtilsBean getInstance()
Return the PropertyUtils bean instance.
Returns:
The PropertyUtils bean instance

getMappedProperty

public Object getMappedProperty(Object bean,
                                String name)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Return the value of the specified mapped property of the specified bean, with no type conversions. The key of the required value must be included (in brackets) as a suffix to the property name, or IllegalArgumentException will be thrown.
Parameters:
bean - Bean whose property is to be extracted
name - propertyname(key) of the property value to be extracted
Returns:
the mapped property value

getMappedProperty

public Object getMappedProperty(Object bean,
                                String name,
                                String key)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Return the value of the specified mapped property of the specified bean, with no type conversions.
Parameters:
bean - Bean whose property is to be extracted
name - Mapped property name of the property value to be extracted
key - Key of the property value to be extracted
Returns:
the mapped property value

getMappedPropertyDescriptors

public FastHashMap getMappedPropertyDescriptors(Class beanClass)

Deprecated. This method should not be exposed

Return the mapped property descriptors for this bean class.

FIXME - Does not work with DynaBeans.

Parameters:
beanClass - Bean class to be introspected
Returns:
the mapped property descriptors

getMappedPropertyDescriptors

public FastHashMap getMappedPropertyDescriptors(Object bean)

Deprecated. This method should not be exposed

Return the mapped property descriptors for this bean.

FIXME - Does not work with DynaBeans.

Parameters:
bean - Bean to be introspected
Returns:
the mapped property descriptors

getNestedProperty

public Object 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, with no type conversions.
Parameters:
bean - Bean whose property is to be extracted
name - Possibly nested name of the property to be extracted
Returns:
the nested property value

getProperty

public Object 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, with no type conversions.
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 value

getPropertyDescriptor

public PropertyDescriptor getPropertyDescriptor(Object bean,
                                                String name)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Retrieve the property descriptor for the specified property of the specified bean, or return null if there is no such descriptor. This method resolves indexed and nested property references in the same manner as other methods in this class, except that if the last (or only) name element is indexed, the descriptor for the last resolved property itself is returned.

FIXME - Does not work with DynaBeans.

Parameters:
bean - Bean for which a property descriptor is requested
name - Possibly indexed and/or nested name of the property for which a property descriptor is requested
Returns:
the property descriptor

getPropertyDescriptors

public PropertyDescriptor[] getPropertyDescriptors(Class beanClass)
Retrieve the property descriptors for the specified class, introspecting and caching them the first time a particular bean class is encountered.

FIXME - Does not work with DynaBeans.

Parameters:
beanClass - Bean class for which property descriptors are requested
Returns:
the property descriptors

getPropertyDescriptors

public PropertyDescriptor[] getPropertyDescriptors(Object bean)
Retrieve the property descriptors for the specified bean, introspecting and caching them the first time a particular bean class is encountered.

FIXME - Does not work with DynaBeans.

Parameters:
bean - Bean for which property descriptors are requested
Returns:
the property descriptors

getPropertyEditorClass

public Class getPropertyEditorClass(Object bean,
                                    String name)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Return the Java Class repesenting the property editor class that has been registered for this property (if any). This method follows the same name resolution rules used by getPropertyDescriptor(), so if the last element of a name reference is indexed, the property editor for the underlying property's class is returned.

Note that null will be returned if there is no property, or if there is no registered property editor class. Because this return value is ambiguous, you should determine the existence of the property itself by other means.

FIXME - Does not work with DynaBeans.

Parameters:
bean - Bean for which a property descriptor is requested
name - Possibly indexed and/or nested name of the property for which a property descriptor is requested
Returns:
the property editor class

getPropertyOfMapBean

protected Object getPropertyOfMapBean(Map bean,
                                      String propertyName)
            throws IllegalArgumentException,
                   IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
This method is called by getNestedProperty and setNestedProperty to define what it means to get a property from an object which implements Map. See setPropertyOfMapBean for more information.
Parameters:
bean - Map bean
propertyName - The property name
Returns:
the property value

getPropertyType

public Class getPropertyType(Object bean,
                             String name)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Return the Java Class representing the property type of the specified property, or null if there is no such property for the specified bean. This method follows the same name resolution rules used by getPropertyDescriptor(), so if the last element of a name reference is indexed, the type of the property itself will be returned. If the last (or only) element has no property with the specified name, null is returned.
Parameters:
bean - Bean for which a property descriptor is requested
name - Possibly indexed and/or nested name of the property for which a property descriptor is requested
Returns:
The property type

getReadMethod

public Method getReadMethod(PropertyDescriptor descriptor)
Return an accessible property getter method for this property, if there is one; otherwise return null.

FIXME - Does not work with DynaBeans.

Parameters:
descriptor - Property descriptor to return a getter for
Returns:
The read method

getResolver

public Resolver getResolver()
Return the configured Resolver implementation used by BeanUtils.

The Resolver handles the property name expressions and the implementation in use effectively controls the dialect of the expression language that BeanUtils recongnises.

DefaultResolver is the default implementation used.

Returns:
resolver The property expression resolver.

getSimpleProperty

public Object getSimpleProperty(Object bean,
                                String name)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Return the value of the specified simple property of the specified bean, with no type conversions.
Parameters:
bean - Bean whose property is to be extracted
name - Name of the property to be extracted
Returns:
The property value

getWriteMethod

public Method getWriteMethod(PropertyDescriptor descriptor)
Return an accessible property setter method for this property, if there is one; otherwise return null.

FIXME - Does not work with DynaBeans.

Parameters:
descriptor - Property descriptor to return a setter for
Returns:
The write method

invokeMethod

private Object invokeMethod(Method method,
                            Object bean,
                            Object[] values)
            throws IllegalAccessException,
                   InvocationTargetException
This just catches and wraps IllegalArgumentException.

isReadable

public boolean isReadable(Object bean,
                          String name)
Return true if the specified property name identifies a readable property on the specified bean; otherwise, return false.
Returns:
true if the property is readable, otherwise false
Since:
BeanUtils 1.6

isWriteable

public boolean isWriteable(Object bean,
                           String name)
Return true if the specified property name identifies a writeable property on the specified bean; otherwise, return false.
Returns:
true if the property is writeable, otherwise false
Since:
BeanUtils 1.6

setIndexedProperty

public void setIndexedProperty(Object bean,
                               String name,
                               Object value)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Set the value of the specified indexed property of the specified bean, with no type conversions. 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. In addition to supporting the JavaBeans specification, this method has been extended to support List objects as well.
Parameters:
bean - Bean whose property is to be modified
name - propertyname[index] of the property value to be modified
value - Value to which the specified property element should be set

setIndexedProperty

public void setIndexedProperty(Object bean,
                               String name,
                               int index,
                               Object value)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Set the value of the specified indexed property of the specified bean, with no type conversions. In addition to supporting the JavaBeans specification, this method has been extended to support List objects as well.
Parameters:
bean - Bean whose property is to be set
name - Simple property name of the property value to be set
index - Index of the property value to be set
value - Value to which the indexed property element is to be set

setMappedProperty

public void setMappedProperty(Object bean,
                              String name,
                              Object value)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Set the value of the specified mapped property of the specified bean, with no type conversions. The key of the value to set must be included (in brackets) as a suffix to the property name, or IllegalArgumentException will be thrown.
Parameters:
bean - Bean whose property is to be set
name - propertyname(key) of the property value to be set
value - The property value to be set

setMappedProperty

public void setMappedProperty(Object bean,
                              String name,
                              String key,
                              Object value)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Set the value of the specified mapped property of the specified bean, with no type conversions.
Parameters:
bean - Bean whose property is to be set
name - Mapped property name of the property value to be set
key - Key of the property value to be set
value - The property value to be set

setNestedProperty

public void setNestedProperty(Object bean,
                              String name,
                              Object value)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Set the value of the (possibly nested) property of the specified name, for the specified bean, with no type conversions.

Example values for parameter "name" are:

  • "a" -- sets the value of property a of the specified bean
  • "a.b" -- gets the value of property a of the specified bean, then on that object sets the value of property b.
  • "a(key)" -- sets a value of mapped-property a on the specified bean. This effectively means bean.setA("key").
  • "a[3]" -- sets a value of indexed-property a on the specified bean. This effectively means bean.setA(3).
Parameters:
bean - Bean whose property is to be modified
name - Possibly nested name of the property to be modified
value - Value to which the property is to be set

setProperty

public void setProperty(Object bean,
                        String name,
                        Object value)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Set the value of the specified property of the specified bean, no matter which property reference format is used, with no type conversions.
Parameters:
bean - Bean whose property is to be modified
name - Possibly indexed and/or nested name of the property to be modified
value - Value to which this property is to be set

setPropertyOfMapBean

protected void setPropertyOfMapBean(Map bean,
                                    String propertyName,
                                    Object value)
            throws IllegalArgumentException,
                   IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
This method is called by method setNestedProperty when the current bean is found to be a Map object, and defines how to deal with setting a property on a Map.

The standard implementation here is to:

  • call bean.set(propertyName) for all propertyName values.
  • throw an IllegalArgumentException if the property specifier contains MAPPED_DELIM or INDEXED_DELIM, as Map entries are essentially simple properties; mapping and indexing operations do not make sense when accessing a map (even thought the returned object may be a Map or an Array).

The default behaviour of beanutils 1.7.1 or later is for assigning to "a.b" to mean a.put(b, obj) always. However the behaviour of beanutils version 1.6.0, 1.6.1, 1.7.0 was for "a.b" to mean a.setB(obj) if such a method existed, and a.put(b, obj) otherwise. In version 1.5 it meant a.put(b, obj) always (ie the same as the behaviour in the current version). In versions prior to 1.5 it meant a.setB(obj) always. [yes, this is all very unfortunate]

Users who would like to customise the meaning of "a.b" in method setNestedProperty when a is a Map can create a custom subclass of this class and override this method to implement the behaviour of their choice, such as restoring the pre-1.4 behaviour of this class if they wish. When overriding this method, do not forget to deal with MAPPED_DELIM and INDEXED_DELIM characters in the propertyName.

Note, however, that the recommended solution for objects that implement Map but want their simple properties to come first is for those objects to override their get/put methods to implement that behaviour, and not to solve the problem by modifying the default behaviour of the PropertyUtilsBean class by overriding this method.

Parameters:
bean - Map bean
propertyName - The property name
value - the property value

setResolver

public void setResolver(Resolver resolver)
Configure the Resolver implementation used by BeanUtils.

The Resolver handles the property name expressions and the implementation in use effectively controls the dialect of the expression language that BeanUtils recongnises.

DefaultResolver is the default implementation used.

Parameters:
resolver - The property expression resolver.

setSimpleProperty

public void setSimpleProperty(Object bean,
                              String name,
                              Object value)
            throws IllegalAccessException,
                   InvocationTargetException,
                   NoSuchMethodException
Set the value of the specified simple property of the specified bean, with no type conversions.
Parameters:
bean - Bean whose property is to be modified
name - Name of the property to be modified
value - Value to which the property should be set

Copyright (c) 2001-2007 - Apache Software Foundation