'Nesting.innerObservable' now contains an 'Optional' of the nested observable to make clear that is might be null.

Author: Nicolai Parlog

src/org/codefx/nesting/AbstractNestingBuilder.java

@@ -2,6 +2,7 @@
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Objects;
 import java.util.function.Function;
 
 import javafx.beans.Observable;
@@ -58,6 +59,8 @@ abstract class AbstractNestingBuilder<T, O extends Observable> {
 	 *            the outer observable upon which the constructed nesting depends
 	 */
 	protected AbstractNestingBuilder(O outerObservable) {
+		Objects.requireNonNull(outerObservable, "The argument 'outerObservable' must not be null.");
+
 		this.outerObservable = outerObservable;
 		this.previousBuilder = null;
 		this.nestingStep = null;
@@ -77,6 +80,9 @@ protected AbstractNestingBuilder(O outerObservable) {
 	protected <P> AbstractNestingBuilder(
 			AbstractNestingBuilder<P, ?> previousBuilder, NestingStep<P, ? extends O> nestingStep) {
 
+		Objects.requireNonNull(previousBuilder, "The argument 'previousBuilder' must not be null.");
+		Objects.requireNonNull(nestingStep, "The argument 'nestingStep' must not be null.");
+
 		this.outerObservable = null;
 		this.previousBuilder = previousBuilder;
 		this.nestingStep = nestingStep;
@@ -122,21 +128,21 @@ private NestingConstructionKit createNestingConstructionKit() {
 	}
 
 	/**
-	 * Fills the specified kit with an observable value and all observable getters which were given to this and its
-	 * previous nesting builders.
+	 * Fills the specified kit with an observable value and all nesting steps which were given to this and its previous
+	 * nesting builders. The steps' order is from outer to inner property and hence is correct for the constructor of
+	 * {@link DeepNesting}.
 	 *
 	 * @param kit
 	 *            the {@link NestingConstructionKit} to fill with an {@link #outerObservable} and {@link #nestingStep
-	 *            nestedObservableGetters}
+	 *            nestingSteps}
 	 */
 	@SuppressWarnings("rawtypes")
 	private void fillNestingConstructionKit(NestingConstructionKit kit) {
 
 		/*
 		 * Uses recursion to move up the chain of 'previousNestedBuilder's until the outer builder is reached. This
 		 * builder's 'outerObservable' is set to the specified 'kit'. The 'kit's list of nesting steps is then filled
-		 * when the recursion is closed, i.e. top down from the outermost builder to the inner one. This creates the
-		 * list on the correct order for the 'Nesting' constructor.
+		 * when the recursion is closed, i.e. top down from the outermost builder to the inner one.
 		 */
 
 		if (isOuterBuilder())

src/org/codefx/nesting/AbstractNestingNestingBuilder.java

@@ -57,8 +57,6 @@ protected <P> AbstractNestingNestingBuilder(AbstractNestingBuilder<P, ?> previou
 	 *            the function which performs the nesting step from one observable to the next
 	 * @return an {@link ObservableValueNestingBuilder} which builds a nesting from this builder's settings and the
 	 *         specified nesting steps
-	 * @throws NullPointerException
-	 *             if the specified function is null
 	 */
 	public <N> ObservableValueNestingBuilder<N> nestObservable(NestingStep<T, ObservableValue<N>> nestingStep) {
 		Objects.requireNonNull(nestingStep, "The argument 'nestingStep' must not be null.");
@@ -75,8 +73,6 @@ public <N> ObservableValueNestingBuilder<N> nestObservable(NestingStep<T, Observ
 	 *            the function which performs the nesting step from one observable to the next
 	 * @return an {@link ObservableValueNestingBuilder} which builds a nesting from this builder's settings and the
 	 *         specified nesting steps
-	 * @throws NullPointerException
-	 *             if the specified function is null
 	 */
 	public <N> ObjectPropertyNestingBuilder<N> nestProperty(NestingStep<T, Property<N>> nestingStep) {
 		Objects.requireNonNull(nestingStep, "The argument 'nestingStep' must not be null.");

src/org/codefx/nesting/DeepNesting.java

@@ -2,6 +2,7 @@
 
 import java.util.List;
 import java.util.Objects;
+import java.util.Optional;
 
 import javafx.beans.Observable;
 import javafx.beans.property.Property;
@@ -84,7 +85,7 @@ final class DeepNesting<O extends Observable> implements Nesting<O> {
 	/**
 	 * The property holding the current innermost observable.
 	 */
-	private final Property<O> inner;
+	private final Property<Optional<O>> inner;
 
 	//#end PROPERTIES
 
@@ -107,8 +108,6 @@ final class DeepNesting<O extends Observable> implements Nesting<O> {
 	 *            </ul>
 	 *            These conditions are not checked by the compiler nor during construction. Violations will later lead
 	 *            to {@link ClassCastException ClassCastExceptions}.
-	 * @throws NullPointerException
-	 *             if any of the arguments is null
 	 * @throws IllegalArgumentException
 	 *             if the list is empty
 	 */
@@ -124,7 +123,7 @@ public DeepNesting(ObservableValue outerObservable, List<NestingStep> nestingSte
 		this.values = new Object[maxLevel];
 		this.nestingSteps = nestingSteps.toArray(new NestingStep[maxLevel]);
 		this.changeListeners = createChangeListeners(maxLevel);
-		this.inner = new SimpleObjectProperty<O>(this, "inner");
+		this.inner = new SimpleObjectProperty<>(this, "inner");
 
 		initializeNesting();
 	}
@@ -161,8 +160,6 @@ private ChangeListener[] createChangeListeners(int levels) {
 		return listeners;
 	}
 
-	//#end CONSTRUCTION
-
 	/**
 	 * Initializes this nesting by filling the arrays {@link #observables} and {@link #values} and adding the
 	 * corresponding {@link #changeListeners changeListener} to each observable.
@@ -171,6 +168,8 @@ private void initializeNesting() {
 		new NestingInitializer().initialize();
 	}
 
+	//#end CONSTRUCTION
+
 	/**
 	 * Updates the nesting from the specified level on. This includes moving listeners from old to new observables and
 	 * updating the arrays {@link #observables} and {@link #values}.
@@ -189,7 +188,7 @@ private void updateNestingFromLevel(int startLevel) {
 	 * {@inheritDoc}
 	 */
 	@Override
-	public ReadOnlyProperty<O> innerObservable() {
+	public ReadOnlyProperty<Optional<O>> innerObservable() {
 		return inner;
 	}
 
@@ -235,7 +234,7 @@ public void initialize() {
 	 * identical and nothing more needs to be updated. <br>
 	 * Note that the loop will not stop on null observables and null values. Instead it continues and replaces all
 	 * stored observables and values with null. This is the desired behavior as the hierarchy is in now an incomplete
-	 * state and the old observables and values are obsolete.
+	 * state and the old observables and values are obsolete and have to be replaced.
 	 */
 	private class NestingUpdater {
 
@@ -386,8 +385,10 @@ private void moveToNextLevel() {
 		private void updateInnerObservable() {
 			// if the loop encountered a level where the stored and the current value are identical,
 			// all higher levels are identical as well and the inner observable can not have changed
-			if (currentLevelIsInnerLevel)
-				inner.setValue((O) innerObservable);
+			if (currentLevelIsInnerLevel) {
+				Optional innerObservableOptional = Optional.ofNullable(innerObservable);
+				inner.setValue(innerObservableOptional);
+			}
 		}
 
 	}

src/org/codefx/nesting/Nesting.java

@@ -1,13 +1,15 @@
 package org.codefx.nesting;
 
+import java.util.Optional;
+
 import javafx.beans.Observable;
 import javafx.beans.property.ReadOnlyProperty;
 import javafx.beans.value.ObservableValue;
 
 /**
  * A nesting encapsulates a hierarchy of nested {@link ObservableValue ObservableValues}; its {@link #innerObservable()}
- * always contains the current innermost {@link Observable} in that hierarchy. If some observable or its value were
- * null, {@code innerObservable} contains null as well.
+ * always contains the current innermost {@link Observable} in that hierarchy as an {@link Optional}. If some observable
+ * or its value were null, {@code innerObservable} contains {@link Optional#empty()}.
  * <p>
  * Nestings will usually be implemented such that they eagerly evaluate the nested observables.
  *
@@ -22,6 +24,6 @@ public interface Nesting<O extends Observable> {
 	 *
 	 * @return the innermost {@link ObservableValue}
 	 */
-	ReadOnlyProperty<O> innerObservable();
+	ReadOnlyProperty<Optional<O>> innerObservable();
 
 }

src/org/codefx/nesting/Nestings.java

@@ -14,6 +14,8 @@
  * O(outer) and N(ested)
  * <p>
  * TODO examples; differences between builder types
+ * <p>
+ * TODO comment about nulls (here?)
  */
 public class Nestings {
 

src/org/codefx/nesting/ShallowNesting.java

@@ -1,6 +1,7 @@
 package org.codefx.nesting;
 
 import java.util.Objects;
+import java.util.Optional;
 
 import javafx.beans.Observable;
 import javafx.beans.property.ReadOnlyProperty;
@@ -18,7 +19,7 @@ final class ShallowNesting<O extends Observable> implements Nesting<O> {
 	 * The property holding the current inner observable, which is always the outer observable specified during
 	 * construction.
 	 */
-	private final ReadOnlyProperty<O> inner;
+	private final ReadOnlyProperty<Optional<O>> inner;
 
 	/**
 	 * Creates a new shallow nesting whose {@link #innerObservable} property always holds the specified outer
@@ -29,11 +30,12 @@ final class ShallowNesting<O extends Observable> implements Nesting<O> {
 	 */
 	public ShallowNesting(O outerObservable) {
 		Objects.requireNonNull(outerObservable, "The argument 'outerObservable' must not be null.");
-		inner = new SimpleObjectProperty<O>(this, "inner", outerObservable);
+		Optional<O> optionalInner = Optional.of(outerObservable);
+		inner = new SimpleObjectProperty<>(this, "inner", optionalInner);
 	}
 
 	@Override
-	public ReadOnlyProperty<O> innerObservable() {
+	public ReadOnlyProperty<Optional<O>> innerObservable() {
 		return inner;
 	}
 

src/org/codefx/nesting/property/AbstractNestedPropertyBuilder.java

@@ -45,6 +45,7 @@ abstract class AbstractNestedPropertyBuilder<N extends Property<?>, P extends Ne
 	 *            the nesting which will be used for all nested properties
 	 */
 	protected AbstractNestedPropertyBuilder(Nesting<N> nesting) {
+		Objects.requireNonNull(nesting, "The argument 'nesting' must not be null.");
 		this.nesting = nesting;
 	}
 

src/org/codefx/nesting/property/NestedIntegerProperty.java

@@ -1,5 +1,7 @@
 package org.codefx.nesting.property;
 
+import java.util.Objects;
+
 import javafx.beans.property.BooleanProperty;
 import javafx.beans.property.IntegerProperty;
 import javafx.beans.property.Property;
@@ -31,12 +33,13 @@ public class NestedIntegerProperty extends SimpleIntegerProperty implements Nest
 	 * @param nesting
 	 *            the nesting this property is based on
 	 * @param bean
-	 *            the bean which owns this property
+	 *            the bean which owns this property; can be null
 	 * @param name
-	 *            this property's name
+	 *            this property's name; can be null
 	 */
 	NestedIntegerProperty(Nesting<? extends Property<Number>> nesting, Object bean, String name) {
 		super(bean, name);
+		Objects.requireNonNull(nesting, "The argument 'nesting' must not be null.");
 		this.innerObservableNull = new SimpleBooleanProperty(this, "innerObservableNull");
 
 		PropertyToNestingBinding.bind(this, isNull -> innerObservableNull.set(isNull), nesting);

src/org/codefx/nesting/property/NestedObjectProperty.java

@@ -1,5 +1,7 @@
 package org.codefx.nesting.property;
 
+import java.util.Objects;
+
 import javafx.beans.property.BooleanProperty;
 import javafx.beans.property.ObjectProperty;
 import javafx.beans.property.Property;
@@ -11,7 +13,7 @@
 
 /**
  * An {@link ObjectProperty} which also implements {@link NestedProperty}.
- * 
+ *
  * @param <T>
  *            the type of the value wrapped by this property
  */
@@ -34,12 +36,13 @@ public class NestedObjectProperty<T> extends SimpleObjectProperty<T> implements
 	 * @param nesting
 	 *            the nesting this property is based on
 	 * @param bean
-	 *            the bean which owns this property
+	 *            the bean which owns this property; can be null
 	 * @param name
-	 *            this property's name
+	 *            this property's name; can be null
 	 */
 	NestedObjectProperty(Nesting<? extends Property<T>> nesting, Object bean, String name) {
 		super(bean, name);
+		Objects.requireNonNull(nesting, "The argument 'nesting' must not be null.");
 		this.innerObservableNull = new SimpleBooleanProperty(this, "innerObservableNull");
 
 		PropertyToNestingBinding.bind(this, isNull -> innerObservableNull.set(isNull), nesting);

src/org/codefx/nesting/property/PropertyToNestingBinding.java

@@ -97,14 +97,10 @@ public static <T> void bind(
 	 */
 	private void bindToNestingProperty() {
 		// bind to the nesting's current property
-		moveBinding(Optional.empty(), Optional.ofNullable(nesting.innerObservable().getValue()));
+		moveBinding(Optional.empty(), nesting.innerObservable().getValue());
 		// add a listener to the nesting which moves the binding from one property to the next
 		nesting.innerObservable().addListener(
-				(observable, oldProperty, newProperty) -> {
-					Optional<Property<T>> oldPropertyOpt = Optional.ofNullable(oldProperty);
-					Optional<Property<T>> newPropertyOpt = Optional.ofNullable(newProperty);
-					moveBinding(oldPropertyOpt, newPropertyOpt);
-				});
+				(observable, oldProperty, newProperty) -> moveBinding(oldProperty, newProperty));
 	}
 
 	/**
@@ -115,7 +111,8 @@ private void bindToNestingProperty() {
 	 * @param newPropertyOpt
 	 *            the {@link Property} to which to bind
 	 */
-	private void moveBinding(Optional<Property<T>> oldPropertyOpt, Optional<Property<T>> newPropertyOpt) {
+	private void moveBinding(Optional<? extends Property<T>> oldPropertyOpt,
+			Optional<? extends Property<T>> newPropertyOpt) {
 		oldPropertyOpt.ifPresent(oldProperty -> nestedProperty.unbindBidirectional(oldProperty));
 		newPropertyOpt.ifPresent(newProperty -> nestedProperty.bindBidirectional(newProperty));