javax.beans.binding
Class Binding

java.lang.Object
  javax.beans.binding.Binding

public class Binding
extends java.lang.Object

Binding represents a binding between two properties of two objects. Once bound, the two properties of the two objects are kept in sync.

The following example illustrates binding the "name" property of a Customer to the "text" property of a JTextField:

   class Customer {
     public void setName(String text);
     public String getName();
   }
   JTextField textField = ...;
   Customer customer = ...;
   new Binding(customer, "${name}", textField, "text").bind();
 

The properties of the two objects are identified as a dot separated list of property names resolved using reflection. For example, the path "manager.firstName" is equivalent to target.getManager().getFirstName(). Binding makes use of PropertyResolver to resolve the value for a property; refer to it for information on the path syntax.

To keep the two properties of the two objects in sync, listeners are installed on all objects along the paths. Any time an object along the path changes, the other object is updated. For example, if the source path is "manager.firstName", and either the "manager" or "firstName" property changes, the the target property is updated. There is one exception to this; when initially bound if the target path is incomplete, changes in the target path only update the source if getValueForIncompleteTargetPath returns non-null, otherwise, once the target path becomes complete it's value is reset from that of the source.

Data flowing from the source to the target, and from target to source, are passed to a BindingConverter. A BindingConverter is used to convert the value in some way. For example, you might bind the background color of a JTextField to a string property with a BindingConverter that can convert the String to a Color.

If a BindingValidator is specified, all changes from the target are passed to the BindingValidator. The BindingValidator is used for testing the validity of a change, as well as for specifying if the change should be propagated back to the source.

A Binding also specifies an update strategy for the binding. The update strategy dictates how the source and target properties are kept in sync.

The source and target are typically non-null values. An exception to this is for children bindings, in which case the parent binding supplies the two endpoints.

Once a Binding is bound it can not be mutated. All setter methods of this class throw an IllegalStateException if invoked on a bound Binding.

Often times it is not possible to evaluate the path of the source or target; this is referred to as an incomplete path. For example, if source.getManager() returns null when evaluating the path "manager.firstName", then the path is incomplete. Binding provides the setValueForIncompleteSourcePath and setValueForIncompleteTargetPath methods that allow you to specify the value to use when the source or target path is incomplete. If a property along the source or target path changes, and the corresponding value for incomplete path property is non-null, then it is applied to the opposite object, otherwise the opposite property is not updated. For example, if the source path is "manager.firstName", the target path is "text", and the "manager" property of the source is initially null, then if setValueForIncompleteSourcePath is non-null, it is set on the target, otherwise the target is not updated.

See Also:

SwingBindingSupport

Nested Class Summary

class	Binding.BindingController BindingController is used by BindingTargets to control the binding.
static class	Binding.Parameter<T> Parameter is used to provide additional information to configure a specific binding.
static class	Binding.UpdateStrategy Enumeration of the possible ways the source and target properties can be kept in sync.
static class	Binding.ValueState Enumeration of the possible states the source and target may be in.

Constructor Summary

Binding()
Creates a Binding.

Binding(java.lang.Object source, java.lang.String sourcePath, java.lang.Object target, java.lang.String targetPath, java.lang.Object... args)
Creates a Binding.

Binding(java.lang.String sourcePath, java.lang.String targetPath, java.lang.Object... args)
Creates a Binding.

Method Summary

