Future (Vert.x Stack - Docs 4.5.11 API)

All Superinterfaces:

AsyncResult<T>

All Known Subinterfaces:

CompositeFuture, Timer
```
public interface Future<T>
extends AsyncResult<T>
```
Represents the result of an action that may, or may not, have occurred yet.

Author:

Tim Fox

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
Modifier and Type	Method and Description
`static CompositeFuture`	`all(Future<?> f1, Future<?> f2)` Return a composite future, succeeded when all futures are succeeded, failed when any future is failed.
`static CompositeFuture`	`all(Future<?> f1, Future<?> f2, Future<?> f3)` Like `all(Future, Future)` but with 3 futures.
`static CompositeFuture`	`all(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4)` Like `all(Future, Future)` but with 4 futures.
`static CompositeFuture`	`all(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4, Future<?> f5)` Like `all(Future, Future)` but with 5 futures.
`static CompositeFuture`	`all(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4, Future<?> f5, Future<?> f6)` Like `all(Future, Future)` but with 6 futures.
`static CompositeFuture`	`all(List<? extends Future<?>> futures)` Like `all(Future, Future)` but with a list of futures.
`default Future<T>`	`andThen(Handler<AsyncResult<T>> handler)` Invokes the given `handler` upon completion.
`static CompositeFuture`	`any(Future<?> f1, Future<?> f2)` Return a composite future, succeeded when any futures is succeeded, failed when all futures are failed.
`static CompositeFuture`	`any(Future<?> f1, Future<?> f2, Future<?> f3)` Like `any(Future, Future)` but with 3 futures.
`static CompositeFuture`	`any(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4)` Like `any(Future, Future)` but with 4 futures.
`static CompositeFuture`	`any(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4, Future<?> f5)` Like `any(Future, Future)` but with 5 futures.
`static CompositeFuture`	`any(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4, Future<?> f5, Future<?> f6)` Like `any(Future, Future)` but with 6 futures.
`static CompositeFuture`	`any(List<? extends Future<?>> futures)` Like `any(Future, Future)` but with a list of futures.
`static <T> T`	`await(Future<T> future)` Park the current thread until the `future` is completed, when the future is completed the thread is un-parked and the result value is returned when the future was completed with a result otherwise, the failure is thrown This method must be called from a virtual thread.
`Throwable`	`cause()` A Throwable describing failure.
`default <U> Future<U>`	`compose(java.util.function.Function<T,Future<U>> mapper)` Compose this future with a `mapper` function.
`<U> Future<U>`	`compose(java.util.function.Function<T,Future<U>> successMapper, java.util.function.Function<Throwable,Future<U>> failureMapper)` Compose this future with a `successMapper` and `failureMapper` functions.
`<U> Future<T>`	`eventually(java.util.function.Function<Void,Future<U>> function)` Deprecated. instead use `eventually(Supplier)`, this method will be removed in Vert.x 5
`default <U> Future<T>`	`eventually(java.util.function.Supplier<Future<U>> supplier)` Compose this future with a `supplier` that will be always be called.
`Future<T>`	`expecting(Expectation<? super T> expectation)` Guard the control flow of this future with an expectation.
`boolean`	`failed()` Did it fail?
`static <T> Future<T>`	`failedFuture(String failureMessage)` Create a failed future with the specified failure message.
`static <T> Future<T>`	`failedFuture(Throwable t)` Create a failed future with the specified failure cause.
`default <U> Future<U>`	`flatMap(java.util.function.Function<T,Future<U>> mapper)` Alias for `compose(Function)`.
`static <T> Future<T>`	`fromCompletionStage(CompletionStage<T> completionStage)` Bridges a `CompletionStage` object to a Vert.x future instance.
`static <T> Future<T>`	`fromCompletionStage(CompletionStage<T> completionStage, Context context)` Bridges a `CompletionStage` object to a Vert.x future instance.
`static <T> Future<T>`	`future(Handler<Promise<T>> handler)` Create a future that hasn't completed yet and that is passed to the `handler` before it is returned.
`boolean`	`isComplete()` Has the future completed?
`static CompositeFuture`	`join(Future<?> f1, Future<?> f2)` Return a composite future, succeeded when all futures are succeeded, failed when any future is failed.
`static CompositeFuture`	`join(Future<?> f1, Future<?> f2, Future<?> f3)` Like `join(Future, Future)` but with 3 futures.
`static CompositeFuture`	`join(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4)` Like `join(Future, Future)` but with 4 futures.
`static CompositeFuture`	`join(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4, Future<?> f5)` Like `join(Future, Future)` but with 5 futures.
`static CompositeFuture`	`join(Future<?> f1, Future<?> f2, Future<?> f3, Future<?> f4, Future<?> f5, Future<?> f6)` Like `join(Future, Future)` but with 6 futures.
`static CompositeFuture`	`join(List<? extends Future<?>> futures)` Like `join(Future, Future)` but with a list of futures.
`<U> Future<U>`	`map(java.util.function.Function<T,U> mapper)` Apply a `mapper` function on this future.
`<V> Future<V>`	`map(V value)` Map the result of a future to a specific `value`.
`default <V> Future<V>`	`mapEmpty()` Map the result of a future to `null`.
`Future<T>`	`onComplete(Handler<AsyncResult<T>> handler)` Add a handler to be notified of the result.
`default Future<T>`	`onComplete(Handler<T> successHandler, Handler<Throwable> failureHandler)` Add handlers to be notified on succeeded result and failed result.
`default Future<T>`	`onFailure(Handler<Throwable> handler)` Add a handler to be notified of the failed result.
`default Future<T>`	`onSuccess(Handler<T> handler)` Add a handler to be notified of the succeeded result.
`Future<T>`	`otherwise(java.util.function.Function<Throwable,T> mapper)` Apply a `mapper` function on this future.
`Future<T>`	`otherwise(T value)` Map the failure of a future to a specific `value`.
`default Future<T>`	`otherwiseEmpty()` Map the failure of a future to `null`.
`default Future<T>`	`recover(java.util.function.Function<Throwable,Future<T>> mapper)` Handles a failure of this Future by returning the result of another Future.
`T`	`result()` The result of the operation.
`boolean`	`succeeded()` Did it succeed?
`static <T> Future<T>`	`succeededFuture()` Create a succeeded future with a null result
`static <T> Future<T>`	`succeededFuture(T result)` Created a succeeded future with the specified result.
`Future<T>`	`timeout(long delay, TimeUnit unit)` Returns a future succeeded or failed with the outcome of this future when it happens before the timeout fires.
`default CompletionStage<T>`	`toCompletionStage()` Bridges this Vert.x future to a `CompletionStage` instance.
`<U> Future<U>`	`transform(java.util.function.Function<AsyncResult<T>,Future<U>> mapper)` Transform this future with a `mapper` functions.

