org.jbeans
Class JavaBean

java.lang.Object
  |
  +--org.jbeans.JavaBean

Direct Known Subclasses:

SynchronizedJavaBean

public class JavaBean

extends Object

This class can be used to facilitate getting and setting of JavaBean properties. It is an object representation of a JavaBean and allows the developer to add new properties, get property values and set property values. This class also models indexed and nested JavaBeans properties as well as nested JavaBeans themselves.

Nested JavaBeans are when a JavaBean property is another JavaBean. In normal Java code, retrieval would look something like:

bean1.getProperty().getProperty2()...getPropertyN().

The bean1 instance is the base JavaBean for this example. Within this JavaBean there is a property named property1, whose return type is another JavaBean. This is repeated until a leaf property is hit. Leaf properties return object instances that do not contain any JavaBean properties. Although all leaf properties do not meet this requirement a property that does is automatically a leaf property.

A property might return an instance of an object that does contain JavaBean properties, but in the context of a particular application, these are not accessed using the JBeans package or through reflection. These properties are also considered leaf properties.

Using this class these properties can be retrieved using the standard JavaBean notation of property.property2...propertyN (for the example above)

It should also be noted that the properties already accessed or added are stored so that continued access is quicker than using the NestedBeanProperty class. This also means that this class will only store the information about the properties and nested JavaBeans requested. It does NOT build a complete list of the properties and nested JavaBeans of a particular class at any time. It is not recommended that this class be heavily used because of the space usage of storing all the properties and nested JavaBeans. If it the local and nested properties are relatively few, then this class can offer speed benefits. If not, this class is not a good solution because of its memory consumption.

NOTE:
When this class creates new JavaBean instances for nested properties, the new instances have the same value for the strict property as the parent JavaBean instance.

Author:

Brian Pontarelli

Field Summary

protected Class	beanClass
protected Map	children
protected Map	properties
protected boolean	strict

Constructor Summary

JavaBean(Class beanClass)
Creates new JavaBean using the given bean class object and with strict set to false.

JavaBean(Class beanClass, boolean strict)
Creates new JavaBean using the given bean class object and the given strict value.

JavaBean(String beanClass)
Creates new JavaBean using the given fully qualified name of the bean class object and with strict set to false.

JavaBean(String beanClass, boolean strict)
Creates new JavaBean using the given fully qualified name of the bean class object and the given strict value.

Method Summary

void	addProperty(String propertyName) Adds the given property to this JavaBean object.
void	checkBeanProperty(String propertyName, Class type) Checks if the given bean property is a valid bean property for this JavaBean or a child JavaBean.
Class	getBeanClass() Gets the bean class that this JavaBean is for
BeanProperty	getBeanProperty(String propertyName) Returns the bean property described by the propertyName String parameter.
JavaBean	getChildJavaBean(String propertyName) Returns the child JavaBean described by the propertyName String parameter.
IndexedBeanProperty	getIndexedBeanProperty(String propertyName) Returns the indexed bean property described by the propertyName String parameter.
Object	getPropertyValue(String propertyName, Object bean) Retrieves the local or nested bean property using the property name, the bean object (which will be used to retrieve and/or store child objects).
Object	getPropertyValue(String propertyName, Object bean, int[] indices) Retrieves the local or nested bean property using the property name, the bean object (which will be used to retrieve and/or store child objects) and the list of indices which will be used for any indexed properties.
Object	getPropertyValue(String propertyName, Object bean, List indices) Retrieves the local or nested bean property using the property name, the bean object (which will be used to retrieve and/or store child objects) and the list of indices which will be used for any indexed properties.
Object	instantiate() Returns a new instance of the Java bean class that this JavaBean instance was cosntructed for.
boolean	isBeanPropertyIndexed(String propertyName) Returns whether or not the property described by the propertyName String parameter is an indexed bean property or not.
boolean	isStrict() Retrieves the value of the strict property
void	setPropertyValue(String propertyName, Object bean, int[] indices, Object value, boolean convert) Sets the local or nested property using the property name, the bean object (which will be used to retrieve and/or store the child objects if this is a nested property), the array of indices for any indexed properties, the value with which to set the property, the convert flag to determine whether or not to convert the value to the appropriate type before setting.
void	setPropertyValue(String propertyName, Object bean, List indices, Object value, boolean convert) Sets the local or nested property using the property name, the bean object (which will be used to retrieve and/or store the child objects if this is a nested property), the list of indices for any indexed properties, the value with which to set the property, the convert flag to determine whether or not to convert the value to the appropriate type before setting.
void	setPropertyValue(String propertyName, Object bean, Object value) Sets the local or nested property to the given value on the given bean instance.
void	setPropertyValue(String propertyName, Object bean, Object value, boolean convert) Sets the local or nested property using the property name, the bean object (which will be used to retrieve and/or store the child objects if this is a nested property), the value with which to set the property, the convert flag to determine whether or not to convert the value to the appropriate type before setting.
void	setStrict(boolean value) Sets the value of the strict property for this JavaBean only.

