io.vertx.core

Interface Future<T>

All Superinterfaces:

AsyncResult<T>, Handler<AsyncResult<T>>

All Known Subinterfaces:

CompositeFuture

public interface Future<T>
extends AsyncResult<T>, Handler<AsyncResult<T>>

Represents the result of an action that may, or may not, have occurred yet.

Author:

Tim Fox

Field Summary

Fields

Modifier and Type	Field and Description
static FutureFactory	factory

Method Summary

Modifier and Type	Method and Description
Throwable	cause() A Throwable describing failure.
void	complete() Deprecated. instead create a Promise and use Promise.complete()
void	complete(T result) Deprecated. instead create a Promise and use Promise.complete(Object)
default Handler<AsyncResult<T>>	completer() Deprecated. use this object instead since it extends Handler<AsyncResult<T>>
default <U> Future<U>	compose(java.util.function.Function<T,Future<U>> mapper) Compose this future with a mapper function.
default <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.
default <U> Future<U>	compose(Handler<T> handler, Future<U> next) Deprecated. use compose(Function))} instead
void	fail(String failureMessage) Deprecated. instead create a Promise and use Promise.fail(String)
void	fail(Throwable cause) Deprecated. instead create a Promise and use Promise.fail(Throwable)
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)
static <T> Future<T>	fromCompletionStage(CompletionStage<T> completionStage, Context context)
static <T> Future<T>	future() Deprecated. instead use Promise.promise()
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.
void	handle(AsyncResult<T> asyncResult) Succeed or fail this future with the AsyncResult event.
boolean	isComplete() Has the future completed?
default <U> Future<U>	map(java.util.function.Function<T,U> mapper) Apply a mapper function on this future.
default <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>	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.
default Future<T>	otherwise(java.util.function.Function<Throwable,T> mapper) Apply a mapper function on this future.
default 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.
default Future<T>	setHandler(Handler<AsyncResult<T>> handler) Deprecated. use onComplete(io.vertx.core.Handler<io.vertx.core.AsyncResult<T>>) instead
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.
default CompletionStage<T>	toCompletionStage()
boolean	tryComplete() Deprecated. instead create a Promise and use Promise.tryComplete()
boolean	tryComplete(T result) Deprecated. instead create a Promise and use Promise.tryComplete(Object)
boolean	tryFail(String failureMessage) Deprecated. instead create a Promise and use Promise.tryFail(String)
boolean	tryFail(Throwable cause) Deprecated. instead create a Promise and use Promise.tryFail(Throwable)

Field Detail

factory

static final FutureFactory factory

Method Detail

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.

future

@Deprecated
static <T> Future<T> future()

Deprecated. instead use Promise.promise()

Create a future that hasn't completed yet

Type Parameters:

T - the result type

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

setHandler

@Deprecated
default Future<T> setHandler(Handler<AsyncResult<T>> handler)

Deprecated. use onComplete(io.vertx.core.Handler<io.vertx.core.AsyncResult<T>>) instead

Like onComplete(Handler).

onComplete

Future<T> onComplete(Handler<AsyncResult<T>> handler)

Add a handler to be notified of the result.

Parameters:

handler - the handler that will be called with the 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.

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.

Parameters:

handler - the handler that will be called with the failed result

Returns:

a reference to this, so it can be used fluently

complete

@Deprecated
void complete(T result)

Deprecated. instead create a Promise and use Promise.complete(Object)

Set the result. Any handler will be called, if there is one, and the future will be marked as completed.

Parameters:

result - the result

complete

@Deprecated
void complete()

Deprecated. instead create a Promise and use Promise.complete()

Set a null result. Any handler will be called, if there is one, and the future will be marked as completed.

fail

@Deprecated
void fail(Throwable cause)

Deprecated. instead create a Promise and use Promise.fail(Throwable)

Set the failure. Any handler will be called, if there is one, and the future will be marked as completed.

Parameters:

cause - the failure cause

fail

@Deprecated
void fail(String failureMessage)

Deprecated. instead create a Promise and use Promise.fail(String)

Try to set the failure. When it happens, any handler will be called, if there is one, and the future will be marked as completed.

Parameters:

failureMessage - the failure message

tryComplete

@Deprecated
boolean tryComplete(T result)

Deprecated. instead create a Promise and use Promise.tryComplete(Object)

Set the failure. Any handler will be called, if there is one, and the future will be marked as completed.

Parameters:

result - the result

Returns:

false when the future is already completed

tryComplete

@Deprecated
boolean tryComplete()

Deprecated. instead create a Promise and use Promise.tryComplete()

Try to set the result. When it happens, any handler will be called, if there is one, and the future will be marked as completed.

Returns:

false when the future is already completed

tryFail

@Deprecated
boolean tryFail(Throwable cause)

Deprecated. instead create a Promise and use Promise.tryFail(Throwable)

Try to set the failure. When it happens, any handler will be called, if there is one, and the future will be marked as completed.

Parameters:

cause - the failure cause

Returns:

false when the future is already completed

tryFail

@Deprecated
boolean tryFail(String failureMessage)

Deprecated. instead create a Promise and use Promise.tryFail(String)

Try to set the failure. When it happens, any handler will be called, if there is one, and the future will be marked as completed.

Parameters:

failureMessage - the failure message

Returns:

false when the future is already completed

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<T,Future<U>> mapper)

Alias for compose(Function).

compose

@Deprecated
default <U> Future<U> compose(Handler<T> handler,
                                          Future<U> next)

Deprecated. use compose(Function))} instead

Compose this future with a provided next future.

When this (the one on which compose is called) future succeeds, the handler will be called with the completed value, this handler should complete the next future.

If the handler throws an exception, the returned future will be failed with this exception.

When this future fails, the failure will be propagated to the next future and the handler will not be called.

Parameters:

handler - the handler

next - the next future

Returns:

the next future, used for chaining

compose

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

compose

default <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.

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

map

default <U> Future<U> 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

default <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

handle

void handle(AsyncResult<T> asyncResult)

Succeed or fail this future with the AsyncResult event.

Specified by:

handle in interface Handler<AsyncResult<T>>

Parameters:

asyncResult - the async result to handle

completer

@Deprecated
default Handler<AsyncResult<T>> completer()

Deprecated. use this object instead since it extends Handler<AsyncResult<T>>

Returns:

an handler completing this 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

otherwise

default 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

default 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

toCompletionStage

default CompletionStage<T> toCompletionStage()

fromCompletionStage

static <T> Future<T> fromCompletionStage(CompletionStage<T> completionStage)

fromCompletionStage

static <T> Future<T> fromCompletionStage(CompletionStage<T> completionStage,
                                         Context context)