Factory class 'ListenerHandles' creates handles for observable collections.

Author: nicolaiparlog

src/main/java/org/codefx/libfx/listener/handle/ListenerHandleBuilder.java

@@ -16,6 +16,8 @@
  * This implies that they can be stateless functions which simply add and remove the listener. The functions are called
  * with the observable and listener specified during construction.
  * <p>
+ * The {@link ListenerHandle} returned by this builder is not yet attached.
+ * <p>
  * <h2>Example</h2> A typical use looks like this:
  *
  * <pre>

src/main/java/org/codefx/libfx/listener/handle/ListenerHandles.java

@@ -4,6 +4,14 @@
 import javafx.beans.Observable;
 import javafx.beans.value.ChangeListener;
 import javafx.beans.value.ObservableValue;
+import javafx.collections.ArrayChangeListener;
+import javafx.collections.ListChangeListener;
+import javafx.collections.MapChangeListener;
+import javafx.collections.ObservableArray;
+import javafx.collections.ObservableList;
+import javafx.collections.ObservableMap;
+import javafx.collections.ObservableSet;
+import javafx.collections.SetChangeListener;
 
 /**
  * Factory class for functionality surrounding {@link ListenerHandle}s.
@@ -30,15 +38,16 @@ private ListenerHandles() {
 	 * @param listener
 	 *            the listener which will be added to the {@code observable}
 	 * @return a {@link ListenerHandleBuilder} for a {@code ListenerHandle}.
+	 * @see ListenerHandleBuilder
 	 */