Methods inherited from class java.lang.Object

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

Field Detail

beanClass

protected Class beanClass

properties

protected Map properties

children

protected Map children

strict

protected boolean strict

Constructor Detail

JavaBean

public JavaBean(Class beanClass)

Creates new JavaBean using the given bean class object and with strict set to false. This constructor does nothing but setup the JavaBean for access. As mentioned in the class comment, this does not build a list of properties or nested JavaBeans. This occurs when either the properties are added or used to get and set values.

Parameters:

beanClass - The Class object used to find the properties and nested JavaBeans

JavaBean

public JavaBean(String beanClass)
         throws BeanException

Creates new JavaBean using the given fully qualified name of the bean class object and with strict set to false. This constructor does nothing but setup the JavaBean for access. As mentioned in the class comment, this does not build a list of properties or nested JavaBeans. This occurs when either the properties are added or used to get and set values.

Parameters:

beanClass - The fully qualified name of the bean class used to find properties and nested JavaBeans

Throws:

BeanException - If the class name is not a valid class in the classpath

JavaBean

public JavaBean(Class beanClass,
                boolean strict)

Creates new JavaBean using the given bean class object and the given strict value. The strict value determines the behavior of this class when getting and setting properties from nested JavaBeans that are null. If strict is true and a null value is encountered for a nested JavaBean's property (ie property1.property2.property3 and property1 is null), an exception is thrown. This only holds true for accessing nested properties that aren't the leaf property (i.e. value is a leaf property for the nested property property1.property2.value).

Parameters:

beanClass - The Class object used to find the properties and nested JavaBeans

strict - Determines how this class handles cases when setting and retrieving property values and a child bean is null

JavaBean

public JavaBean(String beanClass,
                boolean strict)
         throws BeanException

Creates new JavaBean using the given fully qualified name of the bean class object and the given strict value. The strict value determines the behavior of this class when getting and setting properties from nested JavaBeans that are null. If strict is true and a null value is encountered for a nested JavaBean's property (ie property1.property2.property3 and property1 is null), an exception is thrown. This only holds true for accessing nested properties that aren't the leaf property (i.e. value is a leaf property for the nested property property1.property2.value).

Parameters:

beanClass - The fully qualified name of the bean class used to find properties and nested JavaBeans

strict - Determines how this class handles cases when setting and retrieving property values and a child bean is null

Throws:

BeanException - If the class name is not a valid class in the classpath

Method Detail

isStrict

public boolean isStrict()

Retrieves the value of the strict property

setStrict

public void setStrict(boolean value)

Sets the value of the strict property for this JavaBean only. That means that the nested JavaBeans of this JavaBean retain the strictness used when creating the JavaBean.

Parameters:

value - The value to set for the strictness of this and only this JavaBean

getBeanClass

public Class getBeanClass()

Gets the bean class that this JavaBean is for

addProperty

public void addProperty(String propertyName)
                 throws BeanException

Adds the given property to this JavaBean object. This property can either be a local or nested property (ie value is a local property and property1.property2.value is a nested property). This can also be an indexed property. The String passed in should only contain the property names and shoul dnot contain index values or index notation. This method will determine which of the properties are indexed and which aren't.

It is not necessary to add properties before they are accessed using the getPropertyValue() or the setPropertyValue() methods. You can also retrieve BeanProperties from the getBeanProperty() method without adding them.

