org.joda.property
Interface Property

All Superinterfaces:

ModelElement, java.io.Serializable

All Known Subinterfaces:

BooleanicProperty, BooleanPrimitiveProperty, BooleanProperty, ClassProperty, CollectionProperty, DataListProperty, DataMapProperty, DataProperty, DateProperty, DateTimeProperty, DecimalProperty, DoublePrimitiveProperty, DoubleProperty, InstantProperty, IntegerPrimitiveProperty, IntegerProperty, LinkingProperty, LinkListProperty, LinkMapProperty, LinkProperty, ListProperty, LocaleProperty, LongPrimitiveProperty, LongProperty, MapProperty, NumericProperty, ObjectProperty, Property.Internal, StringProperty, TimeProperty

All Known Implementing Classes:

AbstractBooleanicProperty, AbstractListProperty, AbstractMapProperty, AbstractNumericProperty, AbstractProperty, DefaultBooleanPrimitiveProperty, DefaultBooleanProperty, DefaultClassProperty, DefaultDataListProperty, DefaultDataMapProperty, DefaultDateProperty, DefaultDateTimeProperty, DefaultDecimalProperty, DefaultDoublePrimitiveProperty, DefaultDoubleProperty, DefaultIntegerPrimitiveProperty, DefaultIntegerProperty, DefaultLinkListProperty, DefaultLinkMapProperty, DefaultLinkProperty, DefaultLocaleProperty, DefaultLongPrimitiveProperty, DefaultLongProperty, DefaultObjectProperty, DefaultStringProperty, DefaultTimeProperty

public interface Property

extends ModelElement

Property defines the concept of a property on a Bean. This is the principal interface for properties. Applications will use generally use one of the type specific subinterfaces in their code, such as StringProperty or BooleanProperty.

A Property has the ability to be changed from modifiable to unmodifiable dynamically. This can provide a weak form of the const keyword in C.

A Property has methods to support event listeners. Events will be sent every time the value of the property is changed. Note that in order for this to work all updates must go through the methods on the Property object. When this is not the case, the event must be fired manually.

A Property contains a Map of String attributes. This map allows additional arbitrary data to be attached to any property. This corresponds to the XML attribute concept. One use for attributes is to attach an error code to the property which caused the error during validation.

Author:

Stephen Colebourne

Nested Class Summary

static interface

Property.Internal Interface used during the cloning process.

Method Summary

void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) Add a listener to the list of those receiving change events.
Bean	bean() Get the bean which owns this property.
boolean	equals(java.lang.Object anotherObject) Is this property equal to another property.
boolean	equalsValue(java.lang.Object anotherObject) Is this value of this property equal to another object.
void	firePropertyChange(java.lang.Object oldObject, java.lang.Object newObject) Fire a value changed event for the property.
java.lang.String	getContentName() Get the effective name of the property.
java.lang.Class	getContentType() Get the type of the objects contained in the property.
java.lang.String	getPropertyName() Get the name of this property in its parent.
java.lang.Class	getPropertyType() Get the type that this property is.
int	hashCode() Get the hashCode for the property in line with the definition of equals().
boolean	isModifiable() Check whether the object can currently be modified.
boolean	isNull() Test if the property currently set to null.
boolean	isReadOnly() Check whether the object is permanently read only.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Remove the specified listener from the list currently receiving change events.
void	set(java.lang.Object propertyValue) Set the property's value as an object.
void	setModifiable(boolean modifiable) Set the flag to indicate if the object is currently modifiable.
void	setReadOnly() Set the object to be permanently read only.
java.lang.Object	toObject() Get the property's value as an object.
java.lang.String	toString() Get a debugging string.

Methods inherited from interface org.joda.property.ModelElement

getAttribute, getAttributeCount, getAttributeMap, setAttribute

Method Detail

bean

public Bean bean()

Get the bean which owns this property.

Returns:

the bean

toObject

public java.lang.Object toObject()

Get the property's value as an object. The object type will be appropriate for the type of property. The object will either be immutable or a clone of the real object.