void	addBinding(Binding binding) Adds a Binding as a child of this Binding.
Binding	addBinding(java.lang.String sourcePath, java.lang.String targetPath, java.lang.Object... args) Creates and adds a Binding as a child of this Binding.
void	addBindingListener(BindingListener listener) Adds a BindingListener to this Binding.
void	bind() Realizes this Binding.
java.util.List<Binding>	getBindings() Returns a list of the child Bindings of this Binding.
BindingContext	getContext() Returns the BindingContext this Binding is contained in.
BindingConverter	getConverter() Returns the BindingConverter used to convert values.
ListCondenser	getListCondenser() Returns the ListCondenser that is used to condense a list into a single value.
java.lang.Object	getNullSourceValue() Returns the value to use if the value of the property of the source is null.
java.lang.Object	getNullTargetValue() Returns the value to use if the value of the property of the target is null.
java.lang.Object	getSource() Returns the source of the binding.
java.lang.String	getSourcePath() Returns the path to the property of the source to bind to.
BindingConverter	getSourceToTargetConverter(java.lang.Class<?> sourceType, java.lang.Object sourceValue, java.lang.Class<?> targetType) Returns the BindingConverter used to convert the source value to the target value.
Binding.ValueState	getSourceValueState() Returns the value state of the source.
java.lang.Object	getTarget() Returns the target of the binding.
java.lang.String	getTargetPath() Returns the path to the property of the target to bind to as a PropertyPath.
BindingConverter	getTargetToSourceConverter(java.lang.Class<?> targetType, java.lang.Object targetValue, java.lang.Class<?> sourceType) Returns the BindingConverter used to convert the target value to the source value.
Binding.ValueState	getTargetValueState() Returns the value state of the target.
Binding.UpdateStrategy	getUpdateStrategy() Returns the update strategy.
BindingValidator	getValidator() Returns the BindingValidator used to validate changes originating from the target.
<T> T	getValue(Binding.Parameter<T> key, T defaultValue) Returns the value for the specified parameter.
java.lang.Object	getValueForIncompleteSourcePath() Returns the value to use if the source path can not be completely evaluated.
java.lang.Object	getValueForIncompleteTargetPath() Returns the value to use if the target path can not be completely evaluated.
boolean	isBound() Returns true if currently bound.
void	removeBinding(Binding binding) Removes a previously added Binding.
void	removeBindingListener(BindingListener listener) Removes a BindingListener from this Binding.
void	setConverter(BindingConverter converter) Sets the BindingConverter used to convert values.
void	setListCondenser(ListCondenser condenser) Sets the ListCondenser that is used to condense a list into a single value.
void	setNullSourceValue(java.lang.Object value) Sets the value to use if the value of the property of the source is null.
void	setNullTargetValue(java.lang.Object value) Sets the value to use if the value of the property of the target is null.
void	setSource(java.lang.Object source) Sets the source of the binding.
void	setSourcePath(java.lang.String path) Sets the path to the property of the source to bind to.
void	setSourceValueFromTargetValue() Sets the property of the source from that of the target.
void	setTarget(java.lang.Object target) Sets the target of the binding.
void	setTargetPath(java.lang.String path) Sets the path to the property of the target to bind to.
void	setTargetValueFromSourceValue() Sets the property of the target from that of the source.
void	setUpdateStrategy(Binding.UpdateStrategy strategy) Sets the update strategy for the binding.
void	setValidator(BindingValidator validator) Sets the BindingValidator used to validate changes originating from the target.
<T> void	setValue(Binding.Parameter<T> key, T value) Sets a parameter for the binding.
void	setValueForIncompleteSourcePath(java.lang.Object value) Sets the value to use if the source path can not be completely evaluated.
void	setValueForIncompleteTargetPath(java.lang.Object value) Sets the value to use if the target path can not be completely evaluated.
java.lang.String	toString() Returns a string representing the state of this binding.
void	unbind() Unrealizes this binding.

Methods inherited from class java.lang.Object

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

Constructor Detail

Binding

public Binding()

Creates a Binding.

Binding

public Binding(java.lang.String sourcePath,
               java.lang.String targetPath,
               java.lang.Object... args)

Creates a Binding. See SwingBindingSupport for examples.

Parameters:

sourcePath - path to the property of the source

targetPath - path to the property of the target

args - alternating set of key/value pairs where each even numbered entry is of type Paramater, and the following value is of a type specified by the Parameter

Throws:

java.lang.NullPointerException - if one of the even entries in args is null

java.lang.ClassCastException - if one of the even entries in args is not a Parameter, or one of the odd entries is not of a type identified by the preceeding Parameter entry

java.lang.IllegalArgumentException - if args is odd

Binding

public Binding(java.lang.Object source,
               java.lang.String sourcePath,
               java.lang.Object target,
               java.lang.String targetPath,
               java.lang.Object... args)

Creates a Binding. See SwingBindingSupport for examples.

Parameters:

source - the source of the binding

sourcePath - path to the property of the source

target - the target of the binding

targetPath - path to the paroperty of the target

args - alternating set of key/value pairs; each even numbered entry is of type Parameter, and the following value is of a type specified by the Parameter

Throws:

java.lang.NullPointerException - if one of the even entries in args is null

java.lang.ClassCastException - if one of the even entries in args is not a Parameter, or one of the odd entries is not of a type identified by the preceeding Parameter entry

java.lang.IllegalArgumentException - if args is odd

Method Detail

setSource

public final void setSource(java.lang.Object source)

Sets the source of the binding.

Parameters:

source - the source of the binding

Throws:

java.lang.IllegalStateException - if bound

getSource

public final java.lang.Object getSource()

Returns the source of the binding.

Returns:

the source of the binding

setSourcePath