- Method Detail
 - all
```
static CompositeFuture all(Future<?> f1,
 Future<?> f2)
```
 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 f1 or f2 fails.
 
 Parameters:
 
 f1 - future
 
 f2 - future
 
 Returns:
 
 the composite future
 - all
```
static CompositeFuture all(Future<?> f1,
 Future<?> f2,
 Future<?> f3)
```
 Like all(Future, Future) but with 3 futures.
 - all
```
static CompositeFuture all(Future<?> f1,
 Future<?> f2,
 Future<?> f3,
 Future<?> f4)
```
 Like all(Future, Future) but with 4 futures.
 - all
```
static CompositeFuture all(Future<?> f1,
 Future<?> f2,
 Future<?> f3,
 Future<?> f4,
 Future<?> f5)
```
 Like all(Future, Future) but with 5 futures.
 - all
```
static CompositeFuture all(Future<?> f1,
 Future<?> f2,
 Future<?> f3,
 Future<?> f4,
 Future<?> f5,
 Future<?> f6)
```
 Like all(Future, Future) but with 6 futures.
 - all
```
static CompositeFuture all(List<? extends Future<?>> futures)
```
 Like all(Future, Future) but with a list of futures.
 When the list is empty, the returned future will be already completed.
 - any
```
static CompositeFuture any(Future<?> f1,
 Future<?> f2)
```
 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 f1 or f2 succeeds.
 
 Parameters:
 
 f1 - future
 
 f2 - future
 
 Returns:
 
 the composite future
 - any
