diff --git a/cffu-core/src/main/java/io/foldright/cffu/CffuFactory.java b/cffu-core/src/main/java/io/foldright/cffu/CffuFactory.java index c8f603eb..f6c6d0ee 100644 --- a/cffu-core/src/main/java/io/foldright/cffu/CffuFactory.java +++ b/cffu-core/src/main/java/io/foldright/cffu/CffuFactory.java @@ -19,7 +19,6 @@ import java.util.concurrent.TimeUnit; import java.util.function.Supplier; -import static io.foldright.cffu.CompletableFutureUtils.toCompletableFutureArray; import static java.util.Objects.requireNonNull; @@ -301,8 +300,8 @@ public final Cffu[] toCffuArray(CompletionStage... stages) { /** * Returns a new Cffu that is completed when all the given stages complete. - * If any of the given stages complete exceptionally, then the returned - * Cffu also does so, with a CompletionException holding this exception as its cause.
+ * If any of the given stages complete exceptionally, then the returned Cffu also does so, + * with a CompletionException holding this exception as its cause.
* Otherwise, the results, if any, of the given stages are not reflected in * the returned Cffu({@code Cffu}), but may be obtained by inspecting them individually.
* If no stages are provided, returns a Cffu completed with the value {@code null}. @@ -323,12 +322,11 @@ public final Cffu[] toCffuArray(CompletionStage... stages) { * @see #allTupleOf(CompletionStage, CompletionStage, CompletionStage) * @see #allTupleOf(CompletionStage, CompletionStage, CompletionStage, CompletionStage) * @see #allTupleOf(CompletionStage, CompletionStage, CompletionStage, CompletionStage, CompletionStage) - * @see CompletableFuture#allOf(CompletableFuture[]) + * @see CompletableFutureUtils#allOf(CompletionStage[]) */ @Contract(pure = true) - @SuppressWarnings({"unchecked", "rawtypes"}) public Cffu allOf(CompletionStage... cfs) { - return new0(CompletableFuture.allOf(toCompletableFutureArray((CompletionStage[]) cfs))); + return new0(CompletableFutureUtils.allOf(cfs)); } /** diff --git a/cffu-core/src/main/java/io/foldright/cffu/CompletableFutureUtils.java b/cffu-core/src/main/java/io/foldright/cffu/CompletableFutureUtils.java index 207819df..fc43455f 100644 --- a/cffu-core/src/main/java/io/foldright/cffu/CompletableFutureUtils.java +++ b/cffu-core/src/main/java/io/foldright/cffu/CompletableFutureUtils.java @@ -32,6 +32,34 @@ public final class CompletableFutureUtils { //# allOf* methods //////////////////////////////////////////////////////////////////////////////// + /** + * Returns a new CompletableFuture that is completed when all the given stages complete. + * If any of the given stages complete exceptionally, then the returned CompletableFuture also does so, + * with a CompletionException holding this exception as its cause. + * Otherwise, the results, if any, of the given stages are not reflected + * in the returned CompletableFuture, but may be obtained by inspecting them individually. + * If no stages are provided, returns a CompletableFuture completed with the value {@code null}. + *

+ * if you need the results of given stages, prefer below methods: + *

    + *
  • {@link #allResultsOf(CompletionStage[])} + *
  • {@link #allTupleOf(CompletionStage, CompletionStage)} / + * {@link #allTupleOf(CompletionStage, CompletionStage, CompletionStage, CompletionStage, CompletionStage)} + * (provided overloaded methods with 2~5 input) + *
+ *

+ * This method is the same as {@link CompletableFuture#allOf(CompletableFuture[])}, + * except the parameter type is more generic({@link CompletionStage}). + * + * @param cfs the stages + * @return a new CompletableFuture that is completed when all the given stages complete + * @throws NullPointerException if the array or any of its elements are {@code null} + */ + @SuppressWarnings({"unchecked", "rawtypes"}) + public static CompletableFuture allOf(CompletionStage... cfs) { + return CompletableFuture.allOf(toCompletableFutureArray((CompletionStage[]) cfs)); + } + /** * Returns a new CompletableFuture with the results in the same order of all the given * CompletableFutures, the new CompletableFuture is completed when all the given CompletableFutures complete. @@ -197,13 +225,14 @@ private static void fill(CompletionStage[] cfs, /** * Returns a new CompletableFuture that is completed - * when any of the given CompletableFutures complete, with the same result. + * when any of the given CompletableFutures(stages) complete, with the same result. * Otherwise, if it completed exceptionally, the returned CompletableFuture also does so, * with a CompletionException holding this exception as its cause. * If no CompletableFutures are provided, returns an incomplete CompletableFuture. *

* This method is the same as {@link CompletableFuture#anyOf(CompletableFuture[])}, - * except the return result type is generic type instead of {@code Object}. + * except the parameter type is more generic type {@link CompletionStage}. + * and the return result type is generic type instead of {@code Object}. * * @param cfs the CompletableFutures * @return a new CompletableFuture that is completed with the result diff --git a/cffu-kotlin/src/main/java/io/foldright/cffu/kotlin/CompletableFutureExtensions.kt b/cffu-kotlin/src/main/java/io/foldright/cffu/kotlin/CompletableFutureExtensions.kt index 049b65c6..6bf3a3ab 100644 --- a/cffu-kotlin/src/main/java/io/foldright/cffu/kotlin/CompletableFutureExtensions.kt +++ b/cffu-kotlin/src/main/java/io/foldright/cffu/kotlin/CompletableFutureExtensions.kt @@ -29,49 +29,52 @@ import java.util.function.Function //////////////////////////////////////// /** - * Returns a new CompletableFuture that is completed when all the given CompletableFutures complete. - * If any of the given CompletableFutures complete exceptionally, then the returned CompletableFuture - * also does so, with a CompletionException holding this exception as its cause. - * Otherwise, the results, if any, of the given CompletableFutures are not reflected in the returned - * CompletableFuture, but may be obtained by inspecting them individually. - * If no CompletableFutures are provided, returns a CompletableFuture completed with the value `null`. + * Returns a new CompletableFuture that is completed when all the given stages complete. + * If any of the given stages complete exceptionally, then the returned CompletableFuture also does so, + * with a CompletionException holding this exception as its cause. + * Otherwise, the results, if any, of the given stages are not reflected + * in the returned CompletableFuture, but may be obtained by inspecting them individually. + * If no stages are provided, returns a CompletableFuture completed with the value `null`. + * + * If you need the results of given stages, prefer below methods: * - * Among the applications of this method is to await completion of a set of independent CompletableFutures - * before continuing a program, as in: `CompletableFuture.allOf(c1, c2, c3).join();`. - * Returns a new CompletableFuture that is completed when all the given CompletableFutures complete. + * - [allResultsOfCompletableFuture] + * - [allTupleOf] (provided overloaded methods with 2~5 input) * - * This method is the same as [CompletableFuture.allOf], providing this method is convenient for method chaining. + * This method is the same as [CompletableFutureUtils.allOf], providing this method is convenient for method chaining. * + * @see allResultsOfCompletableFuture * @see allResultsOfCffu * @see allOfCffu - * @see allResultsOfCompletableFuture + * @see CompletableFutureUtils.allOf * @see CompletableFuture.allOf */ fun Collection>.allOfCompletableFuture(): CompletableFuture = - CompletableFuture.allOf(*this.map { it.toCompletableFuture() }.toTypedArray()) + CompletableFutureUtils.allOf(*this.toTypedArray()) /** - * Returns a new CompletableFuture that is completed when all the given CompletableFutures complete. - * If any of the given CompletableFutures complete exceptionally, then the returned CompletableFuture - * also does so, with a CompletionException holding this exception as its cause. - * Otherwise, the results, if any, of the given CompletableFutures are not reflected in the returned - * CompletableFuture, but may be obtained by inspecting them individually. - * If no CompletableFutures are provided, returns a CompletableFuture completed with the value `null`. + * Returns a new CompletableFuture that is completed when all the given stages complete. + * If any of the given stages complete exceptionally, then the returned CompletableFuture also does so, + * with a CompletionException holding this exception as its cause. + * Otherwise, the results, if any, of the given stages are not reflected + * in the returned CompletableFuture, but may be obtained by inspecting them individually. + * If no stages are provided, returns a CompletableFuture completed with the value `null`. + * + * If you need the results of given stages, prefer below methods: * - * Among the applications of this method is to await completion of a set of independent CompletableFutures - * before continuing a program, as in: `CompletableFuture.allOf(c1, c2, c3).join();`. - * Returns a new CompletableFuture that is completed when all the given CompletableFutures complete. + * - [allResultsOfCompletableFuture] + * - [allTupleOf] (provided overloaded methods with 2~5 input) * - * This method is the same as [CompletableFuture.allOf], providing this method is convenient for method chaining. + * This method is the same as [CompletableFutureUtils.allOf], providing this method is convenient for method chaining. * + * @see allResultsOfCompletableFuture * @see allResultsOfCffu * @see allOfCffu - * @see allResultsOfCompletableFuture + * @see CompletableFutureUtils.allOf * @see CompletableFuture.allOf */ -@Suppress("UNCHECKED_CAST") fun Array>.allOfCompletableFuture(): CompletableFuture = - CompletableFuture.allOf(*(this as Array>).toCompletableFuture()) + CompletableFutureUtils.allOf(*this) /** * Returns a new CompletableFuture that is successful when all the given CompletableFutures success, @@ -82,6 +85,11 @@ fun Array>.allOfCompletableFuture(): CompletableFuture>.allOfFastFailCompletableFuture(): Completable * with a CompletionException holding this exception as its cause. * If no CompletableFutures are provided, returns a CompletableFuture completed with the value `null`. * + * If you need the results of given stages, prefer below methods: + * + * - [allResultsOfFastFailCompletableFuture] + * - [allTupleOfFastFail] (provided overloaded methods with 2~5 input) + * * This method is the same as [CompletableFutureUtils.allOfFastFail], * providing this method is convenient for method chaining. *