- Type Parameters:
T
- The type of the wrapped value.
- All Superinterfaces:
Observable
- All Known Subinterfaces:
Binding<T>
,JavaBeanProperty<T>
,NumberBinding
,NumberExpression
,ObservableBooleanValue
,ObservableDoubleValue
,ObservableFloatValue
,ObservableIntegerValue
,ObservableListValue<E>
,ObservableLongValue
,ObservableMapValue<K,
,V> ObservableNumberValue
,ObservableObjectValue<T>
,ObservableSetValue<E>
,ObservableStringValue
,Property<T>
,ReadOnlyJavaBeanProperty<T>
,ReadOnlyProperty<T>
,TextInputControl.Content
- All Known Implementing Classes:
BooleanBinding
,BooleanExpression
,BooleanProperty
,BooleanPropertyBase
,DoubleBinding
,DoubleExpression
,DoubleProperty
,DoublePropertyBase
,FloatBinding
,FloatExpression
,FloatProperty
,FloatPropertyBase
,IntegerBinding
,IntegerExpression
,IntegerProperty
,IntegerPropertyBase
,JavaBeanBooleanProperty
,JavaBeanDoubleProperty
,JavaBeanFloatProperty
,JavaBeanIntegerProperty
,JavaBeanLongProperty
,JavaBeanObjectProperty
,JavaBeanStringProperty
,ListBinding
,ListExpression
,ListProperty
,ListPropertyBase
,LongBinding
,LongExpression
,LongProperty
,LongPropertyBase
,MapBinding
,MapExpression
,MapProperty
,MapPropertyBase
,NumberExpressionBase
,ObjectBinding
,ObjectExpression
,ObjectProperty
,ObjectPropertyBase
,ObservableValueBase
,ReadOnlyBooleanProperty
,ReadOnlyBooleanPropertyBase
,ReadOnlyBooleanWrapper
,ReadOnlyDoubleProperty
,ReadOnlyDoublePropertyBase
,ReadOnlyDoubleWrapper
,ReadOnlyFloatProperty
,ReadOnlyFloatPropertyBase
,ReadOnlyFloatWrapper
,ReadOnlyIntegerProperty
,ReadOnlyIntegerPropertyBase
,ReadOnlyIntegerWrapper
,ReadOnlyJavaBeanBooleanProperty
,ReadOnlyJavaBeanDoubleProperty
,ReadOnlyJavaBeanFloatProperty
,ReadOnlyJavaBeanIntegerProperty
,ReadOnlyJavaBeanLongProperty
,ReadOnlyJavaBeanObjectProperty
,ReadOnlyJavaBeanStringProperty
,ReadOnlyListProperty
,ReadOnlyListPropertyBase
,ReadOnlyListWrapper
,ReadOnlyLongProperty
,ReadOnlyLongPropertyBase
,ReadOnlyLongWrapper
,ReadOnlyMapProperty
,ReadOnlyMapPropertyBase
,ReadOnlyMapWrapper
,ReadOnlyObjectProperty
,ReadOnlyObjectPropertyBase
,ReadOnlyObjectWrapper
,ReadOnlySetProperty
,ReadOnlySetPropertyBase
,ReadOnlySetWrapper
,ReadOnlyStringProperty
,ReadOnlyStringPropertyBase
,ReadOnlyStringWrapper
,SetBinding
,SetExpression
,SetProperty
,SetPropertyBase
,SimpleBooleanProperty
,SimpleDoubleProperty
,SimpleFloatProperty
,SimpleIntegerProperty
,SimpleListProperty
,SimpleLongProperty
,SimpleMapProperty
,SimpleObjectProperty
,SimpleSetProperty
,SimpleStringProperty
,SimpleStyleableBooleanProperty
,SimpleStyleableDoubleProperty
,SimpleStyleableFloatProperty
,SimpleStyleableIntegerProperty
,SimpleStyleableLongProperty
,SimpleStyleableObjectProperty
,SimpleStyleableStringProperty
,StringBinding
,StringExpression
,StringProperty
,StringPropertyBase
,StyleableBooleanProperty
,StyleableDoubleProperty
,StyleableFloatProperty
,StyleableIntegerProperty
,StyleableLongProperty
,StyleableObjectProperty
,StyleableStringProperty
ObservableValue
is an entity that wraps a value and allows to
observe the value for changes. In general this interface should not be
implemented directly but one of its sub-interfaces
(ObservableBooleanValue
etc.).
The value of the ObservableValue
can be requested with
getValue()
.
An implementation of ObservableValue
may support lazy evaluation,
which means that the value is not immediately recomputed after changes, but
lazily the next time the value is requested (see note 1 in "Implementation Requirements").
An ObservableValue
generates two types of events: change events and
invalidation events. A change event indicates that the value has changed
(see note 2 in "Implementation Requirements"). An
invalidation event is generated if the current value is not valid anymore.
This distinction becomes important if the ObservableValue
supports
lazy evaluation, because for a lazily evaluated value one does not know if an
invalid value really has changed until it is recomputed. For this reason,
generating change events requires eager evaluation while invalidation events
can be generated for eager and lazy implementations.
Implementations of this class should strive to generate as few events as possible to avoid wasting too much time in event handlers. Implementations in this library mark themselves as invalid when the first invalidation event occurs. They do not generate any more invalidation events until their value is recomputed and valid again.
Two types of listeners can be attached to an ObservableValue
:
InvalidationListener
to listen to invalidation events and
ChangeListener
to listen to change events.
Important note: attaching a ChangeListener
enforces eager computation
even if the implementation of the ObservableValue
supports lazy
evaluation.
- Implementation Requirements:
- All bindings and properties in the JavaFX library support lazy evaluation.
- All implementing classes in the JavaFX library check for a change using reference
equality (and not object equality,
Object#equals(Object)
) of the value.
- Since:
- JavaFX 2.0
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addListener
(ChangeListener<? super T> listener) Adds aChangeListener
which will be notified whenever the value of theObservableValue
changes.default <U> ObservableValue
<U> flatMap
(Function<? super T, ? extends ObservableValue<? extends U>> mapper) Returns anObservableValue
that holds the value of anObservableValue
produced by applying the given mapping function on this value.getValue()
Returns the current value of thisObservableValue
default <U> ObservableValue
<U> Returns anObservableValue
that holds the result of applying the given mapping function on this value.default ObservableValue
<T> Returns anObservableValue
that holds this value, or the given constant if it isnull
.void
removeListener
(ChangeListener<? super T> listener) Removes the given listener from the list of listeners that are notified whenever the value of theObservableValue
changes.default Subscription
subscribe
(BiConsumer<? super T, ? super T> changeSubscriber) Creates aSubscription
on thisObservableValue
which calls the givenchangeSubscriber
with the old and new value whenever its value changes.default Subscription
Creates aSubscription
on thisObservableValue
which immediately provides the current value to the givenvalueSubscriber
, followed by any subsequent values whenever its value changes.default ObservableValue
<T> when
(ObservableValue<Boolean> condition) Returns anObservableValue
that holds this value and is updated only whencondition
holdstrue
.Methods declared in interface javafx.beans.Observable
addListener, removeListener, subscribe
-
Method Details
-
addListener
Adds aChangeListener
which will be notified whenever the value of theObservableValue
changes. If the same listener is added more than once, then it will be notified more than once. That is, no check is made to ensure uniqueness.Note that the same actual
ChangeListener
instance may be safely registered for differentObservableValues
.The
ObservableValue
stores a strong reference to the listener which will prevent the listener from being garbage collected and may result in a memory leak. It is recommended to either unregister a listener by callingremoveListener
after use or to use an instance ofWeakChangeListener
avoid this situation.- Parameters:
listener
- The listener to register- Throws:
NullPointerException
- if the listener is null- See Also:
-
removeListener
Removes the given listener from the list of listeners that are notified whenever the value of theObservableValue
changes.If the given listener has not been previously registered (i.e. it was never added) then this method call is a no-op. If it had been previously added then it will be removed. If it had been added more than once, then only the first occurrence will be removed.
- Parameters:
listener
- The listener to remove- Throws:
NullPointerException
- if the listener is null- See Also:
-
getValue
T getValue()Returns the current value of thisObservableValue
- Returns:
- The current value
-
map
Returns anObservableValue
that holds the result of applying the given mapping function on this value. The result is updated when thisObservableValue
changes. If this value isnull
, no mapping is applied and the resulting value is alsonull
.For example, mapping a string to an upper case string:
var text = new SimpleStringProperty("abcd"); ObservableValue<String> upperCase = text.map(String::toUpperCase); upperCase.getValue(); // Returns "ABCD" text.set("xyz"); upperCase.getValue(); // Returns "XYZ" text.set(null); upperCase.getValue(); // Returns null
- Type Parameters:
U
- the type of values held by the resultingObservableValue
- Parameters:
mapper
- the mapping function to apply to a value, cannot benull
- Returns:
- an
ObservableValue
that holds the result of applying the given mapping function on this value, ornull
when it isnull
; never returnsnull
- Throws:
NullPointerException
- if the mapping function isnull
- Since:
- 19
-
orElse
Returns anObservableValue
that holds this value, or the given constant if it isnull
. The result is updated when thisObservableValue
changes. This method, when combined withmap(Function)
, allows handling of all values includingnull
values.For example, mapping a string to an upper case string, but leaving it blank if the input is
null
:var text = new SimpleStringProperty("abcd"); ObservableValue<String> upperCase = text.map(String::toUpperCase).orElse(""); upperCase.getValue(); // Returns "ABCD" text.set(null); upperCase.getValue(); // Returns ""
- Parameters:
constant
- the value to use when thisObservableValue
holdsnull
; can benull
- Returns:
- an
ObservableValue
that holds this value, or the given constant if it isnull
; never returnsnull
- Since:
- 19
-
flatMap
default <U> ObservableValue<U> flatMap(Function<? super T, ? extends ObservableValue<? extends U>> mapper) Returns anObservableValue
that holds the value of anObservableValue
produced by applying the given mapping function on this value. The result is updated when either thisObservableValue
or theObservableValue
produced by the mapping changes. If this value isnull
, no mapping is applied and the resulting value isnull
. If the mapping resulted innull
, then the resulting value is alsonull
.This method is similar to
map(Function)
, but the mapping function is one whose result is already anObservableValue
, and if invoked,flatMap
does not wrap it within an additionalObservableValue
.For example, a property that is only
true
when a UI element is part of aScene
that is part of aWindow
that is currently shown on screen:
Changes in any of the values of: the scene ofObservableValue<Boolean> isShowing = listView.sceneProperty() .flatMap(Scene::windowProperty) .flatMap(Window::showingProperty) .orElse(false); // Assuming the listView is currently shown to the user, then: isShowing.getValue(); // Returns true listView.getScene().getWindow().hide(); isShowing.getValue(); // Returns false listView.getScene().getWindow().show(); isShowing.getValue(); // Returns true listView.getParent().getChildren().remove(listView); isShowing.getValue(); // Returns false
listView
, the window of that scene, or the showing of that window, will update the boolean valueisShowing
.This method is preferred over
Bindings
methods since it is type safe.- Type Parameters:
U
- the type of values held by the resultingObservableValue
- Parameters:
mapper
- the mapping function to apply to a value, cannot benull
- Returns:
- an
ObservableValue
that holds the value of anObservableValue
produced by applying the given mapping function on this value, ornull
when the value isnull
; never returnsnull
- Throws:
NullPointerException
- if the mapping function isnull
- Since:
- 19
-
when
Returns anObservableValue
that holds this value and is updated only whencondition
holdstrue
.The returned
ObservableValue
only observes this value whencondition
holdstrue
. This allows thisObservableValue
and the conditionalObservableValue
to be garbage collected if neither is otherwise strongly referenced whencondition
holdsfalse
. This is in contrast to the general behavior of bindings, where the binding is only eligible for garbage collection when not observed itself.A
condition
holdingnull
is treated as holdingfalse
.For example:
ObservableValue<Boolean> condition = new SimpleBooleanProperty(true); ObservableValue<String> longLivedProperty = new SimpleStringProperty("A"); ObservableValue<String> whenProperty = longLivedProperty.when(condition); // observe whenProperty, which will in turn observe longLivedProperty whenProperty.addListener((ov, old, current) -> System.out.println(current)); longLivedProperty.setValue("B"); // "B" is printed condition.setValue(false); // After condition becomes false, whenProperty stops observing longLivedProperty; condition // and whenProperty may now be eligible for GC despite being observed by the ChangeListener longLivedProperty.setValue("C"); // nothing is printed longLivedProperty.setValue("D"); // nothing is printed condition.setValue(true); // longLivedProperty is observed again, and "D" is printed
- Parameters:
condition
- a booleanObservableValue
, cannot benull
- Returns:
- an
ObservableValue
that holds this value whenever the given condition evaluates totrue
, otherwise holds the last seen value; never returnsnull
- Since:
- 20
-
subscribe
Creates aSubscription
on thisObservableValue
which calls the givenchangeSubscriber
with the old and new value whenever its value changes. The provided subscriber is akin to aChangeListener
without theObservableValue
parameter.The parameters supplied to the
BiConsumer
are the old and new values, respectively.Note that the same subscriber instance may be safely subscribed for different
Observables
.Also note that when subscribing on an
Observable
with a longer lifecycle than the subscriber, the subscriber must be unsubscribed when no longer needed as the subscription will otherwise keep the subscriber from being garbage collected. Considering creating a derivedObservableValue
usingwhen(ObservableValue)
and subscribing on this derived observable value to automatically decouple the lifecycle of the subscriber from thisObservableValue
when some condition holds.- Parameters:
changeSubscriber
- aBiConsumer
to supply with the old and new values of thisObservableValue
, cannot benull
- Returns:
- a
Subscription
which can be used to cancel this subscription, nevernull
- Throws:
NullPointerException
- if the subscriber isnull
- Since:
- 21
- See Also:
-
subscribe
Creates aSubscription
on thisObservableValue
which immediately provides the current value to the givenvalueSubscriber
, followed by any subsequent values whenever its value changes. ThevalueSubscriber
is called immediately for convenience, since usually the user will want to initialize a value and then update on changes.Note that the same subscriber instance may be safely subscribed for different
Observables
.Also note that when subscribing on an
Observable
with a longer lifecycle than the subscriber, the subscriber must be unsubscribed when no longer needed as the subscription will otherwise keep the subscriber from being garbage collected. Considering creating a derivedObservableValue
usingwhen(ObservableValue)
and subscribing on this derived observable value to automatically decouple the lifecycle of the subscriber from thisObservableValue
when some condition holds.- Parameters:
valueSubscriber
- aConsumer
to supply with the values of thisObservableValue
, cannot benull
- Returns:
- a
Subscription
which can be used to cancel this subscription, nevernull
- Throws:
NullPointerException
- if the subscriber isnull
- Since:
- 21
-