Class ELProperty<S,V>
- java.lang.Object
-
- org.jdesktop.beansbinding.Property<S,V>
-
- org.jdesktop.beansbinding.PropertyHelper<S,V>
-
- org.jdesktop.beansbinding.ELProperty<S,V>
-
- Type Parameters:
S
- the type of source object that thisELProperty
operates onV
- the type of value that thisELProperty
represents
public final class ELProperty<S,V> extends PropertyHelper<S,V>
An implementation ofProperty
that allows Java Beans properties of source objects to be addressed using a simple dot-separated path syntax within an EL expression. For example, to create a simple property representing aPerson
bean's mother'sfirstName
:
Note thatELProperty.create("${mother.firstName}")
BeanProperty
is more suitable for such a simple property.To create a property representing the concatenation of a
Person
bean'sfirstName
andlastName
properties:ELProperty.create("${firstName} ${lastName}");
To create a property that is
true
orfalse
depending on whether or not thePerson's
mother is older than 65:BeanProperty.create("${mother.age > 65}");
Paths specified in the EL expressions are resolved against the source object with which the property is being used.
An instance of
ELProperty
is immutable and can be used with different source objects. When aPropertyStateListener
is added to anELProperty
for a given source object, theELProperty
starts listening to all objects along the paths in the expression (based on that source object) for change notification, and reflects any changes by notifying the listener associated with the property for that source object. So, for example, if aPropertyStateListener
is added to the property from the second example above for an objectDuke
, thePropertyStateListener
is notified when eitherDuke's
first name changes, or his last name changes. If a listener is added to the property from the third example, thePropertyStateListener
is notified when either a change inDuke's
mother orDuke's
mother'sage
results in a change to the result of the expression.It is very important that any bean properties addressed via a
ELProperty
follow the Java Beans specification, including firing property change notification; otherwise,ELProperty
cannot respond to change. As some beans outside of your control may not follow the Java Beans specification,ELProperty
always checks theBeanAdapterFactory
to see if a delegate provider has been registered to provide a delegate bean to take the place of an object for a given property. See the ext package level documentation for more details.When there are no
PropertyStateListeners
installed on anELProperty
for a given source, allProperty
methods act by evaluating the full expression, thereby always providing "live" information. On the contrary, when there arePropertyStateListeners
installed, the beans along the paths, and the final value, are cached, and only updated upon notification of change from a bean. Again, this makes it very important that any bean property that could change along the path fires property change notification. Note: ThesetValue
method is currently excluded from the previous assertion; with the exception of checking the cache to determine if the property is writeable, it always evaluates the entire expression. The result of this is that when working with paths containing beans that don't fire property change notification, you can end up with all methods (includinggetValue
) working on cached information, butsetValue
working on the live expression. There are plans to resolve this inconsistency in a future release.Readability of an
ELProperty
for a given source is defined as follows: AnELProperty
is readable for a given source if and only if the following is true for all paths used in the expression: a) each bean the path, starting with the source, defines a Java Beans getter method for the the property to be read on it AND b) each bean in the path, starting with the source and ending with the bean on which we read the final property, isnon-null
. The final value beingnull
does not affect the readability.So, in the third example given earlier, the
ELProperty
is readable forDuke
when all of the following are true:Duke
defines a Java Beans getter formother
,Duke's mother
defines a Java Beans getter forage
,Duke
isnon-null
,Duke's mother
isnon-null
. TheELProperty
is therefore unreadable when any of the following is true:Duke
does not define a Java Beans getter formother
,Duke's mother
does not define a Java Beans getter forage
,Duke
isnull
,Duke's mother
isnull
.Writeability of an
ELProperty
for a given source is defined as follows: AnELProperty
is writeable for a given source if and only if a) the EL expression itself is not read-only (ie. it is a simple expression involving one path such as "${foo.bar.baz}" AND b) each bean in the path, starting with the source and ending with the bean on which we set the final property, defines a Java Beans getter method for the property to be read on it AND c) the bean on which we set the final property defines a Java Beans setter for the property to be set on it AND d) each bean in the path, starting with the source and ending with the bean on which we set the final property, isnon-null
. The final value beingnull
does not affect the writeability.So in the first example given earlier (a simple path), the
ELProperty
is writeable forDuke
when all of the following are true:Duke
defines a Java Beans getter formother
,Duke's mother
defines a Java Beans setter forfirstName
,Duke
isnon-null
,Duke's mother
isnon-null
. TheELProperty
is therefore unreadable when any of the following is true:Duke
does not define a Java Beans getter formother
,Duke's mother
does not define a Java Beans setter forfirstName
,Duke
isnull
,Duke's mother
isnull
. The second and third examples above both represent read-only ELExpressions and are therefore unwritable.In addition to working on Java Beans properties, any object in the paths can be an instance of
Map
. In this case, theMap's get
method is used with the property name as the getter, and theMap's put
method is used with the property name as the setter.ELProperty
can only respond to changes inMaps
if they are instances ofObservableMap
.Some methods in this class document that they can throw
PropertyResolutionException
if an exception occurs while trying to evaluate the expression. The throwing of this exception represents an abnormal condition and if listeners are installed for the given source object, leaves theELProperty
in an inconsistent state for that source object. AnELProperty
should not be used again for that same source object after such an exception without first removing all listeners associated with theELProperty
for that source object.
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static <S,V>
ELProperty<S,V>create(java.lang.String expression)
Creates an instance ofELProperty
for the given expression.static <S,V>
ELProperty<S,V>create(Property<S,?> baseProperty, java.lang.String expression)
Creates an instance ofELProperty
for the given base property and expression.V
getValue(S source)
Returns the value of thisProperty
for the given source.java.lang.Class<? extends V>
getWriteType(S source)
Returns the type of object that is suitable for setting as the value of thisProperty
by calls tosetValue
.boolean
isReadable(S source)
Returns whether or not theProperty
is readable for the given source.boolean
isWriteable(S source)
Returns whether or not theProperty
is writeable for the given source.protected void
listeningStarted(S source)
Called when thisPropertyHelper
changes from having no listeners installed for the given source object to having listeners installed for the given source object.protected void
listeningStopped(S source)
Called when thisPropertyHelper
changes from having listeners installed for the given source object to having no listeners installed for the given source object.void
setValue(S source, V value)
Sets the value of thisProperty
for the given source.java.lang.String
toString()
Returns a string representation of theELProperty
.-
Methods inherited from class org.jdesktop.beansbinding.PropertyHelper
addPropertyStateListener, firePropertyStateChange, getPropertyStateListeners, isListening, removePropertyStateListener
-
-
-
-
Method Detail
-
create
public static final <S,V> ELProperty<S,V> create(java.lang.String expression)
Creates an instance ofELProperty
for the given expression.- Parameters:
expression
- the expression- Returns:
- an instance of
ELProperty
for the given expression - Throws:
java.lang.IllegalArgumentException
- if the path is null or emptyPropertyResolutionException
- if there's a problem with the expression
-
create
public static final <S,V> ELProperty<S,V> create(Property<S,?> baseProperty, java.lang.String expression)
Creates an instance ofELProperty
for the given base property and expression. The expression is relative to the value of the base property.- Parameters:
baseProperty
- the base propertyexpression
- the expression- Returns:
- an instance of
ELProperty
for the given base property and expression - Throws:
java.lang.IllegalArgumentException
- if the path is null or emptyPropertyResolutionException
- if there's a problem with the expression
-
getWriteType
public java.lang.Class<? extends V> getWriteType(S source)
Returns the type of object that is suitable for setting as the value of thisProperty
by calls tosetValue
.See the class level documentation for the definition of writeability.
- Specified by:
getWriteType
in classPropertyHelper<S,V>
- Parameters:
source
- the source object on which to operate- Returns:
- the type of object suitable for setting as the value
- Throws:
java.lang.UnsupportedOperationException
- if theProperty
is not writeable for the given sourcePropertyResolutionException
- if an exception occurs while evaluating the expression- See Also:
setValue(S, V)
,isWriteable(S)
-
getValue
public V getValue(S source)
Returns the value of thisProperty
for the given source.See the class level documentation for the definition of readability.
- Specified by:
getValue
in classPropertyHelper<S,V>
- Parameters:
source
- the source object on which to operate- Returns:
- the value of this
Property
for the given source - Throws:
java.lang.UnsupportedOperationException
- if theProperty
is not readable for the given sourcePropertyResolutionException
- if an exception occurs while evaluating the expression- See Also:
isReadable(S)
-
setValue
public void setValue(S source, V value)
Sets the value of thisProperty
for the given source.See the class level documentation for the definition of writeability.
- Specified by:
setValue
in classPropertyHelper<S,V>
- Parameters:
source
- the source object on which to operatevalue
- the new value for theProperty
- Throws:
java.lang.UnsupportedOperationException
- if theProperty
is not writeable for the given sourcePropertyResolutionException
- if an exception occurs while evaluating the expression- See Also:
isWriteable(S)
,getWriteType(S)
-
isReadable
public boolean isReadable(S source)
Returns whether or not theProperty
is readable for the given source.See the class level documentation for the definition of readability.
- Specified by:
isReadable
in classPropertyHelper<S,V>
- Parameters:
source
- the source object on which to operate- Returns:
- whether or not the
Property
is readable for the given source. - Throws:
java.lang.UnsupportedOperationException
PropertyResolutionException
- if an exception occurs while evaluating the expression- See Also:
isWriteable(S)
-
isWriteable
public boolean isWriteable(S source)
Returns whether or not theProperty
is writeable for the given source.See the class level documentation for the definition of writeability.
- Specified by:
isWriteable
in classPropertyHelper<S,V>
- Parameters:
source
- the source object on which to operate- Returns:
- whether or not the
Property
is writeable for the given source. - Throws:
java.lang.UnsupportedOperationException
PropertyResolutionException
- if an exception occurs while evaluating the expression- See Also:
isReadable(S)
-
listeningStarted
protected final void listeningStarted(S source)
Description copied from class:PropertyHelper
Called when thisPropertyHelper
changes from having no listeners installed for the given source object to having listeners installed for the given source object. This is the ideal time for subclasses to install any listeners needed to track change on the source object.- Overrides:
listeningStarted
in classPropertyHelper<S,V>
- See Also:
PropertyHelper.listeningStopped(S)
-
listeningStopped
protected final void listeningStopped(S source)
Description copied from class:PropertyHelper
Called when thisPropertyHelper
changes from having listeners installed for the given source object to having no listeners installed for the given source object. This is the ideal time for subclasses to remove any listeners that they've installed to track changes on the source object.- Overrides:
listeningStopped
in classPropertyHelper<S,V>
- See Also:
PropertyHelper.listeningStopped(S)
-
toString
public java.lang.String toString()
Returns a string representation of theELProperty
. This method is intended to be used for debugging purposes only, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not benull
.- Overrides:
toString
in classjava.lang.Object
- Returns:
- a string representation of this
ELProperty
-
-