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 java.lang.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.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected Binding​(SS sourceObject, Property<SS,​SV> sourceProperty, TS targetObject, Property<TS,​TV> targetProperty, java.lang.String name)
      Create an instance of Binding between two properties of two objects.
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void addBindingListener​(BindingListener listener)
      Adds a BindingListener to be notified of changes to this Binding.
      void addPropertyChangeListener​(java.beans.PropertyChangeListener listener)
      Adds a PropertyChangeListener to be notified when any property of this Binding changes.
      void addPropertyChangeListener​(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
      Adds a PropertyChangeListener to be notified when the property identified by the propertyName argument changes on this Binding.
      void bind()
      Binds this binding.
      protected abstract void bindImpl()
      Called by bind() to allow subclasses to initiate binding.
      protected void bindUnmanaged()
      A protected version of bind() that allows managed subclasses to bind without throwing an exception for being managed.
      protected void firePropertyChange​(java.lang.String propertyName, java.lang.Object oldValue, java.lang.Object newValue)
      Sends a PropertyChangeEvent to the PropertyChangeListeners registered on the Binding.
      BindingListener[] getBindingListeners()
      Returns the list of BindingListeners registered on this Binding.
      Converter<SV,​TV> getConverter()
      Returns the Binding's Converter, which may be null.
      java.lang.String getName()
      Returns the Binding's name, which may be null.
      java.beans.PropertyChangeListener[] getPropertyChangeListeners()
      Returns the list of PropertyChangeListeners registered on this Binding.
      java.beans.PropertyChangeListener[] getPropertyChangeListeners​(java.lang.String propertyName)
      Returns the list of PropertyChangeListeners registered on this Binding for the given property name.
      TV getSourceNullValue()
      Returns the value to be returned by getSourceValueForTarget() when the source property returns null for the source object.
      SS getSourceObject()
      Returns the Binding's source object, which may be null.
      Property<SS,​SV> getSourceProperty()
      Returns the Binding's source property, which may not be null.
      TV getSourceUnreadableValue()
      If set, returns the value to be returned by getSourceValueForTarget() when the source property is unreadable for the source object.
      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.
      SV getTargetNullValue()
      Returns the value to be returned by getTargetValueForSource() when the target property returns null for the target object.
      TS getTargetObject()
      Returns the Binding's target object, which may be null.
      Property<TS,​TV> getTargetProperty()
      Returns the Binding's target property, which may not be null.
      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.
      Validator<? super SV> getValidator()
      Returns the Binding's Validator, which may be null.
      boolean isBound()
      Returns whether or not this Binding is bound.
      boolean isManaged()
      Returns whether or not this Binding is managed.
      boolean isSourceUnreadableValueSet()
      Returns the value of the sourceUnreadableValueSet property, which indicates whether or not the sourceUnreadableValue property is set on the Binding.
      protected void notifySynced()
      Notifies all registered BindingListeners of a successful sync (refresh or save), by calling synced on each one.
      protected void notifySyncFailed​(Binding.SyncFailure failure)
      Notifies all registered BindingListeners of a failure to sync (refresh or save), by calling syncFailed on each one.
      protected java.lang.String paramString()
      Returns a string representing the internal state of the Binding.
      Binding.SyncFailure refresh()
      Fetches the value of the source property for the source object and sets it as the value of the target property for the target object.
      Binding.SyncFailure refreshAndNotify()
      The same as refresh() with the additional behavior of notifying all registered BindingListeners with synced if refresh returns null or syncFailed if refresh returns a SyncFailure.
      protected Binding.SyncFailure refreshAndNotifyUnmanaged()
      A protected version of refreshAndNotify() that allows managed subclasses to refresh and notify without throwing an exception for being managed.
      protected Binding.SyncFailure refreshUnmanaged()
      A protected version of refresh() that allows managed subclasses to refresh without throwing an exception for being managed.
      void removeBindingListener​(BindingListener listener)
      Removes a BindingListener from the Binding.
      void removePropertyChangeListener​(java.beans.PropertyChangeListener listener)
      Removes a PropertyChangeListener from the Binding.
      void removePropertyChangeListener​(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
      Removes a PropertyChangeListener from the Binding for the given property name.
      Binding.SyncFailure save()
      Fetches the value of the target property for the target object and sets it as the value of the source property for the source object.
      Binding.SyncFailure saveAndNotify()
      The same as save() with the additional behavior of notifying all registered BindingListeners with synced if save returns null or syncFailed if save returns a SyncFailure.
      protected Binding.SyncFailure saveAndNotifyUnmanaged()
      A protected version of saveAndNotify() that allows managed subclasses to save and notify without throwing an exception for being managed.
      protected Binding.SyncFailure saveUnmanaged()
      A protected version of save() that allows managed subclasses to save without throwing an exception for being managed.
      void setConverter​(Converter<SV,​TV> converter)
      Sets the Converter for the Binding, which may be null.
      protected void setManaged​(boolean isManaged)
      Sets whether or not this Binding is managed.
      void setSourceNullValue​(TV sourceNullValue)
      Sets the value to be returned by getSourceValueForTarget() when the source property returns null for the source object.
      void setSourceObject​(SS sourceObject)
      Sets the Binding's source object, which may be null.
      protected 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.
      protected void setSourceProperty​(Property<SS,​SV> sourceProperty)
      Sets the Binding's source property.
      void setSourceUnreadableValue​(TV sourceUnreadableValue)
      Sets the value to be returned by getSourceValueForTarget() when the source property is unreadable for the source object.
      void setTargetNullValue​(SV targetNullValue)
      Sets the value to be returned by getTargetValueForSource() when the target property returns null for the target object.
      void setTargetObject​(TS targetObject)
      Sets the Binding's target object, which may be null.
      protected 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.
      protected void setTargetProperty​(Property<TS,​TV> targetProperty)
      Sets the Binding's target property.
      void setValidator​(Validator<? super SV> validator)
      Sets the Validator for the Binding, which may be null.
      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.
      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.
      protected void throwIfBound()
      Throws an IllegalStateException if the Binding is bound.
      protected void throwIfManaged()
      Throws an UnsupportedOperationException if the Binding is managed.
      protected void throwIfUnbound()
      Throws an IllegalStateException if the Binding is unbound.
      java.lang.String toString()
      Returns a string representation of the Binding.
      void unbind()
      Unbinds this binding.
      protected abstract void unbindImpl()
      Called by unbind() to allow subclasses to uninitiate binding.
      protected void unbindUnmanaged()
      A protected version of unbind() that allows managed subclasses to unbind without throwing an exception for being managed.
      void unsetSourceUnreadableValue()
      Unsets the value of the sourceUnreadableValue property by clearing the value and setting the value of the sourceUnreadableValueSet property to false.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • Binding

        protected Binding​(SS sourceObject,
                          Property<SS,​SV> sourceProperty,
                          TS targetObject,
                          Property<TS,​TV> targetProperty,
                          java.lang.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:
        java.lang.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:
        java.lang.IllegalArgumentException - if the source property is null
        java.lang.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:
        java.lang.IllegalArgumentException - if the target property is null
        java.lang.IllegalStateException - if the Binding is bound
        See Also:
        isBound()
      • getName

        public final java.lang.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:
        java.lang.UnsupportedOperationException - if the Binding is managed
        java.lang.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:
        java.lang.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:
        java.lang.UnsupportedOperationException - if the Binding is managed
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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()
      • getSourceUnreadableValue

        public final TV getSourceUnreadableValue()
        If set, returns the value to be returned by getSourceValueForTarget() when the source property is unreadable for the source object. Throws UnsupportedOperationException if the property is not set, as indicated by isSourceUnreadableValueSet().

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

        Returns:
        the value that replaces an unreadable source value, which may be null
        Throws:
        java.lang.UnsupportedOperationException - if the property is not set, as indicated by isSourceUnreadableValueSet
        See Also:
        unsetSourceUnreadableValue()
      • 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:
        java.lang.RuntimeException - if thrown by any of the converters
        java.lang.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:
        java.lang.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:
        java.lang.UnsupportedOperationException - if the Binding is managed
        java.lang.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:
        java.lang.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:
        java.lang.UnsupportedOperationException - if the Binding is managed
        java.lang.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:
        java.lang.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
      • refreshAndNotify

        public final Binding.SyncFailure refreshAndNotify()
        The same as refresh() with the additional behavior of notifying all registered BindingListeners with synced if refresh returns null or syncFailed if refresh returns a SyncFailure.
        Returns:
        the return value from the call to refresh
        Throws:
        java.lang.UnsupportedOperationException - if the Binding is managed
        java.lang.RuntimeException - as specified by refresh()
        java.lang.ClassCastException - as specified by refresh()
        See Also:
        isManaged()
      • refreshAndNotifyUnmanaged

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

        public final Binding.SyncFailure saveAndNotify()
        The same as save() with the additional behavior of notifying all registered BindingListeners with synced if save returns null or syncFailed if save returns a SyncFailure.
        Returns:
        the return value from the call to save
        Throws:
        java.lang.UnsupportedOperationException - if the Binding is managed
        java.lang.ClassCastException - as specified by refresh()
        See Also:
        isManaged()
      • 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:
        java.lang.ClassCastException - as specified by save()
        See Also:
        isManaged()
      • refresh

        public final Binding.SyncFailure refresh()
        Fetches the value of the source property for the source object and sets it as the value of the target property for the target object. First calls getSourceValueForTarget(). If the return value from that method represents a failure, this method returns the failure. Otherwise, it calls setValue on the target property for the target object with the value obtained from the source.
        Returns:
        the reason for failure if the binding could not be refreshed, or null for success
        Throws:
        java.lang.UnsupportedOperationException - if the Binding is managed
        java.lang.RuntimeException - if thrown by getSourceValueForTarget()
        java.lang.ClassCastException - if thrown by getSourceValueForTarget()
        See Also:
        isManaged(), save()
      • refreshUnmanaged

        protected final Binding.SyncFailure refreshUnmanaged()
        A protected version of refresh() that allows managed subclasses to refresh without throwing an exception for being managed.
        Returns:
        the reason for failure if the binding could not be refreshed, or null for success
        Throws:
        java.lang.RuntimeException - if thrown by getSourceValueForTarget()
        java.lang.ClassCastException - if thrown by getSourceValueForTarget()
        See Also:
        isManaged()
      • save

        public final Binding.SyncFailure save()
        Fetches the value of the target property for the target object and sets it as the value of the source property for the source object. First calls getTargetValueForSource(). If the return value from that method represents a failure, this method returns the failure. Otherwise, it calls setValue on the source property for the source object with the value obtained from the target.
        Returns:
        the reason for failure if the binding could not be saved, or null for success
        Throws:
        java.lang.UnsupportedOperationException - if the Binding is managed
        java.lang.ClassCastException - if thrown by getTargetValueForSource()
        See Also:
        isManaged(), refresh()
      • saveUnmanaged

        protected final Binding.SyncFailure saveUnmanaged()
        A protected version of save() that allows managed subclasses to save without throwing an exception for being managed.
        Returns:
        the reason for failure if the binding could not be saved, or null for success
        Throws:
        java.lang.ClassCastException - if thrown by getTargetValueForSource()
        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:
        java.lang.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:
        java.lang.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:
        java.lang.IllegalStateException - if the Binding is unbound.
      • toString

        public java.lang.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 java.lang.Object
        Returns:
        a string representation of this Binding
      • paramString

        protected java.lang.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​(java.beans.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​(java.lang.String propertyName,
                                                    java.beans.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​(java.beans.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​(java.lang.String propertyName,
                                                       java.beans.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 java.beans.PropertyChangeListener[] getPropertyChangeListeners()
        Returns the list of PropertyChangeListeners registered on this Binding. Order is undefined. Returns an empty array if there are no listeners.
        Returns:
        the list of PropertyChangeListeners registered on this Binding
        See Also:
        addPropertyChangeListener(java.beans.PropertyChangeListener)
      • getPropertyChangeListeners

        public final java.beans.PropertyChangeListener[] getPropertyChangeListeners​(java.lang.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​(java.lang.String propertyName,
                                                java.lang.Object oldValue,
                                                java.lang.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