diff --git a/src/main/asciidoc/futures.adoc b/src/main/asciidoc/futures.adoc index 210ed23bff2..c87d96b49c4 100644 --- a/src/main/asciidoc/futures.adoc +++ b/src/main/asciidoc/futures.adoc @@ -81,7 +81,7 @@ Beyond this, {@link io.vertx.core.Future} offers more: `map`, `recover`, `otherw Coordination of multiple futures can be achieved with Vert.x {@link io.vertx.core.Future futures}. It supports concurrent composition (run several async operations in parallel) and sequential composition (chain async operations). -{@link io.vertx.core.CompositeFuture#all} takes several futures arguments (up to 6) and returns a future that is +{@link io.vertx.core.Future#all} takes several futures arguments (up to 6) and returns a future that is _succeeded_ when all the futures are _succeeded_ and _failed_ when at least one of the futures is failed: [source,$lang] @@ -93,8 +93,7 @@ The operations run concurrently, the {@link io.vertx.core.Handler} attached to t When one of the operation fails (one of the passed future is marked as a failure), the resulting future is marked as failed too. When all the operations succeed, the resulting future is completed with a success. -On success, the `resultAt` method guarantees the results in the same order specified in the call to `CompositeFuture.all`. In the example above, regardless of which -item completed first, the `httpServer` result can be accessed using `resultAt(0)` and the `netServer` result can be accessed using `resultAt(1)`. +On success, the `resultAt` method guarantees the results in the same order specified in the call to `Future.all`. In the example above, regardless of which item completed first, the `httpServer` result can be accessed using `resultAt(0)` and the `netServer` result can be accessed using `resultAt(1)`. Alternatively, you can pass a list (potentially empty) of futures: @@ -103,8 +102,7 @@ Alternatively, you can pass a list (potentially empty) of futures: {@link examples.CoreExamples#exampleFutureAll2} ---- -While the `all` composition _waits_ until all futures are successful (or one fails), the `any` composition -_waits_ for the first succeeded future. {@link io.vertx.core.CompositeFuture#any} takes several futures arguments (up to 6) and returns a future that is succeeded when one of the futures is, and failed when all the futures are failed: +While the `all` composition _waits_ until all futures are successful (or one fails), the `any` composition _waits_ for the first succeeded future. {@link io.vertx.core.Future#any} takes several futures arguments (up to 6) and returns a future that is succeeded when one of the futures is, and failed when all the futures are failed: [source,$lang] ---- @@ -118,8 +116,7 @@ A list of futures can be used also: {@link examples.CoreExamples#exampleFutureAny2} ---- -The `join` composition _waits_ until all futures are completed, either with a success or a failure. -{@link io.vertx.core.CompositeFuture#join} takes several futures arguments (up to 6) and returns a future that is succeeded when all the futures are succeeded, and failed when all the futures are completed and at least one of them is failed: +The `join` composition _waits_ until all futures are completed, either with a success or a failure. {@link io.vertx.core.Future#join} takes several futures arguments (up to 6) and returns a future that is succeeded when all the futures are succeeded, and failed when all the futures are completed and at least one of them is failed: [source,$lang] ---- diff --git a/src/main/java/examples/CoreExamples.java b/src/main/java/examples/CoreExamples.java index af3b5ea1ca4..6c2ec14c912 100644 --- a/src/main/java/examples/CoreExamples.java +++ b/src/main/java/examples/CoreExamples.java @@ -180,7 +180,7 @@ public void exampleFutureAll1(HttpServer httpServer, NetServer netServer) { Future netServerFuture = netServer.listen(); - CompositeFuture.all(httpServerFuture, netServerFuture).onComplete(ar -> { + Future.all(httpServerFuture, netServerFuture).onComplete(ar -> { if (ar.succeeded()) { // All servers started } else { @@ -189,12 +189,12 @@ public void exampleFutureAll1(HttpServer httpServer, NetServer netServer) { }); } - public void exampleFutureAll2(Future future1, Future future2, Future future3) { - CompositeFuture.all(Arrays.asList(future1, future2, future3)); + public void exampleFutureAll2(Future future1, Future future2, Future future3) { + Future.all(Arrays.asList(future1, future2, future3)); } public void exampleFutureAny1(Future future1, Future future2) { - CompositeFuture.any(future1, future2).onComplete(ar -> { + Future.any(future1, future2).onComplete(ar -> { if (ar.succeeded()) { // At least one is succeeded } else { @@ -203,12 +203,12 @@ public void exampleFutureAny1(Future future1, Future future2) { }); } - public void exampleFutureAny2(Future f1, Future f2, Future f3) { - CompositeFuture.any(Arrays.asList(f1, f2, f3)); + public void exampleFutureAny2(Future f1, Future f2, Future f3) { + Future.any(Arrays.asList(f1, f2, f3)); } - public void exampleFutureJoin1(Future future1, Future future2, Future future3) { - CompositeFuture.join(future1, future2, future3).onComplete(ar -> { + public void exampleFutureJoin1(Future future1, Future future2, Future future3) { + Future.join(future1, future2, future3).onComplete(ar -> { if (ar.succeeded()) { // All succeeded } else { @@ -217,8 +217,8 @@ public void exampleFutureJoin1(Future future1, Future future2, Future future3) { }); } - public void exampleFutureJoin2(Future future1, Future future2, Future future3) { - CompositeFuture.join(Arrays.asList(future1, future2, future3)); + public void exampleFutureJoin2(Future future1, Future future2, Future future3) { + Future.join(Arrays.asList(future1, future2, future3)); } public void example7_1(Vertx vertx) { diff --git a/src/main/java/io/vertx/core/CompositeFuture.java b/src/main/java/io/vertx/core/CompositeFuture.java index e7abfa46bde..c82a5d1d24f 100644 --- a/src/main/java/io/vertx/core/CompositeFuture.java +++ b/src/main/java/io/vertx/core/CompositeFuture.java @@ -34,35 +34,45 @@ public interface CompositeFuture extends Future { * @param f1 future * @param f2 future * @return the composite future + * @deprecated instead use {@link Future#all(Future, Future)} */ + @Deprecated static CompositeFuture all(Future f1, Future f2) { return CompositeFutureImpl.all(f1, f2); } /** * Like {@link #all(Future, Future)} but with 3 futures. + * @deprecated instead use {@link Future#all(Future, Future, Future)} */ + @Deprecated static CompositeFuture all(Future f1, Future f2, Future f3) { return CompositeFutureImpl.all(f1, f2, f3); } /** * Like {@link #all(Future, Future)} but with 4 futures. + * @deprecated instead use {@link Future#all(Future, Future, Future, Future)} */ + @Deprecated static CompositeFuture all(Future f1, Future f2, Future f3, Future f4) { return CompositeFutureImpl.all(f1, f2, f3, f4); } /** * Like {@link #all(Future, Future)} but with 5 futures. + * @deprecated instead use {@link Future#all(Future, Future, Future, Future, Future)} */ + @Deprecated static CompositeFuture all(Future f1, Future f2, Future f3, Future f4, Future f5) { return CompositeFutureImpl.all(f1, f2, f3, f4, f5); } /** * Like {@link #all(Future, Future)} but with 6 futures. + * @deprecated instead use {@link Future#all(Future, Future, Future, Future, Future, Future)} */ + @Deprecated static CompositeFuture all(Future f1, Future f2, Future f3, Future f4, Future f5, Future f6) { return CompositeFutureImpl.all(f1, f2, f3, f4, f5, f6); } @@ -71,7 +81,9 @@ static CompositeFuture all(Future f1, Future f2 * Like {@link #all(Future, Future)} but with a list of futures.

* * When the list is empty, the returned future will be already completed. + * @deprecated instead use {@link Future#all(List)} */ + @Deprecated static CompositeFuture all(List futures) { return CompositeFutureImpl.all(futures.toArray(new Future[0])); } @@ -84,35 +96,45 @@ static CompositeFuture all(List futures) { * @param f1 future * @param f2 future * @return the composite future + * @deprecated instead use {@link Future#any(Future, Future)} */ + @Deprecated static CompositeFuture any(Future f1, Future f2) { return CompositeFutureImpl.any(f1, f2); } /** * Like {@link #any(Future, Future)} but with 3 futures. + * @deprecated instead use {@link Future#any(Future, Future, Future)} */ + @Deprecated static CompositeFuture any(Future f1, Future f2, Future f3) { return CompositeFutureImpl.any(f1, f2, f3); } /** * Like {@link #any(Future, Future)} but with 4 futures. + * @deprecated instead use {@link Future#any(Future, Future, Future, Future)} */ + @Deprecated static CompositeFuture any(Future f1, Future f2, Future f3, Future f4) { return CompositeFutureImpl.any(f1, f2, f3, f4); } /** * Like {@link #any(Future, Future)} but with 5 futures. + * @deprecated instead use {@link Future#any(Future, Future, Future, Future, Future)} */ + @Deprecated static CompositeFuture any(Future f1, Future f2, Future f3, Future f4, Future f5) { return CompositeFutureImpl.any(f1, f2, f3, f4, f5); } /** * Like {@link #any(Future, Future)} but with 6 futures. + * @deprecated instead use {@link Future#any(Future, Future, Future, Future, Future, Future)} */ + @Deprecated static CompositeFuture any(Future f1, Future f2, Future f3, Future f4, Future f5, Future f6) { return CompositeFutureImpl.any(f1, f2, f3, f4, f5, f6); } @@ -121,7 +143,9 @@ static CompositeFuture any(Future f1, Future f2 * Like {@link #any(Future, Future)} but with a list of futures.

* * When the list is empty, the returned future will be already completed. + * @deprecated instead use {@link Future#any(List)} */ + @Deprecated static CompositeFuture any(List futures) { return CompositeFutureImpl.any(futures.toArray(new Future[0])); } @@ -134,35 +158,45 @@ static CompositeFuture any(List futures) { * @param f1 future * @param f2 future * @return the composite future + * @deprecated instead use {@link Future#join(Future, Future)} */ + @Deprecated static CompositeFuture join(Future f1, Future f2) { return CompositeFutureImpl.join(f1, f2); } /** * Like {@link #join(Future, Future)} but with 3 futures. + * @deprecated instead use {@link Future#join(Future, Future, Future)} */ + @Deprecated static CompositeFuture join(Future f1, Future f2, Future f3) { return CompositeFutureImpl.join(f1, f2, f3); } /** * Like {@link #join(Future, Future)} but with 4 futures. + * @deprecated instead use {@link Future#join(Future, Future, Future, Future)} */ + @Deprecated static CompositeFuture join(Future f1, Future f2, Future f3, Future f4) { return CompositeFutureImpl.join(f1, f2, f3, f4); } /** * Like {@link #join(Future, Future)} but with 5 futures. + * @deprecated instead use {@link Future#join(Future, Future, Future, Future, Future)} */ + @Deprecated static CompositeFuture join(Future f1, Future f2, Future f3, Future f4, Future f5) { return CompositeFutureImpl.join(f1, f2, f3, f4, f5); } /** * Like {@link #join(Future, Future)} but with 6 futures. + * @deprecated instead use {@link Future#join(Future, Future, Future, Future, Future, Future)} */ + @Deprecated static CompositeFuture join(Future f1, Future f2, Future f3, Future f4, Future f5, Future f6) { return CompositeFutureImpl.join(f1, f2, f3, f4, f5, f6); } @@ -171,7 +205,9 @@ static CompositeFuture join(Future f1, Future f * Like {@link #join(Future, Future)} but with a list of futures.

* * When the list is empty, the returned future will be already completed. + * @deprecated instead use {@link Future#join(List)} */ + @Deprecated static CompositeFuture join(List futures) { return CompositeFutureImpl.join(futures.toArray(new Future[0])); } diff --git a/src/main/java/io/vertx/core/Future.java b/src/main/java/io/vertx/core/Future.java index 95ff060b72c..3b121c40040 100644 --- a/src/main/java/io/vertx/core/Future.java +++ b/src/main/java/io/vertx/core/Future.java @@ -14,9 +14,11 @@ import io.vertx.codegen.annotations.Fluent; import io.vertx.codegen.annotations.GenIgnore; import io.vertx.core.impl.ContextInternal; +import io.vertx.core.impl.future.CompositeFutureImpl; import io.vertx.core.impl.future.FailedFuture; import io.vertx.core.impl.future.SucceededFuture; +import java.util.List; import java.util.concurrent.CompletableFuture; import java.util.concurrent.CompletionStage; import java.util.function.Function; @@ -29,6 +31,156 @@ */ public interface Future extends AsyncResult { + /** + * Return a composite future, succeeded when all futures are succeeded, failed when any future is failed. + *

+ * The returned future fails as soon as one of {@code f1} or {@code f2} fails. + * + * @param f1 future + * @param f2 future + * @return the composite future + */ + static CompositeFuture all(Future f1, Future f2) { + return CompositeFutureImpl.all(f1, f2); + } + + /** + * Like {@link #all(Future, Future)} but with 3 futures. + */ + static CompositeFuture all(Future f1, Future f2, Future f3) { + return CompositeFutureImpl.all(f1, f2, f3); + } + + /** + * Like {@link #all(Future, Future)} but with 4 futures. + */ + static CompositeFuture all(Future f1, Future f2, Future f3, Future f4) { + return CompositeFutureImpl.all(f1, f2, f3, f4); + } + + /** + * Like {@link #all(Future, Future)} but with 5 futures. + */ + static CompositeFuture all(Future f1, Future f2, Future f3, Future f4, Future f5) { + return CompositeFutureImpl.all(f1, f2, f3, f4, f5); + } + + /** + * Like {@link #all(Future, Future)} but with 6 futures. + */ + static CompositeFuture all(Future f1, Future f2, Future f3, Future f4, Future f5, Future f6) { + return CompositeFutureImpl.all(f1, f2, f3, f4, f5, f6); + } + + /** + * Like {@link #all(Future, Future)} but with a list of futures.

+ * + * When the list is empty, the returned future will be already completed. + */ + static CompositeFuture all(List> futures) { + return CompositeFutureImpl.all(futures.toArray(new Future[0])); + } + + /** + * Return a composite future, succeeded when any futures is succeeded, failed when all futures are failed. + *

+ * The returned future succeeds as soon as one of {@code f1} or {@code f2} succeeds. + * + * @param f1 future + * @param f2 future + * @return the composite future + */ + static CompositeFuture any(Future f1, Future f2) { + return CompositeFutureImpl.any(f1, f2); + } + + /** + * Like {@link #any(Future, Future)} but with 3 futures. + */ + static CompositeFuture any(Future f1, Future f2, Future f3) { + return CompositeFutureImpl.any(f1, f2, f3); + } + + /** + * Like {@link #any(Future, Future)} but with 4 futures. + */ + static CompositeFuture any(Future f1, Future f2, Future f3, Future f4) { + return CompositeFutureImpl.any(f1, f2, f3, f4); + } + + /** + * Like {@link #any(Future, Future)} but with 5 futures. + */ + static CompositeFuture any(Future f1, Future f2, Future f3, Future f4, Future f5) { + return CompositeFutureImpl.any(f1, f2, f3, f4, f5); + } + + /** + * Like {@link #any(Future, Future)} but with 6 futures. + */ + static CompositeFuture any(Future f1, Future f2, Future f3, Future f4, Future f5, Future f6) { + return CompositeFutureImpl.any(f1, f2, f3, f4, f5, f6); + } + + /** + * Like {@link #any(Future, Future)} but with a list of futures.

+ * + * When the list is empty, the returned future will be already completed. + */ + static CompositeFuture any(List> futures) { + return CompositeFutureImpl.any(futures.toArray(new Future[0])); + } + + /** + * Return a composite future, succeeded when all futures are succeeded, failed when any future is failed. + *

+ * It always wait until all its futures are completed and will not fail as soon as one of {@code f1} or {@code f2} fails. + * + * @param f1 future + * @param f2 future + * @return the composite future + */ + static CompositeFuture join(Future f1, Future f2) { + return CompositeFutureImpl.join(f1, f2); + } + + /** + * Like {@link #join(Future, Future)} but with 3 futures. + */ + static CompositeFuture join(Future f1, Future f2, Future f3) { + return CompositeFutureImpl.join(f1, f2, f3); + } + + /** + * Like {@link #join(Future, Future)} but with 4 futures. + */ + static CompositeFuture join(Future f1, Future f2, Future f3, Future f4) { + return CompositeFutureImpl.join(f1, f2, f3, f4); + } + + /** + * Like {@link #join(Future, Future)} but with 5 futures. + */ + static CompositeFuture join(Future f1, Future f2, Future f3, Future f4, Future f5) { + return CompositeFutureImpl.join(f1, f2, f3, f4, f5); + } + + /** + * Like {@link #join(Future, Future)} but with 6 futures. + */ + static CompositeFuture join(Future f1, Future f2, Future f3, Future f4, Future f5, Future f6) { + return CompositeFutureImpl.join(f1, f2, f3, f4, f5, f6); + } + + /** + * Like {@link #join(Future, Future)} but with a list of futures.

+ * + * When the list is empty, the returned future will be already completed. + */ + static CompositeFuture join(List> futures) { + return CompositeFutureImpl.join(futures.toArray(new Future[0])); + } + /** * Create a future that hasn't completed yet and that is passed to the {@code handler} before it is returned. *