Abstracted most of the code of 'PropertyToNestingBinding' into a more general 'NestingObserver' and implemented tests for that class.

Author: nicolaiparlog

src/org/codefx/libfx/nesting/Nesting.java

@@ -15,7 +15,7 @@
  * Nestings will usually be implemented such that they eagerly evaluate the nested observables.
  *
  * @param <O>
- *            the hierarchy's innermost type of {@link Observable}
+ *            the type of the hierarchy's innermost {@link Observable}
  */
 public interface Nesting<O extends Observable> {
 

src/org/codefx/libfx/nesting/NestingObserver.java

@@ -0,0 +1,225 @@
+package org.codefx.libfx.nesting;
+
+import java.util.Optional;
+import java.util.function.BiConsumer;
+import java.util.function.Consumer;
+
+import javafx.beans.Observable;
+
+/**
+ * Usability class which observes a {@link Nesting} and executes some methods when the nesting's
+ * {@link Nesting#innerObservableProperty() innerObservable} changes (in that order):
+ * <ol>
+ * <li>if the old inner observable was present, a method is called with that observable as its argument; the method is
+ * specified during building (see {@link NestingObserverBuilder#withOldInnerObservable(Consumer) withOldInnerObservable})
+ * <li>if the new inner observable is present, a method is called with that observable as its argument; the method is
+ * specified during building (see {@link NestingObserverBuilder#withNewInnerObservable(Consumer) withNewInnerObservable})
+ * <li>in every case, another method is called with two Booleans as its arguments which indicate whether the old and the
+ * new observable were/are present; the method is specified during building (see
+ * {@link NestingObserverBuilder#whenInnerObservableChanges(BiConsumer) whenInnerObservableChanges})
+ * </ol>
+ * These methods are also called once after construction. At this point, there is of course no old inner observable
+ * present.
+ * <p>
+ * The observer is created with a {@link NestingObserverBuilder} which can be obtained from
+ * {@link NestingObserver#observe(Nesting) observe}. After setting some of the methods mentioned above, the observer is
+ * built by calling {@link NestingObserverBuilder#build()}.
+ *
+ * @param <O>
+ *            the type of the nesting hierarchy's innermost {@link Observable}
+ */
+public final class NestingObserver<O extends Observable> {
+
+	// #region PROPERTIES
+
+	/**
+	 * The observed {@link Nesting}.
+	 */
+	private final Nesting<? extends O> nesting;
+
+	/**
+	 * Called when the inner observable changes and an old inner observable was present. That observable is also the
+	 * argument.
+	 */
+	private final Consumer<? super O> oldInnerObservableConsumer;
+
+	/**
+	 * Called when the inner observable changes and the new inner observable is present. That observable is also the
+	 * argument.
+	 */
+	private final Consumer<? super O> newInnerObservableConsumer;
+
+	/**
+	 * Called when the inner observable changes. The arguments are two Booleans indicating whether the old and new inner
+	 * observables are present.
+	 */
+	private final BiConsumer<Boolean, Boolean> innerObservableChanges;
+
+	//#end PROPERTIES
+
+	// #region CONSTRUCTION
+
+	/**
+	 * Creates a new {@link NestingObserver} from the specified {@link NestingObserverBuilder builder}.
+	 *
+	 * @param builder
+	 *            the {@link NestingObserverBuilder} from which the observer is created
+	 */
+	private NestingObserver(NestingObserverBuilder<O> builder) {
+		nesting = builder.nesting;
+		oldInnerObservableConsumer = builder.oldInnerObservableConsumer;
+		newInnerObservableConsumer = builder.newInnerObservableConsumer;
+		innerObservableChanges = builder.innerObservableChanges;
+
+		initializeObserver();
+	}
+
+	/**
+	 * Starts building a new {@link NestingObserver} which observes the specified nesting.
+	 *
+	 * @param <O>
+	 *            the type of the nesting hierarchy's innermost {@link Observable}
+	 * @param nesting
+	 *            the observed {@link Nesting}
+	 * @return a new {@link NestingObserverBuilder}
+	 */
+	public static <O extends Observable> NestingObserverBuilder<O> observe(Nesting<O> nesting) {
+		return new NestingObserverBuilder<O>(nesting);
+	}
+
+	//#end CONSTRUCTION
+
+	// #region OBSERVE
+
+	/**
+	 * Initializes the observer by observing the initial status and any changes made to it.
+	 */
+	private void initializeObserver() {
+		// observe the initial status
+		observeInnerObservableChange(Optional.empty(), nesting.innerObservableProperty().getValue());
+
+		// add a listener to the nesting which observes changes
+		nesting.innerObservableProperty().addListener(
+				(o, oldInnerObservable, newInnerObservable)
+				-> observeInnerObservableChange(oldInnerObservable, newInnerObservable));
+	}
+
+	/**
+	 * Calls {@link #oldInnerObservableConsumer}, {@link #newInnerObservableConsumer} and
+	 * {@link #innerObservableChanges} when the inner observable changes.
+	 *
+	 * @param oldInnerObservable
+	 *            the old {@link Nesting#innerObservableProperty() innerObservable}
+	 * @param newInnerObservable
+	 *            the new {@link Nesting#innerObservableProperty() innerObservable}
+	 */
+	private void observeInnerObservableChange(
+			Optional<? extends O> oldInnerObservable, Optional<? extends O> newInnerObservable) {
+
+		oldInnerObservable.ifPresent(oldObservable -> oldInnerObservableConsumer.accept(oldObservable));
+		newInnerObservable.ifPresent(newObservable -> newInnerObservableConsumer.accept(newObservable));
+
+		boolean oldInnerObservablePresent = oldInnerObservable.isPresent();
+		boolean newInnerObservablePresent = newInnerObservable.isPresent();
+		innerObservableChanges.accept(oldInnerObservablePresent, newInnerObservablePresent);
+	}
+
+	//#end BIND
+
+	// #region INNER CLASSES
+
+	/**
+	 * Builds a {@link NestingObserver}.
+	 *
+	 * @param <O>
+	 *            the type of the nesting hierarchy's innermost {@link Observable}
+	 */
+	public static class NestingObserverBuilder<O extends Observable> {
+
+		/**
+		 * The future value for {@link NestingObserver#nesting}.
+		 */
+		private final Nesting<? extends O> nesting;
+
+		/**
+		 * The future value for {@link NestingObserver#oldInnerObservableConsumer}.
+		 */
+		private Consumer<? super O> oldInnerObservableConsumer;
+
+		/**
+		 * The future value for {@link NestingObserver#newInnerObservableConsumer}.
+		 */
+		private Consumer<? super O> newInnerObservableConsumer;
+
+		/**
+		 * The future value for {@link NestingObserver#innerObservableChanges}.
+		 */
+		private BiConsumer<Boolean, Boolean> innerObservableChanges;
+
+		/**
+		 * Creates a new builder for a nesting observer which observes the specified nesting.
+		 *
+		 * @param nesting
+		 *            the nesting which will be observed by the created {@link NestingObserver}
+		 */
+		private NestingObserverBuilder(Nesting<? extends O> nesting) {
+			this.nesting = nesting;
+			oldInnerObservableConsumer = observable -> {/* by default do nothing */};
+			newInnerObservableConsumer = observable -> {/* by default do nothing */};
+			innerObservableChanges = (oldObservablePresent, newObservablePresent) -> {/* by default do nothing */};
+		}
+
+		/**
+		 * The specified method will be executed when the {@link Nesting#innerObservableProperty() innerObservable}
+		 * changes <b>and</b> the old observable was present.
+		 *
+		 * @param oldInnerObservableConsumer
+		 *            the executed method; its argument is the old inner observable
+		 * @return this builder for fluent calls
+		 */
+		public NestingObserverBuilder<O> withOldInnerObservable(Consumer<? super O> oldInnerObservableConsumer) {
+			this.oldInnerObservableConsumer = oldInnerObservableConsumer;
+			return this;
+		}
+
+		/**
+		 * The specified method will be executed when the {@link Nesting#innerObservableProperty() innerObservable}
+		 * changes <b>and</b> the new observable is present.
+		 *
+		 * @param newInnerObservableConsumer
+		 *            the executed method; its argument is the new inner observable
+		 * @return this builder for fluent calls
+		 */
+		public NestingObserverBuilder<O> withNewInnerObservable(Consumer<? super O> newInnerObservableConsumer) {
+			this.newInnerObservableConsumer = newInnerObservableConsumer;
+			return this;
+		}
+
+		/**
+		 * The specified method will be executed when the {@link Nesting#innerObservableProperty() innerObservable}
+		 * changes.
+		 *
+		 * @param innerObservableChanges
+		 *            the executed method; its argument are two Booleans indicating whether the old and new inner
+		 *            observables are present.
+		 * @return this builder for fluent calls
+		 */
+		public NestingObserverBuilder<O> whenInnerObservableChanges(BiConsumer<Boolean, Boolean> innerObservableChanges) {
+			this.innerObservableChanges = innerObservableChanges;
+			return this;
+		}
+
+		/**
+		 * Builds a observer from this builder's settings.
+		 *
+		 * @return a new {@link NestingObserver}
+		 */
+		public NestingObserver<O> build() {
+			return new NestingObserver<O>(this);
+		}
+
+	}
+
+	//#end region
+
+}

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

@@ -1,12 +1,13 @@
 package org.codefx.libfx.nesting.property;
 
 import java.util.Objects;
-import java.util.Optional;
+import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 
 import javafx.beans.property.Property;
 
 import org.codefx.libfx.nesting.Nesting;
+import org.codefx.libfx.nesting.NestingObserver;
 
 /**
  * Implements the bidirectional binding between a nested property and its nesting's
@@ -17,33 +18,13 @@
  */
 class PropertyToNestingBinding<T> {
 
-	// #region PROPERTIES
-
-	/**
-	 * The property which will be bound to the {@link #nesting}
-	 */
-	private final NestedProperty<T> nestedProperty;
-
-	/**
-	 * Sets the {@link #nestedProperty}'s {@link NestedProperty#innerObservablePresentProperty() innerObservablePresent}
-	 * property.
-	 */
-	private final Consumer<Boolean> innerObservablePresentSetter;
-
-	/**
-	 * The nesting to which the {@link #nestedProperty} will be bound.
-	 */
-	private final Nesting<? extends Property<T>> nesting;
-
-	//#end PROPERTIES
-
-	// #region CONSTRUCTION
-
 	/**
 	 * Bidirectionally binds the specified nested property to the specified nesting's property. The specified setter is
 	 * used to update the nested property's {@link NestedProperty#innerObservablePresentProperty()
 	 * innerObservablePresent} property.
 	 *
+	 * @param <T>
+	 *            the type wrapped by the property
 	 * @param nestedProperty
 	 *            the {@link Property} which will be bound to the specified nesting
 	 * @param innerObservablePresentSetter
@@ -53,7 +34,7 @@ class PropertyToNestingBinding<T> {
 	 * @throws NullPointerException
 	 *             if any of the arguments is null
 	 */
-	private PropertyToNestingBinding(
+	public static <T> void bind(
 			NestedProperty<T> nestedProperty, Consumer<Boolean> innerObservablePresentSetter,
 			Nesting<? extends Property<T>> nesting) {
 
@@ -62,70 +43,18 @@ private PropertyToNestingBinding(
 				"The argument 'innerObservablePresentSetter' must not be null.");
 		Objects.requireNonNull(nesting, "The argument 'nesting' must not be null.");
 
-		this.nestedProperty = nestedProperty;
-		this.innerObservablePresentSetter = innerObservablePresentSetter;
-		this.nesting = nesting;
+		// the 'innerObservablePresentSetter' only accepts one Boolean; create a 'BiConsumer' from it,
+		// which accepts two and ignores the first
+		BiConsumer<Boolean, Boolean> innerObservablePresentBiSetter =
+				(oldPropertyPresent, newPropertyPresent) -> innerObservablePresentSetter.accept(newPropertyPresent);
+
+				// use a nesting observer to accomplish the binding/unbinding
+		NestingObserver
+				.observe(nesting)
+				.withOldInnerObservable(oldProperty -> nestedProperty.unbindBidirectional(oldProperty))
+				.withNewInnerObservable(newProperty -> nestedProperty.bindBidirectional(newProperty))
+				.whenInnerObservableChanges(innerObservablePresentBiSetter)
+				.build();
 	}
 
-	/**
-	 * Bidirectionally binds the specified nested property to the specified nesting's property. The specified setter is
-	 * used to update the nested property's {@link NestedProperty#innerObservablePresentProperty()
-	 * innerObservablePresent} property.
-	 *
-	 * @param <T>
-	 *            the type wrapped by the property
-	 * @param nestedProperty
-	 *            the {@link Property} which will be bound to the specified nesting
-	 * @param innerObservablePresentSetter
-	 *            the {@link Consumer} which sets the {@link NestedProperty#innerObservablePresentProperty()} property
-	 * @param nesting
-	 *            the {@link Nesting} to which the property will be bound
-	 * @throws NullPointerException
-	 *             if any of the arguments is null
-	 */
-	public static <T> void bind(
-			NestedProperty<T> nestedProperty, Consumer<Boolean> innerObservablePresentSetter,
-			Nesting<? extends Property<T>> nesting) {
-
-		PropertyToNestingBinding<T> binding =
-				new PropertyToNestingBinding<>(nestedProperty, innerObservablePresentSetter, nesting);
-		binding.bindToNestingProperty();
-	}
-
-	//#end CONSTRUCTION
-
-	// #region BIND
-
-	/**
-	 * Binds this property's value to the nesting's property's value and adds a listener which updates that binding.
-	 */
-	private void bindToNestingProperty() {
-		// bind to the nesting's current property
-		moveBinding(Optional.empty(), nesting.innerObservableProperty().getValue());
-		// add a listener to the nesting which moves the binding from one property to the next
-		nesting.innerObservableProperty().addListener(
-				(observable, oldProperty, newProperty) -> moveBinding(oldProperty, newProperty));
-	}
-
-	/**
-	 * Moves the bidirectional binding from the specified old to the specified new observable (one or both can be null).
-	 *
-	 * @param oldPropertyOpt
-	 *            the {@link Property} from which to unbind
-	 * @param newPropertyOpt
-	 *            the {@link Property} to which to bind
-	 */
-	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));
-
-		boolean innerObservablePresent = newPropertyOpt.isPresent();
-		innerObservablePresentSetter.accept(innerObservablePresent);
-	}
-
-	//#end BIND
-
 }