org.jbeans
Class BaseBeanProperty

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

Direct Known Subclasses:

BeanProperty, DynamicNestedBeanProperty

public abstract class BaseBeanProperty

extends Object

This class is the base class for the BeanProperty and the NestedBeanProperty classes. It provides the standard methods used by both classes and the standard properties

Author:

Brian Pontarelli

Field Summary

protected static int	BAD_CONVERT Used to denote a conversion event has failed to take place when sub-classes are firing events
protected Class	beanClass Holds the Class that the property is contain in
protected List	conversionListeners This holds the list of conversion listeners for the bean property
protected static int	GET Used to denote a get event when sub-classes are firing events
protected static int	POST_CONVERT Used to denote a conversion event has just taken place when sub-classes are firing events
protected static int	PRE_CONVERT Used to denote a conversion event is about to take place when sub-classes are firing events
protected List	propertyListeners This holds the list of property listeners for the bean property
protected String	propertyName Holds the name of the property that this bean property describes
protected Class	propertyType Holds the Class type of the property that this bean property describes
protected static int	SET Used to denote a set event when sub-classes are firing events

Constructor Summary

protected	BaseBeanProperty() Empty default constructor which can be called by sub-classes that are not going to use the propertyName and beanClass or need to delay the initialization of those members until later.
protected	BaseBeanProperty(String propertyName, Class beanClass) Constuctor with initial properties.
protected	BaseBeanProperty(String propertyName, String beanClass) Constuctor with initial properties.

Method Summary

void	addConversionListener(ConversionListener listener) Adds a conversion listener to the list of listeners for this property.
void	addPropertyListener(PropertyListener listener) Adds a property listener to the list of listeners for this property.
protected Object	convertParameter(Object parameter, Object bean) Converts the given value parameter (parameter) to a type that is accepted by the set method of this property.
protected void	fireConversionEvent(int type, Object oldValue, Object newValue, Object bean) Fires off a conversion event using the type constants of this class and the parameters given.
protected void	firePropertyEvent(int type, Object oldValue, Object newValue, Object bean, int index) Fires off a property event using the type constants of this class and the parameters given.
Class	getBeanClass() Returns the class of the bean that this property is contained in
Iterator	getConversionListeners() Returns an iterator for the list of conversion listeners.
String	getFullName() Gets the full name of the property.
Iterator	getPropertyListeners() Returns an iterator for the list of property listeners.
String	getPropertyName() Gets the name of the property.
Class	getPropertyType() Gets the type of the property.
abstract Object	getPropertyValue(Object bean) Gets the the property value.
boolean	hasConversionListeners() Returns true if there are any conversion listeners for this property.
boolean	hasPropertyListeners() Returns true if there are any property listeners for this property.
protected abstract void	initialize() Sub-classes should put all the initialization logic in this method NOT in constructors.
Object	instantiate() Creates an instance of the class that this BeanProperty's property is contained in.
void	removeConversionListener(ConversionListener listener) Removes the given conversion listener from the list of conversion listeners.
void	removePropertyListener(PropertyListener listener) Removes the given property listener from the list of property listeners.
void	setPropertyValue(Object bean, Object value) Sets the value of the bean property to the given value.
abstract void	setPropertyValue(Object bean, Object value, boolean convert) Sets the the property value.

Methods inherited from class java.lang.Object

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

Field Detail

GET

protected static final int GET

Used to denote a get event when sub-classes are firing events

SET

protected static final int SET

Used to denote a set event when sub-classes are firing events

PRE_CONVERT

protected static final int PRE_CONVERT

Used to denote a conversion event is about to take place when sub-classes are firing events

POST_CONVERT

protected static final int POST_CONVERT

Used to denote a conversion event has just taken place when sub-classes are firing events

BAD_CONVERT

protected static final int BAD_CONVERT

Used to denote a conversion event has failed to take place when sub-classes are firing events

propertyName

protected String propertyName

Holds the name of the property that this bean property describes

beanClass

protected Class beanClass

Holds the Class that the property is contain in

propertyType

protected Class propertyType

Holds the Class type of the property that this bean property describes

propertyListeners

protected List propertyListeners

