org.apache.commons.beanutils

Class PropertyUtilsBean

public class PropertyUtilsBean extends 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 layout of an identifying String in parentheses:

Since: 1.7

Version: $Revision: 1.14.2.1 $ $Date: 2004/07/27 21:31:00 $

Author: Craig R. McClanahan Ralph Schaer Chris Audley Rey François Gregor Raýman Jan Sorensen Scott Sanders

See Also: PropertyUtils

Field Summary
FastHashMapdescriptorsCache
The cache of PropertyDescriptor arrays for beans we have already introspected, keyed by the java.lang.Class of this object.
Loglog
Log instance
FastHashMapmappedDescriptorsCache
Constructor Summary
PropertyUtilsBean()
Base constructor
Method Summary
voidclearDescriptors()
Clear any cached property descriptors information for all classes loaded by any class loaders.
voidcopyProperties(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).

Mapdescribe(Object bean)

Return the entire set of properties for which the specified bean provides a read method.

intfindNextNestedIndex(String expression)
ObjectgetIndexedProperty(Object bean, String name)
Return the value of the specified indexed property of the specified bean, with no type conversions.
ObjectgetIndexedProperty(Object bean, String name, int index)
Return the value of the specified indexed property of the specified bean, with no type conversions.
protected static PropertyUtilsBeangetInstance()
ObjectgetMappedProperty(Object bean, String name)
Return the value of the specified mapped property of the specified bean, with no type conversions.
ObjectgetMappedProperty(Object bean, String name, String key)
Return the value of the specified mapped property of the specified bean, with no type conversions.
FastHashMapgetMappedPropertyDescriptors(Class beanClass)

Return the mapped property descriptors for this bean class.

FIXME - Does not work with DynaBeans.

FastHashMapgetMappedPropertyDescriptors(Object bean)

Return the mapped property descriptors for this bean.

FIXME - Does not work with DynaBeans.

