| java.lang.Object
 org.apache.commons.beanutils.PropertyUtilsBean
All known Subclasses: org.apache.commons.beanutils.PropsFirstPropertyUtilsBean,
| PropertyUtilsBean | | public class PropertyUtilsBean (Code) | | 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:
- Simple (
name) - The specified
name identifies an individual property of a particular
JavaBean. The name of the actual getter or setter method to be used
is determined using standard JavaBeans instrospection, so that (unless
overridden by a BeanInfo class, a property named "xyz"
will have a getter method named getXyz() or (for boolean
properties only) isXyz(), and a setter method named
setXyz().
- Nested (
name1.name2.name3) The first
name element is used to select a property getter, as for simple
references above. The object returned for this property is then
consulted, using the same approach, for a property getter for a
property named name2, and so on. The property value that
is ultimately retrieved or modified is the one identified by the
last name element.
- Indexed (
name[index]) - The underlying
property value is assumed to be an array, or this JavaBean is assumed
to have indexed property getter and setter methods. The appropriate
(zero-relative) entry in the array is selected. List
objects are now also supported for read/write. You simply need to define
a getter that returns the List
- Mapped (
name(key)) - The JavaBean
is assumed to have an property getter and setter methods with an
additional attribute of type java.lang.String.
- Combined (
name1.name2[index].name3(key)) -
Combining mapped, nested, and indexed references is also
supported.
author:
Craig R. McClanahan
author:
Ralph Schaer
author:
Chris Audley
author:
Rey Francois
author:
Gregor Rayman
author:
Jan Sorensen
author:
Scott Sanders
author:
Erik Meade
version:
$Revision: 557008 $ $Date: 2007-07-17 19:27:26 +0100 (Tue, 17 Jul 2007) $
See Also: Resolver
See Also: PropertyUtils
since:
1.7 |
| Method Summary | |
| public void | clearDescriptors()
Clear any cached property descriptors information for all classes
loaded by any class loaders. | | 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). | | public Map | describe(Object bean)
Return the entire set of properties for which the specified bean
provides a read method. | | public Object | getIndexedProperty(Object bean, String name)
Return the value of the specified indexed property of the specified
bean, with no type conversions. | | 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. | | protected static PropertyUtilsBean | getInstance()
Return the PropertyUtils bean instance. | | public Object | getMappedProperty(Object bean, String name)
Return the value of the specified mapped property of the
specified bean, with no type conversions. | | 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. | | public FastHashMap | getMappedPropertyDescriptors(Class beanClass)
| | public FastHashMap | getMappedPropertyDescriptors(Object bean)
| | 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. | | 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. | | 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. | | public PropertyDescriptor[] | getPropertyDescriptors(Class beanClass)
| | public PropertyDescriptor[] | getPropertyDescriptors(Object bean)
| | 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). | | 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. | | 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. | | public Method | getReadMethod(PropertyDescriptor descriptor)
| | public Resolver | getResolver()
Return the configured
Resolver implementation used by BeanUtils. | | public Object | getSimpleProperty(Object bean, String name)
Return the value of the specified simple property of the specified
bean, with no type conversions. | | public Method | getWriteMethod(PropertyDescriptor descriptor)
| | 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. | | 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. | | 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. | | 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. | | 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. | | 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. | | 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.
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.
| | 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. | | 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.
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. | | public void | setResolver(Resolver resolver)
Configure the
Resolver implementation used by BeanUtils. | | 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. |
| PropertyUtilsBean | | public PropertyUtilsBean()(Code) | | Base constructor
|
| clearDescriptors | | public void clearDescriptors()(Code) | | 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(Code) | | 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
Parameters:
orig - Origin bean whose properties are retrieved
exception:
IllegalAccessException - if the caller does not haveaccess to the property accessor method
exception:
IllegalArgumentException - if the dest ororig argument is null
exception:
InvocationTargetException - if the property accessor methodthrows an exception
exception:
NoSuchMethodException - if an accessor method for thispropety cannot be found |
| getIndexedProperty | | public Object getIndexedProperty(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException(Code) | | 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
Parameters:
name - propertyname[index] of the property valueto be extracted the indexed property value
exception:
IndexOutOfBoundsException - if the specified indexis outside the valid range for the underlying array or List
exception:
IllegalAccessException - if the caller does not haveaccess to the property accessor method
exception:
IllegalArgumentException - if bean orname is null
exception:
InvocationTargetException - if the property accessor methodthrows an exception
exception:
NoSuchMethodException - if an accessor method for thispropety cannot be found |
| getIndexedProperty | | public Object getIndexedProperty(Object bean, String name, int index) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException(Code) | | 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
Parameters:
name - Simple property name of the property value to be extracted
Parameters:
index - Index of the property value to be extracted the indexed property value
exception:
IndexOutOfBoundsException - if the specified indexis outside the valid range for the underlying property
exception:
IllegalAccessException - if the caller does not haveaccess to the property accessor method
exception:
IllegalArgumentException - if bean orname is null
exception:
InvocationTargetException - if the property accessor methodthrows an exception
exception:
NoSuchMethodException - if an accessor method for thispropety cannot be found |
| getInstance | | protected static PropertyUtilsBean getInstance()(Code) | | Return the PropertyUtils bean instance.
The PropertyUtils bean instance |
| getMappedProperty | | public Object getMappedProperty(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException(Code) | | 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
Parameters:
name - propertyname(key) of the property valueto be extracted the mapped property value
exception:
IllegalAccessException - if the caller does not haveaccess to the property accessor method
exception:
InvocationTargetException - if the property accessor methodthrows an exception
exception:
NoSuchMethodException - if an accessor method for thispropety cannot be found |
| getMappedPropertyDescriptors | | public FastHashMap getMappedPropertyDescriptors(Class beanClass)(Code) | | Return the mapped property descriptors for this bean class.
FIXME - Does not work with DynaBeans.
Parameters:
beanClass - Bean class to be introspected the mapped property descriptors |
| getMappedPropertyDescriptors | | public FastHashMap getMappedPropertyDescriptors(Object bean)(Code) | | Return the mapped property descriptors for this bean.
FIXME - Does not work with DynaBeans.
Parameters:
bean - Bean to be introspected the mapped property descriptors |
| getPropertyDescriptor | | public PropertyDescriptor getPropertyDescriptor(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException(Code) | | 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
Parameters:
name - Possibly indexed and/or nested name of the property forwhich a property descriptor is requested the property descriptor
exception:
IllegalAccessException - if the caller does not haveaccess to the property accessor method
exception:
IllegalArgumentException - if bean orname is null
exception:
IllegalArgumentException - if a nested reference to aproperty returns null
exception:
InvocationTargetException - if the property accessor methodthrows an exception
exception:
NoSuchMethodException - if an accessor method for thispropety cannot be found |
| getPropertyDescriptors | | public PropertyDescriptor[] getPropertyDescriptors(Class beanClass)(Code) | | 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 the property descriptors
exception:
IllegalArgumentException - if beanClass is null |
| getPropertyDescriptors | | public PropertyDescriptor[] getPropertyDescriptors(Object bean)(Code) | | 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 the property descriptors
exception:
IllegalArgumentException - if bean is null |
| getPropertyEditorClass | | public Class getPropertyEditorClass(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException(Code) | | 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
Parameters:
name - Possibly indexed and/or nested name of the property forwhich a property descriptor is requested the property editor class
exception:
IllegalAccessException - if the caller does not haveaccess to the property accessor method
exception:
IllegalArgumentException - if bean orname is null
exception:
IllegalArgumentException - if a nested reference to aproperty returns null
exception:
InvocationTargetException - if the property accessor methodthrows an exception
exception:
NoSuchMethodException - if an accessor method for thispropety cannot be found |
| getPropertyOfMapBean | | protected Object getPropertyOfMapBean(Map bean, String propertyName) throws IllegalArgumentException, IllegalAccessException, InvocationTargetException, NoSuchMethodException(Code) | | 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
Parameters:
propertyName - The property name the property value
throws:
IllegalArgumentException - when the propertyName is regarded asbeing invalid.
throws:
IllegalAccessException - just in case subclasses override thismethod to try to access real getter methods and find permission is denied.
throws:
InvocationTargetException - just in case subclasses override thismethod to try to access real getter methods, and find it throws anexception when invoked.
throws:
NoSuchMethodException - just in case subclasses override thismethod to try to access real getter methods, and want to fail ifno simple method is available. |
| getPropertyType | | public Class getPropertyType(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException(Code) | | 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
Parameters:
name - Possibly indexed and/or nested name of the property forwhich a property descriptor is requested The property type
exception:
IllegalAccessException - if the caller does not haveaccess to the property accessor method
exception:
IllegalArgumentException - if bean orname is null
exception:
IllegalArgumentException - if a nested reference to aproperty returns null
exception:
InvocationTargetException - if the property accessor methodthrows an exception
exception:
NoSuchMethodException - if an accessor method for thispropety cannot be found |
| getReadMethod | | public Method getReadMethod(PropertyDescriptor descriptor)(Code) | | 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 The read method |
| getResolver | | public Resolver getResolver()(Code) | | 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.
resolver The property expression resolver. |
| getWriteMethod | | public Method getWriteMethod(PropertyDescriptor descriptor)(Code) | | 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 The write method |
| isReadable | | public boolean isReadable(Object bean, String name)(Code) | | 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 DynaBean
Parameters:
name - Property name to be evaluated true if the property is readable,otherwise false
exception:
IllegalArgumentException - if beanor name is null
since:
BeanUtils 1.6 |
| isWriteable | | public boolean isWriteable(Object bean, String name)(Code) | | 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 DynaBean
Parameters:
name - Property name to be evaluated true if the property is writeable,otherwise false
exception:
IllegalArgumentException - if beanor name is null
since:
BeanUtils 1.6 |
| setIndexedProperty | | public void setIndexedProperty(Object bean, String name, Object value) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException(Code) | | 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
Parameters:
name - propertyname[index] of the property valueto be modified
Parameters:
value - Value to which the specified property elementshould be set
exception:
IndexOutOfBoundsException - if the specified indexis outside the valid range for the underlying property
exception:
IllegalAccessException - if the caller does not haveaccess to the property accessor method
exception:
IllegalArgumentException - if bean orname is null
exception:
InvocationTargetException - if the property accessor methodthrows an exception
exception:
NoSuchMethodException - if an accessor method for thispropety cannot be found |
| setIndexedProperty | | public void setIndexedProperty(Object bean, String name, int index, Object value) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException(Code) | | 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
Parameters:
name - Simple property name of the property value to be set
Parameters:
index - Index of the property value to be set
Parameters:
value - Value to which the indexed property element is to be set
exception:
IndexOutOfBoundsException - if the specified indexis outside the valid range for the underlying property
exception:
IllegalAccessException - if the caller does not haveaccess to the property accessor method
exception:
IllegalArgumentException - if bean orname is null
exception:
InvocationTargetException - if the property accessor methodthrows an exception
exception:
NoSuchMethodException - if an accessor method for thispropety cannot be found |
| setMappedProperty | | public void setMappedProperty(Object bean, String name, Object value) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException(Code) | | 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
Parameters:
name - propertyname(key) of the property valueto be set
Parameters:
value - The property value to be set
exception:
IllegalAccessException - if the caller does not haveaccess to the property accessor method
exception:
InvocationTargetException - if the property accessor methodthrows an exception
exception:
NoSuchMethodException - if an accessor method for thispropety cannot be found |
| setNestedProperty | | public void setNestedProperty(Object bean, String name, Object value) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException(Code) | | 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
Parameters:
name - Possibly nested name of the property to be modified
Parameters:
value - Value to which the property is to be set
exception:
IllegalAccessException - if the caller does not haveaccess to the property accessor method
exception:
IllegalArgumentException - if bean orname is null
exception:
IllegalArgumentException - if a nested reference to aproperty returns null
exception:
InvocationTargetException - if the property accessor methodthrows an exception
exception:
NoSuchMethodException - if an accessor method for thispropety cannot be found |
| setPropertyOfMapBean | | protected void setPropertyOfMapBean(Map bean, String propertyName, Object value) throws IllegalArgumentException, IllegalAccessException, InvocationTargetException, NoSuchMethodException(Code) | | 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
Parameters:
propertyName - The property name
Parameters:
value - the property value
throws:
IllegalArgumentException - when the propertyName is regarded asbeing invalid.
throws:
IllegalAccessException - just in case subclasses override thismethod to try to access real setter methods and find permission is denied.
throws:
InvocationTargetException - just in case subclasses override thismethod to try to access real setter methods, and find it throws anexception when invoked.
throws:
NoSuchMethodException - just in case subclasses override thismethod to try to access real setter methods, and want to fail ifno simple method is available. |
| setResolver | | public void setResolver(Resolver resolver)(Code) | | 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. |
|
|