Implemented a generic 'ListenerHandle'.

Author: nicolaiparlog

src/main/java/org/codefx/libfx/listener/GenericListenerHandle.java

@@ -0,0 +1,99 @@
+package org.codefx.libfx.listener;
+
+import java.util.Objects;
+import java.util.function.BiConsumer;
+
+/**
+ * A generic implementation of {@link ListenerHandle} which uses functions specified during construction to
+ * {@link #attach()} and {@link #detach()} the listener to the observable instance.
+ *
+ * @param <O>
+ *            the type of the observable instance (e.g {@link javafx.beans.value.ObservableValue ObservableValue} or
+ *            {@link javafx.collections.ObservableMap ObservableMap}) to which the listener will be added
+ * @param <L>
+ *            the type of the listener which will be added to the observable
+ */
+final class GenericListenerHandle<O, L> implements ListenerHandle {
+
+	// #region FIELDS
+
+	/**
+	 * The observable instance to which the {@link #listener} will be added.
+	 */
+	private final O observable;
+
+	/**
+	 * The listener which will be added to the {@link #observable}.
+	 */
+	private final L listener;
+
+	/**
+	 * Called on {@link #attach()}.
+	 */
+	private final BiConsumer<? super O, ? super L> add;
+
+	/**
+	 * Called on {@link #detach()}.
+	 */
+	private final BiConsumer<? super O, ? super L> remove;
+
+	/**
+	 * Indicates whether the {@link #listener} is currently added to the {@link #observable}.
+	 */
+	private boolean attached;
+
+	// #end FIELDS
+
+	// #region CONSTRUCITON
+
+	/**
+	 * Creates a new listener handle for the specified arguments. The listener is initially detached.
+	 *
+	 * @param observable
+	 *            the observable instance to which the {@code listener} will be added
+	 * @param listener
+	 *            the listener which will be added to the {@code observable}
+	 * @param add
+	 *            called when the {@code listener} must be added to the {@code observable}
+	 * @param remove
+	 *            called when the {@code listener} must be removed from the {@code observable}
+	 */
+	public GenericListenerHandle(
+			O observable, L listener, BiConsumer<? super O, ? super L> add, BiConsumer<? super O, ? super L> remove) {
+
+		Objects.requireNonNull(observable, "The argument 'observable' must not be null.");
+		Objects.requireNonNull(listener, "The argument 'listener' must not be null.");
+		Objects.requireNonNull(add, "The argument 'add' must not be null.");
+		Objects.requireNonNull(remove, "The argument 'remove' must not be null.");
+
+		this.observable = observable;
+		this.listener = listener;
+		this.add = add;
+		this.remove = remove;
+	}
+
+	// #end CONSTRUCITON
+
+	// #region IMPLEMENTATION OF 'ListenerHandle'
+
+	@Override
+	public void attach() {
+		if (attached)
+			return;
+
+		attached = true;
+		add.accept(observable, listener);
+	}
+
+	@Override
+	public void detach() {
+		if (!attached)
+			return;
+
+		attached = false;
+		remove.accept(observable, listener);
+	}
+
+	// #end IMPLEMENTATION OF 'ListenerHandle'
+
+}

src/test/java/org/codefx/libfx/listener/GenericListenerHandleTest.java

