JavaDoc-s; minor refactoring of Promises methods' names

Author: vsilaev

src/main/java/net/tascalate/concurrent/AbstractCompletableTask.java

@@ -38,6 +38,14 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
+/**
+ * Base superclass for both root and intermediate {@link Promise}-s that
+ * represent blocking long-running tasks
+ * 
+ * @author vsilaev
+ *
+ * @param <T>
+ */
 abstract class AbstractCompletableTask<T> extends PromiseAdapter<T> implements Promise<T> {
 
     private final CallbackRegistry<T> callbackRegistry = new CallbackRegistry<>();

src/main/java/net/tascalate/concurrent/AbstractDelegatingPromise.java

@@ -23,6 +23,15 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
+/**
+ * Helper class to create a concrete {@link Promise} subclass via delegation
+ * to the wrapped {@link CompletionStage}
+ * 
+ * @author vsilaev
+ *
+ * @param <T>
+ * @param <D>
+ */
 abstract public class AbstractDelegatingPromise<T, D extends CompletionStage<T>> implements Promise<T> {
     final protected D completionStage;
 

src/main/java/net/tascalate/concurrent/AggregatingPromise.java

@@ -106,7 +106,7 @@ void onComplete(int idx, T result, Throwable error) {
                     // Synchronized around done
                     markRemainingCancelled();
                     // Now no other thread can modify errors array.
-                    onError(new MultitargetException(new ArrayList<>(Arrays.asList(errors))));
+                    onFailure(new MultitargetException(new ArrayList<>(Arrays.asList(errors))));
 
                     if (cancelRemaining) {
                         cancelPromises();

src/main/java/net/tascalate/concurrent/CompletablePromise.java

@@ -24,6 +24,13 @@
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 
+/**
+ * The {@link CompletablePromise} is an adapter of a {@link CompletableFuture} to the {@link Promise} API 
+ * 
+ * @author vsilaev
+ *
+ * @param <T>
+ */
 public class CompletablePromise<T> extends AbstractDelegatingPromise<T, CompletableFuture<T>> implements Promise<T> {
 
     public CompletablePromise() {
@@ -38,7 +45,7 @@ protected boolean onSuccess(T value) {
         return completionStage.complete(value);
     }
 
-    protected boolean onError(Throwable ex) {
+    protected boolean onFailure(Throwable ex) {
         return completionStage.completeExceptionally(ex);
     }
 

src/main/java/net/tascalate/concurrent/CompletableSubTask.java

@@ -19,6 +19,12 @@
 import java.util.concurrent.Executor;
 import java.util.concurrent.atomic.AtomicBoolean;
 
+/**
+ * The {@link Promise} implementation for intermediate long-running blocking task
+ * @author vsilaev
+ *
+ * @param <T>
+ */
 class CompletableSubTask<T> extends AbstractCompletableTask<T> {
 
     static class DelegatingCallable<T> implements Callable<T> {

src/main/java/net/tascalate/concurrent/CompletableTask.java

@@ -19,32 +19,100 @@
 import java.util.concurrent.Executor;
 import java.util.concurrent.RunnableFuture;
 
+/**
+ * 
+ * Concrete implementation of {@link Promise} interface for long-running blocking tasks
+ * 
+ * @author vsilaev
+ *
+ * @param <T>
+ */
 public class CompletableTask<T> extends AbstractCompletableTask<T> implements RunnableFuture<T> {
 
+    /**
+     * Creates a CompletableTask; for internal use only 
+     * @param executor
+     *   a default {@link Executor} to run functions passed to async composition methods 
+     * @param callable
+     *   a {@link Callable} that completes this task
+     */
     protected CompletableTask(final Executor executor, Callable<T> callable) {
         super(executor, callable);
     }
 
+    /**
+     * Executes wrapped {@link Callable}; don't use explicitly
+     */
     @Override
     public void run() {
         task.run();
     }
 
-    public static <T> Promise<T> resolve(T value, Executor defaultExecutor) {
+    /**
+     * Returns a resolved {@link Promise} with specified value; the promise is "bound" to the specified executor. 
+     * I.e. any function passed to composition methods of Promise (like <code>thenApplyAsync</code> 
+     * / <code>thenAcceptAsync</code> / <code>whenCompleteAsync</code> etc.) will be executed using this executor 
+     * unless executor is overridden via explicit composition method parameter. Moreover, any nested 
+     * composition calls will use same executor, if it’s not redefined via explicit composition method parameter:
+     * {@code}<pre>CompletableTask
+     *   .complete("Hello!", myExecutor)
+     *   .thenApplyAsync(myMapper)
+     *   .thenApplyAsync(myTransformer)   
+     *   .thenAcceptAsync(myConsumer)
+     *   .thenRunAsync(myAction)
+     *  </pre>
+     * All of <code>myMapper</code>, <code>myTransformer</code>, <code>myConsumer</code>, <code>myActtion</code> will be executed using <code>myExecutor</code>
+     * 
+     * @param value
+     *   a resolved value of the promise
+     * @param executor
+     *   a default {@link Executor} to run functions passed to async composition methods 
+     *   (like <code>thenApplyAsync</code> / <code>thenAcceptAsync</code> / <code>whenCompleteAsync</code> etc.)
+     * @return
+     *   resolved {@link Promise} with a value passed; the promise is bound to the specified executor
+     */
+    public static <T> Promise<T> complete(T value, Executor defaultExecutor) {
         CompletableTask<T> result = new CompletableTask<T>(defaultExecutor, () -> value);
         SAME_THREAD_EXECUTOR.execute(result);
         return result;
     }
-    
-    public static Promise<Void> asyncOn(Executor defaultExecutor) {
-        return resolve(null, defaultExecutor);
+
+    /**
+     * Returns a resolved no-value {@link Promise} that is "bound" to the specified executor. 
+     * I.e. any function passed to composition methods of Promise (like <code>thenApplyAsync</code> 
+     * / <code>thenAcceptAsync</code> / <code>whenCompleteAsync</code> etc.) will be executed using this executor 
+     * unless executor is overridden via explicit composition method parameter. Moreover, any nested 
+     * composition calls will use same executor, if it’s not redefined via explicit composition method parameter:
+     * {@code}<pre>CompletableTask
+     *   .asyncOn(myExecutor)
+     *   .thenApplyAsync(myValueGenerator)
+     *   .thenAcceptAsync(myConsumer)
+     *   .thenRunAsync(myAction)
+     *  </pre>
+     * All of <code>myValueGenerator</code>, <code>myConsumer</code>, <code>myActtion</code> will be executed using <code>myExecutor</code>
+     * 
+     * @param executor
+     *   a default {@link Executor} to run functions passed to async composition methods 
+     *   (like <code>thenApplyAsync</code> / <code>thenAcceptAsync</code> / <code>whenCompleteAsync</code> etc.)
+     * @return
+     *   resolved non-value {@link Promise} bound to the specified executor
+     */
+    public static Promise<Void> asyncOn(Executor executor) {
+        return complete(null, executor);
     }
 
     @Override
     Runnable setupTransition(Callable<T> code) {
         throw new UnsupportedOperationException();
     }
-
+    
+    /**
+     * Creates a nested sub-task for a composition method 
+     * @param executor
+     *   a default executor for async composition methods of nested sub-task
+     * @return
+     *   an instance of {@link CompletableSubTask} bound to the specified executor
+     */
     @Override
     protected <U> AbstractCompletableTask<U> createCompletionStage(Executor executor) {
         return new CompletableSubTask<U>(executor);

src/main/java/net/tascalate/concurrent/Promise.java

@@ -23,6 +23,15 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
+/**
+ * <p>{@link Promise} is a combination of the {@link CompletionStage} and {@link Future} contracts.
+ * It provides both composition methods of the former and blocking access methods of the later.
+ * <p>Every composition method derived from the {@link CompletionStage} interface is overridden to
+ * return a new Promise;
+ * @author vsilaev
+ *
+ * @param <T>
+ */
 public interface Promise<T> extends Future<T>, CompletionStage<T> {
 
     public <U> Promise<U> thenApply(Function<? super T, ? extends U> fn);

src/main/java/net/tascalate/concurrent/PromiseAdapter.java

@@ -29,6 +29,13 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
+/**
+ * Helper class to create a concrete {@link Promise} subclass as an
+ * implementation from scratch.
+ * @author vsilaev
+ *
+ * @param <T>
+ */
 abstract public class PromiseAdapter<T> implements Promise<T> {
     protected static final Executor SAME_THREAD_EXECUTOR = new Executor() {
         public void execute(Runnable command) {

src/main/java/net/tascalate/concurrent/Promises.java

@@ -23,14 +23,49 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
+/**
+ * Utility class to create a resolved (either successfully or faulty) {@link Promise}-s; 
+ * to wrap an arbitrary {@link CompletionStage} interface to the {@link Promise} API;
+ * to combine several {@link CompletionStage}-s into aggregating promise.
+ *    
+ * @author vsilaev
+ *
+ */
 public class Promises {
 
-    public static <T> Promise<T> readyValue(T value) {
+    /**
+     * Method to create a successfully resolved {@link Promise} with a value provided 
+     * @param value
+     *   a value to wrap
+     * @return 
+     *   a successfully resolved {@link Promise} with a value provided
+     */
+    public static <T> Promise<T> success(T value) {
         final CompletablePromise<T> result = new CompletablePromise<>();
         result.onSuccess(value);
         return result;
     }
+    
+    /**
+     * Method to create a faulty resolved {@link Promise} with an exception provided 
+     * @param exception
+     *   an exception to wrap
+     * @return 
+     *   a faulty resolved {@link Promise} with an exception provided
+     */    
+    public static Promise<?> failure(Throwable exception) {
+        final CompletablePromise<?> result = new CompletablePromise<>();
+        result.onFailure(exception);
+        return result;
+    }
 
+    /**
+     * Adapts a stage passed to the {@link Promise} API
+     * @param stage
+     *   a {@link CompletionStage} to be wrapped
+     * @return
+     *   a {@link Promise}
+     */
     public static <T> Promise<T> from(CompletionStage<T> stage) {
         if (stage instanceof Promise) {
             return (Promise<T>) stage;
@@ -41,7 +76,7 @@ public static <T> Promise<T> from(CompletionStage<T> stage) {
         }
 
         final CompletablePromise<T> result = createLinkedPromise(stage);
-        stage.whenComplete(handler(result::onSuccess, result::onError));
+        stage.whenComplete(handler(result::onSuccess, result::onFailure));
         return result;
     }
 
@@ -52,7 +87,7 @@ static <T, R> Promise<R> from(CompletionStage<T> stage,
         final CompletablePromise<R> result = createLinkedPromise(stage);
         stage.whenComplete(handler(
             acceptConverted(result::onSuccess, resultConverter),
-            acceptConverted(result::onError, errorConverter)
+            acceptConverted(result::onFailure, errorConverter)
         ));
         return result;
     }
@@ -70,17 +105,50 @@ public boolean cancel(boolean mayInterruptIfRunning) {
             }
         };
     }
-
+    
+    /**
+     * <p>Returns a promise that is resolved successfully when all {@link CompletionStage}-s passed as parameters are completed normally; 
+     * if any promise completed exceptionally, then resulting promise is resolved exceptionally as well.
+     * <p>The resolved result of this promise contains a list of the resolved results of the {@link CompletionStage}-s passed as an 
+     * argument at corresponding positions.
+     *  
+     * @param promises
+     *   an array of {@link CompletionStage}-s to combine
+     * @return
+     *   a combined promise
+     */
     @SafeVarargs
     public static <T> Promise<List<T>> all(final CompletionStage<? extends T>... promises) {
         return atLeast(promises.length, 0, true, promises);
     }
 
+    /**
+     * <p>Returns a promise that is resolved successfully when any {@link CompletionStage} passed as parameters is completed normally (race is possible); 
+     * if all promises completed exceptionally, then resulting promise is resolved exceptionally as well.
+     * <p>The resolved result of this promise contains a value of the first resolved result of the {@link CompletionStage}-s passed as an 
+     * argument.
+     * @param promises
+     *    an array of {@link CompletionStage}-s to combine
+     * @return
+     *   a combined promise
+     */
     @SafeVarargs
     public static <T> Promise<T> any(final CompletionStage<? extends T>... promises) {
         return unwrap(atLeast(1, promises.length - 1, true, promises), false);
     }
 
+    /**
+     * <p>Returns a promise that is resolved successfully when any {@link CompletionStage} passed as parameters is completed normally (race is possible); 
+     * if any promise completed exceptionally before first result is available, then resulting promise is resolved exceptionally as well 
+     * (unlike non-Strict variant, where exceptions are ignored if result is available at all).
+     * <p>The resolved result of this promise contains a value of the first resolved result of the {@link CompletionStage}-s passed as an 
+     * argument.
+     * 
+     * @param promises
+     *    an array of {@link CompletionStage}-s to combine
+     * @return
+     *   a combined promise
+     */
     @SafeVarargs
     public static <T> Promise<T> anyStrict(final CompletionStage<? extends T>... promises) {
         return unwrap(atLeast(1, 0, true, promises), true);
@@ -104,7 +172,7 @@ public static <T> Promise<List<T>> atLeast(final int minResultsCount, final int
             throw new IllegalArgumentException(
                     "The number of futures supplied is less than a number of futures to await");
         } else if (minResultsCount == 0) {
-            return readyValue(Collections.emptyList());
+            return success(Collections.emptyList());
         } else if (promises.length == 1) {
             return from(promises[0], Collections::singletonList, Function.<Throwable> identity());
         } else {