This holds the list of property listeners for the bean property

conversionListeners

protected List conversionListeners

This holds the list of conversion listeners for the bean property

Constructor Detail

BaseBeanProperty

protected BaseBeanProperty()

Empty default constructor which can be called by sub-classes that are not going to use the propertyName and beanClass or need to delay the initialization of those members until later. This only sets up the list for the property listeners. This constructor does not make a template method call to initialize. Sub-classes must make this call inside constructors or elsewhere if they wish to use the initialize method for initialization.

BaseBeanProperty

protected BaseBeanProperty(String propertyName,
                           Class beanClass)
                    throws BeanException

Constuctor with initial properties. This constructor should be called by the sub-classes if they want to setup the propertyName and beanClass members during construction. This constructor also makes a template method call to initialize(). The initialize method must be implemented my sub-classes and should do all the initialization work. This constructor simply calls the default constructor, sets up the propertyName and beanClass members and then calls to initialize

BaseBeanProperty

protected BaseBeanProperty(String propertyName,
                           String beanClass)
                    throws BeanException

Constuctor with initial properties. This constructor should be called by the sub-classes if they want to setup the propertyName and beanClass members during construction. This constructor also makes a template method call to initialize(). The initialize method must be implemented my sub-classes and should do all the initialization work. This constructor simply calls the default constructor, sets up the propertyName and beanClass members and then calls to initialize. This method takes the fully qualified name of the bean class to be used.

Method Detail

initialize

protected abstract void initialize()
                            throws BeanException

Sub-classes should put all the initialization logic in this method NOT in constructors. The reason for this is that constructors can chain effectively without causing un-wanted initialization to occur.

For example, if the the BeanProperty constructor set up the read and write Method objects for itself and the IndexedBeanProperty wanted to chain constructors an error would occur because the indexed properties do not have the same signatures as the bean properties. This would cause the BeanProperty constructor that did the initialization to throw a BeanException stating that the property didn't exist even though it did.

For this reason, the initialize method should be used to do all the initialization.

Throws:

BeanException - If there was any errors during initialization

getPropertyName

public String getPropertyName()

Gets the name of the property. If this is a simple BeanProperty, than the name is just the name of the property.

For BeanProperty
getName() -> name

For IndexedBeanProperty
getFoo(index) -> foo

For NestedBeanProperty
getFoo().getBar().getName() -> foo.bar.name

New sub-classes can override this method, but it is advisable to use the default version because it returns the property name that was used during construction.

NOTE: If a sub-classes uses the default constructor and does not make use of the propertyName member of this class, then this method should be overridden (if applicable).

Returns:

The name of the property

getPropertyType

public Class getPropertyType()

Gets the type of the property. If this is a simple BeanProperty, than the type is the type of the property method.

For BeanProperty and IndexedBeanProperty
public String getName() {} -> java.lang.String

For NestedBeanProperty, this method returns the type of the last property in the nesting.
i.e. getFoo().getBar().getName() and public String getName() {} -> java.lang.String

Returns:

The type of the property

getFullName

public String getFullName()

Gets the full name of the property. This is most useful for sub-classes because it allows them to specify a custom name for the property rather than using the propertyName member variable. The default implementation here simply returns the propertyName member variable.

Returns:

The full name of the property, which is usually just the propertyName member variable, but sub-classes can override this method to change the name however they see fit.

getBeanClass

public Class getBeanClass()

Returns the class of the bean that this property is contained in

instantiate

public Object instantiate()
                   throws BeanException

Creates an instance of the class that this BeanProperty's property is contained in.

Returns:

A new instance of the class

Throws:

BeanException - If there was a problem instantiating the class

addPropertyListener

public void addPropertyListener(PropertyListener listener)

Adds a property listener to the list of listeners for this property. This method is not thread safe. If you need to have a thread safe implementation, please use one of the Synchronized sub-classes.

Parameters:

listener - The new property listener to add to the list

removePropertyListener

public void removePropertyListener(PropertyListener listener)

Removes the given property listener from the list of property listeners. This method is not thread safe. If you need to have a thread safe implementation, please use one of the Synchronized sub-classes.

Parameters:

