Module javafx.base
Package javafx.beans.binding

# Class ObjectBinding<T>

java.lang.Object
javafx.beans.binding.ObjectExpression<T>
javafx.beans.binding.ObjectBinding<T>

Type Parameters:
  `T` - the type of the wrapped `Object`

All Implemented Interfaces:
  `Binding<T>`, `Observable`, `ObservableObjectValue<T>`, `ObservableValue<T>`

public abstract class ObjectBinding<T> extends ObjectExpression<T> implements Binding<T>
Base class that provides most of the functionality needed to implement a `Binding` of an `Object`.

`ObjectBinding` provides a simple invalidation-scheme. An extending class can register dependencies by calling `bind(Observable...)`. If One of the registered dependencies becomes invalid, this `ObjectBinding` is marked as invalid. With `unbind(Observable...)` listening to dependencies can be stopped.

To provide a concrete implementation of this class, the method `computeValue()` has to be implemented to calculate the value of this binding based on the current state of the dependencies. It is called when `get()` is called for an invalid binding.

See `DoubleBinding` for an example how this base class can be extended.

Since:
  JavaFX 2.0
See Also:
  - `Binding`
  - `ObjectExpression`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ObjectBinding()`
  Creates a default `ObjectBinding`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addListener(InvalidationListener listener)`
  Adds an `InvalidationListener` which will be notified whenever the `Observable` becomes invalid.
  `void`
  `addListener(ChangeListener<? super T> listener)`
  Adds a `ChangeListener` which will be notified whenever the value of the `ObservableValue` changes.
  `protected boolean`
  `allowValidation()`
  Checks if the binding is allowed to become valid.
  `protected final void`
  `bind(Observable... dependencies)`
  Start observing the dependencies for changes.
  `protected abstract T`
  `computeValue()`
  Calculates the current value of this binding.
  `void`
  `dispose()`
  A default implementation of `dispose()` that is empty.
  `final T`
  `get()`
  Returns the result of `computeValue()`.
  `ObservableList<?>`
  `getDependencies()`
  A default implementation of `getDependencies()` that returns an empty `ObservableList`.
  `final void`
  `invalidate()`
  Mark a binding as invalid.
  `protected final boolean`
  `isObserved()`
  Checks if the binding has at least one listener registered on it.
  `final boolean`
  `isValid()`
  Checks if a binding is valid.
  `protected void`
  `onInvalidating()`
  Called when this binding becomes invalid.
  `void`
  `removeListener(InvalidationListener listener)`
  Removes the given listener from the list of listeners, that are notified whenever the value of the `Observable` becomes invalid.
  `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.
  `String`
  `toString()`
  Returns a string representation of this `ObjectBinding` object.
  `protected final void`
  `unbind(Observable... dependencies)`
  Stop observing the dependencies for changes.

  ### Methods declared in class javafx.beans.binding.ObjectExpression

  `asString, asString, asString, getValue, isEqualTo, isEqualTo, isNotEqualTo, isNotEqualTo, isNotNull, isNull, objectExpression`

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods declared in interface javafx.beans.Observable

  `subscribe`

  ### Methods declared in interface javafx.beans.value.ObservableValue

  `flatMap, getValue, map, orElse, subscribe, subscribe, when`

- ## Constructor Details

  - ### ObjectBinding

    public ObjectBinding()
    Creates a default `ObjectBinding`.

- ## Method Details

  - ### addListener

    public void addListener(InvalidationListener listener)
    Description copied from interface: `Observable`
    Adds an `InvalidationListener` which will be notified whenever the `Observable` becomes invalid. 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 `InvalidationListener` instance may be safely registered for different `Observables`.

    The `Observable` 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 `WeakInvalidationListener` avoid this situation.

    Specified by:
      `addListener` in interface `Observable`
    Parameters:
      `listener` - The listener to register
    See Also:
      - `Observable.removeListener(InvalidationListener)`

  - ### removeListener

    public void removeListener(InvalidationListener listener)
    Description copied from interface: `Observable`
    Removes the given listener from the list of listeners, that are notified whenever the value of the `Observable` becomes invalid.

    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.

    Specified by:
      `removeListener` in interface `Observable`
    Parameters:
      `listener` - The listener to remove
    See Also:
      - `Observable.addListener(InvalidationListener)`

  - ### addListener

    public void addListener(ChangeListener<? super T> listener)
    Description copied from interface: `ObservableValue`
    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.

    Specified by:
      `addListener` in interface `ObservableValue<T>`
    Parameters:
      `listener` - The listener to register
    See Also:
      - `ObservableValue.removeListener(ChangeListener)`

  - ### removeListener

    public void removeListener(ChangeListener<? super T> listener)
    Description copied from interface: `ObservableValue`
    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.

    Specified by:
      `removeListener` in interface `ObservableValue<T>`
    Parameters:
      `listener` - The listener to remove
    See Also:
      - `ObservableValue.addListener(ChangeListener)`

  - ### bind

    protected final void bind(Observable... dependencies)
    Start observing the dependencies for changes. If the value of one of the dependencies changes, the binding is marked as invalid.
    Parameters:
      `dependencies` - the dependencies to observe

  - ### unbind

    protected final void unbind(Observable... dependencies)
    Stop observing the dependencies for changes.
    Parameters:
      `dependencies` - the dependencies to stop observing

  - ### dispose

    public void dispose()
    A default implementation of `dispose()` that is empty.
    Specified by:
      `dispose` in interface `Binding<T>`

  - ### getDependencies

    public ObservableList<?> getDependencies()
    A default implementation of `getDependencies()` that returns an empty `ObservableList`.
    Specified by:
      `getDependencies` in interface `Binding<T>`
    Returns:
      an empty `ObservableList`

  - ### get

    public final T get()
    Returns the result of `computeValue()`. The method `computeValue()` is only called if the binding is invalid. The result is cached and returned if the binding did not become invalid since the last call of `get()`.
    Specified by:
      `get` in interface `ObservableObjectValue<T>`
    Returns:
      the current value

  - ### onInvalidating

    protected void onInvalidating()
    Called when this binding becomes invalid. Can be overridden by extending classes to react to the invalidation. The default implementation is empty.

  - ### invalidate

    public final void invalidate()
    Description copied from interface: `Binding`
    Mark a binding as invalid. This forces the recalculation of the value of the `Binding` next time it is request.
    Specified by:
      `invalidate` in interface `Binding<T>`

  - ### isValid

    public final boolean isValid()
    Description copied from interface: `Binding`
    Checks if a binding is valid.
    Specified by:
      `isValid` in interface `Binding<T>`
    Returns:
      `true` if the `Binding` is valid, `false` otherwise

  - ### isObserved

    protected final boolean isObserved()
    Checks if the binding has at least one listener registered on it. This is useful for subclasses which want to conserve resources when not observed.
    Returns:
      `true` if this binding currently has one or more listeners registered on it, otherwise `false`
    Since:
      19

  - ### allowValidation

    protected boolean allowValidation()
    Checks if the binding is allowed to become valid. Overriding classes can prevent a binding from becoming valid. This is useful in subclasses which do not always listen for invalidations of their dependencies and prefer to recompute the current value instead. This can also be useful if caching of the current computed value is not desirable.

    The default implementation always allows bindings to become valid.

    Returns:
      `true` if this binding is allowed to become valid, otherwise `false`
    Since:
      19

  - ### computeValue

    protected abstract T computeValue()
    Calculates the current value of this binding.

    Classes extending `ObjectBinding` have to provide an implementation of `computeValue`.

    Returns:
      the current value

  - ### toString

    public String toString()
    Returns a string representation of this `ObjectBinding` object.
    Overrides:
      `toString` in class `Object`
    Returns:
      a string representation of this `ObjectBinding` object.