[!] New class 'ExecuteWhen' builds 'ExecuteAlwaysWhen' and 'ExecuteOnceWhen'. Constructor visibility reduced to package. Also included wildcards were possible and improved comments.

ATTENTION: Unfortunately this revision does not compile! I screwed things up... :(

Author: nicolaiparlog

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;

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

@@ -0,0 +1,146 @@
+package org.codefx.libfx.concurrent.when;
+
+import java.util.Objects;
+import java.util.Optional;
+import java.util.function.Consumer;
+import java.util.function.Predicate;
+
+import javafx.beans.value.ObservableValue;
+
+/**
+ * Builder for {@link ExecuteAlwaysWhen} and {@link ExecuteOnceWhen}.
+ * <p>
+ * <h2>Example</h2>A typical use would look like this:
+ *
+ * <pre>
+ * 	ObservableValue<State> workerState;
+ *	ExecuteWhen.on(workerState)
+ *		.when(state -> state == State.SUCCEEDED)
+ *		.thenOnce(state -> logSuccess())
+ *		.executeWhen();
+ * </pre>
+ *
+ * @param <T>
+ *            the type the {@link ObservableValue} which will be observed by the constructed instance wraps
+ */
+public class ExecuteWhen<T> {
+
+	// #region FIELDS
+
+	/**
+	 * The {@link ObservableValue} upon whose value the action's execution depends.
+	 */
+	private final ObservableValue<T> observable;
+
+	/**
+	 * The condition the {@link #observable}'s value must fulfill for the action to be executed.
+	 */
+	private Optional<Predicate<? super T>> condition;
+
+	// #end FIELDS
+
+	// #region CONSTRUCTION
+
+	/**
+	 * Creates a new instance for the specified observable
+	 *
+	 * @param observable
+	 *            the {@link ObservableValue} which will be observed by the created {@code Execute...When} instances
+	 */
+	private ExecuteWhen(ObservableValue<T> observable) {
+		this.observable = observable;
+		condition = Optional.empty();
+	}
+
+	/**
+	 * Creates a new builder. The built instance of {@code Execute...When} will observe the specified observable.
+	 *
+	 * @param <T>
+	 *            the type the {@link ObservableValue} which will be observed by the constructed instance wraps
+	 * @param observable
+	 *            the {@link ObservableValue} which will be observed by the created {@code Execute...When} instances
+	 * @return a new builder instance
+	 */
+	public static <T> ExecuteWhen<T> on(ObservableValue<T> observable) {
+		return new ExecuteWhen<>(observable);
+	}
+
+	// #end CONSTRUCTION
+
+	// #region SETTING VALUES
+
+	/**
+	 * Specifies the condition the observable's value must fulfill in order for the action to be executed.
+	 *
+	 * @param condition
+	 *            the condition as a {@link Predicate}
+	 * @return this builder
+	 */
+	public ExecuteWhen<T> when(Predicate<? super T> condition) {
+		Objects.requireNonNull(condition, "The argument 'condition' must not be null.");
+		this.condition = Optional.of(condition);
+		return this;
+	}
+
+	// #end SETTING VALUES
+
+	// #region BUILD
+
+	/**
+	 * Creates an instance which:
+	 * <ul>
+	 * <li>observes the {@link ObservableValue} (specified for this builder's construction) for new values
+	 * <li>checks each new value against the condition set with {@link #when(Predicate)} (calling which is required)
+	 * <li>executes the specified {@code action} once if a value fulfills the condition
+	 * </ul>
+	 * Note that the observation does not start until {@link ExecuteOnceWhen#executeWhen()} is called. See
+	 * {@link ExecuteOnceWhen} for details.
+	 *
+	 * @param action
+	 *            the {@link Consumer} of the value which passed the condition
+	 * @return an instance of {@link ExecuteOnceWhen}
+	 * @throws IllegalStateException
+	 *             if {@link #when(Predicate)} was not called
+	 */
+	public ExecuteOnceWhen<T> thenOnce(Consumer<? super T> action) throws IllegalStateException {
+		ensureConditionWasSet();
+		return new ExecuteOnceWhen<T>(observable, condition.get(), action);
+	}
+
+	/**
+	 * Creates an instance which:
+	 * <ul>
+	 * <li>observes the {@link ObservableValue} (specified for this builder's construction) for new values
+	 * <li>checks each new value against the condition set with {@link #when(Predicate)} (calling which is required)
+	 * <li>executes the specified {@code action} every time a value fulfills the condition
+	 * </ul>
+	 * Note that the observation does not start until {@link ExecuteAlwaysWhen#executeWhen()} is called. See
+	 * {@link ExecuteAlwaysWhen} for details.
+	 *
+	 * @param action
+	 *            the {@link Consumer} of the value which passed the condition
+	 * @return an instance of {@link ExecuteOnceWhen}
+	 * @throws IllegalStateException
+	 *             if {@link #when(Predicate)} was not called
+	 */
+	public ExecuteAlwaysWhen<T> thenAlways(Consumer<? super T> action) throws IllegalStateException {
+		ensureConditionWasSet();
+		return new ExecuteAlwaysWhen<T>(observable, condition.get(), action);
+	}
+
+	/**
+	 * Makes sure that {@link #condition} was set, i.e. the {@link Optional} is not empty.
+	 *
+	 * @throws IllegalStateException
+	 *             if {@link #condition} was not set
+	 */
+	private void ensureConditionWasSet() throws IllegalStateException {
+		boolean noCondition = !condition.isPresent();
+		if (noCondition)
+			throw new IllegalStateException(
+					"Set a condition with 'when(Predicate<? super T>)' before calling any 'then' method.");
+	}
+
+	// #end BUILD
+
+}

src/main/java/org/codefx/libfx/concurrent/when/package-info.java

@@ -0,0 +1,11 @@
+/**
+ * With {@link org.codefx.libfx.concurrent.when.ExecuteOnceWhen ExecuteOnceWhen} and
+ * {@link org.codefx.libfx.concurrent.when.ExecuteAlwaysWhen ExecuteAlwaysWhen} this package provides two classes which
+ * help to make sure some action which is triggered by a change on an {@link javafx.beans.value.ObservableValue
+ * ObservableValue} gets executed under threading. Refer to the two classes for a detailed description.
+ * <p>
+ * Instances of those classes can be built with {@link org.codefx.libfx.concurrent.when.ExecuteWhen ExecuteWhen}.
+ *
+ * @see org.codefx.libfx.concurrent.when.ExecuteWhen ExecuteWhen
+ */
+package org.codefx.libfx.concurrent.when;