Package io.vertx.core

Interface Future<T>

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

Modifier and Type	Method	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 <T> CompositeFuture	all(List<? extends Future<?>> futures)	Like all(Future, Future) but with a list of futures.
default Future<T>	andThen(Completable<? super T> handler)	Invokes the given handler upon completion.
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.
default T	await()	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 vertx virtual thread or a non vertx thread.
default T	await(long timeout, TimeUnit unit)	Like await() but with a timeout.
static <T> T	await(Future<T> future)	Calls await() on future.
Throwable	cause()	A Throwable describing failure.
default <U> Future<U>	compose(java.util.function.Function<? super T,Future<U>> mapper)	Compose this future with a mapper function.
<U> Future<U>	compose(java.util.function.Function<? super 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.Supplier<Future<U>> mapper)	Compose this future with a mapper 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<? super 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 promise and pass it to the handler, and then returns this future's promise.
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<? super 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.
default Future<T>	onComplete(Completable<? super T> handler)	Add handlers to be notified on succeeded result and failed result.
default Future<T>	onComplete(Handler<? super T> successHandler, Handler<? super Throwable> failureHandler)	Add handlers to be notified on succeeded result and failed result.
Future<T>	onComplete(Handler<AsyncResult<T>> handler)	Add a handler to be notified of the result.
default Future<T>	onFailure(Handler<? super Throwable> handler)	Add a handler to be notified of the failed result.
default Future<T>	onSuccess(Handler<? super 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.
default <U> Future<U>	transform(java.util.function.BiFunction<? super T,? super Throwable,Future<U>> mapper)	Transform this future with a mapper function.
<U> Future<U>	transform(java.util.function.Function<AsyncResult<T>,Future<U>> mapper)	Transform this future with a mapper function.

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 <T> 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 promise and pass it to the handler, and then returns this future's promise. The handler is responsible for completing the promise, if the handler throws an exception, the promise is attempted to be failed with this exception.

Parameters:

handler - the handler completing the promise

Returns:

the future of the created promise

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<? super T> successHandler,
                             Handler<? super 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

onComplete

default Future<T> onComplete(Completable<? super T> handler)

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:

handler - the handler that will be called with the completion outcome

Returns:

a reference to this, so it can be used fluently

onSuccess

default Future<T> onSuccess(Handler<? super 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<? super 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 <U> Future<U> flatMap(java.util.function.Function<? super T,Future<U>> mapper)

Alias for compose(Function).

compose

default <U> Future<U> compose(java.util.function.Function<? super T,Future<U>> 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

<U> Future<U> compose(java.util.function.Function<? super T,Future<U>> successMapper,
                      java.util.function.Function<Throwable,Future<U>> 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

<U> Future<U> transform(java.util.function.Function<AsyncResult<T>,Future<U>> mapper)

Transform this future with a mapper function.

When this future (the one on which transform is called) completes, the mapper will be called with the async result returning another future instance. This returned future completion will complete the future returned by this method call.

When mapper throws an exception, the returned future will be failed with this exception.

Parameters:

mapper - the function mapping the future

Returns:

the transformed future

transform

default <U> Future<U> transform(java.util.function.BiFunction<? super T,? super Throwable,Future<U>> mapper)

Transform this future with a mapper function.

When this future (the one on which transform is called) completes, the mapper will be called with the result/failure returning another future instance. This returned future completion will complete the future returned by this method call.

When mapper throws an exception, the returned future will be failed with this exception.

Parameters:

mapper - the function mapping the future

Returns:

the transformed future

eventually

<U> Future<T> eventually(java.util.function.Supplier<Future<U>> mapper)

Compose this future with a mapper that will be always be called.

When this future (the one on which eventually is called) completes, the mapper 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 mapper will not influence the nature of the returned future.

Parameters:

mapper - the function returning the future.

Returns:

the composed future

map

<U> Future<U> map(java.util.function.Function<? super 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

andThen

default Future<T> andThen(Completable<? super 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

default T await()

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 vertx virtual thread or a non vertx thread.

Returns:

the result

Throws:

IllegalStateException - when called from a vertx event-loop or worker thread

await

default T await(long timeout,
                TimeUnit unit)
         throws TimeoutException

Like await() but with a timeout.

Parameters:

timeout - the timeout

unit - the timeout unit

Returns:

the result

Throws:

TimeoutException - when the timeout fires before the future completes

IllegalStateException - when called from a vertx event-loop or worker thread

await

static <T> T await(Future<T> future)

Calls await() on future.

Parameters:

future - the future to await

Returns:

the result

Throws:

IllegalStateException - when called from an event-loop thread or a non Vert.x thread