@Beta @GwtCompatible(emulated=true) public abstract class FluentFuture<V> extends AbstractFuture<V>
ListenableFuture
that supports fluent chains of operations. For example:
ListenableFuture<Boolean> adminIsLoggedIn =
FluentFuture.from(usersDatabase.getAdminUser())
.transform(User::getId, directExecutor())
.transform(ActivityService::isLoggedIn, threadPool)
.catching(RpcException.class, e -> false, directExecutor());
When chaining together a graph of asynchronous operations, you will often find it easier to use a framework. Frameworks automate the process, often adding features like monitoring, debugging, and cancellation. Examples of frameworks include:
CompletableFuture
/ CompletionStage
Users of CompletableFuture
will likely want to continue using CompletableFuture
. FluentFuture
is targeted at people who use ListenableFuture
,
who can't use Java 8, or who want an API more focused than CompletableFuture
. (If you
need to adapt between CompletableFuture
and ListenableFuture
, consider Future Converter.)
FluentFuture
but with extra methods, we recommend declaring your
own subclass of ListenableFuture
, complete with a method like from(com.google.common.util.concurrent.ListenableFuture<V>)
to adapt an
existing ListenableFuture
, implemented atop a ForwardingListenableFuture
that
forwards to that future and adds the desired methods.Modifier and Type | Method and Description |
---|---|
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. |
<X extends Throwable> |
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 . |
<X extends Throwable> |
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 . |
static <V> FluentFuture<V> |
from(ListenableFuture<V> future)
Converts the given
ListenableFuture to an equivalent FluentFuture . |
<T> FluentFuture<T> |
transform(Function<? super V,T> function,
Executor executor)
Returns a new
Future whose result is derived from the result of this Future . |
<T> 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 . |
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. |
addListener, afterDone, cancel, get, get, interruptTask, isCancelled, isDone, pendingToString, set, setException, setFuture, toString, tryInternalFastPathGetFailure, wasInterrupted
public static <V> FluentFuture<V> from(ListenableFuture<V> future)
ListenableFuture
to an equivalent FluentFuture
.
If the given ListenableFuture
is already a FluentFuture
, it is returned
directly. If not, it is wrapped in a FluentFuture
that delegates all calls to the
original ListenableFuture
.
@Partially.GwtIncompatible(value="AVAILABLE but requires exceptionType to be Throwable.class") public final <X extends Throwable> FluentFuture<V> catching(Class<X> exceptionType, Function<? super X,? extends V> fallback, Executor executor)
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@Partially.GwtIncompatible(value="AVAILABLE but requires exceptionType to be Throwable.class") public final <X extends Throwable> FluentFuture<V> catchingAsync(Class<X> exceptionType, AsyncFunction<? super X,? extends V> fallback, Executor executor)
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@GwtIncompatible public final FluentFuture<V> withTimeout(long timeout, TimeUnit unit, ScheduledExecutorService scheduledExecutor)
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 futureunit
- the time unit of the time parameterscheduledExecutor
- The executor service to enforce the timeout.public final <T> FluentFuture<T> transformAsync(AsyncFunction<? super V,T> function, Executor executor)
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
futureexecutor
- Executor to run the function in.public final <T> FluentFuture<T> transform(Function<? super V,T> function, Executor executor)
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.public final void addCallback(FutureCallback<? super V> callback, Executor executor)
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.Copyright © 2010–2019. All rights reserved.