com.interface21.beans
Interface BeanWrapper

All Known Implementing Classes:
BeanWrapperImpl

public interface BeanWrapper

The central interface of the Interface21 JavaBeans infrastructure. Interface 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.
This interface supports the ability to add standard JavaBeans API PropertyChangeListeners and VetoableChangeListeners, without the need for supporting code in the target class. VetoableChangeListeners can veto individual property changes.

Since:
13 April 2001
Version:
1.1
Author:
Rod Johnson

Field Summary
static java.lang.String NESTED_PROPERTY_SEPARATOR
          Path separator for nested properties.
 
Method Summary
 void addPropertyChangeListener(java.beans.PropertyChangeListener l)
          Add a PropertyChangeListener that will be notified of property updates
 void addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener l)
          Add a PropertyChangeListener that will be notified of updates to a single property
 void addVetoableChangeListener(java.lang.String propertyName, java.beans.VetoableChangeListener l)
          Add a VetoableChangeListener that will be notified of updates to a single property
 void addVetoableChangeListener(java.beans.VetoableChangeListener l)
          Add a VetoableChangeListener that will be notified of property updates
 java.beans.PropertyEditor findCustomEditor(java.lang.Class requiredType, java.lang.String propertyPath)
          Find a custom property editor for the given type and property.
 java.lang.Object getIndexedPropertyValue(java.lang.String propertyName, int index)
          Get the value of an indexed property
 java.beans.PropertyDescriptor getPropertyDescriptor(java.lang.String propertyName)
          Get the property descriptor for a particular property, or null if there is no such property
 java.beans.PropertyDescriptor[] getPropertyDescriptors()
          Get the PropertyDescriptors standard JavaBeans introspection identified on this object.
 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.
 java.lang.Object invoke(java.lang.String methodName, java.lang.Object[] args)
          Invoke the named method.
 boolean isEventPropagationEnabled()
          Should we send out event notifications?
 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 newWrappedInstance()
          This method is included for efficiency.
 BeanWrapper newWrapper(java.lang.Object obj)
          This method is included for efficiency.
 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 removePropertyChangeListener(java.beans.PropertyChangeListener l)
          Remove a PropertyChangeListener that was formerly notified of property updates
 void removePropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener l)
          Remove a PropertyChangeListener that was notified of updates to a single property
 void removeVetoableChangeListener(java.lang.String propertyName, java.beans.VetoableChangeListener l)
          Remove a VetoableChangeListener that will be notified of updates to a single property
 void removeVetoableChangeListener(java.beans.VetoableChangeListener l)
          Remove a VetoableChangeListener that will be notified of property updates
 void setEventPropagationEnabled(boolean flag)
          Enable or disable event propogation Any existing listeners will be preserved and will again be notified of events when event propagation is reenabled.
 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 m)
          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, PropertyValuesValidator pvsValidator)
          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
Method Detail

setPropertyValue

public void setPropertyValue(java.lang.String propertyName,
                             java.lang.Object value)
                      throws java.beans.PropertyVetoException,
                             BeansException
Set a property value. This method is provided for convenience only. The setPropertyValue(PropertyValue) method is more powerful, providing the ability to set indexed properties etc.
Parameters:
propertyName - name of the property to set value of
value - the new value

setPropertyValue

public void setPropertyValue(PropertyValue pv)
                      throws java.beans.PropertyVetoException,
                             BeansException
Update a property value. This is the preferred way to update an individual property.
Parameters:
pv - object containing new property value

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.

getIndexedPropertyValue

public java.lang.Object getIndexedPropertyValue(java.lang.String propertyName,
                                                int index)
                                         throws BeansException
Get the value of an indexed property
Parameters:
propertyName - name of the property to get value of
index - index from 0 of the property
Returns:
the value of the property
Throws:
FatalBeanException - if there is no such indexed property or if the getter method throws an exception.

setPropertyValues

public void setPropertyValues(java.util.Map m)
                       throws BeansException
Perform a bulk update from a Map. Bulk updates from PropertyValues are more powerful: this method is provided for convenience. It is impossible to set indexed properties using this method. Otherwise, behaviour will be identical to that of the setPropertyValues(PropertyValues) method.
Parameters:
m - 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 PropertyVetoExceptionsException containing all the individual errors. Does not allow unknown fields. Equivalent to setPropertyValues(pvs, false, null). This exception can be examined later to see all binding errors. Properties that were successfully updated stay changed.
Parameters:
pvs - PropertyValues to set on the target object

setPropertyValues