This method has strong semantics such that where a and b are properties of the same type, it must be true that:
b.set( a.toObject() ); a.equals(b);
In other words, the object contains all the data necessary to recreate the property's value.

Returns:

an Object representing the property's value

isNull

public boolean isNull()

Test if the property currently set to null. This will give better performance for some properties than testing toObject() == null.

Returns:

true if the property value is null

set

public void set(java.lang.Object propertyValue)

Set the property's value as an object. The object type should be appropriate for the type of property. If necessary, the object will be cloned before it is stored internally. Implementations will recognise as many types of object passed in as possible. Null should always be accepted, primitive types will be reset back to zero/false.

If a String is passed in, it can be parsed in various ways. If the results of toDataString() are passed in, it must reconstitute the original value.

Parameters:

propertyValue - an Object to set the property's value to

Throws:

java.lang.IllegalArgumentException - thrown if value unacceptable

isReadOnly

public boolean isReadOnly()

Check whether the object is permanently read only. If this is true, then the property can never be made to be modifiable.

Returns:

true if the property value can never be changed

setReadOnly

public void setReadOnly()

Set the object to be permanently read only. Once set the property can never be made to be modifiable again.

isModifiable

public boolean isModifiable()

Check whether the object can currently be modified. This may change during the lifetime of a property due to the setModifiable(boolean) and setReadOnly() method.

Returns:

true if the property value can currently be changed

setModifiable

public void setModifiable(boolean modifiable)

Set the flag to indicate if the object is currently modifiable.

Parameters:

modifiable - true if object should be modifiable

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Add a listener to the list of those receiving change events. No action occurs if null is passed in.

Parameters:

listener - a listener to add to the list

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Remove the specified listener from the list currently receiving change events. No action occurs if the listener is not in the list.

Parameters:

listener - a listener to remove from the list

firePropertyChange

public void firePropertyChange(java.lang.Object oldObject,
                               java.lang.Object newObject)

Fire a value changed event for the property. This method is rarely called by applications. Coded beans must call it in a set method.

getPropertyName

public java.lang.String getPropertyName()

Get the name of this property in its parent. The JavaBean style methods getFoo() and setFoo() will lead to a property name of 'foo' and so on.

Returns:

the name of the property

getPropertyType

public java.lang.Class getPropertyType()

Get the type that this property is. A method String getFoo() has a property type of String.class.

Returns:

the type of the property

getContentName

public java.lang.String getContentName()

Get the effective name of the property. This is the property name minus any suffix, such as 'List', 'Map or 'Link'.

Returns:

the effective name of the property

getContentType

public java.lang.Class getContentType()

Get the type of the objects contained in the property. For simple properties this is the same as getPropertyType, but for Collections and Maps, this is the type of each entry in the collection.

Returns:

the content type

equalsValue

public boolean equalsValue(java.lang.Object anotherObject)

Is this value of this property equal to another object. This will compare the value of the property to the passed in object. The passed in object will be type converted to the type of the property if possible (if that fails, false is returned). If the property value is null, then equalsValue(null) will return true.

For an IntegerProperty with the value 5:
property.equalsValue(new Integer(5)) == true
property.equalsValue(new Integer(3)) == false
property.equalsValue("5") == true
property.equalsValue("3") == false
property.equalsValue(new DateTime()) == false

Parameters:

anotherObject - another object to compare this one to

Returns:

true if the property values are equal

equals

public boolean equals(java.lang.Object anotherObject)

Is this property equal to another property. This will only compare the value of the property. All other fields are ignored.

Overrides:

equals in class java.lang.Object

Parameters:

anotherObject - another object to compare this one to

Returns:

true if the properties are equal

hashCode

public int hashCode()

Get the hashCode for the property in line with the definition of equals().

Overrides:

hashCode in class java.lang.Object

Returns:

a suitable hashcode

toString

public java.lang.String toString()

Get a debugging string. To get the data of the property in a structured format, use toDataString() where available.

Overrides:

toString in class java.lang.Object

Returns:

debugging string