Package org.jdesktop.beansbinding

Class Binding<SS,​SV,​TS,​TV>

  • Type Parameters:
    SS - the type of source object
    SV - the type of value that the source property represents
    TS - the type of target object
    TV - the type of value that the target property represents
    Direct Known Subclasses:
    AbstractColumnBinding, AutoBinding
    public abstract class Binding<SS,​SV,​TS,​TV>
extends Object
    Binding is an abstract class that represents the concept of a binding between two properties, typically of two objects, and contains methods for explicitly syncing the values of the two properties. Binding itself does no automatic syncing between property values. Subclasses will typically keep the values in sync according to some strategy.

    Some Bindings are managed, often by another Binding. A managed Binding does not allow certain methods to be called by the user. These methods are identified in their documentation. Subclasses should call setManaged(true) to make themselves managed. Binding provides protected versions of the managed methods with the suffix "Unmanaged" for subclasses to use internally without checking whether or not they are managed.

    Any PropertyResolutionExceptions thrown by Property objects used by this binding are allowed to flow through to the caller of the Binding methods.

    Author:
    Shannon Hickey

    • Constructor Detail

      • Binding

        protected Binding​(SS sourceObject,
                  Property<SS,​SV> sourceProperty,
                  TS targetObject,
                  Property<TS,​TV> targetProperty,
                  String name)
        Create an instance of Binding between two properties of two objects.
        Parameters:
        sourceObject - the source object
        sourceProperty - a property on the source object
        targetObject - the target object
        targetProperty - a property on the target object
        name - a name for the Binding
        Throws:
        IllegalArgumentException - if the source property or target property is null

    • Method Detail

      • setSourceProperty

        protected final void setSourceProperty​(Property<SS,​SV> sourceProperty)
        Sets the Binding's source property.

        Binding fires a property change notification with property name "sourceProperty" when the value of this property changes.

        This method may not be called on a bound binding.

        Parameters:
        sourceProperty - the source property
        Throws:
        IllegalArgumentException - if the source property is null
        IllegalStateException - if the Binding is bound
        See Also:
        isBound()

      • setTargetProperty

        protected final void setTargetProperty​(Property<TS,​TV> targetProperty)
        Sets the Binding's target property.

        Binding fires a property change notification with property name "targetProperty" when the value of this property changes.

        This method may not be called on a bound binding.

        Parameters:
        targetProperty - the target property
        Throws:
        IllegalArgumentException - if the target property is null
        IllegalStateException - if the Binding is bound
        See Also:
        isBound()

      • getName

        public final String getName()
        Returns the Binding's name, which may be null.
        Returns:
        the Binding's name, or null

      • getSourceObject

        public final SS getSourceObject()
        Returns the Binding's source object, which may be null.
        Returns:
        the Binding's source object, or null
        See Also:
        setSourceObject(SS)

      • getTargetObject

        public final TS getTargetObject()
        Returns the Binding's target object, which may be null.
        Returns:
        the Binding's target object, or null
        See Also:
        setTargetObject(TS)

      • setSourceObject

        public final void setSourceObject​(SS sourceObject)
        Sets the Binding's source object, which may be null.

        Binding fires a property change notification with property name "sourceObject" when the value of this property changes.

        This method may not be called on a managed or bound binding.

        Parameters:
        sourceObject - the source object, or null
        Throws:
        UnsupportedOperationException - if the Binding is managed
        IllegalStateException - if the Binding is bound
        See Also:
        isManaged(), isBound()

      • setSourceObjectUnmanaged

        protected final void setSourceObjectUnmanaged​(SS sourceObject)
        A protected version of setSourceObject(SS) that allows managed subclasses to set the source object without throwing an exception for being managed.
        Parameters:
        sourceObject - the source object, or null
        Throws:
        IllegalStateException - if the Binding is bound
        See Also:
        isManaged(), isBound()

      • setTargetObject

        public final void setTargetObject​(TS targetObject)
        Sets the Binding's target object, which may be null.

        Binding fires a property change notification with property name "targetObject" when the value of this property changes.

        This method may not be called on a managed or bound binding.

        Parameters:
        targetObject - the target object, or null
        Throws:
        UnsupportedOperationException - if the Binding is managed
        IllegalStateException - if the Binding is bound
        See Also:
        isManaged(), isBound()

      • setTargetObjectUnmanaged

        protected final void setTargetObjectUnmanaged​(TS targetObject)
        A protected version of setTargetObject(TS) that allows managed subclasses to set the target object without throwing an exception for being managed.
        Parameters:
        targetObject - the target object, or null
        Throws:
        IllegalStateException - if the Binding is bound
        See Also:
        isManaged(), isBound()

      • setValidator

        public final void setValidator​(Validator<? super SV> validator)
        Sets the Validator for the Binding, which may be null.

        Binding fires a property change notification with property name "validator" when the value of this property changes.

        This method may not be called on a bound binding.

        See the documentation on getTargetValueForSource() for details on how a Binding's Validator is used.

        Parameters:
        validator - the Validator, or null
        Throws:
        IllegalStateException - if the Binding is bound
        See Also:
        isBound()

      • setConverter

        public final void setConverter​(Converter<SV,​TV> converter)
        Sets the Converter for the Binding, which may be null.

        Binding fires a property change notification with property name "converter" when the value of this property changes.

        This method may not be called on a bound binding.

        See the documentation on getTargetValueForSource() and getSourceValueForTarget() for details on how a Binding's Converter is used.

        Parameters:
        converter - the Converter, or null
        Throws:
        IllegalStateException - if the Binding is bound
        See Also:
        isBound()

      • setSourceNullValue

        public final void setSourceNullValue​(TV sourceNullValue)
        Sets the value to be returned by getSourceValueForTarget() when the source property returns null for the source object. The default for this property is null.

        Binding fires a property change notification with property name "sourceNullValue" when the value of this property changes.

        This method may not be called on a bound binding.

        Parameters:
        sourceNullValue - the value, or null
        Throws:
        IllegalStateException - if the Binding is bound

      • getSourceNullValue

        public final TV getSourceNullValue()
        Returns the value to be returned by getSourceValueForTarget() when the source property returns null for the source object. The default for this property is null.
        Returns:
        the value that replaces a source value of null, or null if there is no replacement
        See Also:
        setSourceNullValue(TV)

      • setTargetNullValue

        public final void setTargetNullValue​(SV targetNullValue)
        Sets the value to be returned by getTargetValueForSource() when the target property returns null for the target object. The default for this property is null.

        Binding fires a property change notification with property name "targetNullValue" when the value of this property changes.

        This method may not be called on a bound binding.

        Parameters:
        targetNullValue - the value, or null
        Throws:
        IllegalStateException - if the Binding is bound

      • getTargetNullValue

        public final SV getTargetNullValue()
        Returns the value to be returned by getTargetValueForSource() when the target property returns null for the target object. The default for this property is null.
        Returns:
        the value that replaces a target value of null, or null if there is no replacement
        See Also:
        setTargetNullValue(SV)

      • setSourceUnreadableValue

        public final void setSourceUnreadableValue​(TV sourceUnreadableValue)
        Sets the value to be returned by getSourceValueForTarget() when the source property is unreadable for the source object. Calling this method stores the given value and indicates that getSourceValueForTarget should use it, by setting the sourceUnreadableValueSet property to true.

        By default, the sourceUnreadableValue property is unset, indicated by the sourceUnreadableValueSet property being false.

        Setting this property to null acts the same as setting it to any other value. To return the property to the unset state (clearing the value and setting sourceUnreadableValueSet back to false) call unsetSourceUnreadableValue().

        If this property was previously unset, this method fires a property change notification with property name "sourceUnreadableValueSet". For all invocations, it also fires a property change notification with property name "sourceUnreadableValue", if necessary, to indicate a change in the property value. If previously unset, the event will indicate an old value of null.

        This method may not be called on a bound binding.

        Parameters:
        sourceUnreadableValue - the value, which may be null
        Throws:
        IllegalStateException - if the Binding is bound
        See Also:
        isSourceUnreadableValueSet(), getSourceUnreadableValue()

      • unsetSourceUnreadableValue

        public final void unsetSourceUnreadableValue()
        Unsets the value of the sourceUnreadableValue property by clearing the value and setting the value of the sourceUnreadableValueSet property to false.

        If the property was previously set, fires a property change notification with property name "sourceUnreadableValueSet", and a property change notification with property name "sourceUnreadableValue". The event for the latter notification will have a new value of null.

        See the documentation for setSourceUnreadableValue(TV) for more information on the sourceUnreadableValue property.

        This method may not be called on a bound binding.

        Throws:
        IllegalStateException - if the Binding is bound
        See Also:
        isSourceUnreadableValueSet(), getSourceUnreadableValue()

      • isSourceUnreadableValueSet

        public final boolean isSourceUnreadableValueSet()
        Returns the value of the sourceUnreadableValueSet property, which indicates whether or not the sourceUnreadableValue property is set on the Binding.

        See the documentation for setSourceUnreadableValue(TV) for more information on the sourceUnreadableValue property.

        Returns:
        whether or not the sourceUnreadableValue property is set on the Binding
        See Also:
        unsetSourceUnreadableValue(), getSourceUnreadableValue()

      • addBindingListener

        public final void addBindingListener​(BindingListener listener)
        Adds a BindingListener to be notified of changes to this Binding. Does nothing if the listener is null. If a listener is added more than once, notifications are sent to that listener once for every time that it has been added. The ordering of listener notification is unspecified.
        Parameters:
        listener - the listener to add

      • removeBindingListener

        public final void removeBindingListener​(BindingListener listener)
        Removes a BindingListener from the Binding. Does nothing if the listener is null or is not one of those registered. If the listener being removed was registered more than once, only one occurrence of the listener is removed from the list of listeners. The ordering of listener notification is unspecified.
        Parameters:
        listener - the listener to remove
        See Also:
        addBindingListener(org.jdesktop.beansbinding.BindingListener)

      • getSourceValueForTarget

        public final Binding.ValueResult<TV> getSourceValueForTarget()
        Fetches the value of the source property for the source object and returns a ValueResult representing that value in terms that can be set on the target property for the target object.

        First, if the target property is not writeable for the target object, a ValueResult is returned representing a failure with failure type SyncFailureType.TARGET_UNWRITEABLE. Then, if the source property is unreadable for the source object, the value of isSourceUnreadableValueSet() is checked. If true then a ValueResult is returned containing the value of the Binding's getSourceUnreadableValue(). Otherwise a ValueResult is returned representing a failure with failure type SyncFailureType.SOURCE_UNREADABLE.

        Next, the value of the source property is fetched for the source object. If the value is null, a ValueResult is returned containing the value of the Binding's getSourceNullValue(). If the value is non-null, the Binding's Converter, if any, is run to convert the value from source type to the target property's getWriteType, by calling its convertForward method with the value. If no Converter is registered, a set of default converters is checked to see if one of them can convert the value to the target type. Finally, the value (converted or not) is cast to the target write type.

        This final value is returned in a ValueResult.

        Any RuntimeException or ClassCastException thrown by a converter or the final cast is propogated up to the caller of this method.

        Returns:
        a ValueResult as described above
        Throws:
        RuntimeException - if thrown by any of the converters
        ClassCastException - if thrown by a converter or the final cast

      • getTargetValueForSource

        public final Binding.ValueResult<SV> getTargetValueForSource()
        Fetches the value of the target property for the target object and returns a ValueResult representing that value in terms that can be set on the source property for the source object.

        First, if the source property is not writeable for the source object, a ValueResult is returned representing a failure with failure type SyncFailureType.SOURCE_UNWRITEABLE. Then, if the target property is not readable for the target object, a ValueResult is returned representing a failure with failure type SyncFailureType.TARGET_UNREADABLE.

        Next, the value of the target property is fetched for the target object. If the value is null, a ValueResult is returned containing the value of the Binding's getTargetNullValue(). If the value is non-null, the Binding's Converter, if any, is run to convert the value from target type to the source property's getWriteType, by calling its convertReverse method with the value. If no Converter is registered, a set of default converters is checked to see if one of them can convert the value to the source type. Finally, the value (converted or not) is cast to the source write type.

        If a converter throws a RuntimeException other than ClassCastException, this method returns a ValueResult containing the failure, with failure type SyncFailureType.CONVERSION_FAILURE.

        As the last step, the Binding's Validator, if any, is called upon to validate the final value. If the Validator returns non-null from its validate method, a ValueResult is returned containing the validation result, with failure type SyncFailureType.VALIDATION_FAILURE. Otherwise a ValueResult is returned containing the final validated value.

        Any ClassCastException thrown by a converter or the final cast is propogated up to the caller of this method.

        Returns:
        a ValueResult as described above
        Throws:
        ClassCastException - if thrown by a converter or the final cast

      • bind

        public final void bind()
        Binds this binding. Calls bindImpl() to allow subclasses to initiate binding, adds a PropertyStateListener to the source property for the source object and the target property for the target object to start tracking changes, notifies all registered BindingListeners that the binding has become bound, and fires a property change notification to indicate a change to the "bound" property.
        Throws:
        UnsupportedOperationException - if the Binding is managed
        IllegalStateException - if the Binding is already bound
        See Also:
        isBound(), isManaged(), unbind()

      • bindUnmanaged

        protected final void bindUnmanaged()
        A protected version of bind() that allows managed subclasses to bind without throwing an exception for being managed.
        Throws:
        IllegalStateException - if the Binding is bound
        See Also:
        isManaged(), isBound()

      • unbind

        public final void unbind()
        Unbinds this binding. Removes the PropertyStateListeners added by bind, calls unbindImpl() to allow subclasses to uninitiate binding, notifies all registered BindingListeners that the binding has become unbound, and fires a property change notification to indicate a change to the "bound" property.
        Throws:
        UnsupportedOperationException - if the Binding is managed
        IllegalStateException - if the Binding is not bound
        See Also:
        isBound(), isManaged(), bind()

      • unbindUnmanaged

        protected final void unbindUnmanaged()
        A protected version of unbind() that allows managed subclasses to unbind without throwing an exception for being managed.
        Throws:
        IllegalStateException - if the Binding is not bound
        See Also:
        isManaged(), isBound()

      • unbindImpl

        protected abstract void unbindImpl()
        Called by unbind() to allow subclasses to uninitiate binding.
        See Also:
        bindImpl()

      • isBound

        public final boolean isBound()
        Returns whether or not this Binding is bound.

        Binding fires a property change notification with property name "bound" when the value of this property changes.

        Returns:
        whether or not the Binding is bound
        See Also:
        bind(), unbind()

      • setManaged

        protected final void setManaged​(boolean isManaged)
        Sets whether or not this Binding is managed. Some Bindings are managed, often by another Binding. A managed Binding does not allow certain methods to be called by the user. These methods are identified in their documentation. Subclasses should call setManaged(true) to make themselves managed. Binding provides protected versions of the managed methods, with the suffix "Unmanaged", for subclasses to use internally without checking whether or not they are managed.

      • isManaged

        public final boolean isManaged()
        Returns whether or not this Binding is managed. Some Bindings are managed, often by another Binding. A managed Binding does not allow certain methods to be called by the user. These methods are identified in their documentation. Subclasses should call setManaged(true) to make themselves managed. Binding provides protected versions of the managed methods, with the suffix "Unmanaged", for subclasses to use internally without checking whether or not they are managed.
        Returns:
        whether or not the Binding is managed
        See Also:
        setManaged(boolean)

      • notifySynced

        protected final void notifySynced()
        Notifies all registered BindingListeners of a successful sync (refresh or save), by calling synced on each one.

      • notifySyncFailed

        protected final void notifySyncFailed​(Binding.SyncFailure failure)
        Notifies all registered BindingListeners of a failure to sync (refresh or save), by calling syncFailed on each one.
        Parameters:
        failure - the reason that the sync failed

      • notifySyncWarning

        protected final void notifySyncWarning​(Binding.SyncFailure failure)
        Notifies all registered BindingListeners of a warning to sync (refresh or save), by calling syncFailed on each one.
        Parameters:
        failure - the reason that the sync warning

      • saveAndNotifyUnmanaged

        protected final Binding.SyncFailure saveAndNotifyUnmanaged()
        A protected version of saveAndNotify() that allows managed subclasses to save and notify without throwing an exception for being managed.
        Returns:
        the return value from the call to save
        Throws:
        ClassCastException - as specified by save()
        See Also:
        isManaged()

      • throwIfManaged

        protected final void throwIfManaged()
        Throws an UnsupportedOperationException if the Binding is managed. Useful for calling at the beginning of method implementations that shouldn't be called on managed Bindings
        Throws:
        UnsupportedOperationException - if the Binding is managed
        See Also:
        isManaged()

      • throwIfBound

        protected final void throwIfBound()
        Throws an IllegalStateException if the Binding is bound. Useful for calling at the beginning of method implementations that shouldn't be called when the Binding is bound.
        Throws:
        IllegalStateException - if the Binding is bound.

      • throwIfUnbound

        protected final void throwIfUnbound()
        Throws an IllegalStateException if the Binding is unbound. Useful for calling at the beginning of method implementations that should only be called when the Binding is bound.
        Throws:
        IllegalStateException - if the Binding is unbound.

      • toString

        public String toString()
        Returns a string representation of the Binding. 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 be null.
        Overrides:
        toString in class Object
        Returns:
        a string representation of this Binding

      • paramString

        protected String paramString()
        Returns a string representing the internal state of the Binding. 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 be null.
        Returns:
        a string representing the state of the Binding.

      • sourceChangedImpl

        protected void sourceChangedImpl​(PropertyStateEvent pse)
        Called to indicate that the source property has fired a PropertyStateEvent to indicate that its state has changed for the source object. Called after the Binding has notified any property change listeners and BindingListeners that the source value has been edited (only if the PropertyStateEvent represents a value change). This method is useful for subclasses to detect source changes and perform syncing as appropriate.

      • targetChangedImpl

        protected void targetChangedImpl​(PropertyStateEvent pse)
        Called to indicate that the target property has fired a PropertyStateEvent to indicate that its state has changed for the target object. Called after the Binding has notified any property change listeners and BindingListeners that the target value has been edited (only if the PropertyStateEvent represents a value change). This method is useful for subclasses to detect target changes and perform syncing as appropriate.

      • addPropertyChangeListener

        public final void addPropertyChangeListener​(PropertyChangeListener listener)
        Adds a PropertyChangeListener to be notified when any property of this Binding changes. Does nothing if the listener is null. If a listener is added more than once, notifications are sent to that listener once for every time that it has been added. The ordering of listener notification is unspecified.

        Binding fires property change notification for the following properties:

        • sourceProperty
        • targetProperty
        • sourceObject
        • targetObject
        • validator
        • converter
        • sourceNullValue
        • targetNullValue
        • sourceUnreadableValueSet
        • sourceUnreadableValue
        • bound

        For other types of Binding notifications register a BindingListener.

        Parameters:
        listener - the listener to add
        See Also:
        addBindingListener(org.jdesktop.beansbinding.BindingListener)

      • addPropertyChangeListener

        public final void addPropertyChangeListener​(String propertyName,
                                            PropertyChangeListener listener)
        Adds a PropertyChangeListener to be notified when the property identified by the propertyName argument changes on this Binding. Does nothing if the property name or listener is null. If a listener is added more than once, notifications are sent to that listener once for every time that it has been added. The ordering of listener notification is unspecified.

        Binding fires property change notification for the following properties:

        • sourceProperty
        • targetProperty
        • sourceObject
        • targetObject
        • validator
        • converter
        • sourceNullValue
        • targetNullValue
        • sourceUnreadableValueSet
        • sourceUnreadableValue
        • bound

        For other types of Binding notifications register a BindingListener.

        Parameters:
        propertyName - the name of the property to listen for changes on
        listener - the listener to add

      • removePropertyChangeListener

        public final void removePropertyChangeListener​(PropertyChangeListener listener)
        Removes a PropertyChangeListener from the Binding. Does nothing if the listener is null or is not one of those registered. If the listener being removed was registered more than once, only one occurrence of the listener is removed from the list of listeners. The ordering of listener notification is unspecified.
        Parameters:
        listener - the listener to remove
        See Also:
        addPropertyChangeListener(java.beans.PropertyChangeListener)

      • removePropertyChangeListener

        public final void removePropertyChangeListener​(String propertyName,
                                               PropertyChangeListener listener)
        Removes a PropertyChangeListener from the Binding for the given property name. Does nothing if the property name or listener is null or the listener is not one of those registered. If the listener being removed was registered more than once, only one occurrence of the listener is removed from the list of listeners. The ordering of listener notification is unspecified.
        Parameters:
        propertyName - the name of the property to remove the listener for
        listener - the listener to remove
        See Also:
        addPropertyChangeListener(String, PropertyChangeListener)

      • getPropertyChangeListeners

        public final PropertyChangeListener[] getPropertyChangeListeners​(String propertyName)
        Returns the list of PropertyChangeListeners registered on this Binding for the given property name. Order is undefined. Returns an empty array if there are no listeners registered for the property name.
        Parameters:
        propertyName - the property name to retrieve the listeners for
        Returns:
        the list of PropertyChangeListeners registered on this Binding for the given property name
        See Also:
        addPropertyChangeListener(String, PropertyChangeListener)

      • firePropertyChange

        protected final void firePropertyChange​(String propertyName,
                                        Object oldValue,
                                        Object newValue)
        Sends a PropertyChangeEvent to the PropertyChangeListeners registered on the Binding.
        Parameters:
        propertyName - the name of the property that's changed
        oldValue - the old value of the property
        newValue - the new value of the property