```
static CompositeFuture any(Future<?> f1,
 Future<?> f2,
 Future<?> f3)
```
 Like any(Future, Future) but with 3 futures.
 - any
```
static CompositeFuture any(Future<?> f1,
 Future<?> f2,
 Future<?> f3,
 Future<?> f4)
```
 Like any(Future, Future) but with 4 futures.
 - any
```
static CompositeFuture any(Future<?> f1,
 Future<?> f2,
 Future<?> f3,
 Future<?> f4,
 Future<?> f5)
```
 Like any(Future, Future) but with 5 futures.
 - any
```
static CompositeFuture any(Future<?> f1,
 Future<?> f2,
 Future<?> f3,
 Future<?> f4,
 Future<?> f5,
 Future<?> f6)
```
 Like any(Future, Future) but with 6 futures.
 - any
```
static CompositeFuture any(List<? extends Future<?>> futures)
```
 Like any(Future, Future) but with a list of futures.
 When the list is empty, the returned future will be already completed.
 - join
```
static CompositeFuture join(Future<?> f1,
 Future<?> f2)
```
 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 f1 or f2 fails.
 
 Parameters:
 
 f1 - future
 
 f2 - future
 
 Returns:
 
 the composite future
 - join
```
static CompositeFuture join(Future<?> f1,
 Future<?> f2,
 Future<?> f3)
```
 Like join(Future, Future) but with 3 futures.
 - join
```
static CompositeFuture join(Future<?> f1,
 Future<?> f2,
 Future<?> f3,
 Future<?> f4)
```
 Like join(Future, Future) but with 4 futures.
 - join
```
static CompositeFuture join(Future<?> f1,
 Future<?> f2,
 Future<?> f3,
 Future<?> f4,
 Future<?> f5)
```
 Like join(Future, Future) but with 5 futures.
 - join
```
static CompositeFuture join(Future<?> f1,
 Future<?> f2,
 Future<?> f3,
 Future<?> f4,
 Future<?> f5,
 Future<?> f6)
```
 Like join(Future, Future) but with 6 futures.
 - join
```
static CompositeFuture join(List<? extends Future<?>> futures)
```
 Like join(Future, Future) but with a list of futures.
 When the list is empty, the returned future will be already completed.
 - future
```
static <T> Future<T> future(Handler<Promise<T>> handler)
```
 Create a future that hasn't completed yet and that is passed to the handler before it is returned.
 
 Type Parameters:
 
 T - the result type
 
 Parameters:
 
 handler - the handler
 
 Returns:
 
 the future.
 - succeededFuture
```
static <T> Future<T> succeededFuture()
```
 Create a succeeded future with a null result
 
 Type Parameters:
 
 T - the result type
 
 Returns:
 
 the future
 - succeededFuture
```
static <T> Future<T> succeededFuture(T result)
```
 Created a succeeded future with the specified result.
 
 Type Parameters:
 
 T - the result type
 
 Parameters:
 
 result - the result
 
 Returns:
 
 the future
 - failedFuture
```
static <T> Future<T> failedFuture(Throwable t)
```
 Create a failed future with the specified failure cause.
 
 Type Parameters:
 
 T - the result type
 
 Parameters:
 
 t - the failure cause as a Throwable
 
 Returns:
 
 the future
 - failedFuture
```
static <T> Future<T> failedFuture(String failureMessage)
```
 Create a failed future with the specified failure message.
 
 Type Parameters:
 
 T - the result type
 
 Parameters:
 
 failureMessage - the failure message
 
 Returns:
 
 the future
 - isComplete
```
boolean isComplete()
```
 Has the future completed?
 It's completed if it's either succeeded or failed.
 
 Returns:
 
 true if completed, false if not
 - onComplete