public final void setSourcePath(java.lang.String path)

Sets the path to the property of the source to bind to.

Parameters:

path - path to the property of the source to bind to

Throws:

java.lang.IllegalStateException - if bound

getSourcePath

public final java.lang.String getSourcePath()

Returns the path to the property of the source to bind to.

Returns:

the path to the property of the source to bind to

setTarget

public final void setTarget(java.lang.Object target)

Sets the target of the binding.

Parameters:

target - the target of the binding

Throws:

java.lang.IllegalStateException - if bound

getTarget

public final java.lang.Object getTarget()

Returns the target of the binding.

Returns:

the target of the binding

setTargetPath

public final void setTargetPath(java.lang.String path)

Sets the path to the property of the target to bind to.

Parameters:

path - path to the property of the target to bind to

Throws:

java.lang.IllegalStateException - if bound

java.lang.IllegalArgumentException - if path is non-null and empty

getTargetPath

public final java.lang.String getTargetPath()

Returns the path to the property of the target to bind to as a PropertyPath.

Returns:

path to the property of the target to bind to

setValidator

public final void setValidator(BindingValidator validator)

Sets the BindingValidator used to validate changes originating from the target.

Parameters:

validator - the BindingValidator

Throws:

java.lang.IllegalStateException - if bound

getValidator

public final BindingValidator getValidator()

Returns the BindingValidator used to validate changes originating from the target.

Returns:

the validator

setConverter

public final void setConverter(BindingConverter converter)

Sets the BindingConverter used to convert values. BindingConverter is only used to convert non-null values.

Parameters:

converter - the BindingConverter

Throws:

java.lang.IllegalStateException - if bound

getConverter

public final BindingConverter getConverter()

Returns the BindingConverter used to convert values.

Returns:

the BindingConverter

setValueForIncompleteSourcePath

public final void setValueForIncompleteSourcePath(java.lang.Object value)

Sets the value to use if the source path can not be completely evaluated.

Parameters:

value - the value

getValueForIncompleteSourcePath

public final java.lang.Object getValueForIncompleteSourcePath()

Returns the value to use if the source path can not be completely evaluated.

Returns:

the value

setValueForIncompleteTargetPath

public final void setValueForIncompleteTargetPath(java.lang.Object value)

Sets the value to use if the target path can not be completely evaluated.

Parameters:

value - the value

getValueForIncompleteTargetPath

public final java.lang.Object getValueForIncompleteTargetPath()

Returns the value to use if the target path can not be completely evaluated.

Returns:

the value

setNullSourceValue

public final void setNullSourceValue(java.lang.Object value)

Sets the value to use if the value of the property of the source is null.

Parameters:

value - the value to use if the value of the property of the source is null

Throws:

java.lang.IllegalStateException - if bound

getNullSourceValue

public final java.lang.Object getNullSourceValue()

Returns the value to use if the value of the property of the source is null.

Returns:

the value to use if the value of the property of the source is null

setNullTargetValue

public final void setNullTargetValue(java.lang.Object value)

Sets the value to use if the value of the property of the target is null.

Parameters:

value - the value to use if the value of the property of the target is null

Throws:

java.lang.IllegalStateException - if bound

getNullTargetValue

public final java.lang.Object getNullTargetValue()

Returns the value to use if the value of the property of the target is null.

Returns:

the value to use if the value of the property of the target is null

setUpdateStrategy

public final void setUpdateStrategy(Binding.UpdateStrategy strategy)

Sets the update strategy for the binding. The default is READ_WRITE.

Parameters:

strategy - the update strategy

Throws:

java.lang.IllegalArgumentException - if strategy is null

java.lang.IllegalStateException - if bound

getUpdateStrategy

public final Binding.UpdateStrategy getUpdateStrategy()

Returns the update strategy.

Returns:

update strategy

setListCondenser

public final void setListCondenser(ListCondenser condenser)

Sets the ListCondenser that is used to condense a list into a single value.

Parameters:

condenser - the condenser

getListCondenser

public final ListCondenser getListCondenser()

Returns the ListCondenser that is used to condense a list into a single value.

Returns:

the condenser

setValue

public final <T> void setValue(Binding.Parameter<T> key,
                               T value)

Sets a parameter for the binding. If value is null, the entry is removed. This method is used to specify target specific properties. For example, the following specifies the "text" property of a JTextComponent should change as you type:

   binding.setValue(SwingBindingSupport.TextChangeStrategyParameter,
                    TextChangeStrategy.CHANGE_ON_TYPE);
 

Parameters:

key - the key

