Interface ObservableValue<T>

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.

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.

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

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

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.

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
 

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.

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.