org.springframework.beans
Class BeanWrapperImpl

java.lang.Object
  extended byorg.springframework.beans.BeanWrapperImpl
All Implemented Interfaces:
BeanWrapper, PropertyAccessor

public class BeanWrapperImpl
extends Object
implements BeanWrapper

Default implementation of the BeanWrapper interface that should be sufficient for all typical use cases. Caches introspection results for efficiency.

Note: This class never tries to load a class by name, as this can pose class loading problems in J2EE applications with multiple deployment modules. The caller is responsible for loading a target class.

Note: Auto-registers default property editors from the org.springframework.beans.propertyeditors package, which apply in addition to the JDK's standard PropertyEditors. Applications can call BeanWrapper's registerCustomEditor method to register an editor for the particular instance (i.e. they're not shared across the application).

BeanWrapperImpl will convert collection and array values to the corresponding target collections or arrays, if necessary. Custom property editors that deal with collections or arrays can either be written via PropertyEditor's setValue, or against a comma-delimited String via setAsText, as String arrays are converted in such a format if the array itself is not assignable.

Since:
15 April 2001
Author:
Rod Johnson, Juergen Hoeller
See Also:
registerCustomEditor(java.lang.Class, java.beans.PropertyEditor), PropertyEditorManager, PropertyEditorSupport.setAsText(java.lang.String), PropertyEditorSupport.setValue(java.lang.Object), ByteArrayPropertyEditor, ClassEditor, CustomBooleanEditor, CustomNumberEditor, CustomCollectionEditor, FileEditor, InputStreamEditor, JndiTemplateEditor, LocaleEditor, PropertiesEditor, PropertyValuesEditor, ResourceArrayPropertyEditor, ResourceEditor, StringArrayPropertyEditor, TransactionAttributeEditor, TransactionAttributeSourceEditor, URLEditor

Field Summary
 
Fields inherited from interface org.springframework.beans.PropertyAccessor
NESTED_PROPERTY_SEPARATOR, NESTED_PROPERTY_SEPARATOR_CHAR, PROPERTY_KEY_PREFIX, PROPERTY_KEY_PREFIX_CHAR, PROPERTY_KEY_SUFFIX, PROPERTY_KEY_SUFFIX_CHAR
 
Constructor Summary
BeanWrapperImpl()
          Create new empty BeanWrapperImpl.
BeanWrapperImpl(Class clazz)
          Create new BeanWrapperImpl, wrapping a new instance of the specified class.
BeanWrapperImpl(Object object)
          Create new BeanWrapperImpl for the given object.
BeanWrapperImpl(Object object, String nestedPath)
          Deprecated. in favor of BeanWrapperImpl(object, nestedPath, rootObject)
BeanWrapperImpl(Object object, String nestedPath, Object rootObject)
          Create new BeanWrapperImpl for the given object, registering a nested path that the object is in.
 
Method Summary
 Object doTypeConversionIfNecessary(Object newValue, Class requiredType)
          Convert the value to the required type (if necessary from a String).
protected  Object doTypeConversionIfNecessary(String propertyName, String fullPropertyName, Object oldValue, Object newValue, Class requiredType)
          Convert the value to the required type (if necessary from a String), for the specified property.
 PropertyEditor findCustomEditor(Class requiredType, String propertyPath)
          Find a custom property editor for the given type and property.
protected  BeanWrapperImpl getBeanWrapperForPropertyPath(String propertyPath)
          Recursively navigate to return a BeanWrapper for the nested property path.
 String getNestedPath()
          Return the nested path of the object wrapped by this BeanWrapper.
 PropertyDescriptor getPropertyDescriptor(String propertyName)
          Get the property descriptor for a particular property.
protected  PropertyDescriptor getPropertyDescriptorInternal(String propertyName)
          Internal version of getPropertyDescriptor: Returns null if not found rather than throwing an exception.
 PropertyDescriptor[] getPropertyDescriptors()
          Get the PropertyDescriptors identified on this object (standard JavaBeans introspection).
 Class getPropertyType(String propertyName)
          Determine the property type for a particular property, either checking the property descriptor or checking the value in case of an indexed or mapped element.
protected  Object getPropertyValue(org.springframework.beans.BeanWrapperImpl.PropertyTokenHolder tokens)
           
 Object getPropertyValue(String propertyName)
          Get the value of a property.
 Class getRootClass()
          Return the class of the root object at the top of the path of this BeanWrapper.
 Object getRootInstance()
          Return the root object at the top of the path of this BeanWrapper.
 Class getWrappedClass()
          Convenience method to return the class of the wrapped object.
 Object getWrappedInstance()
          Return the bean wrapped by this object (cannot be null).
 boolean isReadableProperty(String propertyName)
          Return whether this property is readable.
 boolean isWritableProperty(String propertyName)
          Return whether this property is writable.
 void registerCustomEditor(Class requiredType, PropertyEditor propertyEditor)
          Register the given custom property editor for all properties of the given type.
 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.
protected  void setIntrospectionClass(Class clazz)
          Set the class to introspect.
protected  void setPropertyValue(org.springframework.beans.BeanWrapperImpl.PropertyTokenHolder tokens, Object value)
           
 void setPropertyValue(PropertyValue pv)
          Update a property value.
 void setPropertyValue(String propertyName, Object value)
          Set a property value.
 void setPropertyValues(Map map)
          Bulk update from a Map.
 void setPropertyValues(PropertyValues pvs)
          The preferred way to perform a bulk update.
 void setPropertyValues(PropertyValues propertyValues, boolean ignoreUnknown)
          Perform a bulk update with full control over behavior.
 void setWrappedInstance(Object object)
          Switch the target object, replacing the cached introspection results only if the class of the new object is different to that of the replaced object.
 void setWrappedInstance(Object object, String nestedPath)
          Deprecated. in favor of setWrappedInstance(object, nestedPath, rootObject)
 void setWrappedInstance(Object object, String nestedPath, Object rootObject)
          Switch the target object, replacing the cached introspection results only if the class of the new object is different to that of the replaced object.
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

BeanWrapperImpl

public BeanWrapperImpl()
Create new empty BeanWrapperImpl. Wrapped instance needs to be set afterwards.

See Also:
setWrappedInstance(java.lang.Object)

BeanWrapperImpl

public BeanWrapperImpl(Object object)
Create new BeanWrapperImpl for the given object.

Parameters:
object - object wrapped by this BeanWrapper

BeanWrapperImpl

public BeanWrapperImpl(Class clazz)
Create new BeanWrapperImpl, wrapping a new instance of the specified class.

Parameters:
clazz - class to instantiate and wrap

BeanWrapperImpl

public BeanWrapperImpl(Object object,
                       String nestedPath)
Deprecated. in favor of BeanWrapperImpl(object, nestedPath, rootObject)

See Also:
BeanWrapperImpl(Object, String, Object)

BeanWrapperImpl

public BeanWrapperImpl(Object object,
                       String nestedPath,
                       Object rootObject)
Create new BeanWrapperImpl for the given object, registering a nested path that the object is in.

Parameters:
object - object wrapped by this BeanWrapper.
nestedPath - the nested path of the object
rootObject - the root object at the top of the path
Method Detail

setWrappedInstance

public void setWrappedInstance(Object object)
Switch the target object, replacing the cached introspection results only if the class of the new object is different to that of the replaced object.

Specified by:
setWrappedInstance in interface BeanWrapper
Parameters:
object - new target

setWrappedInstance

public void setWrappedInstance(Object object,
                               String nestedPath)
Deprecated. in favor of setWrappedInstance(object, nestedPath, rootObject)

See Also:
setWrappedInstance(Object, String, Object)

setWrappedInstance

public void setWrappedInstance(Object object,
                               String nestedPath,
                               Object rootObject)
Switch the target object, replacing the cached introspection results only if the class of the new object is different to that of the replaced object.

Parameters:
object - new target
nestedPath - the nested path of the object
rootObject - the root object at the top of the path

getWrappedInstance

public Object getWrappedInstance()
Description copied from interface: BeanWrapper
Return the bean wrapped by this object (cannot be null).

Specified by:
getWrappedInstance in interface BeanWrapper
Returns:
the bean wrapped by this object

getWrappedClass

public Class getWrappedClass()
Description copied from interface: BeanWrapper
Convenience method to return the class of the wrapped object.

Specified by:
getWrappedClass in interface BeanWrapper
Returns:
the class of the wrapped object

getNestedPath

public String getNestedPath()
Return the nested path of the object wrapped by this BeanWrapper.


getRootInstance

public Object getRootInstance()
Return the root object at the top of the path of this BeanWrapper.

See Also:
getNestedPath()

getRootClass

public Class getRootClass()
Return the class of the root object at the top of the path of this BeanWrapper.

See Also:
getNestedPath()

setIntrospectionClass

protected void setIntrospectionClass(Class clazz)
Set the class to introspect. Needs to be called when the target object changes.

Parameters:
clazz - the class to introspect

registerCustomEditor

public void registerCustomEditor(Class requiredType,
                                 PropertyEditor propertyEditor)
Description copied from interface: BeanWrapper
Register the given custom property editor for all properties of the given type.

Specified by:
registerCustomEditor in interface BeanWrapper
Parameters:
requiredType - type of the property
propertyEditor - editor to register

registerCustomEditor

public void registerCustomEditor(Class requiredType,
                                 String propertyPath,
                                 PropertyEditor propertyEditor)
Description copied from interface: BeanWrapper
Register the given custom property editor for the given type and property, or for all properties of the given type.

If the property path denotes an array or Collection property, the editor will get applied either to the array/Collection itself (the PropertyEditor has to create an array or Collection value) or to each element (the PropertyEditor has to create the element type), depending on the specified required type.

Note: Only one single registered custom editor per property path is supported. In case of a Collection/array, do not register an editor for both the Collection/array and each element on the same property.

Specified by:
registerCustomEditor in interface BeanWrapper
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 PropertyEditor findCustomEditor(Class requiredType,
                                       String propertyPath)
Description copied from interface: BeanWrapper
Find a custom property editor for the given type and property.

Specified by:
findCustomEditor in interface BeanWrapper
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

getBeanWrapperForPropertyPath

protected BeanWrapperImpl getBeanWrapperForPropertyPath(String propertyPath)
                                                 throws BeansException
Recursively navigate to return a BeanWrapper for the nested property path.

Parameters:
propertyPath - property property path, which may be nested
Returns:
a BeanWrapper for the target bean
Throws:
BeansException

getPropertyValue

public Object getPropertyValue(String propertyName)
                        throws BeansException
Description copied from interface: PropertyAccessor
Get the value of a property.

Specified by:
getPropertyValue in interface PropertyAccessor
Parameters:
propertyName - name of the property to get the value of
Returns:
the value of the property
Throws:
BeansException

getPropertyValue

protected Object getPropertyValue(org.springframework.beans.BeanWrapperImpl.PropertyTokenHolder tokens)
                           throws BeansException
Throws:
BeansException

setPropertyValue

public void setPropertyValue(String propertyName,
                             Object value)
                      throws BeansException
Description copied from interface: PropertyAccessor
Set a property value. This method is provided for convenience only. The setPropertyValue(PropertyValue) method is more powerful.

Specified by:
setPropertyValue in interface PropertyAccessor
Parameters:
propertyName - name of the property to set value of
value - the new value
Throws:
BeansException

setPropertyValue

protected void setPropertyValue(org.springframework.beans.BeanWrapperImpl.PropertyTokenHolder tokens,
                                Object value)
                         throws BeansException
Throws:
BeansException

setPropertyValue

public void setPropertyValue(PropertyValue pv)
                      throws BeansException
Description copied from interface: PropertyAccessor
Update a property value. This is the preferred way to update an individual property.

Specified by:
setPropertyValue in interface PropertyAccessor
Parameters:
pv - object containing new property value
Throws:
BeansException

setPropertyValues

public void setPropertyValues(Map map)
                       throws BeansException
Bulk update from a Map. Bulk updates from PropertyValues are more powerful: this method is provided for convenience.

Specified by:
setPropertyValues in interface PropertyAccessor
Parameters:
map - map containing properties to set, as name-value pairs. The map may include nested properties.
Throws:
BeansException - if there's a fatal, low-level exception

setPropertyValues

public void setPropertyValues(PropertyValues pvs)
                       throws BeansException
Description copied from interface: PropertyAccessor
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 type mismatch, but not an invalid field name 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).

