javax.beans.binding
Class BindingContext

java.lang.Object
  javax.beans.binding.BindingContext

public class BindingContext
extends java.lang.Object

BindingContext manages a set of bindings.

BindingContext provides methods to bind and unbind the set of Bindings it contains. The following example illustrates adding a Binding to a BindingContext and binding it:

   BindingContext context = new BindingContext();
   context.addBinding(source, "${sourcePath}", target, "targetPath");
   context.bind();
 

BindingContext provides methods for tracking the state of the Bindings it contains. The getHasUncommittedValues method may be used to determine if any of the bound Bindings contained in a BindingContext have an uncommited value. Similarly, the hasInvalidValues method may be used to determine if any of Bindings are currently invalid. Both of these properties are bound; a PropertyChangeListener may be attached to the BindingContext to track when either property changes.

BindingContext also supports a BindingListener. BindingListeners are notified when conversion or validation of a Binding fails. BindingListener provides a convenient way to provide feedback to the user when an invalid value is input.

See Also:

Binding, BindingListener

Constructor Summary

BindingContext()
Creates a new BindingContext.

Method Summary

void	addBinding(Binding binding) Adds a Binding to this BindingContext.
Binding	addBinding(java.lang.Object source, java.lang.String sourcePath, java.lang.Object target, java.lang.String targetPath, java.lang.Object... args) Creates and adds Binding to this BindingContext.
void	addBindingListener(BindingListener listener) Adds a BindingListener to this BindingContext.
void	addFunction(java.lang.String prefix, java.lang.String localName, java.lang.reflect.Method m) Adds the specified method to the list functions available to the expression.
void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) Adds a PropertyChangeListener to this BindingContext.
void	addPropertyChangeListener(java.lang.String property, java.beans.PropertyChangeListener listener) Adds a PropertyChangeListener to this BindingContext.
void	addResolver(ELResolver resolver) Adds an ELResover to the list of resolvers used in resolving values.
void	bind() Binds the set of unbound Bindings that have been added to this BindingContext.
void	clearHasEditedTargetValues() Sets the hasEditedTargetValues property to false.
void	commitUncommittedValues() Commits any uncommited values in the Bindings managed by this BindingContext.
java.lang.Iterable<java.beans.FeatureDescriptor>	getFeatureDescriptors(java.lang.Object obj) Returns an iterator over the known FeatureDescriptors for the specified object.
boolean	getHasEditedTargetValues() Returns whether any of the Bindings contained in this BindingDescription have had the target value edited.
boolean	getHasInvalidValues() Returns true if any of the Bindings managed by this BindingContext have a target value state of INVALID.
boolean	getHasUncommittedValues() Returns true if any the Bindings managed by this BindingContext have a source or target value state of UNCOMMITTED.
BindingValidator	getValidator(Binding binding) Returns the BindingValidator for the specified Binding.
void	removeBinding(Binding binding) Returns a Binding.
void	removeBindingListener(BindingListener listener) Removes a BindingListener from this BindingContext.
void	removeFunction(java.lang.String prefix, java.lang.String localName, java.lang.reflect.Method m) Adds the specified method to the list functions available to the expression.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Removes a PropertyChangeListener from this BindingContext.
void	removePropertyChangeListener(java.lang.String property, java.beans.PropertyChangeListener listener) Removes a PropertyChangeListener from this BindingContext.
void	removeResolver(ELResolver resolver) Removes an ELResover from the list of resolvers used in resolving values.
java.lang.String	toString() Returns a string representing the state of this binding context.
void	unbind() Unbinds the set of Bindings that have been added to this BindingContext and bound.

Methods inherited from class java.lang.Object

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

Constructor Detail

BindingContext

public BindingContext()

Creates a new BindingContext.

Method Detail

clearHasEditedTargetValues

public void clearHasEditedTargetValues()

Sets the hasEditedTargetValues property to false. This is typically invoked after a save operation has done.

See Also:

getHasEditedTargetValues()

getHasEditedTargetValues

public boolean getHasEditedTargetValues()

Returns whether any of the Bindings contained in this BindingDescription have had the target value edited. This property is internally set to true when the target property of a Binding chanages. The value of this is set to false by invoking clarHasEditedTargetValues.

Returns:

whether any of the target properties have been changed

See Also:

clearHasEditedTargetValues()

addBinding

public void addBinding(Binding binding)

Adds a Binding to this BindingContext. The specified Binding must not be bound. Bindings are bound by invoking the bind method.

Parameters:

binding - the Binding to add, must be non-null

Throws:

java.lang.IllegalArgumentException - if binding is null

java.lang.IllegalStateException - if binding is bound, or has already been added

See Also:

bind()

addBinding

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

Creates and adds Binding to this BindingContext.

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

Returns:

the Binding

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

java.lang.IllegalArgumentException - if args is odd

removeBinding

public void removeBinding(Binding binding)

Returns a Binding.

Parameters:

binding - the Binding to remove

Throws:

java.lang.NullPointerException - if binding is null

java.lang.IllegalStateException - if binding is bound

java.lang.IllegalStateException - if binding has already been added

bind

public void bind()

Binds the set of unbound Bindings that have been added to this BindingContext.

Throws:

java.lang.IllegalStateException - if a binding added via addBinding has been bound

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

See Also:

unbind()

unbind

public void unbind()

Unbinds the set of Bindings that have been added to this BindingContext and bound.

Throws:

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

addBindingListener

public void addBindingListener(BindingListener listener)

Adds a BindingListener to this BindingContext.

Parameters:

listener - the BindingListener to add

removeBindingListener

public void removeBindingListener(BindingListener listener)

Removes a BindingListener from this BindingContext.

Parameters:

listener - the BindingListener to remove

getValidator

public BindingValidator getValidator(Binding binding)

Returns the BindingValidator for the specified Binding.

Parameters:

binding - the Binding to obtain the BindingValidator for

Returns:

the BindingValidator

Throws:

java.lang.NullPointerException - if binding is null

commitUncommittedValues

public void commitUncommittedValues()

Commits any uncommited values in the Bindings managed by this BindingContext. This is a convenience method that may be used to make sure all edited values are committed. This invokes setSourceValueFromTargetValue() on any Bindings managed by this BindingContext that have target value state of UNCOMMITTED.

Throws:

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

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Adds a PropertyChangeListener to this BindingContext.

Parameters:

listener - the PropertyChangeListener to add

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Removes a PropertyChangeListener from this BindingContext.

Parameters:

listener - the PropertyChangeListener to remove

addPropertyChangeListener

public void addPropertyChangeListener(java.lang.String property,
                                      java.beans.PropertyChangeListener listener)

Adds a PropertyChangeListener to this BindingContext.

Parameters:

property - the name of the property the PropertyChangeListener is interested in

listener - the PropertyChangeListener to add

removePropertyChangeListener

public void removePropertyChangeListener(java.lang.String property,
                                         java.beans.PropertyChangeListener listener)

Removes a PropertyChangeListener from this BindingContext.

Parameters:

property - the name of the property the PropertyChangeListener is interested in

listener - the PropertyChangeListener to remove

getHasUncommittedValues

public boolean getHasUncommittedValues()

Returns true if any the Bindings managed by this BindingContext have a source or target value state of UNCOMMITTED.

Returns:

true if a value is uncommited

getHasInvalidValues

public boolean getHasInvalidValues()

Returns true if any of the Bindings managed by this BindingContext have a target value state of INVALID.

Returns:

true if a target value state is invalid

addResolver

public final void addResolver(ELResolver resolver)

Adds an ELResover to the list of resolvers used in resolving values. Adding a resolver does not effect existing Bindings.

Parameters:

resolver - the resolver to add

Throws:

java.lang.IllegalArgumentException - if resolver is null

removeResolver

public final void removeResolver(ELResolver resolver)

Removes an ELResover from the list of resolvers used in resolving values. Removing a resolver does not effect existing Bindings.

Parameters:

resolver - the resolver to remove

Throws:

java.lang.IllegalArgumentException - if resolver is null

addFunction

public final void addFunction(java.lang.String prefix,
                              java.lang.String localName,
                              java.lang.reflect.Method m)

Adds the specified method to the list functions available to the expression. Adding a function does not effect existing Bindings.

Parameters:

prefix - the prefix of the function, or "" if no prefix; for example, "fn" in ${fn:method()}, or "" in ${method()}.

localName - the short name of the function. For example, "method" in ${fn:method()}.

m - the method

Throws:

java.lang.IllegalArgumentException - if any of the arguments are null

removeFunction

public final void removeFunction(java.lang.String prefix,
                                 java.lang.String localName,
                                 java.lang.reflect.Method m)

Adds the specified method to the list functions available to the expression. Removing a function does not effect existing Bindings.

Parameters:

prefix - the prefix of the function, or "" if no prefix; for example, "fn" in ${fn:method()}, or "" in ${method()}.

localName - the short name of the function. For example, "method" in ${fn:method()}.

m - the method

Throws:

java.lang.IllegalArgumentException - if any of the arguments are null

getFeatureDescriptors

public final java.lang.Iterable<java.beans.FeatureDescriptor> getFeatureDescriptors(java.lang.Object obj)

Returns an iterator over the known FeatureDescriptors for the specified object. This method is primarily intended for builders.

Preferred properties are identified by FeatureDescriptors that return a value of Boolean.TRUE from getValue(PropertyDelegateProvider.PREFERRED_BINDING_PROPERTY).

Parameters:

obj - the object to query for FeatureDescriptors

Returns:

an Iterable over the known FeatureDescriptors for the specified object; this never returns null

Throws:

java.lang.IllegalArgumentException - if obj is null

toString

public java.lang.String toString()

Returns a string representing the state of this binding context. 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 description