listener - The property listener to remove from the list

getPropertyListeners

public Iterator getPropertyListeners()

Returns an iterator for the list of property listeners. This method is not thread safe. If you need to have a thread safe implementation, please use one of the Synchronized sub-classes.

Returns:

An interator for the list of property listeners

hasPropertyListeners

public boolean hasPropertyListeners()

Returns true if there are any property listeners for this property. This method is not thread safe. If you need to have a thread safe implementation, please use one of the Synchronized sub-classes.

Returns:

True or false depending on if there are property listeners or not

addConversionListener

public void addConversionListener(ConversionListener listener)

Adds a conversion listener to the list of listeners for this property. This method is not thread safe. If you need to have a thread safe implementation, please use one of the Synchronized sub-classes.

Parameters:

listener - The new conversion listener to add to the list

removeConversionListener

public void removeConversionListener(ConversionListener listener)

Removes the given conversion listener from the list of conversion listeners. This method is not thread safe. If you need to have a thread safe implementation, please use one of the Synchronized sub-classes.

Parameters:

listener - The conversion listener to remove from the list

getConversionListeners

public Iterator getConversionListeners()

Returns an iterator for the list of conversion listeners. This method is not thread safe. If you need to have a thread safe implementation, pleas use one of the Synchronized sub-classes.

hasConversionListeners

public boolean hasConversionListeners()

Returns true if there are any conversion listeners for this property. This method is not thread safe. If you need to have a thread safe implementation, please use one of the Synchronized sub-classes.

getPropertyValue

public abstract Object getPropertyValue(Object bean)
                                 throws BeanException

Gets the the property value. Sub-classes must implement this method.

Parameters:

bean - The bean instance to set the property on

Throws:

BeanException - If there was an error getting the JavaBean property or the getter/is method threw a checked Exception

setPropertyValue

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

Sets the the property value. Sub-classes must implement this method.

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

TypeConversionException - If there was an error attempting to auto convert the value being set

setPropertyValue

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

Sets the value of the bean property to the given value. This value is set without doing any conversion. This method is the same as calling the other setPropertyValue method with the convert parameter set to false

Parameters:

bean - The instance of the JavaBean to set the property on

value - The value to set the property to

Throws:

BeanException - If there was an error setting the JavaBean property or the setter method threw a checked Exception

convertParameter

protected Object convertParameter(Object parameter,
                                  Object bean)
                           throws TypeConversionException

Converts the given value parameter (parameter) to a type that is accepted by the set method of this property.

Parameters:

parameter - The value parameter object to convert

bean - The bean object that this parameter object is being converted for and is usually used when firing events

Returns:

The value parameter converted to the correct type

Throws:

TypeConversionException - If there was a problem converting the parameter

firePropertyEvent

protected void firePropertyEvent(int type,
                                 Object oldValue,
                                 Object newValue,
                                 Object bean,
                                 int index)
                          throws BeanException

Fires off a property event using the type constants of this class and the parameters given. Most of these parameters are used by all bean properties, except the index parameter which is only used with indexed properties.

Parameters:

type - The type of event to fire. Must be either the GET or SET constants of this class

oldValue - The old value of the property, which is the same as the newValue for all events except the SET event

newValue - The new value of the property, which is normally the current value of the property except for the SET event

bean - The bean object that the event is occurring for

index - The index if this is an IndexedBeanProperty (use -1 for all other types of properties)

Throws:

IllegalArgumentException - If the type is not a valid property event type and there are listeners

fireConversionEvent

protected void fireConversionEvent(int type,
                                   Object oldValue,
                                   Object newValue,
                                   Object bean)

Fires off a conversion event using the type constants of this class and the parameters given.

Parameters:

type - The type of event to fire. Must be either the PRE_CONVERT, POST_CONVERT or BAD_CONVERT constants of this class

oldValue - The old value of the property, which is the parameter value before conversion

newValue - The new value of the property, which is the parameter value after conversion unless this is called for the PRE_CONVERT and BAD_CONVERT events and then it should be the same as the oldValue

bean - The bean object that the event is occurring for

Throws:

IllegalArgumentException - If the type is not a valid conversion event type and there are listeners