org.jbeans
Class DynamicNestedBeanProperty

java.lang.Object
  |
  +--org.jbeans.BaseBeanProperty
        |
        +--org.jbeans.DynamicNestedBeanProperty

Direct Known Subclasses:

NestedBeanProperty, SynchronizedDynamicNestedBeanProperty

public class DynamicNestedBeanProperty

extends BaseBeanProperty

This class is used to store information about and handle getting and setting of both nested and local properties.

A nested property is normally retrieved with a statement like:

getProperty1().getProperty2().getProperty3()...

and set like:

getProperty1().getProperty2()...setPropertyN(value).

This class allows these type of properties to be handled using simple dot notation and JavaBean property names. So the above example would be notated like:

property1.property2...propertyN

. This notation allows this class to be setup so that nested properties can be retrieved and set.

It also allows nested properties to be auto generated. What this means is that if, for the example above, getProperty1() returns null, then a new instance of the return type for getProperty1 is created and set using setProperty1(newInstance).

Local properties are just plain old JavaBean properties which are normally described by java.beans.PropertyDescriptor and have the form propertyName, which would equate to getPropertyName() and setPropertyName() (or isPropertyName for boolean values). This class can be used to access these types of properties in addition to the nested properties.

The way that null children are handled can be changed for this class. Null children are described as nested properties that need to be auto generated using the method described above. This is done using the strict member of the class via a constructor or the strict property methods. If this class describes a nested property and while traversing the nesting a null value is encountered, the value of strict determines is an exception is thrown or the property is auto generated. For example, if the property is foo.bar.value and a call to getFoo() returns a null value, then one of the following outcomes will occur:

If strict is false, and the getPropertyValue() method was called, then null is returned.

If strict is false and the setPropertyValue method was called, then a new instance of the return type for getFoo is created using the default constructor and set using the setFoo() method.

If strict is true and either getPropertyValue or setPropertyValue was called, then an exception is thrown.

This class also handles a mixed set of indexed and normal properties in the nesting. For example, you could access a property such as:

getIndexed(1).getProperty2().getValue()

using this class. The constructor takes the name of the property without distinguishing between indexed and normal properties. So, for the example above, the constructor would take a property String like: indexed.property2.value. Then when the property value is being retrieved or changed, the index values are passed in with either an array of ints or a List of Integer wrappers.

Author:

Brian Pontarelli

Fields inherited from class org.jbeans.BaseBeanProperty

BAD_CONVERT, beanClass, conversionListeners, GET, POST_CONVERT, PRE_CONVERT, propertyListeners, propertyName, propertyType, SET

Constructor Summary

protected	DynamicNestedBeanProperty() Default constructor that can be used by sub-classes that want to delay the initialization of the propertyName and beanClass or that do not use these members.
	DynamicNestedBeanProperty(String propertyName, Class beanClass) Constructs a new NestedBeanProperty that can be used to describe nested or local properties, depending on the value of the property string (see the class comment for more information).
	DynamicNestedBeanProperty(String propertyName, Class beanClass, boolean strict) Constructs a new NestedBeanProperty that can be used to describe nested or local properties, depending on the value of the property string (see the class comment for more information).
	DynamicNestedBeanProperty(String propertyName, String beanClass) Constructs a new NestedBeanProperty that can be used to describe nested or local properties, depending on the value of the property string (see the class comment for more information).
	DynamicNestedBeanProperty(String propertyName, String beanClass, boolean strict) Constructs a new NestedBeanProperty that can be used to describe nested or local properties, depending on the value of the property string (see the class comment for more information).

Method Summary

Object	getPropertyValue(Object bean) Returns the value of the local or nested property described by this instance.
Object	getPropertyValue(Object bean, int[] indices) Returns the value of the local or nested property described by this instance.
Object	getPropertyValue(Object bean, List indices) Returns the value of the local or nested property described by this instance.
BeanProperty	getRootProperty() Returns the base property of nested properties or the property of local properties.
protected void	initialize() Initializes all the members of this class by parsing out the propertyName String and creating the necessary BeanProperty class and everything else that might be needed.
boolean	isStrict() Gets the strictness property of this instance
void	setPropertyValue(Object bean, int[] indices, Object value, boolean convert) Sets the local or nested property value described by this instance.
void	setPropertyValue(Object bean, List indices, Object value, boolean convert) Sets the local or nested property value described by this instance.
void	setPropertyValue(Object bean, Object value, boolean convert) Sets the local or nested property value described by this instance.
void	setStrict(boolean value) Sets the strictness property for this instance

Methods inherited from class org.jbeans.BaseBeanProperty

addConversionListener, addPropertyListener, convertParameter, fireConversionEvent, firePropertyEvent, getBeanClass, getConversionListeners, getFullName, getPropertyListeners, getPropertyName, getPropertyType, hasConversionListeners, hasPropertyListeners, instantiate, removeConversionListener, removePropertyListener, setPropertyValue

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DynamicNestedBeanProperty

protected DynamicNestedBeanProperty()

Default constructor that can be used by sub-classes that want to delay the initialization of the propertyName and beanClass or that do not use these members. This constructor also calls the default constructor from the BaseBeanProperty super-class. This means that using this constructor will not make a template method call to #initialize().

DynamicNestedBeanProperty

public DynamicNestedBeanProperty(String propertyName,
                                 Class beanClass)
                          throws BeanException

Constructs a new NestedBeanProperty that can be used to describe nested or local properties, depending on the value of the property string (see the class comment for more information). It also uses the class given to construct the method list.

Parameters:

propertyName - The name of the local or nested property

beanClass - The class to build the property for

Throws:

BeanException - If anything went wrong during the parsing of the property string or building of the property list

