org.springframework.beans
Interface BeanWrapper

All Known Implementing Classes:

BeanWrapperImpl

public interface BeanWrapper

The central interface of Spring's low-level JavaBeans infrastructure. Typically not directly used by application code but rather implicitly via a BeanFactory or a DataBinder.

To be implemented by classes that can manipulate Java beans. Implementing classes have the ability to get and set property values (individually or in bulk), get property descriptors and query the readability and writability of properties.

This interface supports nested properties enabling the setting of properties on subproperties to an unlimited depth.

If a property update causes an exception, a PropertyVetoException will be thrown. Bulk updates continue after exceptions are encountered, throwing an exception wrapping all exceptions encountered during the update.

BeanWrapper implementations can be used repeatedly, with their "target" or wrapped object changed.

Since:

13 April 2001

Version:

$Id: BeanWrapper.java,v 1.12 2004/03/19 07:40:12 jhoeller Exp $

Author:

Rod Johnson

See Also:

BeanFactory, DataBinder

Field Summary

static java.lang.String

NESTED_PROPERTY_SEPARATOR Path separator for nested properties.

Method Summary

java.beans.PropertyEditor	findCustomEditor(java.lang.Class requiredType, java.lang.String propertyPath) Find a custom property editor for the given type and property.
java.beans.PropertyDescriptor	getPropertyDescriptor(java.lang.String propertyName) Get the property descriptor for a particular property.
java.beans.PropertyDescriptor[]	getPropertyDescriptors() Get the PropertyDescriptors identified on this object (standard JavaBeans introspection).
java.lang.Object	getPropertyValue(java.lang.String propertyName) Get the value of a property.
java.lang.Class	getWrappedClass() Convenience method to return the class of the wrapped object.
java.lang.Object	getWrappedInstance() Return the bean wrapped by this object (cannot be null).
boolean	isReadableProperty(java.lang.String propertyName) Return whether this property is readable.
boolean	isWritableProperty(java.lang.String propertyName) Return whether this property is writable.
void	registerCustomEditor(java.lang.Class requiredType, java.beans.PropertyEditor propertyEditor) Register the given custom property editor for all properties of the given type.
void	registerCustomEditor(java.lang.Class requiredType, java.lang.String propertyPath, java.beans.PropertyEditor propertyEditor) Register the given custom property editor for the given type and property, or for all properties of the given type.
void	setPropertyValue(PropertyValue pv) Update a property value.
void	setPropertyValue(java.lang.String propertyName, java.lang.Object value) Set a property value.
void	setPropertyValues(java.util.Map map) Perform a bulk update from a Map.
void	setPropertyValues(PropertyValues pvs) The preferred way to perform a bulk update.
void	setPropertyValues(PropertyValues pvs, boolean ignoreUnknown) Perform a bulk update with full control over behavior.
void	setWrappedInstance(java.lang.Object obj) Change the wrapped object.

Field Detail

NESTED_PROPERTY_SEPARATOR

public static final java.lang.String NESTED_PROPERTY_SEPARATOR

Path separator for nested properties. Follows normal Java conventions: getFoo().getBar() would be "foo.bar".

See Also:

Constant Field Values

Method Detail

setWrappedInstance

public void setWrappedInstance(java.lang.Object obj)
                        throws BeansException

Change the wrapped object. Implementations are required to allow the type of the wrapped object to change.

Parameters:

obj - wrapped object that we are manipulating

Throws:

BeansException

getWrappedInstance

public java.lang.Object getWrappedInstance()

Return the bean wrapped by this object (cannot be null).

Returns:

the bean wrapped by this object

getWrappedClass

public java.lang.Class getWrappedClass()

Convenience method to return the class of the wrapped object.

Returns:

the class of the wrapped object

registerCustomEditor

public void registerCustomEditor(java.lang.Class requiredType,
                                 java.beans.PropertyEditor propertyEditor)

Register the given custom property editor for all properties of the given type.

Parameters:

requiredType - type of the property

propertyEditor - editor to register

registerCustomEditor

public void registerCustomEditor(java.lang.Class requiredType,
                                 java.lang.String propertyPath,
                                 java.beans.PropertyEditor propertyEditor)

Register the given custom property editor for the given type and property, or for all properties of the given type.

Parameters:

