public interface Nesting<O extends javafx.beans.Observable>

A nesting encapsulates a hierarchy of nested ObservableValues.

Its innerObservable property always contains the current innermost Observable in that hierarchy as an Optional. A Nesting can be used as a basic building block for other nested functionality.

Nesting Hierarchy

A nesting hierarchy is composed of some ObservableValues, often simply called observables, and nesting steps which lead from one observable to the next.

At the top of the hierarchy stands one of the observables, the so called outer observable. A nesting step will use its value to return the next observable. The next step will use that observable's value to return the next observable and so on. All observables returned by nesting steps are called nested observables. Finally and perhaps most importantly, the last step will lead to the hierarchy's inner observable.

As nesting steps require a value to be accessible, all observables on which a step is used must provide a value. Hence they must all implement ObservableValue. No step is used on the inner observable so it suffices that it implements Observable.

Example

Consider a class Employee which has an Property<Address> address, where Address has a StringProperty streetName. There might be a Property<Employee> currentEmployee, which always holds the current employee.

In this case the hierarchy would be currentEmployee -> address -> streetName where currentEmployee is the outer observable and address and streetName are nested observables. Additionally, streetName is the inner observable.

Present or Missing Inner Observable

If all steps return non-null observables and none of them contains null, the inner observable can be accessed and will be contained in the innerObservable property. In this case it is said to be present. The same is true if only the inner observable contains null.

If any nesting step returns null or any observable except the inner contains null as a value, the nesting hierarchy can not be fully accessed. The inner observable is said to be missing and the innerObservable property contains Optional.empty().

Evaluation

Nestings will usually be implemented such that they eagerly evaluate the nested observables.

Build

Instances of Nesting can be created with dedicated builders. These can be obtained by starting with one of the methods in Nestings. More details can be found there.

Nestings are also an important building block for creating other nested instances like NestedProperty. A NestingObserver provides a convenient way to work directly with a Nesting.