'ControlPropertyListenerHandle' implements 'ListenerHandle' contract. This is now fully documented and tested.

Author: nicolaiparlog

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

@@ -28,6 +28,11 @@ abstract class AbstractControlPropertyListenerHandle implements ControlPropertyL
 	 */
 	private final MapChangeListener<Object, Object> listener;
 
+	/**
+	 * Indicates whether the {@link #listener} is currently attached to the {@link #properties} map.
+	 */
+	private boolean attached;
+
 	// #end ATTRIBUTES
 
 	// #region CONSTRUCTION
@@ -97,14 +102,18 @@ private void processAndRemoveValue(Object value) {
 
 	@Override
 	public void attach() {
-		// TODO under threading this can lead to processing the same value twice.
+		if (attached)
+			return;
+
+		attached = true;
 		properties.addListener(listener);
 		if (properties.containsKey(key))
 			processAndRemoveValue(properties.get(key));
 	}
 
 	@Override
 	public void detach() {
+		attached = false;
 		properties.removeListener(listener);
 	}
 

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

@@ -11,7 +11,7 @@ public class ControlProperties {
 	 * 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:
-	 * 
+	 *
 	 * <pre>
 	 * ControlProperties.&lt;String&gt; on(...)
 	 * </pre>
@@ -23,7 +23,7 @@ public class ControlProperties {
 	 * @return a {@link ControlPropertyListenerBuilder}
 	 */
 	public static <T> ControlPropertyListenerBuilder<T> on(ObservableMap<Object, Object> properties) {
-		return new ControlPropertyListenerBuilder<T>(properties);
+		return ControlPropertyListenerBuilder.<T> on(properties);
 	}
 
 }

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

@@ -56,12 +56,31 @@ public class ControlPropertyListenerBuilder<T> {
 	 * @param properties
 	 *            the properties which will be observed by the built listener
 	 */
-	public ControlPropertyListenerBuilder(ObservableMap<Object, Object> properties) {
+	private ControlPropertyListenerBuilder(ObservableMap<Object, Object> properties) {
 		Objects.requireNonNull(properties, "The argument 'properties' must not be null.");
 		this.properties = properties;
 		this.valueType = Optional.empty();
 	}
 
+	/**
+	 * 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:
+	 *
+	 * <pre>
+	 * ControlProperties.&lt;String&gt; on(...)
+	 * </pre>
+	 *
+	 * @param <T>
+	 *            the type of values which the listener processes
+	 * @param properties
+	 *            the {@link ObservableMap} holding the properties
+	 * @return a {@link ControlPropertyListenerBuilder}
+	 */
+	public static <T> ControlPropertyListenerBuilder<T> on(ObservableMap<Object, Object> properties) {
+		return new ControlPropertyListenerBuilder<T>(properties);
+	}
+
 	/**
 	 * Sets the key. This must be called before {@link #buildDetached()}.
 	 *

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

@@ -6,17 +6,21 @@
  * 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.
+ * <h2>ControlPropertyListener</h2> A control property listener listens to the changes in a Control's
+ * {@link javafx.scene.control.Control#getProperties() propertyMap}. It is created to listen for a specific key and
+ * hands all new values for that key to a value processor (a {@link java.util.function.Consumer Consumer})..
  * <p>
  * Even though the property map's value type is {@code Object}, the processor might limit the value's type to any other
  * class. If the actual value can not be cast to that type, it is silently ignored.
  * <p>
  * 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>
- * A listener is best created with the {@link ControlPropertyListenerBuilder}.
+ * <h2>ControlPropertyListenerHandle</h2> Listener handles are not thread-safe. See {@link ListenerHandle} for details.
+ * Additionally, a new value might be processed twice if inserted into a map by another thread while {@link #attach()}
+ * is executed. This behavior should not be relied upon and might change (i.e. be fixed) in the future.
+ * <p>
+ * A listener handle is best created with the {@link ControlPropertyListenerBuilder}.
  */
 public interface ControlPropertyListenerHandle extends ListenerHandle {