Class 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
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.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
SyncFailure
represents a failure to sync (save
orrefresh
) aBinding
.static enum
An enumeration representing the reasons a sync (save
orrefresh
) can fail on aBinding
.static final class
Encapsulates the result from callinggetSourceValueForTarget()
orgetTargetValueForSource()
, which can either be a successful value or a failure. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionfinal void
addBindingListener
(BindingListener listener) Adds aBindingListener
to be notified of changes to thisBinding
.final void
Adds aPropertyChangeListener
to be notified when any property of thisBinding
changes.final void
addPropertyChangeListener
(String propertyName, PropertyChangeListener listener) Adds aPropertyChangeListener
to be notified when the property identified by thepropertyName
argument changes on thisBinding
.final void
bind()
Binds this binding.protected abstract void
bindImpl()
Called bybind()
to allow subclasses to initiate binding.protected final void
A protected version ofbind()
that allows managed subclasses to bind without throwing an exception for being managed.protected final void
firePropertyChange
(String propertyName, Object oldValue, Object newValue) Sends aPropertyChangeEvent
to thePropertyChangeListeners
registered on theBinding
.final BindingListener[]
Returns the list ofBindingListeners
registered on thisBinding
.Returns theBinding's Converter
, which may benull
.final String
getName()
Returns theBinding's
name, which may benull
.final PropertyChangeListener[]
Returns the list ofPropertyChangeListeners
registered on thisBinding
.final PropertyChangeListener[]
getPropertyChangeListeners
(String propertyName) Returns the list ofPropertyChangeListeners
registered on thisBinding
for the given property name.final TV
Returns the value to be returned bygetSourceValueForTarget()
when the source property returnsnull
for the source object.final SS
Returns theBinding's
source object, which may benull
.Returns theBinding's
source property, which may not benull
.final TV
If set, returns the value to be returned bygetSourceValueForTarget()
when the source property is unreadable for the source object.final Binding.ValueResult<TV>
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.final SV
Returns the value to be returned bygetTargetValueForSource()
when the target property returnsnull
for the target object.final TS
Returns theBinding's
target object, which may benull
.Returns theBinding's
target property, which may not benull
.final Binding.ValueResult<SV>
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.Returns theBinding's Validator
, which may benull
.final boolean
isBound()
Returns whether or not thisBinding
is bound.final boolean
Returns whether or not thisBinding
is managed.final boolean
Returns the value of thesourceUnreadableValueSet
property, which indicates whether or not thesourceUnreadableValue
property is set on theBinding
.protected final void
Notifies all registeredBindingListeners
of a successful sync (refresh
orsave
), by callingsynced
on each one.protected final void
notifySyncFailed
(Binding.SyncFailure failure) Notifies all registeredBindingListeners
of a failure to sync (refresh
orsave
), by callingsyncFailed
on each one.protected String
Returns a string representing the internal state of theBinding
.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.final Binding.SyncFailure
The same asrefresh()
with the additional behavior of notifying all registeredBindingListeners
withsynced
ifrefresh
returnsnull
orsyncFailed
ifrefresh
returns aSyncFailure
.protected final Binding.SyncFailure
A protected version ofrefreshAndNotify()
that allows managed subclasses to refresh and notify without throwing an exception for being managed.protected final Binding.SyncFailure
A protected version ofrefresh()
that allows managed subclasses to refresh without throwing an exception for being managed.final void
removeBindingListener
(BindingListener listener) Removes aBindingListener
from theBinding
.final void
Removes aPropertyChangeListener
from theBinding
.final void
removePropertyChangeListener
(String propertyName, PropertyChangeListener listener) Removes aPropertyChangeListener
from theBinding
for the given property name.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.final Binding.SyncFailure
The same assave()
with the additional behavior of notifying all registeredBindingListeners
withsynced
ifsave
returnsnull
orsyncFailed
ifsave
returns aSyncFailure
.protected final Binding.SyncFailure
A protected version ofsaveAndNotify()
that allows managed subclasses to save and notify without throwing an exception for being managed.protected final Binding.SyncFailure
A protected version ofsave()
that allows managed subclasses to save without throwing an exception for being managed.final void
setConverter
(Converter<SV, TV> converter) Sets theConverter
for theBinding
, which may benull
.protected final void
setManaged
(boolean isManaged) Sets whether or not thisBinding
is managed.final void
setSourceNullValue
(TV sourceNullValue) Sets the value to be returned bygetSourceValueForTarget()
when the source property returnsnull
for the source object.final void
setSourceObject
(SS sourceObject) Sets theBinding's
source object, which may benull
.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.protected final void
setSourceProperty
(Property<SS, SV> sourceProperty) Sets theBinding's
source property.final void
setSourceUnreadableValue
(TV sourceUnreadableValue) Sets the value to be returned bygetSourceValueForTarget()
when the source property is unreadable for the source object.final void
setTargetNullValue
(SV targetNullValue) Sets the value to be returned bygetTargetValueForSource()
when the target property returnsnull
for the target object.final void
setTargetObject
(TS targetObject) Sets theBinding's
target object, which may benull
.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.protected final void
setTargetProperty
(Property<TS, TV> targetProperty) Sets theBinding's
target property.final void
setValidator
(Validator<? super SV> validator) Sets theValidator
for theBinding
, which may benull
.protected void
Called to indicate that the source property has fired aPropertyStateEvent
to indicate that its state has changed for the source object.protected void
Called to indicate that the target property has fired aPropertyStateEvent
to indicate that its state has changed for the target object.protected final void
Throws an IllegalStateException if theBinding
is bound.protected final void
Throws an UnsupportedOperationException if theBinding
is managed.protected final void
Throws an IllegalStateException if theBinding
is unbound.toString()
Returns a string representation of theBinding
.final void
unbind()
Unbinds this binding.protected abstract void
Called byunbind()
to allow subclasses to uninitiate binding.protected final void
A protected version ofunbind()
that allows managed subclasses to unbind without throwing an exception for being managed.final void
Unsets the value of thesourceUnreadableValue
property by clearing the value and setting the value of thesourceUnreadableValueSet
property tofalse
.
-
Constructor Details
-
Binding
protected Binding(SS sourceObject, Property<SS, SV> sourceProperty, TS targetObject, Property<TS, TV> targetProperty, 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:
IllegalArgumentException
- if the source property or target property isnull
-
-
Method Details
-
setSourceProperty
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:
IllegalArgumentException
- if the source property isnull
IllegalStateException
- if theBinding
is bound- See Also:
-
setTargetProperty
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:
IllegalArgumentException
- if the target property isnull
IllegalStateException
- if theBinding
is bound- See Also:
-
getName
Returns theBinding's
name, which may benull
.- Returns:
- the
Binding's
name, ornull
-
getSourceProperty
Returns theBinding's
source property, which may not benull
.- Returns:
- the
Binding's
source property,non-null
- See Also:
-
getTargetProperty
Returns theBinding's
target property, which may not benull
.- Returns:
- the
Binding's
target property,non-null
- See Also:
-
getSourceObject
Returns theBinding's
source object, which may benull
.- Returns:
- the
Binding's
source object, ornull
- See Also:
-
getTargetObject
Returns theBinding's
target object, which may benull
.- Returns:
- the
Binding's
target object, ornull
- See Also:
-
setSourceObject
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:
UnsupportedOperationException
- if theBinding
is managedIllegalStateException
- if theBinding
is bound- See Also:
-
setSourceObjectUnmanaged
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:
IllegalStateException
- if theBinding
is bound- See Also:
-
setTargetObject
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:
UnsupportedOperationException
- if theBinding
is managedIllegalStateException
- if theBinding
is bound- See Also:
-
setTargetObjectUnmanaged
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:
IllegalStateException
- if theBinding
is bound- See Also:
-
setValidator
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:
IllegalStateException
- if theBinding
is bound- See Also:
-
getValidator
Returns theBinding's Validator
, which may benull
.- Returns:
- the
Binding's Validator
, ornull
- See Also:
-
setConverter
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:
IllegalStateException
- if theBinding
is bound- See Also:
-
getConverter
Returns theBinding's Converter
, which may benull
.- Returns:
- the
Binding's Converter
, ornull
- See Also:
-
setSourceNullValue
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:
IllegalStateException
- if theBinding
is bound
-
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:
-
setTargetNullValue
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:
IllegalStateException
- if theBinding
is bound
-
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:
-
setSourceUnreadableValue
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:
IllegalStateException
- if theBinding
is bound- See Also:
-
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:
IllegalStateException
- if theBinding
is bound- See Also:
-
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:
-
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:
UnsupportedOperationException
- if the property is not set, as indicated byisSourceUnreadableValueSet
- See Also:
-
addBindingListener
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
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:
-
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:
-
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:
RuntimeException
- if thrown by any of the convertersClassCastException
- if thrown by a converter or the final cast
-
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:
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:
UnsupportedOperationException
- if theBinding
is managedIllegalStateException
- if theBinding
is already bound- See Also:
-
bindUnmanaged
protected final void bindUnmanaged()A protected version ofbind()
that allows managed subclasses to bind without throwing an exception for being managed.- Throws:
IllegalStateException
- if theBinding
is bound- See Also:
-
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:
-
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:
UnsupportedOperationException
- if theBinding
is managedIllegalStateException
- if theBinding
is not bound- See Also:
-
unbindUnmanaged
protected final void unbindUnmanaged()A protected version ofunbind()
that allows managed subclasses to unbind without throwing an exception for being managed.- Throws:
IllegalStateException
- if theBinding
is not bound- See Also:
-
unbindImpl
protected abstract void unbindImpl()Called byunbind()
to allow subclasses to uninitiate binding.- See Also:
-
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:
-
notifySynced
protected final void notifySynced()Notifies all registeredBindingListeners
of a successful sync (refresh
orsave
), by callingsynced
on each one. -
notifySyncFailed
Notifies all registeredBindingListeners
of a failure to sync (refresh
orsave
), by callingsyncFailed
on each one.- Parameters:
failure
- the reason that the sync failed
-
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:
UnsupportedOperationException
- if theBinding
is managedRuntimeException
- as specified byrefresh()
ClassCastException
- as specified byrefresh()
- See Also:
-
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:
RuntimeException
- as specified byrefresh()
ClassCastException
- as specified byrefresh()
- See Also:
-
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:
UnsupportedOperationException
- if theBinding
is managedClassCastException
- as specified byrefresh()
- See Also:
-
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:
ClassCastException
- as specified bysave()
- See Also:
-
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:
UnsupportedOperationException
- if theBinding
is managedRuntimeException
- if thrown bygetSourceValueForTarget()
ClassCastException
- if thrown bygetSourceValueForTarget()
- See Also:
-
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:
RuntimeException
- if thrown bygetSourceValueForTarget()
ClassCastException
- if thrown bygetSourceValueForTarget()
- See Also:
-
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:
UnsupportedOperationException
- if theBinding
is managedClassCastException
- if thrown bygetTargetValueForSource()
- See Also:
-
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:
ClassCastException
- if thrown bygetTargetValueForSource()
- See Also:
-
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:
UnsupportedOperationException
- if theBinding
is managed- See Also:
-
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:
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:
IllegalStateException
- if theBinding
is unbound.
-
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
. -
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
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
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
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:
-
addPropertyChangeListener
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
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:
-
removePropertyChangeListener
public final void removePropertyChangeListener(String propertyName, 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:
-
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:
-
getPropertyChangeListeners
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:
-
firePropertyChange
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
-