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