Class Binding<SS,SV,TS,TV>
- java.lang.Object
-
- org.jdesktop.beansbinding.Binding<SS,SV,TS,TV>
-
- Type Parameters:
SS
- the type of source objectSV
- the type of value that the source property representsTS
- the type of target objectTV
- 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 anotherBinding
. A managedBinding
does not allow certain methods to be called by the user. These methods are identified in their documentation. Subclasses should callsetManaged(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 byProperty
objects used by this binding are allowed to flow through to the caller of theBinding
methods.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Binding.SyncFailure
SyncFailure
represents a failure to sync (save
orrefresh
) aBinding
.static class
Binding.SyncFailureType
An enumeration representing the reasons a sync (save
orrefresh
) can fail on aBinding
.static class
Binding.ValueResult<V>
Encapsulates the result from callinggetSourceValueForTarget()
orgetTargetValueForSource()
, which can either be a successful value or a failure.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description void
addBindingListener(BindingListener listener)
Adds aBindingListener
to be notified of changes to thisBinding
.void
addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Adds aPropertyChangeListener
to be notified when any property of thisBinding
changes.void
addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
Adds aPropertyChangeListener
to be notified when the property identified by thepropertyName
argument changes on thisBinding
.void
bind()
Binds this binding.protected abstract void
bindImpl()
Called bybind()
to allow subclasses to initiate binding.protected void
bindUnmanaged()
A protected version ofbind()
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 aPropertyChangeEvent
to thePropertyChangeListeners
registered on theBinding
.BindingListener[]
getBindingListeners()
Returns the list ofBindingListeners
registered on thisBinding
.Converter<SV,TV>
getConverter()
Returns theBinding's Converter
, which may benull
.java.lang.String
getName()
Returns theBinding's
name, which may benull
.java.beans.PropertyChangeListener[]
getPropertyChangeListeners()
Returns the list ofPropertyChangeListeners
registered on thisBinding
.java.beans.PropertyChangeListener[]
getPropertyChangeListeners(java.lang.String propertyName)
Returns the list ofPropertyChangeListeners
registered on thisBinding
for the given property name.TV
getSourceNullValue()
Returns the value to be returned bygetSourceValueForTarget()
when the source property returnsnull
for the source object.SS
getSourceObject()
Returns theBinding's
source object, which may benull
.Property<SS,SV>
getSourceProperty()
Returns theBinding's
source property, which may not benull
.TV
getSourceUnreadableValue()
If set, returns the value to be returned bygetSourceValueForTarget()
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 aValueResult
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 bygetTargetValueForSource()
when the target property returnsnull
for the target object.TS
getTargetObject()
Returns theBinding's
target object, which may benull
.Property<TS,TV>
getTargetProperty()
Returns theBinding's
target property, which may not benull
.Binding.ValueResult<SV>
getTargetValueForSource()
Fetches the value of the target property for the target object and returns aValueResult
representing that value in terms that can be set on the source property for the source object.Validator<? super SV>
getValidator()
Returns theBinding's Validator
, which may benull
.boolean
isBound()
Returns whether or not thisBinding
is bound.boolean
isManaged()
Returns whether or not thisBinding
is managed.boolean
isSourceUnreadableValueSet()
Returns the value of thesourceUnreadableValueSet
property, which indicates whether or not thesourceUnreadableValue
property is set on theBinding
.protected void
notifySynced()
Notifies all registeredBindingListeners
of a successful sync (refresh
orsave
), by callingsynced
on each one.protected void
notifySyncFailed(Binding.SyncFailure failure)
Notifies all registeredBindingListeners
of a failure to sync (refresh
orsave
), by callingsyncFailed
on each one.protected java.lang.String
paramString()
Returns a string representing the internal state of theBinding
.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 asrefresh()
with the additional behavior of notifying all registeredBindingListeners
withsynced
ifrefresh
returnsnull
orsyncFailed
ifrefresh
returns aSyncFailure
.protected Binding.SyncFailure
refreshAndNotifyUnmanaged()
A protected version ofrefreshAndNotify()
that allows managed subclasses to refresh and notify without throwing an exception for being managed.protected Binding.SyncFailure
refreshUnmanaged()
A protected version ofrefresh()
that allows managed subclasses to refresh without throwing an exception for being managed.void
removeBindingListener(BindingListener listener)
Removes aBindingListener
from theBinding
.void
removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Removes aPropertyChangeListener
from theBinding
.void
removePropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
Removes aPropertyChangeListener
from theBinding
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 assave()
with the additional behavior of notifying all registeredBindingListeners
withsynced
ifsave
returnsnull
orsyncFailed
ifsave
returns aSyncFailure
.protected Binding.SyncFailure
saveAndNotifyUnmanaged()
A protected version ofsaveAndNotify()
that allows managed subclasses to save and notify without throwing an exception for being managed.protected Binding.SyncFailure
saveUnmanaged()
A protected version ofsave()
that allows managed subclasses to save without throwing an exception for being managed.void
setConverter(Converter<SV,TV> converter)
Sets theConverter
for theBinding
, which may benull
.protected void
setManaged(boolean isManaged)
Sets whether or not thisBinding
is managed.void
setSourceNullValue(TV sourceNullValue)
Sets the value to be returned bygetSourceValueForTarget()
when the source property returnsnull
for the source object.void
setSourceObject(SS sourceObject)
Sets theBinding's
source object, which may benull
.protected void
setSourceObjectUnmanaged(SS sourceObject)
A protected version ofsetSourceObject(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 theBinding's
source property.void
setSourceUnreadableValue(TV sourceUnreadableValue)
Sets the value to be returned bygetSourceValueForTarget()
when the source property is unreadable for the source object.void
setTargetNullValue(SV targetNullValue)
Sets the value to be returned bygetTargetValueForSource()
when the target property returnsnull
for the target object.void
setTargetObject(TS targetObject)
Sets theBinding's
target object, which may benull
.protected void
setTargetObjectUnmanaged(TS targetObject)
A protected version ofsetTargetObject(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 theBinding's
target property.void
setValidator(Validator<? super SV> validator)
Sets theValidator
for theBinding
, which may benull
.protected void
sourceChangedImpl(PropertyStateEvent pse)
Called to indicate that the source property has fired aPropertyStateEvent
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 aPropertyStateEvent
to indicate that its state has changed for the target object.protected void
throwIfBound()
Throws an IllegalStateException if theBinding
is bound.protected void
throwIfManaged()
Throws an UnsupportedOperationException if theBinding
is managed.protected void
throwIfUnbound()
Throws an IllegalStateException if theBinding
is unbound.java.lang.String
toString()
Returns a string representation of theBinding
.void
unbind()
Unbinds this binding.protected abstract void
unbindImpl()
Called byunbind()
to allow subclasses to uninitiate binding.protected void
unbindUnmanaged()
A protected version ofunbind()
that allows managed subclasses to unbind without throwing an exception for being managed.void
unsetSourceUnreadableValue()
Unsets the value of thesourceUnreadableValue
property by clearing the value and setting the value of thesourceUnreadableValueSet
property tofalse
.
-
-
-
Constructor Detail
-
Binding
protected Binding(SS sourceObject, Property<SS,SV> sourceProperty, TS targetObject, Property<TS,TV> targetProperty, java.lang.String name)
Create an instance ofBinding
between two properties of two objects.- Parameters:
sourceObject
- the source objectsourceProperty
- a property on the source objecttargetObject
- the target objecttargetProperty
- a property on the target objectname
- a name for theBinding
- Throws:
java.lang.IllegalArgumentException
- if the source property or target property isnull
-
-
Method Detail
-
setSourceProperty
protected final void setSourceProperty(Property<SS,SV> sourceProperty)
Sets theBinding'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 isnull
java.lang.IllegalStateException
- if theBinding
is bound- See Also:
isBound()
-
setTargetProperty
protected final void setTargetProperty(Property<TS,TV> targetProperty)
Sets theBinding'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 isnull
java.lang.IllegalStateException
- if theBinding
is bound- See Also:
isBound()
-
getName
public final java.lang.String getName()
Returns theBinding's
name, which may benull
.- Returns:
- the
Binding's
name, ornull
-
getSourceProperty
public final Property<SS,SV> getSourceProperty()
Returns theBinding's
source property, which may not benull
.- Returns:
- the
Binding's
source property,non-null
- See Also:
setSourceProperty(org.jdesktop.beansbinding.Property<SS, SV>)
-
getTargetProperty
public final Property<TS,TV> getTargetProperty()
Returns theBinding's
target property, which may not benull
.- Returns:
- the
Binding's
target property,non-null
- See Also:
setTargetProperty(org.jdesktop.beansbinding.Property<TS, TV>)
-
getSourceObject
public final SS getSourceObject()
Returns theBinding's
source object, which may benull
.- Returns:
- the
Binding's
source object, ornull
- See Also:
setSourceObject(SS)
-
getTargetObject
public final TS getTargetObject()
Returns theBinding's
target object, which may benull
.- Returns:
- the
Binding's
target object, ornull
- See Also:
setTargetObject(TS)
-
setSourceObject
public final void setSourceObject(SS sourceObject)
Sets theBinding's
source object, which may benull
.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, ornull
- Throws:
java.lang.UnsupportedOperationException
- if theBinding
is managedjava.lang.IllegalStateException
- if theBinding
is bound- See Also:
isManaged()
,isBound()
-
setSourceObjectUnmanaged
protected final void setSourceObjectUnmanaged(SS sourceObject)
A protected version ofsetSourceObject(SS)
that allows managed subclasses to set the source object without throwing an exception for being managed.- Parameters:
sourceObject
- the source object, ornull
- Throws:
java.lang.IllegalStateException
- if theBinding
is bound- See Also:
isManaged()
,isBound()
-
setTargetObject
public final void setTargetObject(TS targetObject)
Sets theBinding's
target object, which may benull
.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, ornull
- Throws:
java.lang.UnsupportedOperationException
- if theBinding
is managedjava.lang.IllegalStateException
- if theBinding
is bound- See Also:
isManaged()
,isBound()
-
setTargetObjectUnmanaged
protected final void setTargetObjectUnmanaged(TS targetObject)
A protected version ofsetTargetObject(TS)
that allows managed subclasses to set the target object without throwing an exception for being managed.- Parameters:
targetObject
- the target object, ornull
- Throws:
java.lang.IllegalStateException
- if theBinding
is bound- See Also:
isManaged()
,isBound()
-
setValidator
public final void setValidator(Validator<? super SV> validator)
Sets theValidator
for theBinding
, which may benull
.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 aBinding's Validator
is used.- Parameters:
validator
- theValidator
, ornull
- Throws:
java.lang.IllegalStateException
- if theBinding
is bound- See Also:
isBound()
-
getValidator
public final Validator<? super SV> getValidator()
Returns theBinding's Validator
, which may benull
.- Returns:
- the
Binding's Validator
, ornull
- See Also:
setValidator(org.jdesktop.beansbinding.Validator<? super SV>)
-
setConverter
public final void setConverter(Converter<SV,TV> converter)
Sets theConverter
for theBinding
, which may benull
.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()
andgetSourceValueForTarget()
for details on how aBinding's Converter
is used.- Parameters:
converter
- theConverter
, ornull
- Throws:
java.lang.IllegalStateException
- if theBinding
is bound- See Also:
isBound()
-
getConverter
public final Converter<SV,TV> getConverter()
Returns theBinding's Converter
, which may benull
.- Returns:
- the
Binding's Converter
, ornull
- See Also:
setConverter(org.jdesktop.beansbinding.Converter<SV, TV>)
-
setSourceNullValue
public final void setSourceNullValue(TV sourceNullValue)
Sets the value to be returned bygetSourceValueForTarget()
when the source property returnsnull
for the source object. The default for this property isnull
.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, ornull
- Throws:
java.lang.IllegalStateException
- if theBinding
is bound
-
getSourceNullValue
public final TV getSourceNullValue()
Returns the value to be returned bygetSourceValueForTarget()
when the source property returnsnull
for the source object. The default for this property isnull
.- Returns:
- the value that replaces a source value of
null
, ornull
if there is no replacement - See Also:
setSourceNullValue(TV)
-
setTargetNullValue
public final void setTargetNullValue(SV targetNullValue)
Sets the value to be returned bygetTargetValueForSource()
when the target property returnsnull
for the target object. The default for this property isnull
.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, ornull
- Throws:
java.lang.IllegalStateException
- if theBinding
is bound
-
getTargetNullValue
public final SV getTargetNullValue()
Returns the value to be returned bygetTargetValueForSource()
when the target property returnsnull
for the target object. The default for this property isnull
.- Returns:
- the value that replaces a target value of
null
, ornull
if there is no replacement - See Also:
setTargetNullValue(SV)
-
setSourceUnreadableValue
public final void setSourceUnreadableValue(TV sourceUnreadableValue)
Sets the value to be returned bygetSourceValueForTarget()
when the source property is unreadable for the source object. Calling this method stores the given value and indicates thatgetSourceValueForTarget
should use it, by setting thesourceUnreadableValueSet
property totrue
.By default, the
sourceUnreadableValue
property is unset, indicated by thesourceUnreadableValueSet
property beingfalse
.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 settingsourceUnreadableValueSet
back tofalse
) callunsetSourceUnreadableValue()
.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 ofnull
.This method may not be called on a bound binding.
- Parameters:
sourceUnreadableValue
- the value, which may benull
- Throws:
java.lang.IllegalStateException
- if theBinding
is bound- See Also:
isSourceUnreadableValueSet()
,getSourceUnreadableValue()
-
unsetSourceUnreadableValue
public final void unsetSourceUnreadableValue()
Unsets the value of thesourceUnreadableValue
property by clearing the value and setting the value of thesourceUnreadableValueSet
property tofalse
.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 ofnull
.See the documentation for
setSourceUnreadableValue(TV)
for more information on thesourceUnreadableValue
property.This method may not be called on a bound binding.
- Throws:
java.lang.IllegalStateException
- if theBinding
is bound- See Also:
isSourceUnreadableValueSet()
,getSourceUnreadableValue()
-
isSourceUnreadableValueSet
public final boolean isSourceUnreadableValueSet()
Returns the value of thesourceUnreadableValueSet
property, which indicates whether or not thesourceUnreadableValue
property is set on theBinding
.See the documentation for
setSourceUnreadableValue(TV)
for more information on thesourceUnreadableValue
property.- Returns:
- whether or not the
sourceUnreadableValue
property is set on theBinding
- See Also:
unsetSourceUnreadableValue()
,getSourceUnreadableValue()
-
getSourceUnreadableValue
public final TV getSourceUnreadableValue()
If set, returns the value to be returned bygetSourceValueForTarget()
when the source property is unreadable for the source object. ThrowsUnsupportedOperationException
if the property is not set, as indicated byisSourceUnreadableValueSet()
.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 byisSourceUnreadableValueSet
- See Also:
unsetSourceUnreadableValue()
-
addBindingListener
public final void addBindingListener(BindingListener listener)
Adds aBindingListener
to be notified of changes to thisBinding
. Does nothing if the listener isnull
. 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 aBindingListener
from theBinding
. Does nothing if the listener isnull
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)
-
getBindingListeners
public final BindingListener[] getBindingListeners()
Returns the list ofBindingListeners
registered on thisBinding
. Order is undefined. Returns an empty array if there are no listeners.- Returns:
- the list of
BindingListeners
registered on thisBinding
- 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 aValueResult
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 typeSyncFailureType.TARGET_UNWRITEABLE
. Then, if the source property is unreadable for the source object, the value ofisSourceUnreadableValueSet()
is checked. Iftrue
then aValueResult
is returned containing the value of theBinding's
getSourceUnreadableValue()
. Otherwise aValueResult
is returned representing a failure with failure typeSyncFailureType.SOURCE_UNREADABLE
.Next, the value of the source property is fetched for the source object. If the value is
null
, aValueResult
is returned containing the value of theBinding's
getSourceNullValue()
. If the value isnon-null
, theBinding's Converter
, if any, is run to convert the value from source type to the target property'sgetWriteType
, by calling itsconvertForward
method with the value. If noConverter
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
orClassCastException
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 convertersjava.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 aValueResult
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 typeSyncFailureType.SOURCE_UNWRITEABLE
. Then, if the target property is not readable for the target object, aValueResult
is returned representing a failure with failure typeSyncFailureType.TARGET_UNREADABLE
.Next, the value of the target property is fetched for the target object. If the value is
null
, aValueResult
is returned containing the value of theBinding's
getTargetNullValue()
. If the value isnon-null
, theBinding's Converter
, if any, is run to convert the value from target type to the source property'sgetWriteType
, by calling itsconvertReverse
method with the value. If noConverter
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 thanClassCastException
, this method returns aValueResult
containing the failure, with failure typeSyncFailureType.CONVERSION_FAILURE
.As the last step, the
Binding's Validator
, if any, is called upon to validate the final value. If theValidator
returnsnon-null
from itsvalidate
method, aValueResult
is returned containing the validation result, with failure typeSyncFailureType.VALIDATION_FAILURE
. Otherwise aValueResult
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. CallsbindImpl()
to allow subclasses to initiate binding, adds aPropertyStateListener
to the source property for the source object and the target property for the target object to start tracking changes, notifies all registeredBindingListeners
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 theBinding
is managedjava.lang.IllegalStateException
- if theBinding
is already bound- See Also:
isBound()
,isManaged()
,unbind()
-
bindUnmanaged
protected final void bindUnmanaged()
A protected version ofbind()
that allows managed subclasses to bind without throwing an exception for being managed.- Throws:
java.lang.IllegalStateException
- if theBinding
is bound- See Also:
isManaged()
,isBound()
-
bindImpl
protected abstract void bindImpl()
Called bybind()
to allow subclasses to initiate binding. Subclasses typically need not installPropertyStateListeners
on the source property and target property as they will be notified by calls tosourceChangedImpl(org.jdesktop.beansbinding.PropertyStateEvent)
andtargetChangedImpl(org.jdesktop.beansbinding.PropertyStateEvent)
when the source and target properties change respectively.- See Also:
unbindImpl()
-
unbind
public final void unbind()
Unbinds this binding. Removes thePropertyStateListeners
added bybind
, callsunbindImpl()
to allow subclasses to uninitiate binding, notifies all registeredBindingListeners
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 theBinding
is managedjava.lang.IllegalStateException
- if theBinding
is not bound- See Also:
isBound()
,isManaged()
,bind()
-
unbindUnmanaged
protected final void unbindUnmanaged()
A protected version ofunbind()
that allows managed subclasses to unbind without throwing an exception for being managed.- Throws:
java.lang.IllegalStateException
- if theBinding
is not bound- See Also:
isManaged()
,isBound()
-
unbindImpl
protected abstract void unbindImpl()
Called byunbind()
to allow subclasses to uninitiate binding.- See Also:
bindImpl()
-
isBound
public final boolean isBound()
Returns whether or not thisBinding
is bound.Binding
fires a property change notification with property name"bound"
when the value of this property changes.
-
setManaged
protected final void setManaged(boolean isManaged)
Sets whether or not thisBinding
is managed. SomeBindings
are managed, often by anotherBinding
. A managedBinding
does not allow certain methods to be called by the user. These methods are identified in their documentation. Subclasses should callsetManaged(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 thisBinding
is managed. SomeBindings
are managed, often by anotherBinding
. A managedBinding
does not allow certain methods to be called by the user. These methods are identified in their documentation. Subclasses should callsetManaged(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 registeredBindingListeners
of a successful sync (refresh
orsave
), by callingsynced
on each one.
-
notifySyncFailed
protected final void notifySyncFailed(Binding.SyncFailure failure)
Notifies all registeredBindingListeners
of a failure to sync (refresh
orsave
), by callingsyncFailed
on each one.- Parameters:
failure
- the reason that the sync failed
-
refreshAndNotify
public final Binding.SyncFailure refreshAndNotify()
The same asrefresh()
with the additional behavior of notifying all registeredBindingListeners
withsynced
ifrefresh
returnsnull
orsyncFailed
ifrefresh
returns aSyncFailure
.- Returns:
- the return value from the call to
refresh
- Throws:
java.lang.UnsupportedOperationException
- if theBinding
is managedjava.lang.RuntimeException
- as specified byrefresh()
java.lang.ClassCastException
- as specified byrefresh()
- See Also:
isManaged()
-
refreshAndNotifyUnmanaged
protected final Binding.SyncFailure refreshAndNotifyUnmanaged()
A protected version ofrefreshAndNotify()
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 byrefresh()
java.lang.ClassCastException
- as specified byrefresh()
- See Also:
isManaged()
-
saveAndNotify
public final Binding.SyncFailure saveAndNotify()
The same assave()
with the additional behavior of notifying all registeredBindingListeners
withsynced
ifsave
returnsnull
orsyncFailed
ifsave
returns aSyncFailure
.- Returns:
- the return value from the call to
save
- Throws:
java.lang.UnsupportedOperationException
- if theBinding
is managedjava.lang.ClassCastException
- as specified byrefresh()
- See Also:
isManaged()
-
saveAndNotifyUnmanaged
protected final Binding.SyncFailure saveAndNotifyUnmanaged()
A protected version ofsaveAndNotify()
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 bysave()
- 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 callsgetSourceValueForTarget()
. If the return value from that method represents a failure, this method returns the failure. Otherwise, it callssetValue
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 theBinding
is managedjava.lang.RuntimeException
- if thrown bygetSourceValueForTarget()
java.lang.ClassCastException
- if thrown bygetSourceValueForTarget()
- See Also:
isManaged()
,save()
-
refreshUnmanaged
protected final Binding.SyncFailure refreshUnmanaged()
A protected version ofrefresh()
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 bygetSourceValueForTarget()
java.lang.ClassCastException
- if thrown bygetSourceValueForTarget()
- 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 callsgetTargetValueForSource()
. If the return value from that method represents a failure, this method returns the failure. Otherwise, it callssetValue
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 theBinding
is managedjava.lang.ClassCastException
- if thrown bygetTargetValueForSource()
- See Also:
isManaged()
,refresh()
-
saveUnmanaged
protected final Binding.SyncFailure saveUnmanaged()
A protected version ofsave()
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 bygetTargetValueForSource()
- See Also:
isManaged()
-
throwIfManaged
protected final void throwIfManaged()
Throws an UnsupportedOperationException if theBinding
is managed. Useful for calling at the beginning of method implementations that shouldn't be called on managedBindings
- Throws:
java.lang.UnsupportedOperationException
- if theBinding
is managed- See Also:
isManaged()
-
throwIfBound
protected final void throwIfBound()
Throws an IllegalStateException if theBinding
is bound. Useful for calling at the beginning of method implementations that shouldn't be called when theBinding
is bound.- Throws:
java.lang.IllegalStateException
- if theBinding
is bound.
-
throwIfUnbound
protected final void throwIfUnbound()
Throws an IllegalStateException if theBinding
is unbound. Useful for calling at the beginning of method implementations that should only be called when theBinding
is bound.- Throws:
java.lang.IllegalStateException
- if theBinding
is unbound.
-
toString
public java.lang.String toString()
Returns a string representation of theBinding
. This method is intended to be used for debugging purposes only, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not benull
.- Overrides:
toString
in classjava.lang.Object
- Returns:
- a string representation of this
Binding
-
paramString
protected java.lang.String paramString()
Returns a string representing the internal state of theBinding
. This method is intended to be used for debugging purposes only, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not benull
.- Returns:
- a string representing the state of the
Binding
.
-
sourceChangedImpl
protected void sourceChangedImpl(PropertyStateEvent pse)
Called to indicate that the source property has fired aPropertyStateEvent
to indicate that its state has changed for the source object. Called after theBinding
has notified any property change listeners andBindingListeners
that the source value has been edited (only if thePropertyStateEvent
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 aPropertyStateEvent
to indicate that its state has changed for the target object. Called after theBinding
has notified any property change listeners andBindingListeners
that the target value has been edited (only if thePropertyStateEvent
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 aPropertyChangeListener
to be notified when any property of thisBinding
changes. Does nothing if the listener isnull
. 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 aBindingListener
.- 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 aPropertyChangeListener
to be notified when the property identified by thepropertyName
argument changes on thisBinding
. Does nothing if the property name or listener isnull
. 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 aBindingListener
.- Parameters:
propertyName
- the name of the property to listen for changes onlistener
- the listener to add
-
removePropertyChangeListener
public final void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Removes aPropertyChangeListener
from theBinding
. Does nothing if the listener isnull
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 aPropertyChangeListener
from theBinding
for the given property name. Does nothing if the property name or listener isnull
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 forlistener
- the listener to remove- See Also:
addPropertyChangeListener(String, PropertyChangeListener)
-
getPropertyChangeListeners
public final java.beans.PropertyChangeListener[] getPropertyChangeListeners()
Returns the list ofPropertyChangeListeners
registered on thisBinding
. Order is undefined. Returns an empty array if there are no listeners.- Returns:
- the list of
PropertyChangeListeners
registered on thisBinding
- See Also:
addPropertyChangeListener(java.beans.PropertyChangeListener)
-
getPropertyChangeListeners
public final java.beans.PropertyChangeListener[] getPropertyChangeListeners(java.lang.String propertyName)
Returns the list ofPropertyChangeListeners
registered on thisBinding
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 thisBinding
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 aPropertyChangeEvent
to thePropertyChangeListeners
registered on theBinding
.- Parameters:
propertyName
- the name of the property that's changedoldValue
- the old value of the propertynewValue
- the new value of the property
-
-