-	public static <O, L> ListenerHandleBuilder<O, L> buildFor(O observable, L listener) {
+	public static <O, L> ListenerHandleBuilder<O, L> createFor(O observable, L listener) {
 		return ListenerHandleBuilder.from(observable, listener);
 	}
 
 	// Observable + InvalidationListener
 
 	/**
-	 * Ands the specified listener to the specified observable and returns a handle for the combination.
+	 * Adds the specified listener to the specified observable and returns a handle for the combination.
 	 *
 	 * @param observable
 	 *            the {@link Observable} to which the {@code invalidationListener} will be added
@@ -72,7 +81,7 @@ public static ListenerHandle createDetached(Observable observable, InvalidationL
 	// ObservableValue + ChangeListener
 
 	/**
-	 * Ands the specified listener to the specified observable and returns a handle for the combination.
+	 * Adds the specified listener to the specified observable value and returns a handle for the combination.
 	 *
 	 * @param <T>
 	 *            the type of the value wrapped by the observable
@@ -91,7 +100,7 @@ public static <T> ListenerHandle create(
 	}
 
 	/**
-	 * Creates a listener handle for the specified observable and listener. The listener is not yet attached!
+	 * Creates a listener handle for the specified observable value and listener. The listener is not yet attached!
 	 *
 	 * @param <T>
 	 *            the type of the value wrapped by the observable
@@ -111,4 +120,176 @@ public static <T> ListenerHandle createDetached(
 				.build();
 	}
 
+	// ObservableArray + ArrayChangeListener
+
+	/**
+	 * Adds the specified listener to the specified observable array and returns a handle for the combination.
+	 *
+	 * @param <T>
+	 *            the type of the array wrapped by the observable
+	 * @param observableArray
+	 *            the {@link ObservableArray} to which the {@code changeListener} will be added
+	 * @param changeListener
+	 *            the {@link ArrayChangeListener} which will be added to the {@code observableArray}
+	 * @return a {@link ListenerHandle} for the specified arguments; the listener is initially attached
+	 */
+	public static <T extends ObservableArray<T>> ListenerHandle create(
+			ObservableArray<T> observableArray, ArrayChangeListener<T> changeListener) {
+
+		ListenerHandle handle = createDetached(observableArray, changeListener);
+		handle.attach();
+		return handle;
+	}
+
+	/**
+	 * Creates a listener handle for the specified observable array and listener. The listener is not yet attached!
+	 *
+	 * @param <T>
+	 *            the type of the array wrapped by the observable
+	 * @param observableArray
+	 *            the {@link ObservableArray} to which the {@code changeListener} will be added
+	 * @param changeListener
+	 *            the {@link ArrayChangeListener} which will be added to the {@code observableArray}
+	 * @return a {@link ListenerHandle} for the specified arguments; the listener is initially detached
+	 */
+	public static <T extends ObservableArray<T>> ListenerHandle createDetached(
+			ObservableArray<T> observableArray, ArrayChangeListener<T> changeListener) {
+
+		return ListenerHandleBuilder
+				.from(observableArray, changeListener)
+				.onAttach((observable, listener) -> observable.addListener(listener))
+				.onDetach((observable, listener) -> observable.removeListener(listener))
+				.build();
+	}
+
+	// ObservableList + ListChangeListener
+
+	/**
+	 * Adds the specified listener to the specified observable list and returns a handle for the combination.
+	 *
+	 * @param <E>
+	 *            the list element type
+	 * @param observableList
+	 *            the {@link ObservableList} to which the {@code changeListener} will be added
+	 * @param changeListener
+	 *            the {@link ListChangeListener} which will be added to the {@code observableList}
+	 * @return a {@link ListenerHandle} for the specified arguments; the listener is initially attached
+	 */
+	public static <E> ListenerHandle create(
+			ObservableList<E> observableList, ListChangeListener<? super E> changeListener) {
+
+		ListenerHandle handle = createDetached(observableList, changeListener);
+		handle.attach();
+		return handle;
+	}
+
+	/**
+	 * Creates a listener handle for the specified observable list and listener. The listener is not yet attached!
+	 *
+	 * @param <E>
+	 *            the list element type
+	 * @param observableList
+	 *            the {@link ObservableList} to which the {@code changeListener} will be added
+	 * @param changeListener
+	 *            the {@link ListChangeListener} which will be added to the {@code observableList}
+	 * @return a {@link ListenerHandle} for the specified arguments; the listener is initially detached
+	 */
+	public static <E> ListenerHandle createDetached(
+			ObservableList<E> observableList, ListChangeListener<? super E> changeListener) {
+
+		return ListenerHandleBuilder
+				.from(observableList, changeListener)
+				.onAttach((observable, listener) -> observable.addListener(listener))
+				.onDetach((observable, listener) -> observable.removeListener(listener))
+				.build();
+	}
+
+	// ObservableSet + SetChangeListener
+
+	/**
+	 * Adds the specified listener to the specified observable set and returns a handle for the combination.
+	 *
+	 * @param <E>
+	 *            the set element type
+	 * @param observableSet
+	 *            the {@link ObservableSet} to which the {@code changeListener} will be added
+	 * @param changeListener
+	 *            the {@link SetChangeListener} which will be added to the {@code observableSet}
+	 * @return a {@link ListenerHandle} for the specified arguments; the listener is initially attached
+	 */
+	public static <E> ListenerHandle create(
+			ObservableSet<E> observableSet, SetChangeListener<? super E> changeListener) {
+
+		ListenerHandle handle = createDetached(observableSet, changeListener);
+		handle.attach();
+		return handle;
+	}
+
+	/**
+	 * Creates a listener handle for the specified observable set and listener. The listener is not yet attached!
+	 *
+	 * @param <E>
+	 *            the set element type
+	 * @param observableSet
+	 *            the {@link ObservableSet} to which the {@code changeListener} will be added
+	 * @param changeListener
+	 *            the {@link SetChangeListener} which will be added to the {@code observableSet}
+	 * @return a {@link ListenerHandle} for the specified arguments; the listener is initially detached
+	 */
+	public static <E> ListenerHandle createDetached(
+			ObservableSet<E> observableSet, SetChangeListener<? super E> changeListener) {
+
+		return ListenerHandleBuilder
+				.from(observableSet, changeListener)
+				.onAttach((observable, listener) -> observable.addListener(listener))
+				.onDetach((observable, listener) -> observable.removeListener(listener))
+				.build();
+	}
+
+	// ObservableMap + MapChangeListener
+
+	/**
+	 * Adds the specified listener to the specified observable map and returns a handle for the combination.
+	 *
+	 * @param <K>
+	 *            the map key element type
+	 * @param <V>
+	 *            the map value element type
+	 * @param observableMap
+	 *            the {@link ObservableMap} to which the {@code changeListener} will be added
+	 * @param changeListener
+	 *            the {@link MapChangeListener} which will be added to the {@code observableMap}
+	 * @return a {@link ListenerHandle} for the specified arguments; the listener is initially attached
+	 */
+	public static <K, V> ListenerHandle create(
+			ObservableMap<K, V> observableMap, MapChangeListener<? super K, ? super V> changeListener) {
+
+		ListenerHandle handle = createDetached(observableMap, changeListener);
+		handle.attach();
+		return handle;
+	}
+
+	/**
+	 * Creates a listener handle for the specified observable map and listener. The listener is not yet attached!
+	 *
+	 * @param <K>
+	 *            the map key element type
+	 * @param <V>
+	 *            the map value element type
+	 * @param observableMap
+	 *            the {@link ObservableMap} to which the {@code changeListener} will be added
+	 * @param changeListener
+	 *            the {@link MapChangeListener} which will be added to the {@code observableMap}
+	 * @return a {@link ListenerHandle} for the specified arguments; the listener is initially detached
+	 */
+	public static <K, V> ListenerHandle createDetached(
+			ObservableMap<K, V> observableMap, MapChangeListener<? super K, ? super V> changeListener) {
+
+		return ListenerHandleBuilder
+				.from(observableMap, changeListener)
+				.onAttach((observable, listener) -> observable.addListener(listener))
+				.onDetach((observable, listener) -> observable.removeListener(listener))
+				.build();
+	}
+
 }