com.google.common.util.concurrent

Class FluentFuture<V>

java.lang.Object

com.google.common.util.concurrent.FluentFuture<V>

All Implemented Interfaces:

ListenableFuture<V>, Future<V>

Direct Known Subclasses:

AbstractFuture

@Beta
 @GwtCompatible(emulated=true)
public abstract class FluentFuture<V>
extends Object

A 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());
 

Alternatives

Frameworks

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:

• Dagger Producers

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

Extension

If you want a class like 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.

Since:

23.0

Method Summary

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

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.google.common.util.concurrent.ListenableFuture

addListener

Methods inherited from interface java.util.concurrent.Future

cancel, get, get, isCancelled, isDone

Method Detail

from

public static <V> FluentFuture<V> from(ListenableFuture<V> future)

Converts the given 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.

catching

@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)

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 ListenableFuture.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).

Parameters:

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

@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)

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 ListenableFuture.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).

Parameters:

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

withTimeout

@GwtIncompatible
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.

Parameters:

timeout - when to time out the future

unit - the time unit of the time parameter

scheduledExecutor - The executor service to enforce the timeout.

transformAsync

public final <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. 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 ListenableFuture.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).

Parameters:

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

public final <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. 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 ListenableFuture.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).

Parameters:

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 ListenableFuture.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 ListenableFuture.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>).

Parameters:

callback - The callback to invoke when this Future is completed.

executor - The executor to run callback when the future completes.