RelayBinding (bindableFX 2.1.0 API)

java.lang.Object
- javafx.beans.binding.ObjectExpression<T>
- - javafx.beans.binding.ObjectBinding<TValue>
  - - de.saxsys.bindablefx.RelayBinding<TParentValue,TValue,TObservedValue>

All Implemented Interfaces:

IFluentBinding<TValue>, javafx.beans.binding.Binding<TValue>, javafx.beans.Observable, javafx.beans.value.ChangeListener<TValue>, javafx.beans.value.ObservableObjectValue<TValue>, javafx.beans.value.ObservableValue<TValue>, javafx.beans.WeakListener
```
public class RelayBinding<TParentValue,TValue,TObservedValue extends javafx.beans.value.ObservableValue<TValue>>
extends javafx.beans.binding.ObjectBinding<TValue>
```
This is a binding that acts as an intermediate binding so that multiple cascaded properties can be observed and the desired property can be bound at the very end. So if you want to bind a property which itself is contained cascadingly in other properties.
e.G. if we have a class A which hold a property of B, which hold property of C, which holds a property of D and D is the property we want to bind to, we would like build something like this
```
 
 A a = new A();
 ObjectProperty<Long> property = new SimpleObjectProperty<>();
 a.getB().getC().dProperty().bindBidirectional(property);
 
 
```
However since B and C might be null we would need to listen to the values to become available at some point in time. This is where the RelayBinding comes into play and handles this by attaching listeners cascadingly so that we can bind to D with no concern that B or C might be null, change or become invalid.
e.g. using the above example, the code to safely bind to D would look like this.
```
 
 A a = new A();
 ObjectProperty<Long> property = new SimpleObjectProperty<>();

 new NestedBinding(a.bProperty(), B::cProperty).bindBidirectional(C::dProperty, property, false);
 
 
```
Author:

xyanid on 30.03.2016.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addListener(@NotNull javafx.beans.value.ChangeListener<? super TValue> listener)`
`void`	`addListener(@NotNull javafx.beans.InvalidationListener listener)`
`protected void`	`afterSetObservedValue(@NotNull javafx.beans.value.ObservableValue<TValue> observableValue)` Will be called when the `observedValue` was set.
`protected void`	`beforeDestroyObservedValue(@NotNull javafx.beans.value.ObservableValue<TValue> observableValue)` Will be called when the `observedValue` is about to be destroyed.
`void`	`changed(@Nullable javafx.beans.value.ObservableValue<? extends TValue> observable, TValue oldValue, TValue newValue)` When the observed value is propertyChanged, this binding is invalidated.
`protected TValue`	`computeValue()` Returns the current value of the `observedValue` if any.
`protected void`	`destroyObservedValue()` Removes this binding as the listener from the `observedValue`, invokes a call to `changed(ObservableValue, Object, Object)` with the oldValue and then sets the `observedValue` to null.
`void`	`dispose()` Stops listening to the `observedValue` and also stops the replacement, fallback value and all attached listeners.
`@NotNull IFluentBinding<TValue>`	`fallbackOn(TValue fallbackValue)` Sets a fallback value that will be returned if the underlying `ObservableValue` is not yet set.
`@NotNull Optional<javafx.beans.value.ObservableValue<TValue>>`	`getObservedValue()` Returns the current value of the `observedValue`.
`boolean`	`hasFallbackValue()` Determines if the binding has as fallback value.
`boolean`	`hasListeners()` Determines if this binding has any `ChangeListener` or `InvalidationListener` attached to it.
`boolean`	`hasReplacement()` Determines if the binding has a replacement.
`void`	`removeListener(@NotNull javafx.beans.value.ChangeListener<? super TValue> listener)`
`void`	`removeListener(@NotNull javafx.beans.InvalidationListener listener)`
`@NotNull IFluentBinding<TValue>`	`replaceWith(@Nullable Function<TValue,TValue> valueReplacer)` Applies the given `Function` whenever the underlying `ObservableValue` is changed, allowing for certain values to be replaced or ignored.
`protected void`	`setObservedValue(@NotNull javafx.beans.value.ObservableValue<TValue> observedValue)` Sets the `observedValue` and adds the this binding as the listener.
`@NotNull IFluentBinding<TValue>`	`stopFallbackOn()` Removes the fallback value, so that null will be returned instead of the fallback value.
`@NotNull IFluentBinding<TValue>`	`stopListeners()` Removes all the `ChangeListener` and `InvalidationListener` that have been attached to this binding.
`@NotNull IFluentBinding<TValue>`	`stopReplacement()` Stops replacing the value of the underlying `ObservableValue`.
`boolean`	`wasGarbageCollected()` Returns true if the `observedValue` is no longer set.

Methods inherited from class javafx.beans.binding.ObjectBinding
bind, get, getDependencies, invalidate, isValid, onInvalidating, toString, unbind

Methods inherited from class javafx.beans.binding.ObjectExpression
asString, asString, asString, getValue, isEqualTo, isEqualTo, isNotEqualTo, isNotEqualTo, isNotNull, isNull, objectExpression

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface de.saxsys.bindablefx.IFluentBinding
convertTo, replaceWith, thenObserve, thenObserveProperty

Methods inherited from interface javafx.beans.binding.Binding
getDependencies, invalidate, isValid

Methods inherited from interface javafx.beans.value.ObservableValue
getValue

- Method Detail
  - dispose
```
public void dispose()
```
    Stops listening to the observedValue and also stops the replacement, fallback value and all attached listeners. Also stops listening to the parent.
    
    Specified by:
    
    dispose in interface javafx.beans.binding.Binding<TValue>
    
    See Also:
    
    stopReplacement(), stopFallbackOn(), stopListeners()
  - getObservedValue
```
@NotNull
public @NotNull Optional<javafx.beans.value.ObservableValue<TValue>> getObservedValue()
```
    Returns the current value of the observedValue.
    
    Returns:
    
    Optional.empty() if the observedValue is null or an Optional of the current value of the observedValue.
  - destroyObservedValue
```
protected final void destroyObservedValue()
```
    Removes this binding as the listener from the observedValue, invokes a call to changed(ObservableValue, Object, Object) with the oldValue and then sets the observedValue to null.
  - setObservedValue
```
protected final void setObservedValue(@NotNull
                                      @NotNull javafx.beans.value.ObservableValue<TValue> observedValue)
