Adapted control property listening to implement 'ListenerHandle'.

Author: nicolaiparlog

src/demo/java/org/codefx/libfx/control/ControlPropertyListenerDemo.java

@@ -6,11 +6,12 @@
 import javafx.collections.ObservableMap;
 
 import org.codefx.libfx.control.properties.ControlProperties;
-import org.codefx.libfx.control.properties.ControlPropertyListener;
+import org.codefx.libfx.control.properties.ControlPropertyListenerHandle;
 
 /**
- * Demonstrates how to use the {@link ControlPropertyListener} and its builder.
+ * Demonstrates how to use the {@link ControlPropertyListenerHandle} and its builder.
  */
+@SuppressWarnings("static-method")
 public class ControlPropertyListenerDemo {
 
 	// #region CONSTRUCTION & MAIN
@@ -29,13 +30,15 @@ private ControlPropertyListenerDemo() {
 	 *            command line arguments (will not be used)
 	 */
 	public static void main(String[] args) {
-		simpleCase();
-		attachAndDetach();
+		ControlPropertyListenerDemo demo = new ControlPropertyListenerDemo();
 
-		timeNoTypeCheck();
-		timeWithTypeCheck();
+		demo.simpleCase();
+		demo.attachAndDetach();
 
-		castVsTypeChecking();
+		demo.timeNoTypeCheck();
+		demo.timeWithTypeCheck();
+
+		demo.castVsTypeChecking();
 	}
 
 	// #end CONSTRUCTION & MAIN
@@ -45,14 +48,14 @@ public static void main(String[] args) {
 	/**
 	 * Demonstrates the simple case, in which a value processor is added for some key.
 	 */
-	public static void simpleCase() {
+	private void simpleCase() {
 		ObservableMap<Object, Object> properties = FXCollections.observableHashMap();
 
 		// build and attach the listener
 		ControlProperties.<String> on(properties)
 				.forKey("Key")
 				.processValue(value -> System.out.println(" -> " + value))
-				.buildAndAttach();
+				.build();
 
 		// set values of the correct type for the correct key
 		System.out.print("Set \"Value\" for the correct key for the first time: ");
@@ -74,14 +77,14 @@ ControlProperties.<String> on(properties)
 	/**
 	 * Demonstrates how a listener can be attached and detached.
 	 */
-	private static void attachAndDetach() {
+	private void attachAndDetach() {
 		ObservableMap<Object, Object> properties = FXCollections.observableHashMap();
 
 		// build the listener (but don't attach it yet) and assign it to a variable
-		ControlPropertyListener listener = ControlProperties.<String> on(properties)
+		ControlPropertyListenerHandle listener = ControlProperties.<String> on(properties)
 				.forKey("Key")
 				.processValue(value -> System.out.println(" -> " + value))
-				.build();
+				.buildDetached();
 
 		// set a value when the listener is not yet attached
 		System.out.println(
@@ -105,7 +108,7 @@ private static void attachAndDetach() {
 	/**
 	 * Measures the time it takes to get a lot of {@link ClassCastException}.
 	 */
-	private static void timeNoTypeCheck() {
+	private void timeNoTypeCheck() {
 		ObservableMap<Object, Object> properties = FXCollections.observableHashMap();
 
 		Consumer<String> unreached = value -> {
@@ -116,7 +119,7 @@ private static void timeNoTypeCheck() {
 		ControlProperties.<String> on(properties)
 				.forKey("Key")
 				.processValue(unreached)
-				.buildAndAttach();
+				.build();
 
 		// add a couple of values of the wrong type to average the time that takes
 		Integer valueOfWrongType = 5;
@@ -136,7 +139,7 @@ ControlProperties.<String> on(properties)
 	/**
 	 * Demonstrates how type checking increases performance if values of an incorrect type are added frequently.
 	 */
-	private static void timeWithTypeCheck() {
+	private void timeWithTypeCheck() {
 		ObservableMap<Object, Object> properties = FXCollections.observableHashMap();
 
 		Consumer<String> unreached = value -> {
@@ -148,7 +151,7 @@ ControlProperties.<String> on(properties)
 				.forKey("Key")
 				.forValueType(String.class)
 				.processValue(unreached)
-				.buildAndAttach();
+				.build();
 
 		// add a couple of values of the wrong type to average the time that takes
 		Integer valueOfWrongType = 5;
@@ -174,7 +177,7 @@ ControlProperties.<String> on(properties)
 	 * Some days later: I ran this again and discovered that the time difference is now very measurable and looks
 	 * correct. Perhaps some JVM optimization because I ran it so often?
 	 */
-	private static void castVsTypeChecking() {
+	private void castVsTypeChecking() {
 		int runs = (int) 1e5;
 		Object integer = 3;
 

src/main/java/org/codefx/libfx/control/properties/AbstractControlPropertyListener.java renamed to src/main/java/org/codefx/libfx/control/properties/AbstractControlPropertyListenerHandle.java

@@ -6,10 +6,10 @@
 import javafx.collections.ObservableMap;
 
 /**
- * Abstract superclass to implementations of {@link ControlPropertyListener}. Handles all aspects of listening except
- * the actual processing of the value which is delegated to the implementations.
+ * Abstract superclass to implementations of {@link ControlPropertyListenerHandle}. Handles all aspects of listening
+ * except the actual processing of the value which is delegated to the implementations.
  */
-abstract class AbstractControlPropertyListener implements ControlPropertyListener {
+abstract class AbstractControlPropertyListenerHandle implements ControlPropertyListenerHandle {
 
 	// #region ATTRIBUTES
 
@@ -33,14 +33,14 @@ abstract class AbstractControlPropertyListener implements ControlPropertyListene
 	// #region CONSTRUCTION
 
 	/**
-	 * Creates a new listener.
+	 * Creates a new listener handle. Initially detached.
 	 *
 	 * @param properties
 	 *            the {@link ObservableMap} holding the properties
 	 * @param key
 	 *            the key to which the listener will listen
 	 */
-	protected AbstractControlPropertyListener(
+	protected AbstractControlPropertyListenerHandle(
 			ObservableMap<Object, Object> properties, Object key) {
 
 		Objects.requireNonNull(properties, "The argument 'properties' must not be null.");
@@ -93,10 +93,11 @@ private void processAndRemoveValue(Object value) {
 
 	// #end PROCESS VALUE
 
-	// #region IMPLEMENTATION OF 'ControlPropertyListener'
+	// #region IMPLEMENTATION OF 'ControlPropertyListenerHandle'
 
 	@Override
 	public void attach() {
+		// TODO under threading this can lead to processing the same value twice.
 		properties.addListener(listener);
 		if (properties.containsKey(key))
 			processAndRemoveValue(properties.get(key));
@@ -107,6 +108,6 @@ public void detach() {
 		properties.removeListener(listener);
 	}
 
-	// #end IMPLEMENTATION OF 'ControlPropertyListener'
+	// #end IMPLEMENTATION OF 'ControlPropertyListenerHandle'
 
 }

src/main/java/org/codefx/libfx/control/properties/CastingControlPropertyListener.java renamed to src/main/java/org/codefx/libfx/control/properties/CastingControlPropertyListenerHandle.java

@@ -6,21 +6,21 @@
 import javafx.collections.ObservableMap;
 
 /**
- * Implementation of {@link ControlPropertyListener} which optimistically casts all values to the expected type. If that
- * does not work, the {@link ClassCastException} is caught and ignored.
+ * Implementation of {@link ControlPropertyListenerHandle} which optimistically casts all values to the expected type.
+ * If that does not work, the {@link ClassCastException} is caught and ignored.
  *
  * @param <T>
  *            the type of values which the listener processes
  */
-final class CastingControlPropertyListener<T> extends AbstractControlPropertyListener {
+final class CastingControlPropertyListenerHandle<T> extends AbstractControlPropertyListenerHandle {
 
 	/**
 	 * The user specified processor for values.
 	 */
 	private final Consumer<? super T> valueProcessor;
 
 	/**
-	 * Creates a new listener.
+	 * Creates a new listener handle. Initially detached.
 	 *
 	 * @param properties
 	 *            the {@link ObservableMap} holding the properties
@@ -29,7 +29,7 @@ final class CastingControlPropertyListener<T> extends AbstractControlPropertyLis
 	 * @param valueProcessor
 	 *            the {@link Consumer} for the key's values
 	 */
-	CastingControlPropertyListener(
+	CastingControlPropertyListenerHandle(
 			ObservableMap<Object, Object> properties, Object key, Consumer<? super T> valueProcessor) {
 
 		super(properties, key);

src/main/java/org/codefx/libfx/control/properties/ControlProperties.java

@@ -8,7 +8,7 @@
 public class ControlProperties {
 
 	/**
-	 * Creates a builder for a {@link ControlPropertyListener} which observes the specified property map.
+	 * Creates a builder for a {@link ControlPropertyListenerHandle} which observes the specified property map.
 	 * <p>
 	 * Note that it is often necessary to explicitly specify the type parameter {@code T} like so:
 	 * 

src/main/java/org/codefx/libfx/control/properties/ControlPropertyListenerBuilder.java

@@ -7,11 +7,12 @@
 import javafx.collections.ObservableMap;
 
 /**
- * A builder for {@link ControlPropertyListener}.
+ * A builder for a {@code ControlPropertyListener}. This is no type on its own as explained in
+ * {@link ControlPropertyListenerHandle}. Such a handle is returned by this builder.
  * <p>
  * It is best created by calling {@link ControlProperties#on(ObservableMap)} with the control's property map as an
  * argument. It is necessary to set a key (with {@link #forKey(Object)}) and a processor function for the value (with
- * {@link #processValue(Consumer)}) before calling {@link #build()}.
+ * {@link #processValue(Consumer)}) before calling {@link #buildDetached()}.
  * <p>
  * Specifying the value's type with {@link #forValueType(Class)} is optional. If it is done, the built listener will use
  * it to check the type of the value before casting it to the type accepted by the value processor. If those types do
@@ -31,12 +32,12 @@ public class ControlPropertyListenerBuilder<T> {
 	private final ObservableMap<Object, Object> properties;
 
 	/**
-	 * The key to which the listener will listen; must no be null by the time {@link #build()} is called.
+	 * The key to which the listener will listen; must no be null by the time {@link #buildDetached()} is called.
 	 */
 	private Object key;
 
 	/**
-	 * The processor of the key's values; must no be null by the time {@link #build()} is called.
+	 * The processor of the key's values; must no be null by the time {@link #buildDetached()} is called.
 	 */
 	private Consumer<? super T> valueProcessor;
 
@@ -62,7 +63,7 @@ public ControlPropertyListenerBuilder(ObservableMap<Object, Object> properties)
 	}
 
 	/**
-	 * Sets the key. This must be called before {@link #build()}.
+	 * Sets the key. This must be called before {@link #buildDetached()}.
 	 *
 	 * @param key
 	 *            the key the built listener will observe
@@ -108,36 +109,39 @@ public ControlPropertyListenerBuilder<T> processValue(Consumer<? super T> valueP
 	// #region BUILD
 
 	/**
-	 * Usability method which calls {@link #build()} and (on the built listener)
-	 * {@link ControlPropertyListener#attach() attach()} before returning the new listener.
+	 * Creates a new property listener according to the arguments specified before and
+	 * {@link ControlPropertyListenerHandle#attach() attaches} it.
 	 *
-	 * @return a {@link ControlPropertyListener}
+	 * @return a {@link ControlPropertyListenerHandle}
+	 * @see ControlPropertyListenerHandle#attach()
 	 */
-	public ControlPropertyListener buildAndAttach() {
-		ControlPropertyListener listener = build();
+	public ControlPropertyListenerHandle build() {
+		ControlPropertyListenerHandle listener = buildDetached();
 		listener.attach();
 		return listener;
 	}
 
 	/**
 	 * Creates a new property listener according to the arguments specified before.
 	 * <p>
-	 * Note that this builder is not yet added to the map! This can be done by calling
-	 * {@link ControlPropertyListener#attach() attach()} on the returned instance.
+	 * Note that this builder is not yet attached to the map! This can be done by calling
+	 * {@link ControlPropertyListenerHandle#attach() attach()} on the returned instance.
 	 *
-	 * @return a {@link ControlPropertyListener}
+	 * @return a {@link ControlPropertyListenerHandle}
+	 * @see #build()
+	 * @see ControlPropertyListenerHandle#attach()
 	 */
-	public ControlPropertyListener build() {
+	public ControlPropertyListenerHandle buildDetached() {
 		checkFields();
 
 		if (valueType.isPresent())
-			return new TypeCheckingControlPropertyListener<T>(properties, key, valueType.get(), valueProcessor);
+			return new TypeCheckingControlPropertyListenerHandle<T>(properties, key, valueType.get(), valueProcessor);
 		else
-			return new CastingControlPropertyListener<T>(properties, key, valueProcessor);
+			return new CastingControlPropertyListenerHandle<T>(properties, key, valueProcessor);
 	}
 
 	/**
-	 * Checks whether the attributes are valid so they can be used to {@link #build()} a listener.
+	 * Checks whether the attributes are valid so they can be used to {@link #buildDetached()} a listener.
 	 */
 	private void checkFields() {
 		if (key == null)

src/main/java/org/codefx/libfx/control/properties/ControlPropertyListener.java renamed to src/main/java/org/codefx/libfx/control/properties/ControlPropertyListenerHandle.java

@@ -1,6 +1,11 @@
 package org.codefx.libfx.control.properties;
 
+import org.codefx.libfx.listener.ListenerHandle;
+
 /**
+ * This is a {@link ListenerHandle handle} on a {@code ControlPropertyListener}, which can be used to {@link #attach()}
+ * and {@link #detach()} it. The {@code ControlPropertyListener} is no type on its own so it is described here.
+ * <p>
  * A control property listener listens to the changes in a Control's
  * {@link javafx.scene.control.Control#getProperties() propertyMap} and hands values to a value processor (a
  * {@link java.util.function.Consumer Consumer}) specified during construction.
@@ -11,20 +16,20 @@
  * Regardless of whether a value could be cast and processed or not, it will be removed from the map. So if the same
  * value is set repeatedly, the specified value processor is called every time.
  * <p>
- * The listener can be detached and reattached by calling the methods provided by this interface.
- * <p>
  * A listener is best created with the {@link ControlPropertyListenerBuilder}.
  */
-public interface ControlPropertyListener {
+public interface ControlPropertyListenerHandle extends ListenerHandle {
 
 	/**
 	 * Attaches/adds the listener to the properties map. This immediately processes the key if it is present.
 	 */
+	@Override
 	void attach();
 
 	/**
 	 * Detaches/removes the listener from the properties map.
 	 */
+	@Override
 	void detach();
 
 }

src/main/java/org/codefx/libfx/control/properties/TypeCheckingControlPropertyListener.java renamed to src/main/java/org/codefx/libfx/control/properties/TypeCheckingControlPropertyListenerHandle.java

@@ -6,13 +6,13 @@
 import javafx.collections.ObservableMap;
 
 /**
- * A {@link ControlPropertyListener} which uses a {@link Class} instance specified during construction to check whether
- * a value is of the correct type.
+ * A {@link ControlPropertyListenerHandle} which uses a {@link Class} instance specified during construction to check
+ * whether a value is of the correct type.
  *
  * @param <T>
  *            the type of values which the listener processes
  */
-final class TypeCheckingControlPropertyListener<T> extends AbstractControlPropertyListener {
+final class TypeCheckingControlPropertyListenerHandle<T> extends AbstractControlPropertyListenerHandle {
 
 	/**
 	 * The type of values which the listener processes.
@@ -25,7 +25,7 @@ final class TypeCheckingControlPropertyListener<T> extends AbstractControlProper
 	private final Consumer<? super T> valueProcessor;
 
 	/**
-	 * Creates a listener.
+	 * Creates a listener handle. Initially detached.
 	 *
 	 * @param properties
 	 *            the {@link ObservableMap} holding the properties
@@ -36,7 +36,7 @@ final class TypeCheckingControlPropertyListener<T> extends AbstractControlProper
 	 * @param valueProcessor
 	 *            the {@link Consumer} for the key's values
 	 */
-	TypeCheckingControlPropertyListener(
+	TypeCheckingControlPropertyListenerHandle(
 			ObservableMap<Object, Object> properties, Object key, Class<T> valueType, Consumer<? super T> valueProcessor) {
 
 		super(properties, key);

src/main/java/org/codefx/libfx/control/properties/package-info.java

@@ -24,10 +24,10 @@
  * 	.processValue(valueString -> System.out.println(valueString))
  * 	.buildAndAttach();
  * </pre>
- * It returns an instance of {@link org.codefx.libfx.control.properties.ControlPropertyListener ControlPropertyListener} which can
- * be used to easily detach and reattach the listener.
+ * It returns an instance of {@link org.codefx.libfx.control.properties.ControlPropertyListenerHandle
+ * ControlPropertyListenerHandle} which can be used to easily detach and reattach the listener.
  *
- * @see org.codefx.libfx.control.properties.ControlPropertyListener ControlPropertyListener
+ * @see org.codefx.libfx.control.properties.ControlPropertyListenerHandle ControlPropertyListener
  * @see org.codefx.libfx.control.properties.ControlPropertyListenerBuilder ControlPropertyListenerBuilder
  */
 package org.codefx.libfx.control.properties;