requiredType - type of the property, can be null if a property is given but should be specified in any case for consistency checking

propertyPath - path of the property (name or nested path), or null if registering an editor for all properties of the given type

propertyEditor - editor to register

findCustomEditor

public java.beans.PropertyEditor findCustomEditor(java.lang.Class requiredType,
                                                  java.lang.String propertyPath)

Find a custom property editor for the given type and property.

Parameters:

requiredType - type of the property, can be null if a property is given but should be specified in any case for consistency checking

propertyPath - path of the property (name or nested path), or null if looking for an editor for all properties of the given type

Returns:

the registered editor, or null if none

getPropertyValue

public java.lang.Object getPropertyValue(java.lang.String propertyName)
                                  throws BeansException

Get the value of a property.

Parameters:

propertyName - name of the property to get the value of

Returns:

the value of the property.

Throws:

FatalBeanException - if there is no such property, if the property isn't readable, or if the property getter throws an exception.

BeansException

setPropertyValue

public void setPropertyValue(java.lang.String propertyName,
                             java.lang.Object value)
                      throws BeansException

Set a property value. This method is provided for convenience only. The setPropertyValue(PropertyValue) method is more powerful.

Parameters:

propertyName - name of the property to set value of

value - the new value

Throws:

BeansException

setPropertyValue

public void setPropertyValue(PropertyValue pv)
                      throws BeansException

Update a property value. This is the preferred way to update an individual property.

Parameters:

pv - object containing new property value

Throws:

BeansException

setPropertyValues

public void setPropertyValues(java.util.Map map)
                       throws BeansException

Perform a bulk update from a Map.

Bulk updates from PropertyValues are more powerful: This method is provided for convenience. Behaviour will be identical to that of the setPropertyValues(PropertyValues) method.

Parameters:

map - Map to take properties from. Contains property value objects, keyed by property name

Throws:

BeansException

setPropertyValues

public void setPropertyValues(PropertyValues pvs)
                       throws BeansException

The preferred way to perform a bulk update.

Note that performing a bulk update differs from performing a single update, in that an implementation of this class will continue to update properties if a recoverable error (such as a vetoed property change or a type mismatch, but not an invalid fieldname or the like) is encountered, throwing a PropertyAccessExceptionsException containing all the individual errors. This exception can be examined later to see all binding errors. Properties that were successfully updated stay changed.

Does not allow unknown fields. Equivalent to setPropertyValues(pvs, false, null).

Parameters:

pvs - PropertyValues to set on the target object

Throws:

BeansException

setPropertyValues

public void setPropertyValues(PropertyValues pvs,
                              boolean ignoreUnknown)
                       throws BeansException

Perform a bulk update with full control over behavior. Note that performing a bulk update differs from performing a single update, in that an implementation of this class will continue to update properties if a recoverable error (such as a vetoed property change or a type mismatch, but not an invalid fieldname or the like) is encountered, throwing a PropertyAccessExceptionsException containing all the individual errors. This exception can be examined later to see all binding errors. Properties that were successfully updated stay changed.

Does not allow unknown fields.

Parameters:

pvs - PropertyValues to set on the target object

ignoreUnknown - should we ignore unknown values (not found in the bean!?)

Throws:

BeansException

getPropertyDescriptors

public java.beans.PropertyDescriptor[] getPropertyDescriptors()
                                                       throws BeansException

Get the PropertyDescriptors identified on this object (standard JavaBeans introspection).

Returns:

the PropertyDescriptors identified on this object

Throws:

BeansException

getPropertyDescriptor

public java.beans.PropertyDescriptor getPropertyDescriptor(java.lang.String propertyName)
                                                    throws BeansException

Get the property descriptor for a particular property.

Parameters:

propertyName - property to check status for

Returns:

the property descriptor for a particular property

Throws:

FatalBeanException - if there is no such property

BeansException

isReadableProperty

public boolean isReadableProperty(java.lang.String propertyName)

Return whether this property is readable. Returns false if the property doesn't exist.

Parameters:

propertyName - property to check status for

Returns:

whether this property is readable

isWritableProperty

public boolean isWritableProperty(java.lang.String propertyName)

Return whether this property is writable. Returns false if the property doesn't exist.

Parameters:

propertyName - property to check status for

Returns:

whether this property is writable