Module javafx.base

Package javafx.beans.value

Interface ObservableValue<T>

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

public interface ObservableValue<T>
extends Observable

An 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:

1. All bindings and properties in the JavaFX library support lazy evaluation.
2. 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:

• ObservableBooleanValue
• ObservableDoubleValue
• ObservableFloatValue
• ObservableIntegerValue
• ObservableLongValue
• ObservableNumberValue
• ObservableObjectValue
• ObservableStringValue

Method Summary

Modifier and Type	Method	Description
void	addListener(ChangeListener<? super T> listener)	Adds a ChangeListener which will be notified whenever the value of the ObservableValue changes.
default <U> ObservableValue<U>	flatMap(Function<? super T,? extends ObservableValue<? extends U>> mapper)	Returns an ObservableValue that holds the value of an ObservableValue produced by applying the given mapping function on this value.
T	getValue()	Returns the current value of this ObservableValue
default <U> ObservableValue<U>	map(Function<? super T,? extends U> mapper)	Returns an ObservableValue that holds the result of applying the given mapping function on this value.
default ObservableValue<T>	orElse(T constant)	Returns an ObservableValue that holds this value, or the given constant if it is null.
void	removeListener(ChangeListener<? super T> listener)	Removes the given listener from the list of listeners that are notified whenever the value of the ObservableValue changes.
default Subscription	subscribe(BiConsumer<? super T,? super T> changeSubscriber)	Creates a Subscription on this ObservableValue which calls the given changeSubscriber with the old and new value whenever its value changes.
default Subscription	subscribe(Consumer<? super T> valueSubscriber)	Creates a Subscription on this ObservableValue which immediately provides the current value to the given valueSubscriber, followed by any subsequent values whenever its value changes.
default ObservableValue<T>	when(ObservableValue<Boolean> condition)	Returns an ObservableValue that holds this value and is updated only when condition holds true.

Methods declared in interface javafx.beans.Observable

addListener, removeListener, subscribe

Method Details

addListener

void addListener(ChangeListener<? super T> listener)

Adds a ChangeListener which will be notified whenever the value of the ObservableValue 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 different ObservableValues.

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 calling removeListener after use or to use an instance of WeakChangeListener avoid this situation.

Parameters:

listener - The listener to register

Throws:

NullPointerException - if the listener is null

See Also:

• removeListener(ChangeListener)

removeListener

void removeListener(ChangeListener<? super T> listener)

Removes the given listener from the list of listeners that are notified whenever the value of the ObservableValue 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:

• addListener(ChangeListener)

getValue

T getValue()

Returns the current value of this ObservableValue

Returns:

The current value

map

default <U> ObservableValue<U> map(Function<? super T,? extends U> mapper)

Returns an ObservableValue that holds the result of applying the given mapping function on this value. The result is updated when this ObservableValue changes. If this value is null, no mapping is applied and the resulting value is also null.

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 resulting ObservableValue

Parameters:

mapper - the mapping function to apply to a value, cannot be null

Returns:

an ObservableValue that holds the result of applying the given mapping function on this value, or null when it is null; never returns null

Throws:

NullPointerException - if the mapping function is null

Since:

19

orElse

default ObservableValue<T> orElse(T constant)

Returns an ObservableValue that holds this value, or the given constant if it is null. The result is updated when this ObservableValue changes. This method, when combined with map(Function), allows handling of all values including null 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 this ObservableValue holds null; can be null

Returns:

an ObservableValue that holds this value, or the given constant if it is null; never returns null

Since:

19

flatMap

default <U> ObservableValue<U> flatMap(Function<? super T,? extends ObservableValue<? extends U>> mapper)

Returns an ObservableValue that holds the value of an ObservableValue produced by applying the given mapping function on this value. The result is updated when either this ObservableValue or the ObservableValue produced by the mapping changes. If this value is null, no mapping is applied and the resulting value is null. If the mapping resulted in null, then the resulting value is also null.

This method is similar to map(Function), but the mapping function is one whose result is already an ObservableValue, and if invoked, flatMap does not wrap it within an additional ObservableValue.

For example, a property that is only true when a UI element is part of a Scene that is part of a Window that is currently shown on screen:

 ObservableValue<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
 

Changes in any of the values of: the scene of listView, the window of that scene, or the showing of that window, will update the boolean value isShowing.

This method is preferred over Bindings methods since it is type safe.

Type Parameters:

U - the type of values held by the resulting ObservableValue

Parameters:

mapper - the mapping function to apply to a value, cannot be null

Returns:

an ObservableValue that holds the value of an ObservableValue produced by applying the given mapping function on this value, or null when the value is null; never returns null

Throws:

NullPointerException - if the mapping function is null

Since:

19

when

default ObservableValue<T> when(ObservableValue<Boolean> condition)

Returns an ObservableValue that holds this value and is updated only when condition holds true.

The returned ObservableValue only observes this value when condition holds true. This allows this ObservableValue and the conditional ObservableValue to be garbage collected if neither is otherwise strongly referenced when condition holds false. 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 holding null is treated as holding false.

For example:

 Property<Boolean> condition = new SimpleBooleanProperty(true);
 Property<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 boolean ObservableValue, cannot be null

Returns:

an ObservableValue that holds this value whenever the given condition evaluates to true, otherwise holds the last seen value; never returns null

Since:

20

subscribe

default Subscription subscribe(BiConsumer<? super T,? super T> changeSubscriber)

Creates a Subscription on this ObservableValue which calls the given changeSubscriber with the old and new value whenever its value changes. The provided subscriber is akin to a ChangeListener without the ObservableValue 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 derived ObservableValue using when(ObservableValue) and subscribing on this derived observable value to automatically decouple the lifecycle of the subscriber from this ObservableValue when some condition holds.

Parameters:

changeSubscriber - a BiConsumer to supply with the old and new values of this ObservableValue, cannot be null

Returns:

a Subscription which can be used to cancel this subscription, never null

Throws:

NullPointerException - if the subscriber is null

Since:

21

See Also:

• addListener(ChangeListener)

subscribe

default Subscription subscribe(Consumer<? super T> valueSubscriber)

Creates a Subscription on this ObservableValue which immediately provides the current value to the given valueSubscriber, followed by any subsequent values whenever its value changes. The valueSubscriber 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 derived ObservableValue using when(ObservableValue) and subscribing on this derived observable value to automatically decouple the lifecycle of the subscriber from this ObservableValue when some condition holds.

Parameters:

valueSubscriber - a Consumer to supply with the values of this ObservableValue, cannot be null

Returns:

a Subscription which can be used to cancel this subscription, never null

Throws:

NullPointerException - if the subscriber is null

Since:

21