Интерфейс ObservableValue<T>

void addListener(ChangeListener<? super T> listener)

Добавляет слушателя ChangeListener, который будет уведомляться всякий раз, когда изменяется значение ObservableValue. Если один и тот же слушатель добавляется более одного раза, он будет уведомляться более одного раза. То есть, проверка уникальности не выполняется.

Обратите внимание, что один и тот же экземпляр ChangeListener может быть безопасно зарегистрирован для разных ObservableValues.

ObservableValue хранит сильную ссылку на слушателя, что предотвратит сборку мусора слушателя и может привести к утечке памяти. Рекомендуется либо отменить регистрацию слушателя, вызвав removeListener после использования, либо использовать экземпляр WeakChangeListener, чтобы избежать этой ситуации.

void removeListener(ChangeListener<? super T> listener)

Удаляет заданного слушателя из списка слушателей, которые уведомляются всякий раз, когда изменяется значение ObservableValue.

Если заданный слушатель ранее не был зарегистрирован (т.е. он никогда не добавлялся), то вызов этого метода является пустым. Если он был ранее добавлен, то он будет удален. Если он был добавлен более одного раза, то будет удалён только первый экземпляр.

T getValue()

Возвращает текущее значение этого ObservableValue

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

Возвращает ObservableValue, содержащий результат применения заданной функции преобразования к этому значению. Результат обновляется при изменении этого ObservableValue. Если это значение равно null, преобразование не применяется, и результирующее значение также равно null.

Например, преобразование строки в строку в верхнем регистре:

 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)

Возвращает ObservableValue, содержащий это значение, или заданное значение по умолчанию, если оно равно null. Результат обновляется при изменении этого ObservableValue. Этот метод, в сочетании с map(Function), позволяет обрабатывать все значения, включая null.

Например, преобразование строки в строку в верхнем регистре, но оставляя пустым, если вход равен 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)

Возвращает ObservableValue, содержащий значение ObservableValue, полученное путем применения заданной функции преобразования к этому значению. Результат обновляется при изменении либо этого ObservableValue, либо ObservableValue, полученного в результате преобразования. Если это значение равно null, преобразование не применяется, и результирующее значение равно null. Если преобразование привело к null, то результирующее значение также равно null.

Этот метод аналогичен map(Function), но функция преобразования — это функция, результат которой уже является ObservableValue, и если она вызвана, flatMap не обернёт его в дополнительный ObservableValue.

Например, свойство, которое является true только когда элемент пользовательского интерфейса является частью Scene, который является частью Window, который в данный момент отображается на экране:

 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
 

Изменения в любом из значений: сцены listView, окна этой сцены или отображения этого окна обновит булево значение isShowing.

Этот метод предпочтительнее Bindings методов, так как он является безошибочным.

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

Возвращает ObservableValue, содержащий это значение и обновляющийся только тогда, когда condition содержит true.

Возвращаемый ObservableValue наблюдает только за этим значением, когда condition содержит true. Это позволяет этому ObservableValue и условному ObservableValue быть удалёнными из памяти, если ни тот, ни другой не ссылаются иначе, когда condition содержит false. Это в отличие от общего поведения связей, где связь освобождается от памяти только тогда, когда она сама не наблюдается.

condition, содержащий null, рассматривается как содержащий false.

Например:

 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)

Создаёт Subscription на этом ObservableValue, который вызывает заданный changeSubscriber со старым и новым значением всякий раз, когда его значение изменяется. Предоставленный подписчик подобен ChangeListener без параметра ObservableValue.

Параметры, передаваемые в BiConsumer, представляют собой старое и новое значения соответственно.

Обратите внимание, что тот же экземпляр подписчика может быть безопасно подписан на разные Observables.

Также обратите внимание, что при подписке на Observable с более длительным жизненным циклом, чем у подписчика, подписчик должен быть отписан, когда он больше не нужен, так как подписка в противном случае помешает подписчику быть собранным сборщиком мусора. Рассмотрите возможность создания производного ObservableValue с использованием when(ObservableValue) и подписку на это производное наблюдаемое значение для автоматической отвязки жизненного цикла подписчика от этого ObservableValue, когда выполняется некоторое условие.

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

Создаёт подписку на это ObservableValue, которая немедленно предоставляет текущее значение заданному valueSubscriber, а затем любые последующие значения всякий раз, когда его значение изменяется. valueSubscriber вызывается немедленно для удобства, так как обычно пользователь хочет инициализировать значение, а затем обновлять его при изменении.

Обратите внимание, что один и тот же экземпляр подписчика может быть безопасно подписан на разные Observables.

Также обратите внимание, что при подписке на Observable с более длительным жизненным циклом, чем у подписчика, подписчик должен быть отписан, когда он больше не нужен, так как в противном случае подписка не позволит подписчику быть удалён из памяти. Рассмотрите возможность создания производного ObservableValue с использованием when(ObservableValue) и подписки на это производное наблюдаемое значение, чтобы автоматически отвязать жизненный цикл подписчика от этого ObservableValue при выполнении некоторого условия.