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