```
    Sets the observedValue and adds the this binding as the listener.
    
    Parameters:
    
    observedValue - the ObservableValue which will be used as the observedValue
  - beforeDestroyObservedValue
```
protected void beforeDestroyObservedValue(@NotNull
                                          @NotNull javafx.beans.value.ObservableValue<TValue> observableValue)
```
    Will be called when the observedValue is about to be destroyed.
    
    Parameters:
    
    observableValue - the current observedValue.
  - afterSetObservedValue
```
protected void afterSetObservedValue(@NotNull
                                     @NotNull javafx.beans.value.ObservableValue<TValue> observableValue)
```
    Will be called when the observedValue was set.
    
    Parameters:
    
    observableValue - the current observedValue.
  - computeValue
```
@Nullable
protected TValue computeValue()
```
    Returns the current value of the observedValue if any.
    
    Specified by:
    
    computeValue in class javafx.beans.binding.ObjectBinding<TValue>
    
    Returns:
    
    the current value of the observedValue if any.
  - changed
```
public void changed(@Nullable
                    @Nullable javafx.beans.value.ObservableValue<? extends TValue> observable,
                    @Nullable
                    TValue oldValue,
                    @Nullable
                    TValue newValue)
```
    When the observed value is propertyChanged, this binding is invalidated.
    
    Specified by:
    
    changed in interface javafx.beans.value.ChangeListener<TValue>
  - wasGarbageCollected
```
public boolean wasGarbageCollected()
```
    Returns true if the observedValue is no longer set.
    
    Specified by:
    
    wasGarbageCollected in interface javafx.beans.WeakListener
    
    Returns:
    
    true if the observedValue is no longer set, otherwise false.
  - fallbackOn
```
@NotNull
public @NotNull IFluentBinding<TValue> fallbackOn(@Nullable
                                                            TValue fallbackValue)
```
    Sets a fallback value that will be returned if the underlying ObservableValue is not yet set.
    
    Specified by:
    
    fallbackOn in interface IFluentBinding<TValue>
    
    Parameters:
    
    fallbackValue - the value to fallback on.
    
    Returns:
    
    this IFluentBinding.
    
    See Also:
    
    IFluentBinding.stopFallbackOn(), IFluentBinding.hasFallbackValue()
  - stopFallbackOn
```
@NotNull
public @NotNull IFluentBinding<TValue> stopFallbackOn()
```
    Removes the fallback value, so that null will be returned instead of the fallback value.
    
    Specified by:
    
    stopFallbackOn in interface IFluentBinding<TValue>
    
    Returns:
    
    this IFluentBinding.
    
    See Also:
    
    IFluentBinding.fallbackOn(Object), IFluentBinding.hasFallbackValue()
  - hasFallbackValue
```
public boolean hasFallbackValue()
```
    Determines if the binding has as fallback value.
    
    Specified by:
    
    hasFallbackValue in interface IFluentBinding<TValue>
    
    Returns:
    
    true if the binding has a fallback value, otherwise false.
    
    See Also:
    
    IFluentBinding.fallbackOn(Object), IFluentBinding.stopFallbackOn()
  - replaceWith
```
@NotNull
public @NotNull IFluentBinding<TValue> replaceWith(@Nullable
                                                             @Nullable Function<TValue,TValue> valueReplacer)
