Merge branch '2.x' into cancellation-handler

subprojects/jdeferred-core/src/main/java/org/jdeferred/AlwaysCallback.java

@@ -17,6 +17,22 @@
 
 import org.jdeferred.Promise.State;
 
+/**
+ * A callback that's invoked regardless of the success or fail state of a {@code Promise}.
+ *
+ * @param <D> Type used for {@link Deferred#resolve(Object)}
+ * @param <R> Type used for {@link Deferred#reject(Object)}
+ *
+ * @author Ray Tsang
+ * @see Promise#always(AlwaysCallback)
+ */
 public interface AlwaysCallback<D, R> {
-	public void onAlways(final State state, final D resolved, final R rejected);
+	/**
+	 * Invoked when the {@code Promise} resolves or rejects a value.
+	 *
+	 * @param state    the state of the {@code Promise}
+	 * @param resolved the resolved value (if any) of the {@code Promise}
+	 * @param rejected the rejected value (if any) of the {@code Promise}
+	 */
+	void onAlways(final State state, final D resolved, final R rejected);
 }

subprojects/jdeferred-core/src/main/java/org/jdeferred/Deferred.java

@@ -21,21 +21,18 @@
  * Deferred interface to trigger an event (resolve, reject, notify).
  * Subsequently, this will allow Promise observers to listen in on the event
  * (done, fail, progress).