This method allows the JavaBean to be constructed with the properties that will be used in the future so that access time in the future is faster (ie nothing needs to be constructed in order to access a property).

Parameters:

propertyName - The name of the local or nested property to add

Throws:

BeanException - If the propertyName is not a valid property of this JavaBean

getBeanProperty

public BeanProperty getBeanProperty(String propertyName)
                             throws BeanException

Returns the bean property described by the propertyName String parameter. This parameter can be either a property of this JavaBean or a property of a nested JavaBean. See the class comment for a description of nested JavaBeans.

If the BeanProperty has not been added to either this JavaBean or a child JavaBean, it will be created and likewise, any JavaBean children that do not exist yet, will also be created and added. This is done in order to allow access to the BeanProperty. Not that if the BeanProperty does not exist in the Class of this JavaBean or a child JavaBean an exception is thrown.

Parameters:

propertyName - The name of the property that is a local or nested property

Returns:

Either the local bean property or the nested bean property and never null

Throws:

BeanException - If there was a problem finding or creating the bean property

getIndexedBeanProperty

public IndexedBeanProperty getIndexedBeanProperty(String propertyName)
                                           throws BeanException

Returns the indexed bean property described by the propertyName String parameter. This parameter can be either a property of this JavaBean or a property of a nested JavaBean. See the class comment for a description of nested JavaBeans.

If the IndexedBeanProperty has not been added to either this JavaBean or a child JavaBean, it will be created and likewise, any JavaBean children that do not exist yet, will also be created and added. This is done in order to allow access to the IndexedBeanProperty. Not that if the property does not exist in the Class of this JavaBean or a child JavaBean or it is not indexed an exception is thrown.

Parameters:

propertyName - The name of the property that is a local or nested indexed property

Returns:

Either the local indexed bean property or the nested indexed bean property and never null

Throws:

BeanException - If there was a problem finding or creating the indexed bean property

isBeanPropertyIndexed

public boolean isBeanPropertyIndexed(String propertyName)
                              throws BeanException

Returns whether or not the property described by the propertyName String parameter is an indexed bean property or not. This property can be a property of this JavaBean or a property of a nested JavaBean. See the class comment for a description of nested JavaBeans.

If the property was not added to the JavaBean yet, then this method adds it so that it can determine whether or not it is indexed. Also, if the propertyName is not valid, then an exception is thrown.

Parameters:

propertyName - The name of the property that is a local or nested property and is being check to see if it is indexed or not

Returns:

True if the bean property is indexed, false otherwise

Throws:

BeanException - If the propertyName is not a valid local or nested property

checkBeanProperty

public void checkBeanProperty(String propertyName,
                              Class type)
                       throws BeanException

Checks if the given bean property is a valid bean property for this JavaBean or a child JavaBean. This method also checks if the given type the type or sub-type of the type for the property. If the BeanProperty has not been added to the JavaBean or to a child JavaBean it is created and added.

Parameters:

propertyName - The property to check and possibly add to this the java bean

type - The type to check against the property

Throws:

BeanException - If the property does not exist in this java bean or if the property type is not the same as or assignable to the given type

getChildJavaBean

public JavaBean getChildJavaBean(String propertyName)
                          throws BeanException

Returns the child JavaBean described by the propertyName String parameter. This parameter can be either a property of this JavaBean or a nested property name. See the class comment for a description of nested JavaBeans.

Parameters:

propertyName - The name of the property that is a child bean or the name of a nested property that is a child bean of one of this beans children

Returns:

Either the local child JavaBean or the nested child JavaBean and never null

Throws:

BeanException - If there was a problem finding the sub-bean or there was a problem creating BeanProperty objects for properties of this bean or one of its children or problems creating JavaBean obejcts for one of this beans child beans

instantiate

public Object instantiate()
                   throws BeanException

Returns a new instance of the Java bean class that this JavaBean instance was cosntructed for. This is done using the default constructor for the Java bean. If there was any problems a BeanException is thrown

Returns:

A new instance of the Java bean for this JavaBean instance

Throws:

BeanException - If there was a problem creating the instance

getPropertyValue

public Object getPropertyValue(String propertyName,
                               Object bean)
                        throws BeanException

