Class Futures
- java.lang.Object
-
- com.google.common.util.concurrent.Futures
-
@Beta @GwtCompatible(emulated=true) public final class Futures extends java.lang.Object
Static utility methods pertaining to theFuture
interface.Many of these methods use the
ListenableFuture
API; consult the Guava User Guide article onListenableFuture
.- Since:
- 1.0
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Futures.FutureCombiner<V>
A helper to create a newListenableFuture
whose result is generated from a combination of input futures.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static <V> void
addCallback(ListenableFuture<V> future, FutureCallback<? super V> callback)
Registers separate success and failure callbacks to be run when theFuture
's computation is complete or, if the computation is already complete, immediately.static <V> void
addCallback(ListenableFuture<V> future, FutureCallback<? super V> callback, java.util.concurrent.Executor executor)
Registers separate success and failure callbacks to be run when theFuture
's computation is complete or, if the computation is already complete, immediately.static <V> ListenableFuture<java.util.List<V>>
allAsList(ListenableFuture<? extends V>... futures)
Creates a newListenableFuture
whose value is a list containing the values of all its input futures, if all succeed.static <V> ListenableFuture<java.util.List<V>>
allAsList(java.lang.Iterable<? extends ListenableFuture<? extends V>> futures)
Creates a newListenableFuture
whose value is a list containing the values of all its input futures, if all succeed.static <V,X extends java.lang.Throwable>
ListenableFuture<V>catching(ListenableFuture<? extends V> input, java.lang.Class<X> exceptionType, Function<? super X,? extends V> fallback)
Returns aFuture
whose result is taken from the given primaryinput
or, if the primary input fails with the givenexceptionType
, from the result provided by thefallback
.static <V,X extends java.lang.Throwable>
ListenableFuture<V>catching(ListenableFuture<? extends V> input, java.lang.Class<X> exceptionType, Function<? super X,? extends V> fallback, java.util.concurrent.Executor executor)
Returns aFuture
whose result is taken from the given primaryinput
or, if the primary input fails with the givenexceptionType
, from the result provided by thefallback
.static <V,X extends java.lang.Throwable>
ListenableFuture<V>catchingAsync(ListenableFuture<? extends V> input, java.lang.Class<X> exceptionType, AsyncFunction<? super X,? extends V> fallback)
Returns aFuture
whose result is taken from the given primaryinput
or, if the primary input fails with the givenexceptionType
, from the result provided by thefallback
.static <V,X extends java.lang.Throwable>
ListenableFuture<V>catchingAsync(ListenableFuture<? extends V> input, java.lang.Class<X> exceptionType, AsyncFunction<? super X,? extends V> fallback, java.util.concurrent.Executor executor)
Returns aFuture
whose result is taken from the given primaryinput
or, if the primary input fails with the givenexceptionType
, from the result provided by thefallback
.static <V> ListenableFuture<V>
dereference(ListenableFuture<? extends ListenableFuture<? extends V>> nested)
Returns a newListenableFuture
whose result is the product of callingget()
on theFuture
nested within the givenFuture
, effectively chaining the futures one after the other.static <V,X extends java.lang.Exception>
VgetChecked(java.util.concurrent.Future<V> future, java.lang.Class<X> exceptionClass)
Returns the result ofFuture.get()
, converting most exceptions to a new instance of the given checked exception type.static <V,X extends java.lang.Exception>
VgetChecked(java.util.concurrent.Future<V> future, java.lang.Class<X> exceptionClass, long timeout, java.util.concurrent.TimeUnit unit)
Returns the result ofFuture.get(long, TimeUnit)
, converting most exceptions to a new instance of the given checked exception type.static <V> V
getDone(java.util.concurrent.Future<V> future)
Returns the result of the inputFuture
, which must have already completed.static <V> V
getUnchecked(java.util.concurrent.Future<V> future)
Returns the result of callingFuture.get()
uninterruptibly on a task known not to throw a checked exception.static <V> ListenableFuture<V>
immediateCancelledFuture()
Creates aListenableFuture
which is cancelled immediately upon construction, so thatisCancelled()
always returnstrue
.static <V,X extends java.lang.Exception>
CheckedFuture<V,X>immediateCheckedFuture(V value)
Returns aCheckedFuture
which has its value set immediately upon construction.static <V,X extends java.lang.Exception>
CheckedFuture<V,X>immediateFailedCheckedFuture(X exception)
Returns aCheckedFuture
which has an exception set immediately upon construction.static <V> ListenableFuture<V>
immediateFailedFuture(java.lang.Throwable throwable)
Returns aListenableFuture
which has an exception set immediately upon construction.static <V> ListenableFuture<V>
immediateFuture(V value)
Creates aListenableFuture
which has its value set immediately upon construction.static <T> ImmutableList<ListenableFuture<T>>
inCompletionOrder(java.lang.Iterable<? extends ListenableFuture<? extends T>> futures)
Returns a list of delegate futures that correspond to the futures received in the order that they complete.static <I,O>
java.util.concurrent.Future<O>lazyTransform(java.util.concurrent.Future<I> input, Function<? super I,? extends O> function)
Liketransform(ListenableFuture, Function)
except that the transformationfunction
is invoked on each call toget()
on the returned future.static <V,X extends java.lang.Exception>
CheckedFuture<V,X>makeChecked(ListenableFuture<V> future, Function<? super java.lang.Exception,X> mapper)
Creates aCheckedFuture
out of a normalListenableFuture
and aFunction
that maps fromException
instances into the appropriate checked type.static <V> ListenableFuture<V>
nonCancellationPropagating(ListenableFuture<V> future)
Creates a newListenableFuture
whose result is set from the supplied future when it completes.static <V> ListenableFuture<java.util.List<V>>
successfulAsList(ListenableFuture<? extends V>... futures)
Creates a newListenableFuture
whose value is a list containing the values of all its successful input futures.static <V> ListenableFuture<java.util.List<V>>
successfulAsList(java.lang.Iterable<? extends ListenableFuture<? extends V>> futures)
Creates a newListenableFuture
whose value is a list containing the values of all its successful input futures.static <I,O>
ListenableFuture<O>transform(ListenableFuture<I> input, Function<? super I,? extends O> function)
Returns a newFuture
whose result is derived from the result of the givenFuture
.static <I,O>
ListenableFuture<O>transform(ListenableFuture<I> input, Function<? super I,? extends O> function, java.util.concurrent.Executor executor)
Returns a newFuture
whose result is derived from the result of the givenFuture
.static <I,O>
ListenableFuture<O>transformAsync(ListenableFuture<I> input, AsyncFunction<? super I,? extends O> function)
Returns a newFuture
whose result is asynchronously derived from the result of the givenFuture
.static <I,O>
ListenableFuture<O>transformAsync(ListenableFuture<I> input, AsyncFunction<? super I,? extends O> function, java.util.concurrent.Executor executor)
Returns a newFuture
whose result is asynchronously derived from the result of the givenFuture
.static <V> Futures.FutureCombiner<V>
whenAllComplete(ListenableFuture<? extends V>... futures)
Creates aFutures.FutureCombiner
that processes the completed futures whether or not they're successful.static <V> Futures.FutureCombiner<V>
whenAllComplete(java.lang.Iterable<? extends ListenableFuture<? extends V>> futures)
Creates aFutures.FutureCombiner
that processes the completed futures whether or not they're successful.static <V> Futures.FutureCombiner<V>
whenAllSucceed(ListenableFuture<? extends V>... futures)
Creates aFutures.FutureCombiner
requiring that all passed in futures are successful.static <V> Futures.FutureCombiner<V>
whenAllSucceed(java.lang.Iterable<? extends ListenableFuture<? extends V>> futures)
Creates aFutures.FutureCombiner
requiring that all passed in futures are successful.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 aTimeoutException
wrapped in anExecutionException
) if the specified duration expires.
-
-
-
Method Detail
-
makeChecked
@GwtIncompatible public static <V,X extends java.lang.Exception> CheckedFuture<V,X> makeChecked(ListenableFuture<V> future, Function<? super java.lang.Exception,X> mapper)
Creates aCheckedFuture
out of a normalListenableFuture
and aFunction
that maps fromException
instances into the appropriate checked type.Warning: We recommend against using
CheckedFuture
in new projects.CheckedFuture
is difficult to build libraries atop.CheckedFuture
ports of methods liketransformAsync(com.google.common.util.concurrent.ListenableFuture<I>, com.google.common.util.concurrent.AsyncFunction<? super I, ? extends O>)
have historically had bugs, and some of these bugs are necessary, unavoidable consequences of theCheckedFuture
API. Additionally,CheckedFuture
encourages users to take exceptions from one thread and rethrow them in another, producing confusing stack traces.The given mapping function will be applied to an
InterruptedException
, aCancellationException
, or anExecutionException
. SeeFuture.get()
for details on the exceptions thrown.- Since:
- 9.0 (source-compatible since 1.0)
-
immediateFuture
public static <V> ListenableFuture<V> immediateFuture(@Nullable V value)
Creates aListenableFuture
which has its value set immediately upon construction. The getters just return the value. ThisFuture
can't be canceled or timed out and itsisDone()
method always returnstrue
.
-
immediateCheckedFuture
@GwtIncompatible public static <V,X extends java.lang.Exception> CheckedFuture<V,X> immediateCheckedFuture(@Nullable V value)
Returns aCheckedFuture
which has its value set immediately upon construction.The returned
Future
can't be cancelled, and itsisDone()
method always returnstrue
. Callingget()
orcheckedGet()
will immediately return the provided value.
-
immediateFailedFuture
public static <V> ListenableFuture<V> immediateFailedFuture(java.lang.Throwable throwable)
Returns aListenableFuture
which has an exception set immediately upon construction.The returned
Future
can't be cancelled, and itsisDone()
method always returnstrue
. Callingget()
will immediately throw the providedThrowable
wrapped in anExecutionException
.
-
immediateCancelledFuture
public static <V> ListenableFuture<V> immediateCancelledFuture()
Creates aListenableFuture
which is cancelled immediately upon construction, so thatisCancelled()
always returnstrue
.- Since:
- 14.0
-
immediateFailedCheckedFuture
@GwtIncompatible public static <V,X extends java.lang.Exception> CheckedFuture<V,X> immediateFailedCheckedFuture(X exception)
Returns aCheckedFuture
which has an exception set immediately upon construction.The returned
Future
can't be cancelled, and itsisDone()
method always returnstrue
. Callingget()
will immediately throw the providedException
wrapped in anExecutionException
, and callingcheckedGet()
will throw the provided exception itself.
-
catching
@GwtIncompatible("AVAILABLE but requires exceptionType to be Throwable.class") public static <V,X extends java.lang.Throwable> ListenableFuture<V> catching(ListenableFuture<? extends V> input, java.lang.Class<X> exceptionType, Function<? super X,? extends V> fallback)
Returns aFuture
whose result is taken from the given primaryinput
or, if the primary input fails with the givenexceptionType
, from the result provided by thefallback
.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 offallback
, an exception is thrown, this exception is used as the result of the outputFuture
.Usage example:
ListenableFuture<Integer> fetchCounterFuture = ...; // Falling back to a zero counter in case an exception happens when // processing the RPC to fetch counters. ListenableFuture<Integer> faultTolerantFuture = Futures.catching( fetchCounterFuture, FetchException.class, new Function<FetchException, Integer>() { public Integer apply(FetchException e) { return 0; } });
This overload, which does not accept an executor, uses
directExecutor
, a dangerous choice in some cases. See the discussion in theListenableFuture.addListener
documentation. The documentation's warnings about "lightweight listeners" refer here to the work done duringFunction.apply
.- Parameters:
input
- the primary inputFuture
exceptionType
- the exception type that triggers use offallback
. The exception type is matched against the input's exception. "The input's exception" means the cause of theExecutionException
thrown byinput.get()
or, ifget()
throws a different kind of exception, that exception itself. To avoid hiding bugs and other unrecoverable errors, callers should prefer more specific types, avoidingThrowable.class
in particular.fallback
- theFunction
to be called ifinput
fails with the expected exception type. The function's argument is the input's exception. "The input's exception" means the cause of theExecutionException
thrown byinput.get()
or, ifget()
throws a different kind of exception, that exception itself.- Since:
- 19.0
-
catching
@GwtIncompatible("AVAILABLE but requires exceptionType to be Throwable.class") public static <V,X extends java.lang.Throwable> ListenableFuture<V> catching(ListenableFuture<? extends V> input, java.lang.Class<X> exceptionType, Function<? super X,? extends V> fallback, java.util.concurrent.Executor executor)
Returns aFuture
whose result is taken from the given primaryinput
or, if the primary input fails with the givenexceptionType
, from the result provided by thefallback
.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 offallback
, an exception is thrown, this exception is used as the result of the outputFuture
.Usage example:
ListenableFuture<Integer> fetchCounterFuture = ...; // Falling back to a zero counter in case an exception happens when // processing the RPC to fetch counters. ListenableFuture<Integer> faultTolerantFuture = Futures.catching( fetchCounterFuture, FetchException.class, new Function<FetchException, Integer>() { public Integer apply(FetchException e) { return 0; } }, directExecutor());
When selecting an executor, note that
directExecutor
is dangerous in some cases. See the discussion in theListenableFuture.addListener
documentation. The documentation's warnings about "lightweight listeners" refer here to the work done duringFunction.apply
.- Parameters:
input
- the primary inputFuture
exceptionType
- the exception type that triggers use offallback
. The exception type is matched against the input's exception. "The input's exception" means the cause of theExecutionException
thrown byinput.get()
or, ifget()
throws a different kind of exception, that exception itself. To avoid hiding bugs and other unrecoverable errors, callers should prefer more specific types, avoidingThrowable.class
in particular.fallback
- theFunction
to be called ifinput
fails with the expected exception type. The function's argument is the input's exception. "The input's exception" means the cause of theExecutionException
thrown byinput.get()
or, ifget()
throws a different kind of exception, that exception itself.executor
- the executor that runsfallback
ifinput
fails- Since:
- 19.0
-
catchingAsync
@GwtIncompatible("AVAILABLE but requires exceptionType to be Throwable.class") public static <V,X extends java.lang.Throwable> ListenableFuture<V> catchingAsync(ListenableFuture<? extends V> input, java.lang.Class<X> exceptionType, AsyncFunction<? super X,? extends V> fallback)
Returns aFuture
whose result is taken from the given primaryinput
or, if the primary input fails with the givenexceptionType
, from the result provided by thefallback
.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 offallback
, an exception is thrown, this exception is used as the result of the outputFuture
.Usage examples:
ListenableFuture<Integer> fetchCounterFuture = ...; // Falling back to a zero counter in case an exception happens when // processing the RPC to fetch counters. ListenableFuture<Integer> faultTolerantFuture = Futures.catchingAsync( fetchCounterFuture, FetchException.class, new AsyncFunction<FetchException, Integer>() { public ListenableFuture<Integer> apply(FetchException e) { return immediateFuture(0); } });
The fallback can also choose to propagate the original exception when desired:
ListenableFuture<Integer> fetchCounterFuture = ...; // Falling back to a zero counter only in case the exception was a // TimeoutException. ListenableFuture<Integer> faultTolerantFuture = Futures.catchingAsync( fetchCounterFuture, FetchException.class, new AsyncFunction<FetchException, Integer>() { public ListenableFuture<Integer> apply(FetchException e) throws FetchException { if (omitDataOnFetchFailure) { return immediateFuture(0); } throw e; } });
This overload, which does not accept an executor, uses
directExecutor
, a dangerous choice in some cases. See the discussion in theListenableFuture.addListener
documentation. The documentation's warnings about "lightweight listeners" refer here to the work done duringAsyncFunction.apply
, not to any work done to complete the returnedFuture
.- Parameters:
input
- the primary inputFuture
exceptionType
- the exception type that triggers use offallback
. The exception type is matched against the input's exception. "The input's exception" means the cause of theExecutionException
thrown byinput.get()
or, ifget()
throws a different kind of exception, that exception itself. To avoid hiding bugs and other unrecoverable errors, callers should prefer more specific types, avoidingThrowable.class
in particular.fallback
- theAsyncFunction
to be called ifinput
fails with the expected exception type. The function's argument is the input's exception. "The input's exception" means the cause of theExecutionException
thrown byinput.get()
or, ifget()
throws a different kind of exception, that exception itself.- Since:
- 19.0 (similar functionality in 14.0 as
withFallback
)
-
catchingAsync
@GwtIncompatible("AVAILABLE but requires exceptionType to be Throwable.class") public static <V,X extends java.lang.Throwable> ListenableFuture<V> catchingAsync(ListenableFuture<? extends V> input, java.lang.Class<X> exceptionType, AsyncFunction<? super X,? extends V> fallback, java.util.concurrent.Executor executor)
Returns aFuture
whose result is taken from the given primaryinput
or, if the primary input fails with the givenexceptionType
, from the result provided by thefallback
.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 offallback
, an exception is thrown, this exception is used as the result of the outputFuture
.Usage examples:
ListenableFuture<Integer> fetchCounterFuture = ...; // Falling back to a zero counter in case an exception happens when // processing the RPC to fetch counters. ListenableFuture<Integer> faultTolerantFuture = Futures.catchingAsync( fetchCounterFuture, FetchException.class, new AsyncFunction<FetchException, Integer>() { public ListenableFuture<Integer> apply(FetchException e) { return immediateFuture(0); } }, directExecutor());
The fallback can also choose to propagate the original exception when desired:
ListenableFuture<Integer> fetchCounterFuture = ...; // Falling back to a zero counter only in case the exception was a // TimeoutException. ListenableFuture<Integer> faultTolerantFuture = Futures.catchingAsync( fetchCounterFuture, FetchException.class, new AsyncFunction<FetchException, Integer>() { public ListenableFuture<Integer> apply(FetchException e) throws FetchException { if (omitDataOnFetchFailure) { return immediateFuture(0); } throw e; } }, directExecutor());
When selecting an executor, note that
directExecutor
is dangerous in some cases. See the discussion in theListenableFuture.addListener
documentation. The documentation's warnings about "lightweight listeners" refer here to the work done duringAsyncFunction.apply
, not to any work done to complete the returnedFuture
.- Parameters:
input
- the primary inputFuture
exceptionType
- the exception type that triggers use offallback
. The exception type is matched against the input's exception. "The input's exception" means the cause of theExecutionException
thrown byinput.get()
or, ifget()
throws a different kind of exception, that exception itself. To avoid hiding bugs and other unrecoverable errors, callers should prefer more specific types, avoidingThrowable.class
in particular.fallback
- theAsyncFunction
to be called ifinput
fails with the expected exception type. The function's argument is the input's exception. "The input's exception" means the cause of theExecutionException
thrown byinput.get()
or, ifget()
throws a different kind of exception, that exception itself.executor
- the executor that runsfallback
ifinput
fails- Since:
- 19.0 (similar functionality in 14.0 as
withFallback
)
-
withTimeout
@GwtIncompatible public 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 aTimeoutException
wrapped in anExecutionException
) if the specified duration expires.The delegate future is interrupted and cancelled if it times out.
- Parameters:
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.- Since:
- 19.0
-
transformAsync
public static <I,O> ListenableFuture<O> transformAsync(ListenableFuture<I> input, AsyncFunction<? super I,? extends O> function)
Returns a newFuture
whose result is asynchronously derived from the result of the givenFuture
. If the givenFuture
fails, the returnedFuture
fails with the same exception (and the function is not invoked).More precisely, the returned
Future
takes its result from aFuture
produced by applying the givenAsyncFunction
to the result of the originalFuture
. Example usage:ListenableFuture<RowKey> rowKeyFuture = indexService.lookUp(query); AsyncFunction<RowKey, QueryResult> queryFunction = new AsyncFunction<RowKey, QueryResult>() { public ListenableFuture<QueryResult> apply(RowKey rowKey) { return dataService.read(rowKey); } }; ListenableFuture<QueryResult> queryFuture = transformAsync(rowKeyFuture, queryFunction);
This overload, which does not accept an executor, uses
directExecutor
, a dangerous choice in some cases. See the discussion in theListenableFuture.addListener
documentation. The documentation's warnings about "lightweight listeners" refer here to the work done duringAsyncFunction.apply
, not to any work done to complete the returnedFuture
.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 function. That is, if the returnedFuture
is cancelled, it will attempt to cancel the other two, and if either of the other two is cancelled, the returnedFuture
will receive a callback in which it will attempt to cancel itself.- Parameters:
input
- The future to transformfunction
- A function to transform the result of the input future to the result of the output future- Returns:
- A future that holds result of the function (if the input succeeded) or the original input's failure (if not)
- Since:
- 19.0 (in 11.0 as
transform
)
-
transformAsync
public static <I,O> ListenableFuture<O> transformAsync(ListenableFuture<I> input, AsyncFunction<? super I,? extends O> function, java.util.concurrent.Executor executor)
Returns a newFuture
whose result is asynchronously derived from the result of the givenFuture
. If the givenFuture
fails, the returnedFuture
fails with the same exception (and the function is not invoked).More precisely, the returned
Future
takes its result from aFuture
produced by applying the givenAsyncFunction
to the result of the originalFuture
. Example usage:ListenableFuture<RowKey> rowKeyFuture = indexService.lookUp(query); AsyncFunction<RowKey, QueryResult> queryFunction = new AsyncFunction<RowKey, QueryResult>() { public ListenableFuture<QueryResult> apply(RowKey rowKey) { return dataService.read(rowKey); } }; ListenableFuture<QueryResult> queryFuture = transformAsync(rowKeyFuture, queryFunction, executor);
When selecting an executor, note that
directExecutor
is dangerous in some cases. See the discussion in theListenableFuture.addListener
documentation. The documentation's warnings about "lightweight listeners" refer here to the work done duringAsyncFunction.apply
, not to any work done to complete the returnedFuture
.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 returnedFuture
is cancelled, it will attempt to cancel the other two, and if either of the other two is cancelled, the returnedFuture
will receive a callback in which it will attempt to cancel itself.- Parameters:
input
- The future to transformfunction
- A function to transform the result of the input future to the result of the output futureexecutor
- 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)
- Since:
- 19.0 (in 11.0 as
transform
)
-
transform
public static <I,O> ListenableFuture<O> transform(ListenableFuture<I> input, Function<? super I,? extends O> function)
Returns a newFuture
whose result is derived from the result of the givenFuture
. Ifinput
fails, the returnedFuture
fails with the same exception (and the function is not invoked). Example usage:ListenableFuture<QueryResult> queryFuture = ...; Function<QueryResult, List<Row>> rowsFunction = new Function<QueryResult, List<Row>>() { public List<Row> apply(QueryResult queryResult) { return queryResult.getRows(); } }; ListenableFuture<List<Row>> rowsFuture = transform(queryFuture, rowsFunction);
This overload, which does not accept an executor, uses
directExecutor
, a dangerous choice in some cases. See the discussion in theListenableFuture.addListener
documentation. The documentation's warnings about "lightweight listeners" refer here to the work done duringFunction.apply
.The returned
Future
attempts to keep its cancellation state in sync with that of the input future. That is, if the returnedFuture
is cancelled, it will attempt to cancel the input, and if the input is cancelled, the returnedFuture
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.
- Parameters:
input
- The future to transformfunction
- A Function to transform the results of the provided future to the results of the returned future. This will be run in the thread that notifies input it is complete.- Returns:
- A future that holds result of the transformation.
- Since:
- 9.0 (in 1.0 as
compose
)
-
transform
public static <I,O> ListenableFuture<O> transform(ListenableFuture<I> input, Function<? super I,? extends O> function, java.util.concurrent.Executor executor)
Returns a newFuture
whose result is derived from the result of the givenFuture
. Ifinput
fails, the returnedFuture
fails with the same exception (and the function is not invoked). Example usage:ListenableFuture<QueryResult> queryFuture = ...; Function<QueryResult, List<Row>> rowsFunction = new Function<QueryResult, List<Row>>() { public List<Row> apply(QueryResult queryResult) { return queryResult.getRows(); } }; ListenableFuture<List<Row>> rowsFuture = transform(queryFuture, rowsFunction, executor);
When selecting an executor, note that
directExecutor
is dangerous in some cases. See the discussion in theListenableFuture.addListener
documentation. The documentation's warnings about "lightweight listeners" refer here to the work done duringFunction.apply
.The returned
Future
attempts to keep its cancellation state in sync with that of the input future. That is, if the returnedFuture
is cancelled, it will attempt to cancel the input, and if the input is cancelled, the returnedFuture
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.
- Parameters:
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.- Returns:
- A future that holds result of the transformation.
- Since:
- 9.0 (in 2.0 as
compose
)
-
lazyTransform
@GwtIncompatible public static <I,O> java.util.concurrent.Future<O> lazyTransform(java.util.concurrent.Future<I> input, Function<? super I,? extends O> function)
Liketransform(ListenableFuture, Function)
except that the transformationfunction
is invoked on each call toget()
on the returned future.The returned
Future
reflects the input's cancellation state directly, and any attempt to cancel the returned Future is likewise passed through to the input Future.Note that calls to timed get only apply the timeout to the execution of the underlying
Future
, not to the execution of the transformation function.The primary audience of this method is callers of
transform
who don't have aListenableFuture
available and do not mind repeated, lazy function evaluation.- Parameters:
input
- The future to transformfunction
- A Function to transform the results of the provided future to the results of the returned future.- Returns:
- A future that returns the result of the transformation.
- Since:
- 10.0
-
dereference
public static <V> ListenableFuture<V> dereference(ListenableFuture<? extends ListenableFuture<? extends V>> nested)
Returns a newListenableFuture
whose result is the product of callingget()
on theFuture
nested within the givenFuture
, effectively chaining the futures one after the other. Example:SettableFuture<ListenableFuture<String>> nested = SettableFuture.create(); ListenableFuture<String> dereferenced = dereference(nested);
Most users will not need this method. To create a
Future
that completes with the result of anotherFuture
, create aSettableFuture
, and callsetFuture(otherFuture)
on it.dereference
has the same cancellation and execution semantics astransformAsync(ListenableFuture, AsyncFunction)
, in that the returnedFuture
attempts to keep its cancellation state in sync with both the inputFuture
and the nestedFuture
. The transformation is very lightweight and therefore takes place in the same thread (either the thread that calleddereference
, or the thread in which the dereferenced future completes).- Parameters:
nested
- The nested future to transform.- Returns:
- A future that holds result of the inner future.
- Since:
- 13.0
-
allAsList
@Beta @SafeVarargs public static <V> ListenableFuture<java.util.List<V>> allAsList(ListenableFuture<? extends V>... futures)
Creates a newListenableFuture
whose value is a list containing the values of all its input futures, if all succeed. If any input fails, the returned future fails immediately.The list of results is in the same order as the input list.
Canceling this future will attempt to cancel all the component futures, and if any of the provided futures fails or is canceled, this one is, too.
- Parameters:
futures
- futures to combine- Returns:
- a future that provides a list of the results of the component futures
- Since:
- 10.0
-
allAsList
@Beta public static <V> ListenableFuture<java.util.List<V>> allAsList(java.lang.Iterable<? extends ListenableFuture<? extends V>> futures)
Creates a newListenableFuture
whose value is a list containing the values of all its input futures, if all succeed. If any input fails, the returned future fails immediately.The list of results is in the same order as the input list.
Canceling this future will attempt to cancel all the component futures, and if any of the provided futures fails or is canceled, this one is, too.
- Parameters:
futures
- futures to combine- Returns:
- a future that provides a list of the results of the component futures
- Since:
- 10.0
-
whenAllComplete
@SafeVarargs public static <V> Futures.FutureCombiner<V> whenAllComplete(ListenableFuture<? extends V>... futures)
Creates aFutures.FutureCombiner
that processes the completed futures whether or not they're successful.- Since:
- 20.0
-
whenAllComplete
public static <V> Futures.FutureCombiner<V> whenAllComplete(java.lang.Iterable<? extends ListenableFuture<? extends V>> futures)
Creates aFutures.FutureCombiner
that processes the completed futures whether or not they're successful.- Since:
- 20.0
-
whenAllSucceed
@SafeVarargs public static <V> Futures.FutureCombiner<V> whenAllSucceed(ListenableFuture<? extends V>... futures)
Creates aFutures.FutureCombiner
requiring that all passed in futures are successful.If any input fails, the returned future fails immediately.
- Since:
- 20.0
-
whenAllSucceed
public static <V> Futures.FutureCombiner<V> whenAllSucceed(java.lang.Iterable<? extends ListenableFuture<? extends V>> futures)
Creates aFutures.FutureCombiner
requiring that all passed in futures are successful.If any input fails, the returned future fails immediately.
- Since:
- 20.0
-
nonCancellationPropagating
public static <V> ListenableFuture<V> nonCancellationPropagating(ListenableFuture<V> future)
Creates a newListenableFuture
whose result is set from the supplied future when it completes. Cancelling the supplied future will also cancel the returned future, but cancelling the returned future will have no effect on the supplied future.- Since:
- 15.0
-
successfulAsList
@Beta @SafeVarargs public static <V> ListenableFuture<java.util.List<V>> successfulAsList(ListenableFuture<? extends V>... futures)
Creates a newListenableFuture
whose value is a list containing the values of all its successful input futures. The list of results is in the same order as the input list, and if any of the provided futures fails or is canceled, its corresponding position will containnull
(which is indistinguishable from the future having a successful value ofnull
).Canceling this future will attempt to cancel all the component futures.
- Parameters:
futures
- futures to combine- Returns:
- a future that provides a list of the results of the component futures
- Since:
- 10.0
-
successfulAsList
@Beta public static <V> ListenableFuture<java.util.List<V>> successfulAsList(java.lang.Iterable<? extends ListenableFuture<? extends V>> futures)
Creates a newListenableFuture
whose value is a list containing the values of all its successful input futures. The list of results is in the same order as the input list, and if any of the provided futures fails or is canceled, its corresponding position will containnull
(which is indistinguishable from the future having a successful value ofnull
).Canceling this future will attempt to cancel all the component futures.
- Parameters:
futures
- futures to combine- Returns:
- a future that provides a list of the results of the component futures
- Since:
- 10.0
-
inCompletionOrder
@Beta @GwtIncompatible public static <T> ImmutableList<ListenableFuture<T>> inCompletionOrder(java.lang.Iterable<? extends ListenableFuture<? extends T>> futures)
Returns a list of delegate futures that correspond to the futures received in the order that they complete. Delegate futures return the same value or throw the same exception as the corresponding input future returns/throws.Cancelling a delegate future has no effect on any input future, since the delegate future does not correspond to a specific input future until the appropriate number of input futures have completed. At that point, it is too late to cancel the input future. The input future's result, which cannot be stored into the cancelled delegate future, is ignored.
- Since:
- 17.0
-
addCallback
public static <V> void addCallback(ListenableFuture<V> future, FutureCallback<? super V> callback)
Registers separate success and failure callbacks to be run when theFuture
's computation is complete or, if the computation is already complete, immediately.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:
ListenableFuture<QueryResult> future = ...; addCallback(future, new FutureCallback<QueryResult>() { public void onSuccess(QueryResult result) { storeInCache(result); } public void onFailure(Throwable t) { reportError(t); } });
This overload, which does not accept an executor, uses
directExecutor
, a dangerous choice in some cases. See the discussion in theListenableFuture.addListener
documentation.For a more general interface to attach a completion listener to a
Future
, seeaddListener
.- Parameters:
future
- The future attach the callback to.callback
- The callback to invoke whenfuture
is completed.- Since:
- 10.0
-
addCallback
public static <V> void addCallback(ListenableFuture<V> future, FutureCallback<? super V> callback, java.util.concurrent.Executor executor)
Registers separate success and failure callbacks to be run when theFuture
's computation is complete or, if the computation is already complete, immediately.The callback is run in
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:ListenableFuture<QueryResult> future = ...; Executor e = ... addCallback(future, new FutureCallback<QueryResult>() { public void onSuccess(QueryResult result) { storeInCache(result); } public void onFailure(Throwable t) { reportError(t); } }, e);
When selecting an executor, note that
directExecutor
is dangerous in some cases. See the discussion in theListenableFuture.addListener
documentation.For a more general interface to attach a completion listener to a
Future
, seeaddListener
.- Parameters:
future
- The future attach the callback to.callback
- The callback to invoke whenfuture
is completed.executor
- The executor to runcallback
when the future completes.- Since:
- 10.0
-
getDone
public static <V> V getDone(java.util.concurrent.Future<V> future) throws java.util.concurrent.ExecutionException
Returns the result of the inputFuture
, 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 callsgetDone
on aFuture
that is still pending, the program will throw instead of block. This can be important for APIs likewhenAllComplete(...)
.
call(...)
, where it is easy to use a new input from thecall
implementation but forget to add it to the arguments ofwhenAllComplete
.If you are looking for a method to determine whether a given
Future
is done, use the instance methodFuture.isDone()
.- Throws:
java.util.concurrent.ExecutionException
- if theFuture
failed with an exceptionjava.util.concurrent.CancellationException
- if theFuture
was cancelledjava.lang.IllegalStateException
- if theFuture
is not done- Since:
- 20.0
-
getChecked
@GwtIncompatible public static <V,X extends java.lang.Exception> V getChecked(java.util.concurrent.Future<V> future, java.lang.Class<X> exceptionClass) throws X extends java.lang.Exception
Returns the result ofFuture.get()
, converting most exceptions to a new instance of the given checked exception type. This reduces boilerplate for a common use ofFuture
in which it is unnecessary to programmatically distinguish between exception types or to extract other information from the exception instance.Exceptions from
Future.get
are treated as follows:- Any
ExecutionException
has its cause wrapped in anX
if the cause is a checked exception, anUncheckedExecutionException
if the cause is aRuntimeException
, or anExecutionError
if the cause is anError
. - Any
InterruptedException
is wrapped in anX
(after restoring the interrupt). - Any
CancellationException
is propagated untouched, as is any otherRuntimeException
(thoughget
implementations are discouraged from throwing such exceptions).
The overall principle is to continue to treat every checked exception as a checked exception, every unchecked exception as an unchecked exception, and every error as an error. In addition, the cause of any
ExecutionException
is wrapped in order to ensure that the new stack trace matches that of the current thread.Instances of
exceptionClass
are created by choosing an arbitrary public constructor that accepts zero or more arguments, all of typeString
orThrowable
(preferring constructors with at least oneString
) and calling the constructor via reflection. If the exception did not already have a cause, one is set by callingThrowable.initCause(Throwable)
on it. If no such constructor exists, anIllegalArgumentException
is thrown.- Throws:
X
- ifget
throws any checked exception except for anExecutionException
whose cause is not itself a checked exceptionUncheckedExecutionException
- ifget
throws anExecutionException
with aRuntimeException
as its causeExecutionError
- ifget
throws anExecutionException
with anError
as its causejava.util.concurrent.CancellationException
- ifget
throws aCancellationException
java.lang.IllegalArgumentException
- ifexceptionClass
extendsRuntimeException
or does not have a suitable constructorX extends java.lang.Exception
- Since:
- 19.0 (in 10.0 as
get
)
- Any
-
getChecked
@GwtIncompatible public static <V,X extends java.lang.Exception> V getChecked(java.util.concurrent.Future<V> future, java.lang.Class<X> exceptionClass, long timeout, java.util.concurrent.TimeUnit unit) throws X extends java.lang.Exception
Returns the result ofFuture.get(long, TimeUnit)
, converting most exceptions to a new instance of the given checked exception type. This reduces boilerplate for a common use ofFuture
in which it is unnecessary to programmatically distinguish between exception types or to extract other information from the exception instance.Exceptions from
Future.get
are treated as follows:- Any
ExecutionException
has its cause wrapped in anX
if the cause is a checked exception, anUncheckedExecutionException
if the cause is aRuntimeException
, or anExecutionError
if the cause is anError
. - Any
InterruptedException
is wrapped in anX
(after restoring the interrupt). - Any
TimeoutException
is wrapped in anX
. - Any
CancellationException
is propagated untouched, as is any otherRuntimeException
(thoughget
implementations are discouraged from throwing such exceptions).
The overall principle is to continue to treat every checked exception as a checked exception, every unchecked exception as an unchecked exception, and every error as an error. In addition, the cause of any
ExecutionException
is wrapped in order to ensure that the new stack trace matches that of the current thread.Instances of
exceptionClass
are created by choosing an arbitrary public constructor that accepts zero or more arguments, all of typeString
orThrowable
(preferring constructors with at least oneString
) and calling the constructor via reflection. If the exception did not already have a cause, one is set by callingThrowable.initCause(Throwable)
on it. If no such constructor exists, anIllegalArgumentException
is thrown.- Throws:
X
- ifget
throws any checked exception except for anExecutionException
whose cause is not itself a checked exceptionUncheckedExecutionException
- ifget
throws anExecutionException
with aRuntimeException
as its causeExecutionError
- ifget
throws anExecutionException
with anError
as its causejava.util.concurrent.CancellationException
- ifget
throws aCancellationException
java.lang.IllegalArgumentException
- ifexceptionClass
extendsRuntimeException
or does not have a suitable constructorX extends java.lang.Exception
- Since:
- 19.0 (in 10.0 as
get
and with different parameter order)
- Any
-
getUnchecked
@GwtIncompatible public static <V> V getUnchecked(java.util.concurrent.Future<V> future)
Returns the result of callingFuture.get()
uninterruptibly on a task known not to throw a checked exception. This makesFuture
more suitable for lightweight, fast-running tasks that, barring bugs in the code, will not fail. This gives it exception-handling behavior similar to that ofForkJoinTask.join
.Exceptions from
Future.get
are treated as follows:- Any
ExecutionException
has its cause wrapped in anUncheckedExecutionException
(if the cause is anException
) orExecutionError
(if the cause is anError
). - Any
InterruptedException
causes a retry of theget
call. The interrupt is restored beforegetUnchecked
returns. - Any
CancellationException
is propagated untouched. So is any otherRuntimeException
(get
implementations are discouraged from throwing such exceptions).
The overall principle is to eliminate all checked exceptions: to loop to avoid
InterruptedException
, to pass throughCancellationException
, and to wrap any exception from the underlying computation in anUncheckedExecutionException
orExecutionError
.For an uninterruptible
get
that preserves other exceptions, seeUninterruptibles.getUninterruptibly(Future)
.- Throws:
UncheckedExecutionException
- ifget
throws anExecutionException
with anException
as its causeExecutionError
- ifget
throws anExecutionException
with anError
as its causejava.util.concurrent.CancellationException
- ifget
throws aCancellationException
- Since:
- 10.0
- Any
-
-