Merged branch 'feature/listenerhandle' into develop.

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/demo/java/org/codefx/libfx/control/webview/WebViewHyperlinkListenerDemo.java

@@ -13,6 +13,8 @@
 import javax.swing.event.HyperlinkEvent;
 import javax.swing.event.HyperlinkEvent.EventType;
 
+import org.codefx.libfx.listener.handle.ListenerHandle;
+
 /**
  * Demonstrates how to use the {@link WebViewHyperlinkListener}.
  */
@@ -110,7 +112,7 @@ private static CheckBox createCancelEventBox() {
 	private static void manageListener(WebView webView, WebViewHyperlinkListener listener,
 			BooleanProperty attachedProperty) {
 		attachedProperty.set(true);
-		WebViewHyperlinkListenerHandle listenerHandle = WebViews.addHyperlinkListener(webView, listener);
+		ListenerHandle listenerHandle = WebViews.addHyperlinkListener(webView, listener);
 
 		attachedProperty.addListener((obs, wasAttached, isAttached) -> {
 			if (isAttached) {

src/demo/java/org/codefx/libfx/listener/handle/ListenerHandleDemo.java

@@ -0,0 +1,156 @@
+package org.codefx.libfx.listener.handle;
+
+import javafx.beans.Observable;
+import javafx.beans.property.Property;
+import javafx.beans.property.SimpleStringProperty;
+import javafx.beans.value.ChangeListener;
+
+/**
+ * Demonstrates how to create and use {@link ListenerHandle}s.
+ */
+@SuppressWarnings("static-method")
+public class ListenerHandleDemo {
+
+	// #region CONSTRUCTION & MAIN
+
+	/**
+	 * Creates a new demo.
+	 */
+	private ListenerHandleDemo() {
+		// nothing to do
+	}
+
+	/**
+	 * Runs this demo.
+	 *
+	 * @param args
+	 *            command line arguments (will not be used)
+	 */
+	public static void main(String[] args) {
+		ListenerHandleDemo demo = new ListenerHandleDemo();
+
+		demo.createCommonListenerHandle();
+		demo.createCustomListenerHandle();
+		demo.attachAndDetach();
+	}
+
+	// #end CONSTRUCTION & MAIN
+
+	// #region DEMOS
+
+	// construction
+
+	/**
+	 * Demonstrates how to simply create a handle for a given observable and listener.
+	 */
+	private void createCommonListenerHandle() {
+		Property<String> property = new SimpleStringProperty();
+		ChangeListener<String> listener = (obs, oldValue, newValue) -> { /* do nothing for this demo */};
+
+		// create the handle; this one is initially attached, i.e. the listener is added to the property
+		ListenerHandle handle = ListenerHandles.createAttached(property, listener);
+		// the handle can be used to easily detach and reattach the listener
+		handle.detach();
+		handle.attach();
+
+		// create a detached handle where the listener was not yet added to the property
+		handle = ListenerHandles.createDetached(property, listener);
+		// this one needs to be attached before the listener is executed on changes
+		handle.attach();
+	}
+
+	/**
+	 * Demonstrates how a listener handle can be created for custom observable implementations with
+	 * {@link ListenerHandleBuilder}.
+	 */
+	private void createCustomListenerHandle() {
+		MyCustomObservable customObservable = new MyCustomObservable();
+		MyCustomListener customListener = new MyCustomListener();
+
+		// use 'ListenerHandles' to get a 'ListenerHandleBuilder' which can be used to create a handle for this
+		// observable and listener
+		ListenerHandle handleForCustomClasses = ListenerHandles
+				.createFor(customObservable, customListener)
+				.onAttach((observable, listener) -> observable.addListener(listener))
+				.onDetach((observable, listener) -> observable.removeListener(listener))
+				.build();
+		handleForCustomClasses.attach();
+	}
+
+	// attach & detach
+
+	/**
+	 * Demonstrates how to add and remove a listener with a {@link ListenerHandle} and compares this to the normal
+	 * approach.
+	 */
+	private void attachAndDetach() {
+		Property<String> observedProperty = new SimpleStringProperty("initial value");
+
+		// usually a listener is directly added to the property;
+		// but if the listener has to be removed later, the reference needs to be stored explicitly
+		ChangeListener<Object> changePrintingListener = (obs, oldValue, newValue) ->
+				System.out.println("[LISTENER] Value changed from \"" + oldValue + "\" to \"" + newValue + "\".");
+		observedProperty.addListener(changePrintingListener);
+
+		// this is the alternative with a 'ListenerHandle'
+		ListenerHandle newValuePrinter = ListenerHandles.createAttached(observedProperty,
+				(obs, oldValue, newValue) -> System.out.println("[HANDLE] New value: \"" + newValue + "\""));
+
+		// now lets change the value to see how it works
+		observedProperty.setValue("new value");
+		observedProperty.setValue("even newer value");
+
+		// removing a listener needs references to both the observable and the listener;
+		// depending on the situation this might not be feasible
+		observedProperty.removeListener(changePrintingListener);
+		// with a handle, the listener can be removed without giving the caller the possibility tp interact with
+		// the observable or the listener; it is also a little more readable
+		newValuePrinter.detach();
+
+		// some unobserved changes...
+		observedProperty.setValue("you won't see this on the console");
+		observedProperty.setValue("nor this");
+
+		// the same as above goes for adding the listener
+		observedProperty.addListener(changePrintingListener);
+		newValuePrinter.attach();
+
+		// now some more changes
+		observedProperty.setValue("but you will see this");
+		observedProperty.setValue("and this");
+	}
+
+	// #end DEMOS
+
+	// #region NESTED CLASSES
+
+	/**
+	 * Represents a custom observable instance. Note that it is not necessary to implement {@link Observable} (or any
+	 * other interface) in order to use this class with the {@link ListenerHandleBuilder}.
+	 */
+	private static class MyCustomObservable {
+
+		@SuppressWarnings({ "javadoc", "unused" })
+		public void addListener(MyCustomListener listener) {
+			// do nothing - just for demo
+		}
+
+		@SuppressWarnings({ "javadoc", "unused" })
+		public void removeListener(MyCustomListener listener) {
+			// do nothing - just for demo
+		}
+
+	}
+
+	/**
+	 * Represents a listener for a custom observable instance. Note that it is not necessary to implement
+	 * {@link ChangeListener} (or any other interface) in order to use this class with the {@link ListenerHandleBuilder}
+	 * .
+	 */
+	private static class MyCustomListener {
+		// has no members - just for demo
+	}
+
+	// #end NESTED CLASSES
+
+}

src/main/java/org/codefx/libfx/concurrent/when/ExecuteAlwaysWhen.java

@@ -24,6 +24,8 @@
  * If the observable is manipulated by several threads during {@code executeWhen()}, this class does not guarantee that
  * the first value to pass the condition is the one handed to the action. Depending on the interaction of those threads
  * it might be the initial value or one of several which were set by those threads.
+ * <p>
+ * Use {@link ExecuteWhen} to build an instance of this class.
  *
  * @param <T>
  *            the type the observed {@link ObservableValue}'s wraps
@@ -66,17 +68,17 @@ public class ExecuteAlwaysWhen<T> {
 	/**
 	 * The condition the {@link #observable}'s value must fulfill for {@link #action} to be executed.
 	 */
-	private final Predicate<T> condition;
+	private final Predicate<? super T> condition;
 
 	/**
 	 * The action which will be executed.
 	 */
-	private final Consumer<T> action;
+	private final Consumer<? super T> action;
 
 	/**
 	 * The listener which executes {@link #action} and sets {@link #alreadyExecuted} accordingly.
 	 */
-	private final ChangeListener<T> listenerWhichExecutesAction;
+	private final ChangeListener<? super T> listenerWhichExecutesAction;
 
 	/**
 	 * Indicates whether {@link #executeWhen()} was already called. If so, it can not be called again.
@@ -107,7 +109,7 @@ public class ExecuteAlwaysWhen<T> {
 	 * @param action
 	 *            the action which will be executed
 	 */
-	public ExecuteAlwaysWhen(ObservableValue<T> observable, Predicate<T> condition, Consumer<T> action) {
+	ExecuteAlwaysWhen(ObservableValue<T> observable, Predicate<? super T> condition, Consumer<? super T> action) {
 		this.observable = observable;
 		this.condition = condition;
 		this.action = action;

src/main/java/org/codefx/libfx/concurrent/when/ExecuteOnceWhen.java

@@ -23,7 +23,9 @@
  * If the observable is manipulated by several threads, this class does not guarantee that the first value to pass the
  * condition is the one handed to the action. Depending on the interaction of those threads it might be the initial
  * value (the one tested during {@code executeWhen()}) or one of several which were set by those threads.
- *
+ * <p>
+ * Use {@link ExecuteWhen} to build an instance of this class.
+ * 
  * @param <T>
  *            the type the observed {@link ObservableValue}'s wraps
  */
@@ -56,12 +58,12 @@ public class ExecuteOnceWhen<T> {
 	/**
 	 * The condition the {@link #observable}'s value must fulfill for {@link #action} to be executed.
 	 */
-	private final Predicate<T> condition;
+	private final Predicate<? super T> condition;
 
 	/**
 	 * The action which will be executed.
 	 */
-	private final Consumer<T> action;
+	private final Consumer<? super T> action;
 
 	/**
 	 * Indicates whether {@link #action} might still be executed at some point in the future. Is used to prevent the
@@ -93,7 +95,7 @@ public class ExecuteOnceWhen<T> {
 	 * @param action
 	 *            the action which will be executed
 	 */
-	public ExecuteOnceWhen(ObservableValue<T> observable, Predicate<T> condition, Consumer<T> action) {
+	ExecuteOnceWhen(ObservableValue<T> observable, Predicate<? super T> condition, Consumer<? super T> action) {
 		this.observable = observable;
 		this.condition = condition;
 		this.action = action;