value - the value

Throws:

java.lang.ClassCastException - if value is not of the type defined by key

java.lang.NullPointerException - if key is null

java.lang.IllegalStateException - if bound

getValue

public final <T> T getValue(Binding.Parameter<T> key,
                            T defaultValue)

Returns the value for the specified parameter.

Parameters:

key - the key to obtain the value for

defaultValue - the value to return if setValue has not been invoked with the specified key

Returns:

the value for the specified key

Throws:

java.lang.NullPointerException - if key is null

getSourceToTargetConverter

public BindingConverter getSourceToTargetConverter(java.lang.Class<?> sourceType,
                                                   java.lang.Object sourceValue,
                                                   java.lang.Class<?> targetType)

Returns the BindingConverter used to convert the source value to the target value.

Parameters:

sourceType - the type of the source property

sourceValue - the value of the source

targetType - the type of the target property

getTargetToSourceConverter

public BindingConverter getTargetToSourceConverter(java.lang.Class<?> targetType,
                                                   java.lang.Object targetValue,
                                                   java.lang.Class<?> sourceType)

Returns the BindingConverter used to convert the target value to the source value.

Parameters:

targetType - the type of the target property

targetValue - the value of the target

sourceType - the type of the source property

getContext

public final BindingContext getContext()

Returns the BindingContext this Binding is contained in.

Returns:

the BindingContext.

isBound

public final boolean isBound()

Returns true if currently bound.

Returns:

true if currently bound

bind

public final void bind()

Realizes this Binding.

Throws:

java.lang.IllegalStateException - if already bound, or the source or target is null

PropertyResolverException - if PropertyResolver throws an exception; refer to PropertyResolver for the conditions under which an exception is thrown

java.lang.IllegalArgumentException - if the child bindings do not contain the expected information for the target

unbind

public final void unbind()

Unrealizes this binding.

Throws:

java.lang.IllegalStateException - if already bound

PropertyResolverException - if PropertyResolver throws an exception; refer to PropertyResolver for the conditions under which an exception is thrown

setSourceValueFromTargetValue

public final void setSourceValueFromTargetValue()

Sets the property of the source from that of the target.

Throws:

PropertyResolverException - if PropertyResolver throws an exception; refer to PropertyResolver for the conditions under which an exception is thrown

java.lang.IllegalStateException - if not bound

setTargetValueFromSourceValue

public final void setTargetValueFromSourceValue()

Sets the property of the target from that of the source.

Throws:

PropertyResolverException

java.lang.IllegalStateException - if not bound

addBindingListener

public void addBindingListener(BindingListener listener)

Adds a BindingListener to this Binding.

Parameters:

listener - the BindingListener to add

removeBindingListener

public void removeBindingListener(BindingListener listener)

Removes a BindingListener from this Binding.

Parameters:

listener - the BindingListener to remove

getTargetValueState

public final Binding.ValueState getTargetValueState()

Returns the value state of the target.

Returns:

the value state of the target

getSourceValueState

public final Binding.ValueState getSourceValueState()

Returns the value state of the source.

Returns:

the value state of the source

addBinding

public final Binding addBinding(java.lang.String sourcePath,
                                java.lang.String targetPath,
                                java.lang.Object... args)

Creates and adds a Binding as a child of this Binding.

Parameters:

sourcePath - path to the property of the source

targetPath - path to the paroperty of the target

args - alternating set of key/value pairs where each even numbered entry is of type Parameter, and the following value is of a type specified by the Parameter

Throws:

java.lang.NullPointerException - if one of the even entries is null

java.lang.ClassCastException - if one of the even entries is not a Parameter, or one of the odd entries is not of a type identified by the preceeding Parameter entry

addBinding

public final void addBinding(Binding binding)

Adds a Binding as a child of this Binding.

Parameters:

binding - the Binding to add as a child

Throws:

java.lang.IllegalArgumentException - if binding has already been added to another Binding

java.lang.IllegalStateException - if bound

java.lang.NullPointerException - if binding is null

removeBinding

public final void removeBinding(Binding binding)

Removes a previously added Binding.

Parameters:

binding - the Binding to remove

Throws:

java.lang.NullPointerException - if binding is null

java.lang.IllegalArgumentException - if binding has not been added to this Binding

java.lang.IllegalStateException - if bound

getBindings

public final java.util.List<Binding> getBindings()

Returns a list of the child Bindings of this Binding. The returned list is unmodifiable.

Returns:

a list of the child Bindings

toString

public java.lang.String toString()

Returns a string representing the state of this binding. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of this binding