```
Future<T> onComplete(Handler<AsyncResult<T>> handler)
```
 Add a handler to be notified of the result.
 WARNING: this is a terminal operation. If several handlers are registered, there is no guarantee that they will be invoked in order of registration.
 
 Parameters:
 
 handler - the handler that will be called with the result
 
 Returns:
 
 a reference to this, so it can be used fluently
 - onComplete
```
default Future<T> onComplete(Handler<T> successHandler,
 Handler<Throwable> failureHandler)
```
 Add handlers to be notified on succeeded result and failed result.
 WARNING: this is a terminal operation. If several handlers are registered, there is no guarantee that they will be invoked in order of registration.
 
 Parameters:
 
 successHandler - the handler that will be called with the succeeded result
 
 failureHandler - the handler that will be called with the failed result
 
 Returns:
 
 a reference to this, so it can be used fluently
 - onSuccess
```
default Future<T> onSuccess(Handler<T> handler)
```
 Add a handler to be notified of the succeeded result.
 WARNING: this is a terminal operation. If several handlers are registered, there is no guarantee that they will be invoked in order of registration.
 
 Parameters:
 
 handler - the handler that will be called with the succeeded result
 
 Returns:
 
 a reference to this, so it can be used fluently
 - onFailure
```
default Future<T> onFailure(Handler<Throwable> handler)
```
 Add a handler to be notified of the failed result.
 WARNING: this is a terminal operation. If several handlers are registered, there is no guarantee that they will be invoked in order of registration.
 
 Parameters:
 
 handler - the handler that will be called with the failed result
 
 Returns:
 
 a reference to this, so it can be used fluently
 - result
```
T result()
```
 The result of the operation. This will be null if the operation failed.
 
 Specified by:
 
 result in interface AsyncResult<T>
 
 Returns:
 
 the result or null if the operation failed.
 - cause
```
Throwable cause()
```
 A Throwable describing failure. This will be null if the operation succeeded.
 
 Specified by:
 
 cause in interface AsyncResult<T>
 
 Returns:
 
 the cause or null if the operation succeeded.
 - succeeded
```
boolean succeeded()
```
 Did it succeed?
 
 Specified by:
 
 succeeded in interface AsyncResult<T>
 
 Returns:
 
 true if it succeded or false otherwise
 - failed
```
boolean failed()
```
 Did it fail?
 
 Specified by:
 
 failed in interface AsyncResult<T>
 
 Returns:
 
 true if it failed or false otherwise
 - flatMap
```
default  Future flatMap(java.util.function.Function<T,Future> mapper)
```
 Alias for compose(Function).
 - compose
```
default  Future compose(java.util.function.Function<T,Future> mapper)
```
 Compose this future with a mapper function.
 When this future (the one on which compose is called) succeeds, the mapper will be called with the completed value and this mapper returns another future object. This returned future completion will complete the future returned by this method call.
 If the mapper throws an exception, the returned future will be failed with this exception.
 When this future fails, the failure will be propagated to the returned future and the mapper will not be called.
 
 Parameters:
 
 mapper - the mapper function
 
 Returns:
 
 the composed future
 - recover
```
default Future<T> recover(java.util.function.Function<Throwable,Future<T>> mapper)
```
 Handles a failure of this Future by returning the result of another Future. If the mapper fails, then the returned future will be failed with this failure.
 
 Parameters:
 
 mapper - A function which takes the exception of a failure and returns a new future.
 
 Returns:
 
 A recovered future
 - compose
```
 Future compose(java.util.function.Function<T,Future> successMapper,
 java.util.function.Function<Throwable,Future> failureMapper)
```
 Compose this future with a successMapper and failureMapper functions.
 When this future (the one on which compose is called) succeeds, the successMapper will be called with the completed value and this mapper returns another future object. This returned future completion will complete the future returned by this method call.
 When this future (the one on which compose is called) fails, the failureMapper will be called with the failure and this mapper returns another future object. This returned future completion will complete the future returned by this method call.
 If any mapper function throws an exception, the returned future will be failed with this exception.
 
 Parameters:
 
 successMapper - the function mapping the success
 
 failureMapper - the function mapping the failure
 
 Returns:
 
 the composed future
 - transform