public void setPropertyValues(PropertyValues pvs,
                              boolean ignoreUnknown,
                              PropertyValuesValidator pvsValidator)
                       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 PropertyVetoExceptionsException containing all the individual errors. This exception can be examined later to see all binding errors. Properties that were successfully updated stay changed.
Parameters:
pvs - PropertyValues to set on the target object
ignoreUnknown - should we ignore unknown values (not found in the bean!?)
pvsValidator - property values validator. Ignored if it's null.

getPropertyDescriptors

public java.beans.PropertyDescriptor[] getPropertyDescriptors()
                                                       throws BeansException
Get the PropertyDescriptors standard JavaBeans introspection identified on this object.
Returns:
the PropertyDescriptors standard JavaBeans introspection identified on this object

getPropertyDescriptor

public java.beans.PropertyDescriptor getPropertyDescriptor(java.lang.String propertyName)
                                                    throws BeansException
Get the property descriptor for a particular property, or null if there is no such property
Parameters:
propertyName - property to check status for
Returns:
the property descriptor for a particular property, or null if there is no such property

isReadableProperty

public boolean isReadableProperty(java.lang.String propertyName)
Return whether this property is readable
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
Parameters:
propertyName - property to check status for
Returns:
whether this property is writable

getWrappedInstance

public java.lang.Object getWrappedInstance()
Return the bean wrapped by this object. Cannot be null
Returns:
the bean wrapped by this object

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

newWrappedInstance

public void newWrappedInstance()
                        throws BeansException
This method is included for efficiency. If an implementation caches all necessary information about the class, it might be faster to instantiate a new instance in the class than create a new wrapper to work with a new object

newWrapper

public BeanWrapper newWrapper(java.lang.Object obj)
                       throws BeansException
This method is included for efficiency. If an implementation caches all necessary information about the class, it might be much faster to instantiate a new wrapper copying the cached information, than to use introspection again. The wrapped instance is independent, as is the new BeanWrapper: only the cached introspection information is copied. Does not copy listeners.

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

addVetoableChangeListener

public void addVetoableChangeListener(java.beans.VetoableChangeListener l)
Add a VetoableChangeListener that will be notified of property updates
Parameters:
l - VetoableChangeListener notified of all property updates

removeVetoableChangeListener

public void removeVetoableChangeListener(java.beans.VetoableChangeListener l)
Remove a VetoableChangeListener that will be notified of property updates
Parameters:
l - VetoableChangeListener to remove

addVetoableChangeListener

public void addVetoableChangeListener(java.lang.String propertyName,
                                      java.beans.VetoableChangeListener l)
Add a VetoableChangeListener that will be notified of updates to a single property
Parameters:
l - VetoableChangeListener to add
propertyName - name of property this listeners will listen to updates for

removeVetoableChangeListener

public void removeVetoableChangeListener(java.lang.String propertyName,
                                         java.beans.VetoableChangeListener l)
Remove a VetoableChangeListener that will be notified of updates to a single property
Parameters:
l - VetoableChangeListener to remove
propertyName - name of property this listeners formerly listened to updates for

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener l)
Add a PropertyChangeListener that will be notified of property updates
Parameters:
l - PropertyChangeListener notified of all property updates

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener l)
Remove a PropertyChangeListener that was formerly notified of property updates
Parameters:
l - PropertyChangeListener to remove

addPropertyChangeListener

public void addPropertyChangeListener(java.lang.String propertyName,
                                      java.beans.PropertyChangeListener l)
Add a PropertyChangeListener that will be notified of updates to a single property
Parameters:
propertyName - property the listener is interested in
l - PropertyChangeListener notified of property updates to this property

removePropertyChangeListener

public void removePropertyChangeListener(java.lang.String propertyName,
                                         java.beans.PropertyChangeListener l)
Remove a PropertyChangeListener that was notified of updates to a single property
Parameters:
propertyName - property the listener is interested in
l - PropertyChangeListener to remove

isEventPropagationEnabled

public boolean isEventPropagationEnabled()
Should we send out event notifications? Disabling this functionality (which is enabled by default) may improve performance.
Returns:
whether we notify listeners of property updates

setEventPropagationEnabled

public void setEventPropagationEnabled(boolean flag)
Enable or disable event propogation Any existing listeners will be preserved and will again be notified of events when event propagation is reenabled. However no new listeners can be added in this period: calls to add or remove listeners will be ignored.
Parameters:
flag - whether we notify listeners of property updates

invoke

public java.lang.Object invoke(java.lang.String methodName,
                               java.lang.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 java.util.Method.invoke(). Void calls return null; primitives are wrapped as objects


Rod Johnson and Spring contributors 2001-2003.