@@ -0,0 +1,163 @@
+package org.codefx.libfx.listener;
+
+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 java.util.function.BiConsumer;
+
+import org.junit.Before;
+import org.junit.Test;
+
+/**
+ * Tests the class {@link GenericListenerHandle}.
+ */
+public class GenericListenerHandleTest {
+
+	// #region INSTANCES
+
+	/**
+	 * The tested handle.
+	 */
+	private GenericListenerHandle<Object, Object> handle;
+
+	/**
+	 * The observable on which the {@link #handle} operates.
+	 */
+	private Object observable;
+
+	/**
+	 * The listener on which the {@link #handle} operates.
+	 */
+	private Object listener;
+
+	/**
+	 * The function which adds the listener to the observable. This is a mock so calls can be verified.
+	 */
+	private BiConsumer<Object, Object> add;
+
+	/**
+	 * The function which adds the listener to the observable. This is a mock so calls can be verified.
+	 */
+	private BiConsumer<Object, Object> remove;
+
+	// #end INSTANCES
+
+	// #region SETUP
+
+	/**
+	 * Creates the tested instances.
+	 */
+	@Before
+	@SuppressWarnings("unchecked")
+	public void setUp() {
+		add = mock(BiConsumer.class);
+		remove = mock(BiConsumer.class);
+		observable = "observable";
+		listener = "listner";
+
+		handle = new GenericListenerHandle<Object, Object>(observable, listener, add, remove);
+	}
+
+	// #end SETUP
+
+	// #region TESTS
+
+	/**
+	 * Tests whether the construction of the handle does not cause any calls to {@link #add} and {@link #remove}.
+	 */
+	@Test
+	public void testNoCallsToAddAndRemoveOnConstruction() {
+		verifyZeroInteractions(add, remove);
+	}
+
+	/**
+	 * Tests whether the a call to {@link ListenerHandle#detach() detach()} after construction does not cause any calls
+	 * to {@link #add} and {@link #remove}.
+	 */
+	@Test
+	public void testDetachAfterConstruction() {
+		handle.detach();
+
+		verifyZeroInteractions(add, remove);
+	}
+
+	/**
+	 * Tests whether the first call to {@link ListenerHandle#attach() attach()} correctly calls {@link #add}.
+	 */
+	@Test
+	public void testAttachAfterConstruction() {
+		handle.attach();
+
+		verify(add, times(1)).accept(observable, listener);
+		verifyNoMoreInteractions(add);
+		verifyZeroInteractions(remove);
+	}
+
+	/**
+	 * Tests whether calling {@link ListenerHandle#attach() attach()} multiple times in a row calls {@link #add} only
+	 * once.
+	 */
+	@Test
+	public void testMultipleAttach() {
+		handle.attach();
+		handle.attach();
+		handle.attach();
+
+		verify(add, times(1)).accept(observable, listener);
+		verifyNoMoreInteractions(add);
+		verifyZeroInteractions(remove);
+	}
+
+	/**
+	 * Tests whether calling {@link ListenerHandle#detach() detach()} correctly calls {@link #remove}.
+	 */
+	@Test
+	public void testDetach() {
+		handle.attach();
+		handle.detach();
+
+		// the order of those calls is not verified here;
+		// but if it would not match the intuition (first 'add', then 'remove'), a more specific test above would fail
+		verify(add, times(1)).accept(observable, listener);
+		verify(remove, times(1)).accept(observable, listener);
+		verifyNoMoreInteractions(add, remove);
+	}
+
+	/**
+	 * Tests whether calling {@link ListenerHandle#detach() detach()} multiple times in a row calls {@link #remove} only
+	 * once.
+	 */
+	@Test
+	public void testMultipleDetach() {
+		handle.attach();
+		handle.detach();
+		handle.detach();
+		handle.detach();
+
+		verify(add, times(1)).accept(observable, listener);
+		verify(remove, times(1)).accept(observable, listener);
+		verifyZeroInteractions(remove);
+	}
+
+	/**
+	 * Tests whether reattaching calls {@link #add} twice.
+	 */
+	@Test
+	public void testReattach() {
+		handle.attach();
+		handle.detach();
+		handle.attach();
+
+		// the order of those calls is not verified here;
+		// but if it would not match the intuition ('add', 'remove', 'add'), a more specific test above would fail
+		verify(add, times(2)).accept(observable, listener);
+		verify(remove, times(1)).accept(observable, listener);
+		verifyNoMoreInteractions(add, remove);
+	}
+
+	// #end TESTS
+
+}