```
 Future transform(java.util.function.Function<AsyncResult<T>,Future> mapper)
```
 Transform this future with a mapper functions.
 When this future (the one on which transform is called) completes, the mapper will be called with the async result and this mapper returns another future object. This returned future completion will complete the future returned by this method call.
 If any mapper function throws an exception, the returned future will be failed with this exception.
 
 Parameters:
 
 mapper - the function mapping the future
 
 Returns:
 
 the transformed future
 - eventually
```
@Deprecated
 Future<T> eventually(java.util.function.Function<Void,Future> function)
```
 Deprecated. instead use eventually(Supplier), this method will be removed in Vert.x 5
 
 Compose this future with a function that will be always be called.
 When this future (the one on which eventually is called) completes, the function will be called and this mapper returns another future object. This returned future completion will complete the future returned by this method call with the original result of the future.
 The outcome of the future returned by the function will not influence the nature of the returned future.
 
 Parameters:
 
 function - the function returning the future.
 
 Returns:
 
 the composed future
 - eventually
```
default  Future<T> eventually(java.util.function.Supplier<Future> supplier)
```
 Compose this future with a supplier that will be always be called.
 When this future (the one on which eventually is called) completes, the supplier will be called and this mapper returns another future object. This returned future completion will complete the future returned by this method call with the original result of the future.
 The outcome of the future returned by the supplier will not influence the nature of the returned future.
 
 Parameters:
 
 supplier - the function returning the future.
 
 Returns:
 
 the composed future
 - map
```
 Future map(java.util.function.Function<T,U> mapper)
```
 Apply a mapper function on this future.
 When this future succeeds, the mapper will be called with the completed value and this mapper returns a value. This value will complete the future returned by this method call.
 If the mapper throws an exception, the returned future will be failed with this exception.
 When this future fails, the failure will be propagated to the returned future and the mapper will not be called.
 
 Specified by:
 
 map in interface AsyncResult<T>
 
 Parameters:
 
 mapper - the mapper function
 
 Returns:
 
 the mapped future
 - map
```
<V> Future<V> map(V value)
```
 Map the result of a future to a specific value.
 When this future succeeds, this value will complete the future returned by this method call.
 When this future fails, the failure will be propagated to the returned future.
 
 Specified by:
 
 map in interface AsyncResult<T>
 
 Parameters:
 
 value - the value that eventually completes the mapped future
 
 Returns:
 
 the mapped future
 - mapEmpty
```
default <V> Future<V> mapEmpty()
```
 Map the result of a future to null.
 This is a conveniency for future.map((T) null) or future.map((Void) null).
 When this future succeeds, null will complete the future returned by this method call.
 When this future fails, the failure will be propagated to the returned future.
 
 Specified by:
 
 mapEmpty in interface AsyncResult<T>
 
 Returns:
 
 the mapped future
 - otherwise
```
Future<T> otherwise(java.util.function.Function<Throwable,T> mapper)
```
 Apply a mapper function on this future.
 When this future fails, the mapper will be called with the completed value and this mapper returns a value. This value will complete the future returned by this method call.
 If the mapper throws an exception, the returned future will be failed with this exception.
 When this future succeeds, the result will be propagated to the returned future and the mapper will not be called.
 
 Specified by:
 
 otherwise in interface AsyncResult<T>
 
 Parameters:
 
 mapper - the mapper function
 
 Returns:
 
 the mapped future
 - otherwise
```
Future<T> otherwise(T value)
```
 Map the failure of a future to a specific value.
 When this future fails, this value will complete the future returned by this method call.
 When this future succeeds, the result will be propagated to the returned future.
 
 Specified by:
 
 otherwise in interface AsyncResult<T>
 
 Parameters:
 
 value - the value that eventually completes the mapped future
 
 Returns:
 
 the mapped future
 - otherwiseEmpty
