@GwtCompatible(emulated=true) public final class Futures extends java.lang.Object
Future interface.
Many of these methods use the ListenableFuture API; consult the Guava User Guide
article on ListenableFuture.
The main purpose of ListenableFuture is to help you chain together a graph of
asynchronous operations. You can chain them together manually with calls to methods like Futures.transform, but 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:
If you do chain your operations manually, you may want to use FluentFuture.
| Modifier and Type | Method and Description |
|---|---|
static <V> V |
getDone(java.util.concurrent.Future<V> future)
Returns the result of the input
Future, which must have already completed. |
static <V> ListenableFuture<V> |
immediateFailedFuture(java.lang.Throwable throwable)
Returns a
ListenableFuture which has an exception set immediately upon construction. |
static <V> ListenableFuture<V> |
immediateFuture(V value)
Creates a
ListenableFuture which has its value set immediately upon construction. |
static <I,O> ListenableFuture<O> |
transform(ListenableFuture<I> input,
Function<? super I,? extends O> function,
java.util.concurrent.Executor executor)
Returns a new
Future whose result is derived from the result of the given Future. |
static <V> ListenableFuture<V> |
withTimeout(ListenableFuture<V> delegate,
long time,
java.util.concurrent.TimeUnit unit,
java.util.concurrent.ScheduledExecutorService scheduledExecutor)
Returns a future that delegates to another but will finish early (via a
TimeoutException wrapped in an ExecutionException) if the specified duration expires. |
public static <V> ListenableFuture<V> immediateFuture(V value)
ListenableFuture which has its value set immediately upon construction. The
getters just return the value. This Future can't be canceled or timed out and its
isDone() method always returns true.public static <V> ListenableFuture<V> immediateFailedFuture(java.lang.Throwable throwable)
ListenableFuture which has an exception set immediately upon construction.
The returned Future can't be cancelled, and its isDone() method always
returns true. Calling get() will immediately throw the provided Throwable wrapped in an ExecutionException.
@Beta @GwtIncompatible public static <V> ListenableFuture<V> withTimeout(ListenableFuture<V> delegate, long time, java.util.concurrent.TimeUnit unit, java.util.concurrent.ScheduledExecutorService scheduledExecutor)
TimeoutException wrapped in an ExecutionException) if the specified duration expires.
The delegate future is interrupted and cancelled if it times out.
delegate - The future to delegate to.time - when to timeout the futureunit - the time unit of the time parameterscheduledExecutor - The executor service to enforce the timeout.@Beta public static <I,O> ListenableFuture<O> transform(ListenableFuture<I> input, Function<? super I,? extends O> function, java.util.concurrent.Executor executor)
Future whose result is derived from the result of the given Future. If input fails, the returned Future fails with the same exception (and
the function is not invoked). Example usage:
ListenableFuture<QueryResult> queryFuture = ...;
ListenableFuture<List<Row>> rowsFuture =
transform(queryFuture, QueryResult::getRows, executor);
When selecting an executor, note that directExecutor is dangerous in some cases. See
the discussion in the ListenableFuture.addListener
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.
input - The future to transformfunction - A Function to transform the results of the provided future to the results of
the returned future.executor - Executor to run the function in.compose)@CanIgnoreReturnValue
public static <V> V getDone(java.util.concurrent.Future<V> future)
throws java.util.concurrent.ExecutionException
Future, which must have already completed.
The benefits of this method are twofold. First, the name "getDone" suggests to readers that
the Future is already done. Second, if buggy code calls getDone on a Future that is still pending, the program will throw instead of block. This can be important
for APIs like whenAllComplete(...).call(...), where it is easy to use a new input from
the call implementation but forget to add it to the arguments of whenAllComplete.
If you are looking for a method to determine whether a given Future is done, use the
instance method Future.isDone().
java.util.concurrent.ExecutionException - if the Future failed with an exceptionjava.util.concurrent.CancellationException - if the Future was cancelledjava.lang.IllegalStateException - if the Future is not doneCopyright © 2007–2023. All rights reserved.