Adapted nested listener to implement 'ListenerHandle' (undocumented).

Author: nicolaiparlog

src/main/java/org/codefx/libfx/nesting/AbstractNestingBuilderOnObservable.java

@@ -9,7 +9,7 @@
 import javafx.beans.Observable;
 import javafx.beans.value.ObservableValue;
 
-import org.codefx.libfx.nesting.listener.NestedInvalidationListener;
+import org.codefx.libfx.nesting.listener.NestedInvalidationListenerHandle;
 import org.codefx.libfx.nesting.listener.NestedInvalidationListenerBuilder;
 
 /**
@@ -170,9 +170,9 @@ private void fillNestingConstructionKit(NestingConstructionKit kit) {
 	 *
 	 * @param listener
 	 *            the added {@link InvalidationListener}
-	 * @return the {@link NestedInvalidationListener} which can be used to check the nesting's state
+	 * @return the {@link NestedInvalidationListenerHandle} which can be used to check the nesting's state
 	 */
-	public NestedInvalidationListener addListener(InvalidationListener listener) {
+	public NestedInvalidationListenerHandle addListener(InvalidationListener listener) {
 		Nesting<O> nesting = buildNesting();
 		return NestedInvalidationListenerBuilder
 				.forNesting(nesting)

src/main/java/org/codefx/libfx/nesting/AbstractNestingBuilderOnObservableValue.java

@@ -4,7 +4,7 @@
 import javafx.beans.value.ChangeListener;
 import javafx.beans.value.ObservableValue;
 
-import org.codefx.libfx.nesting.listener.NestedChangeListener;
+import org.codefx.libfx.nesting.listener.NestedChangeListenerHandle;
 import org.codefx.libfx.nesting.listener.NestedChangeListenerBuilder;
 
 /**
@@ -55,9 +55,9 @@ protected <P> AbstractNestingBuilderOnObservableValue(
 	 *
 	 * @param listener
 	 *            the added {@link ChangeListener}
-	 * @return the {@link NestedChangeListener} which can be used to check the nesting's state
+	 * @return the {@link NestedChangeListenerHandle} which can be used to check the nesting's state
 	 */
-	public NestedChangeListener<T> addListener(ChangeListener<? super T> listener) {
+	public NestedChangeListenerHandle<T> addListener(ChangeListener<? super T> listener) {
 		Nesting<O> nesting = buildNesting();
 		return NestedChangeListenerBuilder
 				.forNesting(nesting)

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

@@ -213,9 +213,9 @@ public NestingObserverBuilder<O> whenInnerObservableChanges(BiConsumer<Boolean,
 		/**
 		 * Builds a observer from this builder's settings.
 		 */
-		@SuppressWarnings("unused")
 		public void observe() {
-			new NestingObserver<O>(this);
+			@SuppressWarnings("unused")
+			NestingObserver<O> observer = new NestingObserver<O>(this);
 		}
 
 	}

src/main/java/org/codefx/libfx/nesting/Nestings.java

@@ -6,8 +6,8 @@
 import javafx.beans.value.ChangeListener;
 import javafx.beans.value.ObservableValue;
 
-import org.codefx.libfx.nesting.listener.NestedChangeListener;
-import org.codefx.libfx.nesting.listener.NestedInvalidationListener;
+import org.codefx.libfx.nesting.listener.NestedChangeListenerHandle;
+import org.codefx.libfx.nesting.listener.NestedInvalidationListenerHandle;
 import org.codefx.libfx.nesting.property.NestedDoubleProperty;
 import org.codefx.libfx.nesting.property.NestedProperty;
 
@@ -51,8 +51,8 @@
  *
  * @see Nesting
  * @see NestedProperty
- * @see NestedChangeListener
- * @see NestedInvalidationListener
+ * @see NestedChangeListenerHandle
+ * @see NestedInvalidationListenerHandle
  */
 public class Nestings {
 

src/main/java/org/codefx/libfx/nesting/listener/NestedChangeListenerBuilder.java

@@ -8,7 +8,7 @@
 import org.codefx.libfx.nesting.Nesting;
 
 /**
- * A builder for a {@link NestedChangeListener}.
+ * A builder for a {@link NestedChangeListenerHandle}.
  *
  * @param <T>
  *            the type of the value wrapped by the {@link ObservableValue}
@@ -113,17 +113,39 @@ private Buildable(NestedChangeListenerBuilder<T, O> builder) {
 		}
 
 		/**
-		 * Builds a nested change listener. This method can only be called once as the same {@link ChangeListener}
-		 * should not be added more than once to the same {@link Nesting}.
+		 * Builds and {@link NestedChangeListenerHandle#attach() attaches} a nested change listener and returns the
+		 * handle for it.
+		 * <p>
+		 * This method can only be called once as the same {@link ChangeListener} should not be added more than once to
+		 * the same {@link Nesting}.
 		 *
-		 * @return a new instance of {@link NestedChangeListener}
+		 * @return a new instance of {@link NestedChangeListenerHandle}
+		 * @see NestedChangeListenerHandle#attach()
 		 */
-		public NestedChangeListener<T> build() {
+		public NestedChangeListenerHandle<T> build() {
+			NestedChangeListenerHandle<T> listenerHandle = buildDetached();
+			listenerHandle.attach();
+			return listenerHandle;
+		}
+
+		/**
+		 * Builds a nested change listener and returns the handle for it.
+		 * <p>
+		 * Note that the listener is not yet {@link NestedChangeListenerHandle#attach() attached}!
+		 * <p>
+		 * This method can only be called once as the same {@link ChangeListener} should not be added more than once to
+		 * the same {@link Nesting}.
+		 *
+		 * @return a new instance of {@link NestedChangeListenerHandle}
+		 * @see #build()
+		 * @see NestedChangeListenerHandle#attach()
+		 */
+		public NestedChangeListenerHandle<T> buildDetached() {
 			if (built)
-				throw new IllegalStateException("This builder can only build one 'NestedChangeListener'.");
+				throw new IllegalStateException("This builder can only build one 'NestedChangeListenerHandle'.");
 
 			built = true;
-			return new NestedChangeListener<T>(nesting, listener);
+			return new NestedChangeListenerHandle<T>(nesting, listener);
 		}
 
 	}

src/main/java/org/codefx/libfx/nesting/listener/NestedChangeListener.java renamed to src/main/java/org/codefx/libfx/nesting/listener/NestedChangeListenerHandle.java

@@ -8,70 +8,106 @@
 import javafx.beans.value.ChangeListener;
 import javafx.beans.value.ObservableValue;
 
-import org.codefx.libfx.nesting.Nested;
 import org.codefx.libfx.nesting.Nesting;
 import org.codefx.libfx.nesting.NestingObserver;
 import org.codefx.libfx.nesting.property.NestedProperty;
 
 /**
- * <p>
  * Contains a {@link ChangeListener} which is connected to a {@link Nesting}. Simply put, the listener is always added
  * to the nesting's inner observable (more precisely, it is added to the {@link ObservableValue} instance contained in
- * the optional value held by the nesting's {@link Nesting#innerObservableProperty() innerObservable} property).
- * <h2>Inner Observable's Value Changes</h2> The listener is added to the nesting's inner observable. So when that
- * observable's value changes, the listener is called as usual.
- * <h2>Inner Observable Is Replaced</h2> When the nesting's inner observable is replaced by another, the listener is
- * removed from the old and added to the new observable. If one of them is missing, the affected removal or add is not
- * performed, which means the listener might not be added to any observable.
+ * the optional value held by the nesting's {@link Nesting#innerObservableProperty() innerObservable} property). <h2>
+ * Inner Observable's Value Changes</h2> The listener is added to the nesting's inner observable. So when that
+ * observable's value changes, the listener is called as usual. <h2>Inner Observable Is Replaced</h2> When the nesting's
+ * inner observable is replaced by another, the listener is removed from the old and added to the new observable. If one
+ * of them is missing, the affected removal or add is not performed, which means the listener might not be added to any
+ * observable.
  * <p>
  * Note that if the observable is replaced, <b>the listener is not called</b>! If this is the desired behavior, a
  * listener has to be added to a {@link NestedProperty}.
  *
  * @param <T>
  *            the type of the value wrapped by the {@link ObservableValue}
  */
-public class NestedChangeListener<T> implements Nested {
+public class NestedChangeListenerHandle<T> implements NestedListenerHandle {
 
 	// #region PROPERTIES
 
+	private final Nesting<? extends ObservableValue<T>> nesting;
+
 	/**
 	 * The property indicating whether the nesting's inner observable is currently present, i.e. not null.
 	 */
 	private final BooleanProperty innerObservablePresent;
 
+	private final ChangeListener<? super T> listener;
+
+	private boolean attached;
+
 	//#end PROPERTIES
 
 	// #region CONSTUCTION
 
 	/**
-	 * Creates a new {@link NestedChangeListener} which adds the specified listener to the specified nesting's inner
-	 * observable.
+	 * Creates a new {@link NestedChangeListenerHandle} which can {@link #attach() attach} the specified listener to the
+	 * specified nesting's inner observable.
+	 * <p>
+	 * The listener is initially detached.
 	 *
 	 * @param nesting
 	 *            the {@link Nesting} to which the listener is added
 	 * @param listener
 	 *            the {@link ChangeListener} which is added to the nesting's {@link Nesting#innerObservableProperty()
 	 *            innerObservable}
 	 */
-	NestedChangeListener(Nesting<? extends ObservableValue<T>> nesting, ChangeListener<? super T> listener) {
+	NestedChangeListenerHandle(Nesting<? extends ObservableValue<T>> nesting, ChangeListener<? super T> listener) {
 		Objects.requireNonNull(nesting, "The argument 'nesting' must not be null.");
 		Objects.requireNonNull(listener, "The argument 'listener' must not be null.");
 
+		this.nesting = nesting;
 		this.innerObservablePresent = new SimpleBooleanProperty(this, "innerObservablePresent");
+		this.listener = listener;
 
 		NestingObserver
 				.forNesting(nesting)
-				.withOldInnerObservable(oldInnerObservable -> oldInnerObservable.removeListener(listener))
-				.withNewInnerObservable(newInnerObservable -> newInnerObservable.addListener(listener))
+				.withOldInnerObservable(this::remove)
+				.withNewInnerObservable(this::addIfAttached)
 				.whenInnerObservableChanges(
-						(Boolean any, Boolean newInnerObservablePresent)
-						-> innerObservablePresent.set(newInnerObservablePresent))
+						(any, newInnerObservablePresent) -> innerObservablePresent.set(newInnerObservablePresent))
 				.observe();
 	}
 
 	//#end CONSTUCTION
 
-	// #region IMPLEMENTATION OF 'Nested'
+	// #region ADD & REMOVE
+
+	private void addIfAttached(ObservableValue<T> observable) {
+		if (attached)
+			observable.addListener(listener);
+	}
+
+	private void remove(ObservableValue<T> observable) {
+		observable.removeListener(listener);
+	}
+
+	// #end ADD & REMOVE
+
+	// #region IMPLEMENTATION OF 'NestedListenerHandle'
+
+	@Override
+	public void attach() {
+		if (!attached) {
+			attached = true;
+			nesting.innerObservableProperty().getValue().ifPresent(this::addIfAttached);
+		}
+	}
+
+	@Override
+	public void detach() {
+		if (attached) {
+			attached = false;
+			nesting.innerObservableProperty().getValue().ifPresent(this::remove);
+		}
+	}
 
 	@Override
 	public ReadOnlyBooleanProperty innerObservablePresentProperty() {
@@ -83,6 +119,6 @@ public boolean isInnerObservablePresent() {
 		return innerObservablePresent.get();
 	}
 
-	//#end IMPLEMENTATION OF 'NestedProperty'
+	//#end IMPLEMENTATION OF 'NestedListenerHandle'
 
 }

src/main/java/org/codefx/libfx/nesting/listener/NestedInvalidationListenerBuilder.java

@@ -7,7 +7,7 @@
 import org.codefx.libfx.nesting.Nesting;
 
 /**
- * A builder for a {@link NestedInvalidationListener}.
+ * A builder for a {@link NestedInvalidationListenerHandle}.
  */
 public class NestedInvalidationListenerBuilder {
 
@@ -105,17 +105,39 @@ private Buildable(NestedInvalidationListenerBuilder builder) {
 		}
 
 		/**
-		 * Builds a nested invalidation listener. This method can only be called once as the same
-		 * {@link InvalidationListener} should not be added more than once to the same {@link Nesting}.
+		 * Builds and {@link NestedInvalidationListenerHandle#attach() attaches} a nested invalidation listener and
+		 * returns the handle for it.
+		 * <p>
+		 * This method can only be called once as the same {@link InvalidationListener} should not be added more than
+		 * once to the same {@link Nesting}.
 		 *
-		 * @return a new instance of {@link NestedChangeListener}
+		 * @return a new instance of {@link NestedInvalidationListenerHandle}
+		 * @see NestedInvalidationListenerHandle#attach()
 		 */
-		public NestedInvalidationListener build() {
+		public NestedInvalidationListenerHandle build() {
+			NestedInvalidationListenerHandle listenerHandle = buildDetached();
+			listenerHandle.attach();
+			return listenerHandle;
+		}
+
+		/**
+		 * Builds a nested invalidation listener and returns the handle for it.
+		 * <p>
+		 * Note that the listener is not yet {@link NestedInvalidationListenerHandle#attach() attached}!
+		 * <p>
+		 * This method can only be called once as the same {@link InvalidationListener} should not be added more than
+		 * once to the same {@link Nesting}.
+		 *
+		 * @return a new instance of {@link NestedInvalidationListenerHandle}
+		 * @see #build()
+		 * @see NestedInvalidationListenerHandle#attach()
+		 */
+		public NestedInvalidationListenerHandle buildDetached() {
 			if (built)
-				throw new IllegalStateException("This builder can only build one 'NestedInvalidationListener'.");
+				throw new IllegalStateException("This builder can only build one 'NestedInvalidationListenerHandle'.");
 
 			built = true;
-			return new NestedInvalidationListener(nesting, listener);
+			return new NestedInvalidationListenerHandle(nesting, listener);
 		}
 
 	}