- * 
- * @see DeferredObject
+ *
+ * @param <D> Type used for {@link #resolve(Object)}
+ * @param <F> Type used for {@link #reject(Object)}
+ * @param <P> Type used for {@link #notify(Object)}
+ *
  * @author Ray Tsang
- * 
- * @param <D>
- *            Type used for {@link #resolve(Object)}
- * @param <F>
- *            Type used for {@link #reject(Object)}
- * @param <P>
- *            Type used for {@link #notify(Object)}
+ * @see DeferredObject
  */
 public interface Deferred<D, F, P> extends Promise<D, F, P> {
 	/**
 	 * This should be called when a task has completed successfully.
-	 * 
+	 * <p>
 	 * <pre>
 	 * <code>
 	 * {@link Deferred} deferredObject = new {@link DeferredObject}();
@@ -45,22 +42,23 @@ public interface Deferred<D, F, P> extends Promise<D, F, P> {
 	 *   	// Done!
 	 *   }
 	 * });
-	 * 
+	 *
 	 * // another thread using the same deferredObject
 	 * deferredObject.resolve("OK");
-	 * 
+	 *
 	 * </code>
 	 * </pre>
-	 * 
-	 * @param resolve
-	 * @return
+	 *
+	 * @param resolve the resolved value for this {@code Deferred}
+	 *
+	 * @return the reference to this {@code Deferred} instance.
 	 */
 	Deferred<D, F, P> resolve(final D resolve);
 
 	/**
-	 * This should be called when a task has completed unsuccessfully, 
+	 * This should be called when a task has completed unsuccessfully,
 	 * i.e., a failure may have occurred.
-	 * 
+	 * <p>
 	 * <pre>
 	 * <code>
 	 * {@link Deferred} deferredObject = new {@link DeferredObject}();
@@ -70,22 +68,23 @@ public interface Deferred<D, F, P> extends Promise<D, F, P> {
 	 *   	// Failed :(
 	 *   }
 	 * });
-	 * 
+	 *
 	 * // another thread using the same deferredObject
 	 * deferredObject.reject("BAD");
-	 * 
+	 *
 	 * </code>
 	 * </pre>
-	 * 
-	 * @param resolve
-	 * @return
+	 *
+	 * @param reject the rejected value for this {@code Deferred}
+	 *
+	 * @return the reference to this {@code Deferred} instance.
 	 */
 	Deferred<D, F, P> reject(final F reject);
 
 	/**
-	 * This should be called when a task is still executing and progress had been made, 
+	 * This should be called when a task is still executing and progress had been made,
 	 * E.g., during a file download, notify the download progress.
-	 * 
+	 * <p>
 	 * <pre>
 	 * <code>
 	 * {@link Deferred} deferredObject = new {@link DeferredObject}();
@@ -95,22 +94,23 @@ public interface Deferred<D, F, P> extends Promise<D, F, P> {
 	 *   	// Failed :(
 	 *   }
 	 * });
-	 * 
+	 *
 	 * // another thread using the same deferredObject
 	 * deferredObject.reject("100%");
-	 * 
+	 *
 	 * </code>
 	 * </pre>
-	 * 
-	 * @param resolve
-	 * @return
+	 *
+	 * @param progress the intermediate result for this {@code Deferred}
+	 *
+	 * @return the reference to this {@code Deferred} instance.
 	 */
 	Deferred<D, F, P> notify(final P progress);
 
 	/**
 	 * Return an {@link Promise} instance (i.e., an observer).  You can register callbacks in this observer.
-	 * 
-	 * @return
+	 *
+	 * @return the reference to this {@code Deferred} instance as a {@code Promise},
 	 */
 	Promise<D, F, P> promise();
 }

subprojects/jdeferred-core/src/main/java/org/jdeferred/DeferredCallable.java

@@ -15,41 +15,52 @@
  */
 package org.jdeferred;
 
-import java.util.concurrent.Callable;
-
 import org.jdeferred.DeferredManager.StartPolicy;
 import org.jdeferred.impl.DeferredObject;
 
+import java.util.concurrent.Callable;
+
 /**
  * Use this as superclass in case you need to be able to return a result and notify progress.
  * If you don't need to notify progress, you can simply use {@link Callable}
- * 
- * @see #notify(Object)
- * @author Ray Tsang
  *
  * @param <D> Type used as return type of {@link Callable#call()}, and {@link Deferred#resolve(Object)}
  * @param <P> Type used for {@link Deferred#notify(Object)}
+ *
+ * @author Ray Tsang
+ * @see #notify(Object)
  */
 public abstract class DeferredCallable<D, P> implements Callable<D> {
 	private final Deferred<D, Throwable, P> deferred = new DeferredObject<D, Throwable, P>();
 	private final StartPolicy startPolicy;
-
+
+	/**
+	 * Creates a new {@code DeferredCallable} with DEFAULT {@code startPolicy}.
+	 */
 	public DeferredCallable() {
 		this.startPolicy = StartPolicy.DEFAULT;
 	}
-
+
+	/**
+	 * Creates a new {@code DeferredCallable} with the given {@code startPolicy}.
+	 *
+	 * @param startPolicy the startPolicy to use. will be set to DEFAULT if {@code null}.
+	 */
 	public DeferredCallable(StartPolicy startPolicy) {
-		this.startPolicy = startPolicy;
+		this.startPolicy = startPolicy != null ? startPolicy : StartPolicy.DEFAULT;
 	}
-	
+
 	/**
+	 * Trigger notification of an intermediate result.
+	 *
+	 * @param progress the value to be sent as a notification
+	 *
 	 * @see Deferred#notify(Object)
-	 * @param progress
 	 */
 	protected void notify(P progress) {
 		deferred.notify(progress);
 	}
-	
+
 	protected Deferred<D, Throwable, P> getDeferred() {
 		return deferred;
 	}

subprojects/jdeferred-core/src/main/java/org/jdeferred/DeferredRunnable.java

@@ -21,32 +21,33 @@
 /**
  * Use this as superclass in case you need to be able to be able to notify progress.
  * If you don't need to notify progress, you can simply use {@link Runnable}
- * 
- * @see #notify(Object)
- * @author Ray Tsang
  *
  * @param <P> Type used for {@link Deferred#notify(Object)}
+ *
+ * @author Ray Tsang
+ * @see #notify(Object)
  */
 public abstract class DeferredRunnable<P> implements Runnable {
 	private final Deferred<Void, Throwable, P> deferred = new DeferredObject<Void, Throwable, P>();
 	private final StartPolicy startPolicy;
-	
+
 	public DeferredRunnable() {
 		this.startPolicy = StartPolicy.DEFAULT;
 	}
-	
+
 	public DeferredRunnable(StartPolicy startPolicy) {
 		this.startPolicy = startPolicy;
 	}
-	
+
 	/**
-	 * @see Deferred#notify(Object)
 	 * @param progress
+	 *
+	 * @see Deferred#notify(Object)
 	 */
 	protected void notify(P progress) {
 		deferred.notify(progress);
 	}
-	
+
 	protected Deferred<Void, Throwable, P> getDeferred() {
 		return deferred;
 	}

subprojects/jdeferred-core/src/main/java/org/jdeferred/DoneCallback.java

@@ -16,12 +16,14 @@
 package org.jdeferred;
 
 /**
+ * A cllback invoked when the {@code Promise} has been resolved.
+ *
+ * @param <D> Type used for {@link Deferred#resolve(Object)}
+ *
+ * @author Ray Tsang
  * @see Deferred#resolve(Object)
  * @see Promise#done(DoneCallback)
- * @author Ray Tsang
- *
- * @param <D>
  */
 public interface DoneCallback<D> {
-	public void onDone(final D result);
+	void onDone(final D result);
 }

subprojects/jdeferred-core/src/main/java/org/jdeferred/DoneFilter.java

@@ -16,12 +16,12 @@
 package org.jdeferred;
 
 /**
- * @see Promise#then(DoneFilter, FailFilter)
- * @author Ray Tsang
+ * @param <D>     Type of the input
+ * @param <D_OUT> Type of the output from this filter
  *
- * @param <P> Type of the input
- * @param <P_OUT> Type of the output from this filter
+ * @author Ray Tsang
+ * @see Promise#then(DoneFilter, FailFilter)
  */
 public interface DoneFilter<D, D_OUT> {
-	public D_OUT filterDone(final D result);
+	D_OUT filterDone(final D result);
 }

subprojects/jdeferred-core/src/main/java/org/jdeferred/DonePipe.java

@@ -16,12 +16,12 @@
 package org.jdeferred;
 
 /**
- * @see Promise#then(DonePipe, FailPipe)
- * @author Ray Tsang
- *
- * @param <P> Type of the input
+ * @param <P>     Type of the input
  * @param <P_OUT> Type of the output from this filter
+ *
+ * @author Ray Tsang
+ * @see Promise#then(DonePipe, FailPipe)
  */
 public interface DonePipe<D, D_OUT, F_OUT, P_OUT> {
-	public Promise<D_OUT, F_OUT, P_OUT> pipeDone(final D result);
+	Promise<D_OUT, F_OUT, P_OUT> pipeDone(final D result);
 }

subprojects/jdeferred-core/src/main/java/org/jdeferred/FailCallback.java

@@ -16,12 +16,14 @@
 package org.jdeferred;
 
 /**
+ * A callback invoked when the {@code Promise}'s state is {@code Promise.State.REJECTED}.
+ *
+ * @param <F> Type used for {@link Deferred#reject(Object)}
+ *
+ * @author Ray Tsang
  * @see Deferred#reject(Object)
  * @see Promise#fail(FailCallback)
- * @author Ray Tsang
- *
- * @param <F>
  */
 public interface FailCallback<F> {
-	public void onFail(final F result);
+	void onFail(final F result);
 }

subprojects/jdeferred-core/src/main/java/org/jdeferred/FailFilter.java

@@ -16,12 +16,12 @@
 package org.jdeferred;
 
 /**
- * @see Promise#then(DoneFilter, FailFilter)
- * @author Ray Tsang
+ * @param <F>     Type of the fail input
+ * @param <F_OUT> Type of the faol output from this filter
  *
- * @param <P> Type of the input
- * @param <P_OUT> Type of the output from this filter
+ * @author Ray Tsang
+ * @see Promise#then(DoneFilter, FailFilter)
  */
 public interface FailFilter<F, F_OUT> {
-	public F_OUT filterFail(final F result);
+	F_OUT filterFail(final F result);
 }

subprojects/jdeferred-core/src/main/java/org/jdeferred/FailPipe.java

@@ -16,12 +16,14 @@
 package org.jdeferred;
 
 /**
- * @see Promise#then(DonePipe, FailPipe)
- * @author Ray Tsang
+ * @param <F>     Type of the fail input
+ * @param <D_OUT> Type of the output from this pipe
+ * @param <F_OUT> Type of the fail output from this pipe
+ * @param <P_OUT> Type of the progress output from this pipe
  *
- * @param <P> Type of the input
- * @param <P_OUT> Type of the output from this filter
+ * @author Ray Tsang
+ * @see Promise#then(DonePipe, FailPipe)
  */
 public interface FailPipe<F, D_OUT, F_OUT, P_OUT> {
-	public Promise<D_OUT, F_OUT, P_OUT> pipeFail(final F result);
+	Promise<D_OUT, F_OUT, P_OUT> pipeFail(final F result);
 }

subprojects/jdeferred-core/src/main/java/org/jdeferred/ProgressCallback.java

@@ -16,12 +16,14 @@
 package org.jdeferred;
 
 /**
+ * A callback invoked when the {@code Promise} publishes intermediate results.
+ *
+ * @param <P> Type used for {@link Deferred#notify(Object)}
+ *
+ * @author Ray Tsang
  * @see Deferred#notify(Object)
  * @see Promise#progress(ProgressCallback)
- * @author Ray Tsang
- *
- * @param <P>
  */
 public interface ProgressCallback<P> {
-	public void onProgress(final P progress);
+	void onProgress(final P progress);
 }