ObjectgetNestedProperty(Object bean, String name)
Return the value of the (possibly nested) property of the specified name, for the specified bean, with no type conversions.
ObjectgetProperty(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.
PropertyDescriptorgetPropertyDescriptor(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.

FIXME - Does not work with DynaBeans.

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.

ClassgetPropertyEditorClass(Object bean, String name)

Return the Java Class repesenting the property editor class that has been registered for this property (if any).

ClassgetPropertyType(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.
MethodgetReadMethod(PropertyDescriptor descriptor)

Return an accessible property getter method for this property, if there is one; otherwise return null.

FIXME - Does not work with DynaBeans.

ObjectgetSimpleProperty(Object bean, String name)
Return the value of the specified simple property of the specified bean, with no type conversions.
MethodgetWriteMethod(PropertyDescriptor descriptor)

Return an accessible property setter method for this property, if there is one; otherwise return null.

FIXME - Does not work with DynaBeans.

ObjectinvokeMethod(Method method, Object bean, Object[] values)
This just catches and wraps IllegalArgumentException.
booleanisReadable(Object bean, String name)

Return true if the specified property name identifies a readable property on the specified bean; otherwise, return false.

booleanisWriteable(Object bean, String name)

Return true if the specified property name identifies a writeable property on the specified bean; otherwise, return false.

voidsetIndexedProperty(Object bean, String name, Object value)
Set the value of the specified indexed property of the specified bean, with no type conversions.
voidsetIndexedProperty(Object bean, String name, int index, Object value)
Set the value of the specified indexed property of the specified bean, with no type conversions.
voidsetMappedProperty(Object bean, String name, Object value)
Set the value of the specified mapped property of the specified bean, with no type conversions.
voidsetMappedProperty(Object bean, String name, String key, Object value)
Set the value of the specified mapped property of the specified bean, with no type conversions.
voidsetNestedProperty(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.
voidsetProperty(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.
voidsetSimpleProperty(Object bean, String name, Object value)
Set the value of the specified simple property of the specified bean, with no type conversions.

Field Detail

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

Constructor Detail

PropertyUtilsBean

public PropertyUtilsBean()
Base constructor

Method Detail

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)

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.

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 argument is null InvocationTargetException if the property accessor method throws an exception NoSuchMethodException if an accessor method for this propety cannot be found

describe

public Map describe(Object bean)

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

Throws: IllegalAccessException if the caller does not have access to the property accessor method IllegalArgumentException if bean is null InvocationTargetException if the property accessor method throws an exception NoSuchMethodException if an accessor method for this propety cannot be found

findNextNestedIndex

private int findNextNestedIndex(String expression)

getIndexedProperty

public Object getIndexedProperty(Object bean, String name)
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

Throws: ArrayIndexOutOfBoundsException if the specified index is outside the valid range for the underlying array IllegalAccessException if the caller does not have access to the property accessor method IllegalArgumentException if bean or name is null InvocationTargetException if the property accessor method throws an exception NoSuchMethodException if an accessor method for this propety cannot be found

getIndexedProperty

public Object getIndexedProperty(Object bean, String name, int index)
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

Throws: ArrayIndexOutOfBoundsException if the specified index is outside the valid range for the underlying array IllegalAccessException if the caller does not have access to the property accessor method IllegalArgumentException if bean or name is null InvocationTargetException if the property accessor method throws an exception NoSuchMethodException if an accessor method for this propety cannot be found

getInstance

protected static PropertyUtilsBean getInstance()

getMappedProperty

public Object getMappedProperty(Object bean, String name)
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

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 propety cannot be found

getMappedProperty

public Object getMappedProperty(Object bean, String name, String key)
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

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 propety cannot be found

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

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

getNestedProperty

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

Parameters: bean Bean whose property is to be extracted name Possibly nested name of the property to be extracted

Throws: IllegalAccessException if the caller does not have access to the property accessor method IllegalArgumentException if bean or name is null NestedNullException 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 propety cannot be found

getProperty

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

Parameters: bean Bean whose property is to be extracted name Possibly indexed and/or nested name of the property to be extracted

Throws: IllegalAccessException if the caller does not have access to the property accessor method IllegalArgumentException if bean or name is null InvocationTargetException if the property accessor method throws an exception NoSuchMethodException if an accessor method for this propety cannot be found

getPropertyDescriptor

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

Throws: IllegalAccessException if the caller does not have access to the property accessor method IllegalArgumentException if bean or name is null 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 propety cannot be found

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

Throws: IllegalArgumentException if beanClass is null

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

Throws: IllegalArgumentException if bean is null

getPropertyEditorClass

public Class getPropertyEditorClass(Object bean, String name)

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

Throws: IllegalAccessException if the caller does not have access to the property accessor method IllegalArgumentException if bean or name is null 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 propety cannot be found

getPropertyType

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

Throws: IllegalAccessException if the caller does not have access to the property accessor method IllegalArgumentException if bean or name is null 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 propety cannot be found

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

getSimpleProperty

public Object getSimpleProperty(Object bean, String name)
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

Throws: IllegalAccessException if the caller does not have access to the property accessor method IllegalArgumentException if bean or name is null IllegalArgumentException if the property name is nested or indexed InvocationTargetException if the property accessor method throws an exception NoSuchMethodException if an accessor method for this propety cannot be found

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

invokeMethod

private Object invokeMethod(Method method, Object bean, Object[] values)
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.

Parameters: bean Bean to be examined (may be a {@link DynaBean} name Property name to be evaluated

Throws: IllegalArgumentException if bean or name is null

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.

Parameters: bean Bean to be examined (may be a {@link DynaBean} name Property name to be evaluated

Throws: IllegalPointerException if bean or name is null

Since: BeanUtils 1.6

setIndexedProperty

public void setIndexedProperty(Object bean, String name, Object value)
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

Throws: ArrayIndexOutOfBoundsException if the specified index is outside the valid range for the underlying array IllegalAccessException if the caller does not have access to the property accessor method IllegalArgumentException if bean or name is null InvocationTargetException if the property accessor method throws an exception NoSuchMethodException if an accessor method for this propety cannot be found

setIndexedProperty

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

Throws: ArrayIndexOutOfBoundsException if the specified index is outside the valid range for the underlying array IllegalAccessException if the caller does not have access to the property accessor method IllegalArgumentException if bean or name is null InvocationTargetException if the property accessor method throws an exception NoSuchMethodException if an accessor method for this propety cannot be found

setMappedProperty

public void setMappedProperty(Object bean, String name, Object value)
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

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 propety cannot be found

setMappedProperty

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

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

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 propety cannot be found

setNestedProperty

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

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

Throws: IllegalAccessException if the caller does not have access to the property accessor method IllegalArgumentException if bean or name is null 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 propety cannot be found

setProperty

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

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

Throws: IllegalAccessException if the caller does not have access to the property accessor method IllegalArgumentException if bean or name is null InvocationTargetException if the property accessor method throws an exception NoSuchMethodException if an accessor method for this propety cannot be found

setSimpleProperty

public void setSimpleProperty(Object bean, String name, Object value)
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

Throws: IllegalAccessException if the caller does not have access to the property accessor method IllegalArgumentException if bean or name is null IllegalArgumentException if the property name is nested or indexed InvocationTargetException if the property accessor method throws an exception NoSuchMethodException if an accessor method for this propety cannot be found

Copyright (c) 2001-2004 - Apache Software Foundation