```
default Future<T> otherwiseEmpty()
```
 Map the failure of a future to null.
 This is a convenience for future.otherwise((T) null).
 When this future fails, the null value will complete the future returned by this method call.
 When this future succeeds, the result will be propagated to the returned future.
 
 Specified by:
 
 otherwiseEmpty in interface AsyncResult<T>
 
 Returns:
 
 the mapped future
 - andThen
```
default Future<T> andThen(Handler<AsyncResult<T>> handler)
```
 Invokes the given handler upon completion.
 If the handler throws an exception, the returned future will be failed with this exception.
 
 Parameters:
 
 handler - invoked upon completion of this future
 
 Returns:
 
 a future completed after the handler has been invoked
 - expecting
```
Future<T> expecting(Expectation<? super T> expectation)
```
 Guard the control flow of this future with an expectation.
 When the future is completed with a success, the expectation is called with the result, when the expectation returns false the returned future is failed, otherwise the future is completed with the same result.
 Expectations are usually lambda expressions:
```
 return future.expecting(response -> response.statusCode() == 200);
 
```
 Expectation instances can also be used:
```
 future = future.expecting(HttpResponseExpectation.SC_OK);
 
```
 Parameters:
 
 expectation - the expectation
 
 Returns:
 
 a future succeeded with the result or failed when the expectation returns false
 - timeout
```
Future<T> timeout(long delay,
 TimeUnit unit)
```
 Returns a future succeeded or failed with the outcome of this future when it happens before the timeout fires. When the timeout fires before, the future is failed with a TimeoutException, guaranteeing the returned future to complete within the specified delay.
 
 Parameters:
 
 delay - the delay
 
 unit - the unit of the delay
 
 Returns:
 
 the timeout future
 - toCompletionStage
```
default CompletionStage<T> toCompletionStage()
```
 Bridges this Vert.x future to a CompletionStage instance.
 The CompletionStage handling methods will be called from the thread that resolves this future.
 
 Returns:
 
 a CompletionStage that completes when this future resolves
 - fromCompletionStage
```
static <T> Future<T> fromCompletionStage(CompletionStage<T> completionStage)
```
 Bridges a CompletionStage object to a Vert.x future instance.
 The Vert.x future handling methods will be called from the thread that completes completionStage.
 
 Type Parameters:
 
 T - the result type
 
 Parameters:
 
 completionStage - a completion stage
 
 Returns:
 
 a Vert.x future that resolves when completionStage resolves
 - fromCompletionStage
```
static <T> Future<T> fromCompletionStage(CompletionStage<T> completionStage,
 Context context)
```
 Bridges a CompletionStage object to a Vert.x future instance.
 The Vert.x future handling methods will be called on the provided context.
 
 Type Parameters:
 
 T - the result type
 
 Parameters:
 
 completionStage - a completion stage
 
 context - a Vert.x context to dispatch to
 
 Returns:
 
 a Vert.x future that resolves when completionStage resolves
 - await
```
static <T> T await(Future<T> future)
```
 Park the current thread until the future is completed, when the future is completed the thread is un-parked and
 - the result value is returned when the future was completed with a result
 - otherwise, the failure is thrown
 This method must be called from a virtual thread.
 Parameters:
 
 future - the future to await
 
 Returns:
 
 the result
 
 Throws:
 
 IllegalStateException - when called from an event-loop thread or a non Vert.x thread

Interface Future<T>

Method Summary

Method Detail

all

all

all

all

all

all

any

any

any

any

any

any

join

join

join

join

join

join

future

succeededFuture

succeededFuture

failedFuture

failedFuture

isComplete

onComplete

onComplete

onSuccess

onFailure

result

cause

succeeded

failed

flatMap

compose

recover

compose

transform

eventually

eventually

map

map

mapEmpty

otherwise

otherwise

otherwiseEmpty

andThen

expecting

timeout

toCompletionStage

fromCompletionStage

fromCompletionStage

await