DynamicNestedBeanProperty

public DynamicNestedBeanProperty(String propertyName,
                                 String beanClass)
                          throws BeanException

Constructs a new NestedBeanProperty that can be used to describe nested or local properties, depending on the value of the property string (see the class comment for more information). It also uses the given fully qualified name of the bean class and the propertyName to construct the method list.

Parameters:

propertyName - The name of the local or nested property

beanClass - The fully qualified name of the bean class to build the property for

Throws:

BeanException - If anything went wrong during the parsing of the property string or building of the property list

DynamicNestedBeanProperty

public DynamicNestedBeanProperty(String propertyName,
                                 Class beanClass,
                                 boolean strict)
                          throws BeanException

Constructs a new NestedBeanProperty that can be used to describe nested or local properties, depending on the value of the property string (see the class comment for more information). It also uses the class given to construct the method list.

Parameters:

propertyName - The name of the property or deep property String

beanClass - The class to build the property for

strict - Determines how this class handles cases when setting and retrieving property values where nested properties need to be auto generated because they are null

Throws:

BeanException - If anything went wrong during the parsing of the property string or building of the property list

DynamicNestedBeanProperty

public DynamicNestedBeanProperty(String propertyName,
                                 String beanClass,
                                 boolean strict)
                          throws BeanException

Constructs a new NestedBeanProperty that can be used to describe nested or local properties, depending on the value of the property string (see the class comment for more information). It also uses the given fully qualified name of the bean class and the propertyName to construct the method list.

Parameters:

propertyName - The name of the property or deep property String

beanClass - The fully qualified name of the bean class to build the property for

strict - Determines how this class handles cases when setting and retrieving property values where nested properties need to be auto generated because they are null

Throws:

BeanException - If anything went wrong during the parsing of the property string or building of the property list

Method Detail

initialize

protected void initialize()
                   throws BeanException

Initializes all the members of this class by parsing out the propertyName String and creating the necessary BeanProperty class and everything else that might be needed.

Overrides:

initialize in class BaseBeanProperty

Throws:

BeanException - If there were any problems initializing this class

isStrict

public boolean isStrict()

Gets the strictness property of this instance

setStrict

public void setStrict(boolean value)

Sets the strictness property for this instance

getRootProperty

public BeanProperty getRootProperty()

Returns the base property of nested properties or the property of local properties. For example, if the property name is property1.property2, this method would return an instance of BeanProperty for property1.

Returns:

The base BeanProperty

getPropertyValue

public Object getPropertyValue(Object bean)
                        throws BeanException

Returns the value of the local or nested property described by this instance.

Overrides:

getPropertyValue in class BaseBeanProperty

Parameters:

bean - The bean to retrieve the property on

Returns:

The value of the property

Throws:

BeanException - If there was an error getting the JavaBean property or the getter/is method threw a checked Exception or if strict is true and a null non-leaf property was encountered

getPropertyValue

public Object getPropertyValue(Object bean,
                               List indices)
                        throws BeanException

Returns the value of the local or nested property described by this instance.

Parameters:

bean - The bean to retrieve the property on

indices - (Optional) The list of indices used when retrieving the property. This can be null if there are no indexed properties in the nesting

Returns:

The value of the property

Throws:

BeanException - If there was an error getting the JavaBean property or the getter/is method threw a checked Exception or if strict is true and a null non-leaf property was encountered

getPropertyValue

public Object getPropertyValue(Object bean,
                               int[] indices)
                        throws BeanException

Returns the value of the local or nested property described by this instance.

Parameters:

bean - The bean to retrieve the property on

indices - (Optional) The array of indices used when retrieving the property. This can be null if there are no indexed properties in the nesting

Returns:

The value of the property

Throws:

BeanException - If there was an error getting the JavaBean property or the getter/is method threw a checked Exception or if strict is true and a null non-leaf property was encountered

setPropertyValue

public void setPropertyValue(Object bean,
                             Object value,
                             boolean convert)
                      throws BeanException

Sets the local or nested property value described by this instance. This method will optionally try to convert the value parameter to the correct type for the property.

Overrides:

setPropertyValue in class BaseBeanProperty

Parameters:

bean - The bean instance to set the property on

value - The value to set on the bean

convert - Determines whether or not the value should be converted to the correct parameter type for the property set method

Throws:

BeanException - If there was an error setting the JavaBean property or the setter method threw a checked Exception or if strict is true an a null non-leaf property was encountered

setPropertyValue

public void setPropertyValue(Object bean,
                             List indices,
                             Object value,
                             boolean convert)
                      throws BeanException

Sets the local or nested property value described by this instance. This method will optionally try to convert the value parameter to the correct type for the property.

Parameters:

bean - The bean instance to set the property on

indices - (Optional) The List indices used when setting the property. This can be null if there are no indexed properties in the nesting

value - The value to set on the bean

convert - Determines whether or not the value should be converted to the correct parameter type for the property set method

Throws:

BeanException - If there was an error setting the JavaBean property or the setter method threw a checked Exception or if strict is true an a null non-leaf property was encountered

setPropertyValue

public void setPropertyValue(Object bean,
                             int[] indices,
                             Object value,
                             boolean convert)
                      throws BeanException

Sets the local or nested property value described by this instance. This method will optionally try to convert the value parameter to the correct type for the property.

Parameters:

bean - The bean instance to set the property on

indices - (Optional) The array of indices used when setting the property. This can be null if there are no indexed properties in the nesting

value - The value to set on the bean

convert - Determines whether or not the value should be converted to the correct parameter type for the property set method

Throws:

BeanException - If there was an error setting the JavaBean property or the setter method threw a checked Exception or if strict is true an a null non-leaf property was encountered