Deprecated.
Simply returns its argument.
Since:
catching
@GwtIncompatible("AVAILABLE but requires exceptionType to be Throwable.class")
@Beta
public final <X extends Throwable> FluentFuture<V> catching(Class<X> exceptionType,
Function<? super X,? extends V> fallback,
Executor executor)
Returns a
Future
whose result is taken from this
Future
or, if this
Future
fails with the given
exceptionType
, from the result provided by the
fallback
.
Function.apply(F)
is not invoked until the primary input has failed, so if the
primary input succeeds, it is never invoked. If, during the invocation of
fallback
, an
exception is thrown, this exception is used as the result of the output
Future
.
Usage example:
// Falling back to a zero counter in case an exception happens when processing the RPC to fetch
// counters.
ListenableFuture<Integer> faultTolerantFuture =
fetchCounters().catching(FetchException.class, x -> 0, directExecutor());
When selecting an executor, note that
directExecutor
is dangerous in some cases. See
the discussion in the
AbstractFuture.addListener(java.lang.Runnable, java.util.concurrent.Executor)
documentation. All its warnings about heavyweight
listeners are also applicable to heavyweight functions passed to this method.
This method is similar to
CompletableFuture.exceptionally(java.util.function.Function<java.lang.Throwable, ? extends T>)
. It
can also serve some of the use cases of
CompletableFuture.handle(java.util.function.BiFunction<? super T, java.lang.Throwable, ? extends U>)
and
CompletableFuture.handleAsync(java.util.function.BiFunction<? super T, java.lang.Throwable, ? extends U>)
when used along with
transform(com.google.common.base.Function<? super V, T>, java.util.concurrent.Executor)
.
exceptionType
- the exception type that triggers use of
fallback
. The exception
type is matched against the input's exception. "The input's exception" means the cause of
the
ExecutionException
thrown by
input.get()
or, if
get()
throws a
different kind of exception, that exception itself. To avoid hiding bugs and other
unrecoverable errors, callers should prefer more specific types, avoiding
Throwable.class
in particular.
fallback
- the
Function
to be called if the input fails with the expected
exception type. The function's argument is the input's exception. "The input's exception"
means the cause of the
ExecutionException
thrown by
this.get()
or, if
get()
throws a different kind of exception, that exception itself.
executor
- the executor that runs
fallback
if the input fails
catchingAsync
@GwtIncompatible("AVAILABLE but requires exceptionType to be Throwable.class")
@Beta
public final <X extends Throwable> FluentFuture<V> catchingAsync(Class<X> exceptionType,
AsyncFunction<? super X,? extends V> fallback,
Executor executor)
Returns a
Future
whose result is taken from this
Future
or, if this
Future
fails with the given
exceptionType
, from the result provided by the
fallback
.
AsyncFunction.apply(I)
is not invoked until the primary input has failed, so if
the primary input succeeds, it is never invoked. If, during the invocation of
fallback
,
an exception is thrown, this exception is used as the result of the output
Future
.
Usage examples:
// Falling back to a zero counter in case an exception happens when processing the RPC to fetch
// counters.
ListenableFuture<Integer> faultTolerantFuture =
fetchCounters().catchingAsync(
FetchException.class, x -> immediateFuture(0), directExecutor());
The fallback can also choose to propagate the original exception when desired:
// Falling back to a zero counter only in case the exception was a
// TimeoutException.
ListenableFuture<Integer> faultTolerantFuture =
fetchCounters().catchingAsync(
FetchException.class,
e -> {
if (omitDataOnFetchFailure) {
return immediateFuture(0);
throw e;
directExecutor());
When selecting an executor, note that
directExecutor
is dangerous in some cases. See
the discussion in the
AbstractFuture.addListener(java.lang.Runnable, java.util.concurrent.Executor)
documentation. All its warnings about heavyweight
listeners are also applicable to heavyweight functions passed to this method. (Specifically,
directExecutor
functions should avoid heavyweight operations inside
AsyncFunction.apply
. Any heavyweight operations should occur in other threads responsible for
completing the returned
Future
.)
This method is similar to
CompletableFuture.exceptionally(java.util.function.Function<java.lang.Throwable, ? extends T>)
. It
can also serve some of the use cases of
CompletableFuture.handle(java.util.function.BiFunction<? super T, java.lang.Throwable, ? extends U>)
and
CompletableFuture.handleAsync(java.util.function.BiFunction<? super T, java.lang.Throwable, ? extends U>)
when used along with
transform(com.google.common.base.Function<? super V, T>, java.util.concurrent.Executor)
.
exceptionType
- the exception type that triggers use of
fallback
. The exception
type is matched against the input's exception. "The input's exception" means the cause of
the
ExecutionException
thrown by
this.get()
or, if
get()
throws a
different kind of exception, that exception itself. To avoid hiding bugs and other
unrecoverable errors, callers should prefer more specific types, avoiding
Throwable.class
in particular.
fallback
- the
AsyncFunction
to be called if the input fails with the expected
exception type. The function's argument is the input's exception. "The input's exception"
means the cause of the
ExecutionException
thrown by
input.get()
or, if
get()
throws a different kind of exception, that exception itself.
executor
- the executor that runs
fallback
if the input fails
@Beta
public final
FluentFuture
<
V
>
withTimeout
(
Duration
timeout,
ScheduledExecutorService
scheduledExecutor)
Returns a future that delegates to this future but will finish early (via a
TimeoutException
wrapped in an
ExecutionException
) if the specified timeout expires.
If the timeout expires, not only will the output future finish, but also the input future
(
this
) will be cancelled and interrupted.
timeout
- when to time out the future
scheduledExecutor
- The executor service to enforce the timeout.
Since:
public final
FluentFuture
<
V
>
withTimeout
(long timeout,
TimeUnit
unit,
ScheduledExecutorService
scheduledExecutor)
Returns a future that delegates to this future but will finish early (via a
TimeoutException
wrapped in an
ExecutionException
) if the specified timeout expires.
If the timeout expires, not only will the output future finish, but also the input future
(
this
) will be cancelled and interrupted.
timeout
- when to time out the future
unit
- the time unit of the time parameter
scheduledExecutor
- The executor service to enforce the timeout.
transformAsync
@Beta
public final <T extends @Nullable Object> FluentFuture<T> transformAsync(AsyncFunction<? super V,T> function,
Executor executor)
Returns a new
Future
whose result is asynchronously derived from the result of this
Future
. If the input
Future
fails, the returned
Future
fails with the
same exception (and the function is not invoked).
More precisely, the returned
Future
takes its result from a
Future
produced
by applying the given
AsyncFunction
to the result of the original
Future
.
Example usage:
FluentFuture<RowKey> rowKeyFuture = FluentFuture.from(indexService.lookUp(query));
ListenableFuture<QueryResult> queryFuture =
rowKeyFuture.transformAsync(dataService::readFuture, executor);
When selecting an executor, note that
directExecutor
is dangerous in some cases. See
the discussion in the
AbstractFuture.addListener(java.lang.Runnable, java.util.concurrent.Executor)
documentation. All its warnings about heavyweight
listeners are also applicable to heavyweight functions passed to this method. (Specifically,
directExecutor
functions should avoid heavyweight operations inside
AsyncFunction.apply
. Any heavyweight operations should occur in other threads responsible for
completing the returned
Future
.)
The returned
Future
attempts to keep its cancellation state in sync with that of the
input future and that of the future returned by the chain function. That is, if the returned
Future
is cancelled, it will attempt to cancel the other two, and if either of the
other two is cancelled, the returned
Future
will receive a callback in which it will
attempt to cancel itself.
This method is similar to
CompletableFuture.thenCompose(java.util.function.Function<? super T, ? extends java.util.concurrent.CompletionStage<U>>)
and
CompletableFuture.thenComposeAsync(java.util.function.Function<? super T, ? extends java.util.concurrent.CompletionStage<U>>)
. It can also serve some of the
use cases of
CompletableFuture.handle(java.util.function.BiFunction<? super T, java.lang.Throwable, ? extends U>)
and
CompletableFuture.handleAsync(java.util.function.BiFunction<? super T, java.lang.Throwable, ? extends U>)
when used along with
catching(java.lang.Class<X>, com.google.common.base.Function<? super X, ? extends V>, java.util.concurrent.Executor)
.
function
- A function to transform the result of this future to the result of the output
future
executor
- Executor to run the function in.
Returns:
A future that holds result of the function (if the input succeeded) or the original
input's failure (if not)
transform
@Beta
public final <T extends @Nullable Object> FluentFuture<T> transform(Function<? super V,T> function,
Executor executor)
Returns a new
Future
whose result is derived from the result of this
Future
. If
this input
Future
fails, the returned
Future
fails with the same exception (and
the function is not invoked). Example usage:
ListenableFuture<List<Row>> rowsFuture =
queryFuture.transform(QueryResult::getRows, executor);
When selecting an executor, note that
directExecutor
is dangerous in some cases. See
the discussion in the
AbstractFuture.addListener(java.lang.Runnable, java.util.concurrent.Executor)
documentation. All its warnings about heavyweight
listeners are also applicable to heavyweight functions passed to this method.
The returned
Future
attempts to keep its cancellation state in sync with that of the
input future. That is, if the returned
Future
is cancelled, it will attempt to cancel
the input, and if the input is cancelled, the returned
Future
will receive a callback
in which it will attempt to cancel itself.
An example use of this method is to convert a serializable object returned from an RPC into
a POJO.
This method is similar to
CompletableFuture.thenApply(java.util.function.Function<? super T, ? extends U>)
and
CompletableFuture.thenApplyAsync(java.util.function.Function<? super T, ? extends U>)
. It can also serve some of the
use cases of
CompletableFuture.handle(java.util.function.BiFunction<? super T, java.lang.Throwable, ? extends U>)
and
CompletableFuture.handleAsync(java.util.function.BiFunction<? super T, java.lang.Throwable, ? extends U>)
when used along with
catching(java.lang.Class<X>, com.google.common.base.Function<? super X, ? extends V>, java.util.concurrent.Executor)
.
function
- A Function to transform the results of this future to the results of the
returned future.
executor
- Executor to run the function in.
Returns:
A future that holds result of the transformation.
addCallback
public final void addCallback(FutureCallback<? super V> callback,
Executor executor)
Registers separate success and failure callbacks to be run when this
Future
's
computation is
complete
or, if the
computation is already complete, immediately.
The callback is run on
executor
. There is no guaranteed ordering of execution of
callbacks, but any callback added through this method is guaranteed to be called once the
computation is complete.
Example:
future.addCallback(
new FutureCallback<QueryResult>() {
public void onSuccess(QueryResult result) {
storeInCache(result);
public void onFailure(Throwable t) {
reportError(t);
}, executor);
When selecting an executor, note that
directExecutor
is dangerous in some cases. See
the discussion in the
AbstractFuture.addListener(java.lang.Runnable, java.util.concurrent.Executor)
documentation. All its warnings about heavyweight
listeners are also applicable to heavyweight callbacks passed to this method.
For a more general interface to attach a completion listener, see
AbstractFuture.addListener(java.lang.Runnable, java.util.concurrent.Executor)
.
This method is similar to
CompletableFuture.whenComplete(java.util.function.BiConsumer<? super T, ? super java.lang.Throwable>)
and
CompletableFuture.whenCompleteAsync(java.util.function.BiConsumer<? super T, ? super java.lang.Throwable>)
. It also serves the use case
of
CompletableFuture.thenAccept(java.util.function.Consumer<? super T>)
and
CompletableFuture.thenAcceptAsync(java.util.function.Consumer<? super T>)
.
callback
- The callback to invoke when this
Future
is completed.
executor
- The executor to run
callback
when the future completes.