Specified by:
setPropertyValues in interface PropertyAccessor
Parameters:
pvs - PropertyValues to set on the target object
Throws:
BeansException
See Also:
PropertyAccessor.setPropertyValues(PropertyValues, boolean)

setPropertyValues

public void setPropertyValues(PropertyValues propertyValues,
                              boolean ignoreUnknown)
                       throws BeansException
Description copied from interface: PropertyAccessor
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 type mismatch, but not an invalid field name 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.

Specified by:
setPropertyValues in interface PropertyAccessor
Parameters:
propertyValues - PropertyValues to set on the target object
ignoreUnknown - should we ignore unknown values (not found in the bean)
Throws:
BeansException

doTypeConversionIfNecessary

public Object doTypeConversionIfNecessary(Object newValue,
                                          Class requiredType)
                                   throws BeansException
Convert the value to the required type (if necessary from a String). Conversions from String to any type use the setAsText method of the PropertyEditor class. Note that a PropertyEditor must be registered for this class for this to work. This is a standard Java Beans API. A number of property editors are automatically registered by this class.

Parameters:
newValue - proposed change value.
requiredType - type we must convert to
Returns:
new value, possibly the result of type convertion
Throws:
BeansException - if there is an internal error

doTypeConversionIfNecessary

protected Object doTypeConversionIfNecessary(String propertyName,
                                             String fullPropertyName,
                                             Object oldValue,
                                             Object newValue,
                                             Class requiredType)
                                      throws BeansException
