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.

Author:

Rod Johnson

Version: $Id: BeanWrapper.java,v 1.10 2004/02/04 17:36:32 jhoeller Exp $

Since: 13 April 2001

See Also: BeanFactory, DataBinder

public final static String NESTED_PROPERTY_SEPARATOR

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

public PropertyEditor findCustomEditor(Class requiredType, 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

public PropertyDescriptor getPropertyDescriptor(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

public PropertyDescriptor[] getPropertyDescriptors()
                                             throws BeansException

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

Returns: the PropertyDescriptors identified on this object

public Object getPropertyValue(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.

public Class getWrappedClass()

Convenience method to return the class of the wrapped object.

Returns: the class of the wrapped object

public Object getWrappedInstance()

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

Returns: the bean wrapped by this object

public Object invoke(String methodName, Object[] args)
               throws BeansException

Invoke the named method. This interface is designed to encourage working with bean properties, rather than methods, so this method shouldn't be used in most cases, but it is necessary to provide a simple means to invoking a named method.

Parameters:

methodName - name of the method to invoke

args - args to pass

Returns: follows Method.invoke(). Void calls return null; primitives are wrapped as objects.

See Also:

java.lang.reflect.Method.invoke(java.lang.Object,java.lang.Object[])

public boolean isReadableProperty(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

public boolean isWritableProperty(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

public void registerCustomEditor(Class requiredType, 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

public void registerCustomEditor(Class requiredType, String propertyPath, 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

public void setPropertyValue(String propertyName, 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

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

public void setPropertyValues(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

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

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!?)

public void setWrappedInstance(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

Association Links

to Class java.lang.String

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