Nested listeners implement 'ListenerHandle' contract. This is now fully documented and tested.

Author: nicolaiparlog

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

@@ -32,15 +32,24 @@ public class NestedChangeListenerHandle<T> implements NestedListenerHandle {
 
 	// #region PROPERTIES
 
+	/**
+	 * The {@link Nesting} to whose inner observable the {@link #listener} is attached.
+	 */
 	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;
 
+	/**
+	 * The {@link ChangeListener} which is added to the {@link #nesting}'s inner observable.
+	 */
 	private final ChangeListener<? super T> listener;
 
+	/**
+	 * Indicates whether the {@link #listener} is currently attached to the {@link #nesting}'s inner observable.
+	 */
 	private boolean attached;
 
 	//#end PROPERTIES
@@ -80,11 +89,23 @@ public class NestedChangeListenerHandle<T> implements NestedListenerHandle {
 
 	// #region ADD & REMOVE
 
+	/**
+	 * Adds the {@link #listener} to the specified observable, when indicated by {@link #attached}.
+	 *
+	 * @param observable
+	 *            the {@link ObservableValue} to which the listener will be added
+	 */
 	private void addIfAttached(ObservableValue<T> observable) {
 		if (attached)
 			observable.addListener(listener);
 	}
 
+	/**
+	 * Removes the {@link #listener} from the specified observable.
+	 * 
+	 * @param observable
+	 *            the {@link ObservableValue} from which the listener will be removed.
+	 */
 	private void remove(ObservableValue<T> observable) {
 		observable.removeListener(listener);
 	}

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

@@ -29,15 +29,24 @@ public class NestedInvalidationListenerHandle implements NestedListenerHandle {
 
 	// #region PROPERTIES
 
+	/**
+	 * The {@link Nesting} to whose inner observable the {@link #listener} is attached.
+	 */
 	private final Nesting<? extends Observable> nesting;
 
 	/**
 	 * The property indicating whether the nesting's inner observable is currently present, i.e. not null.
 	 */
 	private final BooleanProperty innerObservablePresent;
 
+	/**
+	 * The {@link InvalidationListener} which is added to the {@link #nesting}'s inner observable.
+	 */
 	private final InvalidationListener listener;
 
+	/**
+	 * Indicates whether the {@link #listener} is currently attached to the {@link #nesting}'s inner observable.
+	 */
 	private boolean attached;
 
 	//#end PROPERTIES
@@ -75,11 +84,23 @@ public class NestedInvalidationListenerHandle implements NestedListenerHandle {
 
 	// #region ADD & REMOVE
 
+	/**
+	 * Adds the {@link #listener} to the specified observable, when indicated by {@link #attached}.
+	 *
+	 * @param observable
+	 *            the {@link Observable} to which the listener will be added
+	 */
 	private void addIfAttached(Observable observable) {
 		if (attached)
 			observable.addListener(listener);
 	}
 
+	/**
+	 * Removes the {@link #listener} from the specified observable.
+	 *
+	 * @param observable
+	 *            the {@link Observable} from which the listener will be removed.
+	 */
 	private void remove(Observable observable) {
 		observable.removeListener(listener);
 	}

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

@@ -3,6 +3,13 @@
 import org.codefx.libfx.listener.ListenerHandle;
 import org.codefx.libfx.nesting.Nested;
 
+/**
+ * A {@link ListenerHandle} for a listener added to the inner observable of a {@link org.codefx.libfx.nesting.Nesting
+ * Nesting}.
+ * 
+ * @see Nested
+ * @see ListenerHandle
+ */
 public interface NestedListenerHandle extends Nested, ListenerHandle {
-
+	// no additional methods defined
 }

src/test/java/org/codefx/libfx/nesting/listener/AbstractNestedChangeListenerBuilderTest.java

@@ -34,6 +34,9 @@ public void setUp() {
 	/**
 	 * Creates the tested builder. Each call must return a new instance
 	 *
+	 * @param <T>
+	 *            the value wrapped by the nesting's inner observable, which is also the type observed by the change
+	 *            listener
 	 * @return a {@link NestedChangeListenerBuilder}
 	 */
 	protected abstract <T> NestedChangeListenerBuilder<T, Property<T>> createBuilder();

src/test/java/org/codefx/libfx/nesting/listener/AbstractNestedChangeListenerHandleTest.java

@@ -6,11 +6,11 @@
 import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertSame;
 import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.fail;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.times;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.verifyNoMoreInteractions;
-import static org.mockito.Mockito.verifyZeroInteractions;
 import javafx.beans.property.SimpleStringProperty;
 import javafx.beans.property.StringProperty;
 import javafx.beans.value.ChangeListener;
@@ -40,10 +40,15 @@ public abstract class AbstractNestedChangeListenerHandleTest {
 	private NestingAccess.EditableNesting<StringProperty> nesting;
 
 	/**
-	 * The added listener. This {@link ChangeListener} will be mocked to verify possible invocations.
+	 * The default listener. This {@link ChangeListener} will be mocked to verify invocations.
 	 */
 	private ChangeListener<String> listener;
 
+	/**
+	 * A listener which fails the test when being called.
+	 */
+	private ChangeListener<String> listenerWhichFailsWhenCalled;
+
 	/**
 	 * The tested nested listener, which adds the {@link #listener} to the {@link #nesting}.
 	 */
@@ -65,11 +70,15 @@ public void setUp() {
 		innerObservable = new SimpleStringProperty("initial value");
 		nesting = NestingAccess.EditableNesting.createWithInnerObservable(innerObservable);
 		listener = mock(ChangeListener.class);
+		listenerWhichFailsWhenCalled = (obs, oldValue, newValue) -> fail();
 	}
 
 	/**
 	 * Creates a new, initially attached nested listener from the specified nesting and listener.
 	 *
+	 * @param <T>
+	 *            the value wrapped by the nesting's inner observable, which is also the type observed by the change
+	 *            listener
 	 * @param nesting
 	 *            the {@link Nesting} to which the listener will be added
 	 * @param listener
@@ -85,6 +94,9 @@ private <T> NestedChangeListenerHandle<T> createAttachedNestedListenerHandle(
 	/**
 	 * Creates a new, initially detached nested listener from the specified nesting and listener.
 	 *
+	 * @param <T>
+	 *            the value wrapped by the nesting's inner observable, which is also the type observed by the change
+	 *            listener
 	 * @param nesting
 	 *            the {@link Nesting} to which the listener will be added
 	 * @param listener
@@ -100,10 +112,15 @@ private <T> NestedChangeListenerHandle<T> createDetachedNestedListenerHandle(
 	/**
 	 * Creates a new nested listener from the specified nesting and listener.
 	 *
+	 * @param <T>
+	 *            the value wrapped by the nesting's inner observable, which is also the type observed by the change
+	 *            listener
 	 * @param nesting
 	 *            the {@link Nesting} to which the listener will be added
 	 * @param listener
 	 *            the {@link ChangeListener} which will be added to the nesting
+	 * @param attachedOrDetached
+	 *            indicates whether the listener will be initially attached or detached
 	 * @return a new {@link NestedChangeListenerHandle}
 	 */
 	protected abstract <T> NestedChangeListenerHandle<T> createNestedListenerHandle(
@@ -140,11 +157,8 @@ public void testObservablePresentAfterConstruction() {
 	 */
 	@Test
 	public void testNoInteractionWithListenerDuringConstruction() {
-		nestedListenerHandle = createDetachedNestedListenerHandle(nesting, listener);
-		verifyZeroInteractions(listener);
-
-		nestedListenerHandle = createAttachedNestedListenerHandle(nesting, listener);
-		verifyZeroInteractions(listener);
+		nestedListenerHandle = createDetachedNestedListenerHandle(nesting, listenerWhichFailsWhenCalled);
+		nestedListenerHandle = createAttachedNestedListenerHandle(nesting, listenerWhichFailsWhenCalled);
 	}
 
 	// changing value
@@ -155,10 +169,8 @@ public void testNoInteractionWithListenerDuringConstruction() {
 	 */
 	@Test
 	public void testChangingValueWhenInitiallyDetached() {
-		nestedListenerHandle = createDetachedNestedListenerHandle(nesting, listener);
+		nestedListenerHandle = createDetachedNestedListenerHandle(nesting, listenerWhichFailsWhenCalled);
 		innerObservable.set("new value");
-
-		verifyZeroInteractions(listener);
 	}
 
 	/**
@@ -174,50 +186,29 @@ public void testChangingValue() {
 		verifyNoMoreInteractions(listener);
 	}
 
-	/**
-	 * Tests whether no listener invocation occurs when the nesting's inner observable's value is changed after the
-	 * listener was detached.
-	 */
-	@Test
-	public void testChangingValueAfterDetach() {
-		nestedListenerHandle = createAttachedNestedListenerHandle(nesting, listener);
-		// change something while attached
-		innerObservable.set("new value");
-
-		// detach and change something
-		nestedListenerHandle.detach();
-		innerObservable.set("new value while detached");
-
-		// assert that 'changed' was called only once
-		verify(listener, times(1)).changed(innerObservable, "initial value", "new value");
-		verifyNoMoreInteractions(listener);
-	}
-
 	// changing observable
 
 	/**
 	 * Tests whether no listener invocation occurs when the nesting's inner observable is changed.
 	 */
 	@Test
 	public void testChangingObservable() {
-		nestedListenerHandle = createAttachedNestedListenerHandle(nesting, listener);
+		nestedListenerHandle = createAttachedNestedListenerHandle(nesting, listenerWhichFailsWhenCalled);
 		StringProperty newObservable = new SimpleStringProperty("new observable's initial value");
 		setNestingObservable(nesting, newObservable);
 
 		assertTrue(nestedListenerHandle.isInnerObservablePresent());
-		verifyZeroInteractions(listener);
 	}
 
 	/**
 	 * Tests whether no listener invocation occurs when the nesting's inner observable is changed to null.
 	 */
 	@Test
 	public void testChangingObservableToNull() {
-		nestedListenerHandle = createAttachedNestedListenerHandle(nesting, listener);
+		nestedListenerHandle = createAttachedNestedListenerHandle(nesting, listenerWhichFailsWhenCalled);
 		setNestingObservable(nesting, null);
 
 		assertFalse(nestedListenerHandle.isInnerObservablePresent());
-		verifyZeroInteractions(listener);
 	}
 
 	// changing observable and value
@@ -248,7 +239,7 @@ public void testChangingNewObservablesValue() {
 	 */
 	@Test
 	public void testChangingOldObservablesValue() {
-		nestedListenerHandle = createAttachedNestedListenerHandle(nesting, listener);
+		nestedListenerHandle = createAttachedNestedListenerHandle(nesting, listenerWhichFailsWhenCalled);
 		// set a new observable ...
 		StringProperty newObservable = new SimpleStringProperty("new observable's initial value");
 		setNestingObservable(nesting, newObservable);
@@ -257,9 +248,65 @@ public void testChangingOldObservablesValue() {
 
 		// ... and change the old observable's value
 		innerObservable.setValue("intial observable's new value");
+	}
+
+	// attach & detach
+
+	/**
+	 * Tests whether no listener invocation occurs when the nesting's inner observable's value is changed after the
+	 * listener was detached.
+	 */
+	@Test
+	public void testDetach() {
+		nestedListenerHandle = createAttachedNestedListenerHandle(nesting, listenerWhichFailsWhenCalled);
+		nestedListenerHandle.detach();
+
+		innerObservable.set("new value while detached");
+	}
+
+	/**
+	 * Tests whether the listener ignores values after it was detached repeatedly.
+	 */
+	@Test
+	public void testMultipleDetach() {
+		nestedListenerHandle = createAttachedNestedListenerHandle(nesting, listenerWhichFailsWhenCalled);
+		nestedListenerHandle.detach();
+		nestedListenerHandle.detach();
+		nestedListenerHandle.detach();
+
+		innerObservable.set("new value while detached");
+	}
 
-		// assert the listener was not invoked
-		verifyZeroInteractions(listener);
+	/**
+	 * Tests whether the listener is correctly invoked when the nesting's observable changes its value after the
+	 * listener was detached and reattached.
+	 */
+	@Test
+	public void testReattach() {
+		nestedListenerHandle = createAttachedNestedListenerHandle(nesting, listener);
+		nestedListenerHandle.detach();
+		nestedListenerHandle.attach();
+		innerObservable.set("new value");
+
+		// assert that 'changed' was called once and with the right arguments
+		verify(listener, times(1)).changed(innerObservable, "initial value", "new value");
+		verifyNoMoreInteractions(listener);
+	}
+
+	/**
+	 * Tests whether the listener is only called once even when attached is called repeatedly.
+	 */
+	@Test
+	public void testMultipleAttach() {
+		nestedListenerHandle = createAttachedNestedListenerHandle(nesting, listener);
+		nestedListenerHandle.attach();
+		nestedListenerHandle.attach();
+		nestedListenerHandle.attach();
+		innerObservable.set("new value");
+
+		// assert that 'changed' was called only once
+		verify(listener, times(1)).changed(innerObservable, "initial value", "new value");
+		verifyNoMoreInteractions(listener);
 	}
 
 	//#end TESTS