public Interface ObservableValue<T>

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:ChangeListener<? super T>

The listener to register

Exceptions

NullPointerException:

if the listener is null

See Also

removeListener(ChangeListener)

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

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

Parameters

<U>

the type of values held by the resulting ObservableValue

mapper:Function<? super T, ? extends ObservableValue<? extends U>>

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

Returns:ObservableValue<U>

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

Exceptions

NullPointerException:

if the mapping function is null

Since

19

Returns the current value of this ObservableValue

Returns:T

The current value

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

Parameters

<U>

the type of values held by the resulting ObservableValue

mapper:Function<? super T, ? extends U>

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

Returns:ObservableValue<U>

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

Exceptions

NullPointerException:

if the mapping function is null

Since

19

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

the value to use when this ObservableValue holds null; can be null

Returns:ObservableValue<T>

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

Since

19

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:ChangeListener<? super T>

The listener to remove

Exceptions

NullPointerException:

if the listener is null

See Also

addListener(ChangeListener)

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:BiConsumer<? super T, ? super T>

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

Returns:Subscription

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

Exceptions

NullPointerException:

if the subscriber is null

Since

21

See Also

addListener(ChangeListener)

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:Consumer<? super T>

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

Returns:Subscription

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

Exceptions

NullPointerException:

if the subscriber is null

Since

21

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

a boolean ObservableValue, cannot be null

Returns:ObservableValue<T>

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

Since

20