Convert the value to the required type (if necessary from a String), for the specified property.

Parameters:
propertyName - name of the property
oldValue - previous value, if available (may be null)
newValue - proposed change value
requiredType - the type we must convert to (or null if not known, for example in case of a collection element)
Returns:
converted value (i.e. possibly the result of type conversion)
Throws:
BeansException - if there is an internal error

getPropertyDescriptors

public PropertyDescriptor[] getPropertyDescriptors()
Description copied from interface: BeanWrapper
Get the PropertyDescriptors identified on this object (standard JavaBeans introspection).

Specified by:
getPropertyDescriptors in interface BeanWrapper
Returns:
the PropertyDescriptors identified on this object

getPropertyDescriptor

public PropertyDescriptor getPropertyDescriptor(String propertyName)
                                         throws BeansException
Description copied from interface: BeanWrapper
Get the property descriptor for a particular property.

Specified by:
getPropertyDescriptor in interface BeanWrapper
Parameters:
propertyName - property to check status for
Returns:
the property descriptor for the particular property
Throws:
BeansException

getPropertyDescriptorInternal

protected PropertyDescriptor getPropertyDescriptorInternal(String propertyName)
                                                    throws BeansException
Internal version of getPropertyDescriptor: Returns null if not found rather than throwing an exception.

Throws:
BeansException

getPropertyType

public Class getPropertyType(String propertyName)
                      throws BeansException
Description copied from interface: BeanWrapper
Determine the property type for a particular property, either checking the property descriptor or checking the value in case of an indexed or mapped element.

Specified by:
getPropertyType in interface BeanWrapper
Parameters:
propertyName - property to check status for
Returns:
the property type for the particular property, or null if not determinable (can only happen with an indexed or mapped element)
Throws:
BeansException

isReadableProperty

public boolean isReadableProperty(String propertyName)
Description copied from interface: BeanWrapper
Return whether this property is readable. Returns false if the property doesn't exist.

Specified by:
isReadableProperty in interface BeanWrapper
Parameters:
propertyName - property to check status for
Returns:
whether this property is readable

isWritableProperty

public boolean isWritableProperty(String propertyName)
Description copied from interface: BeanWrapper
Return whether this property is writable. Returns false if the property doesn't exist.

Specified by:
isWritableProperty in interface BeanWrapper
Parameters:
propertyName - property to check status for
Returns:
whether this property is writable

toString

public String toString()


Copyright (C) 2003-2004 The Spring Framework Project.