Retrieves the local or nested bean property using the property name, the bean object (which will be used to retrieve and/or store child objects). If this is a nested property and a child JavaBean is ever null, this method throws an exception based on the strictness of this JavaBean. Otherwise, null is returned.

Parameters:

propertyName - The name of the property to retrieve

bean - The bean to retrieve the property value from

Returns:

The value of the property

Throws:

BeanException - If there was a problem retrieving the value

getPropertyValue

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

Retrieves the local or nested bean property using the property name, the bean object (which will be used to retrieve and/or store child objects) and the list of indices which will be used for any indexed properties. The array is used in sequential order as the index whenever a index property is encountered.

If this is a nested property and a child JavaBean is ever null, this method throws an exception based on the strictness of this JavaBean. Otherwise, null is returned.

Parameters:

propertyName - The name of the property to retrieve

bean - The bean to retrieve the property value from

indices - (Optional) The list of indices used for indexed properties

Returns:

The value of the property

Throws:

BeanException - If there was a problem retrieving the value

getPropertyValue

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

Retrieves the local or nested bean property using the property name, the bean object (which will be used to retrieve and/or store child objects) and the list of indices which will be used for any indexed properties. The array is used in sequential order as the index whenever a index property is encountered.

If this is a nested property and a child JavaBean is ever null, this method throws an exception based on the strictness of this JavaBean. Otherwise, null is returned.

Parameters:

propertyName - The name of the property to retrieve

bean - The bean to retrieve the property value from

indices - (Optional) The list of indices used for indexed properties

Returns:

The value of the property

Throws:

BeanException - If there was a problem retrieving the value

setPropertyValue

public void setPropertyValue(String propertyName,
                             Object bean,
                             Object value)
                      throws BeanException

Sets the local or nested property to the given value on the given bean instance. This method does no conversion and is the same as calling the other setPropertyValue method with the convert parameter set to false.

Parameters:

propertyName - The name of the property to set (local or nested)

bean - The bean to set the property on

value - The value to set the property to

Throws:

BeanException - If there was a problem setting the property or converting the value or creating child objects

setPropertyValue

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

Sets the local or nested property using the property name, the bean object (which will be used to retrieve and/or store the child objects if this is a nested property), the value with which to set the property, the convert flag to determine whether or not to convert the value to the appropriate type before setting. Based on the strictness of this JavaBean, if a null property is encountered in a nested property an exception may be thrown. If strict is set to true, then an exception is thrown. If it is set to false, then a new instance of the property is created and set.

Parameters:

propertyName - The name of the property to set (local or nested)

bean - The bean to set the property on

value - The value to set the property to

convert - Determines whether or not to convert the value to the type of the property

Throws:

BeanException - If there was a problem setting the property or converting the value or creating child objects

setPropertyValue

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

Sets the local or nested property using the property name, the bean object (which will be used to retrieve and/or store the child objects if this is a nested property), the array of indices for any indexed properties, the value with which to set the property, the convert flag to determine whether or not to convert the value to the appropriate type before setting.

Based on the strictness of this JavaBean, if a null property is encountered in a nested property an exception may be thrown. If strict is set to true, then an exception is thrown. If it is set to false, then a new instance of the property is created and set.

Parameters:

propertyName - The name of the property to set (local or nested)

bean - The bean to set the property on

indices - (Optional) The array of indices that will be used for any indexed properties

value - The value to set the property to

convert - Determines whether or not to convert the value to the type of the property

Throws:

BeanException - If there was a problem setting the property or converting the value or creating child objects

setPropertyValue

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

Sets the local or nested property using the property name, the bean object (which will be used to retrieve and/or store the child objects if this is a nested property), the list of indices for any indexed properties, the value with which to set the property, the convert flag to determine whether or not to convert the value to the appropriate type before setting.

Based on the strictness of this JavaBean, if a null property is encountered in a nested property an exception may be thrown. If strict is set to true, then an exception is thrown. If it is set to false, then a new instance of the property is created and set.

Parameters:

propertyName - The name of the property to set (local or nested)

bean - The bean to set the property on

indices - (Optional) The array of indices that will be used for any indexed properties

value - The value to set the property to

convert - Determines whether or not to convert the value to the type of the property

Throws:

BeanException - If there was a problem setting the property or converting the value or creating child objects