```
    Applies the given Function whenever the underlying ObservableValue is changed, allowing for certain values to be replaced or ignored. In order to stop this behaviour a call to IFluentBinding.stopReplacement() is required. A call to this method should overwrite previous call, so only the last applied behaviour is used.
    
    Specified by:
    
    replaceWith in interface IFluentBinding<TValue>
    
    Parameters:
    
    valueReplacer - the Function which decided if the value of the underlying ObservableValue will be replaced with the fallback value.
    
    Returns:
    
    this IFluentBinding.
    
    See Also:
    
    IFluentBinding.replaceWith(Predicate, Object), IFluentBinding.stopReplacement(), IFluentBinding.stopReplacement(), IFluentBinding.hasReplacement()
  - stopReplacement
```
@NotNull
public @NotNull IFluentBinding<TValue> stopReplacement()
```
    Stops replacing the value of the underlying ObservableValue.
    
    Specified by:
    
    stopReplacement in interface IFluentBinding<TValue>
    
    Returns:
    
    this IFluentBinding.
    
    See Also:
    
    IFluentBinding.replaceWith(Function), IFluentBinding.replaceWith(Predicate, Object), IFluentBinding.hasReplacement()
  - hasReplacement
```
public boolean hasReplacement()
```
    Determines if the binding has a replacement.
    
    Specified by:
    
    hasReplacement in interface IFluentBinding<TValue>
    
    Returns:
    
    true if the binding has a replacement, otherwise false.
    
    See Also:
    
    IFluentBinding.replaceWith(Predicate, Object), IFluentBinding.replaceWith(Function), IFluentBinding.stopReplacement()
  - addListener
```
public void addListener(@NotNull
                        @NotNull javafx.beans.InvalidationListener listener)
```
    Specified by:
    
    addListener in interface javafx.beans.Observable
    
    Overrides:
    
    addListener in class javafx.beans.binding.ObjectBinding<TValue>
  - removeListener
```
public void removeListener(@NotNull
                           @NotNull javafx.beans.InvalidationListener listener)
```
    Specified by:
    
    removeListener in interface javafx.beans.Observable
    
    Overrides:
    
    removeListener in class javafx.beans.binding.ObjectBinding<TValue>
  - addListener
```
public void addListener(@NotNull
                        @NotNull javafx.beans.value.ChangeListener<? super TValue> listener)
```
    Specified by:
    
    addListener in interface javafx.beans.value.ObservableValue<TValue>
    
    Overrides:
    
    addListener in class javafx.beans.binding.ObjectBinding<TValue>
  - removeListener
```
public void removeListener(@NotNull
                           @NotNull javafx.beans.value.ChangeListener<? super TValue> listener)
```
    Specified by:
    
    removeListener in interface javafx.beans.value.ObservableValue<TValue>
    
    Overrides:
    
    removeListener in class javafx.beans.binding.ObjectBinding<TValue>
  - stopListeners
```
@NotNull
public @NotNull IFluentBinding<TValue> stopListeners()
```
    Removes all the ChangeListener and InvalidationListener that have been attached to this binding.
    
    Specified by:
    
    stopListeners in interface IFluentBinding<TValue>
    
    Returns:
    
    this IFluentBinding.
    
    See Also:
    
    ObservableValue.addListener(ChangeListener), Observable.addListener(InvalidationListener), IFluentBinding.hasListeners()
  - hasListeners
```
public boolean hasListeners()
```
    Description copied from interface: IFluentBinding
    
    Determines if this binding has any ChangeListener or InvalidationListener attached to it.
    
    Specified by:
    
    hasListeners in interface IFluentBinding<TValue>
    
    Returns:
    
    true if the binding has any ChangeListener or InvalidationListener attached to it, otherwise false.
    
    See Also:
    
    IFluentBinding.stopListeners(), ObservableValue.addListener(ChangeListener), Observable.addListener(InvalidationListener)

Class RelayBinding<TParentValue,TValue,TObservedValue extends javafx.beans.value.ObservableValue<TValue>>

Method Summary

Methods inherited from class javafx.beans.binding.ObjectBinding

Methods inherited from class javafx.beans.binding.ObjectExpression

Methods inherited from class java.lang.Object

Methods inherited from interface de.saxsys.bindablefx.IFluentBinding

Methods inherited from interface javafx.beans.binding.Binding

Methods inherited from interface javafx.beans.value.ObservableValue

Method Detail

dispose

getObservedValue

destroyObservedValue

setObservedValue

beforeDestroyObservedValue

afterSetObservedValue

computeValue

changed

wasGarbageCollected

fallbackOn

stopFallbackOn

hasFallbackValue

replaceWith

stopReplacement

hasReplacement

addListener

removeListener

addListener

removeListener

stopListeners

hasListeners