com.google.common.util.concurrent.Futures
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
@Beta public final class Futures
Static utility methods pertaining to the Future interface.
Many of these methods use the ListenableFuture API; consult the
Guava User Guide article on
ListenableFuture.
| Method Summary | ||
|---|---|---|
static
|
addCallback(ListenableFuture<V> future,
FutureCallback<? super V> callback)
Registers separate success and failure callbacks to be run when the Future's computation is complete or, if the computation is already complete, immediately. |
|
static
|
addCallback(ListenableFuture<V> future,
FutureCallback<? super V> callback,
Executor executor)
Registers separate success and failure callbacks to be run when the Future's computation is complete or, if the computation is already complete, immediately. |
|
static
|
allAsList(Iterable<? extends ListenableFuture<? extends V>> futures)
Creates a new ListenableFuture whose value is a list containing the
values of all its input futures, if all succeed. |
|
static
|
allAsList(ListenableFuture<? extends V>... futures)
Creates a new ListenableFuture whose value is a list containing the
values of all its input futures, if all succeed. |
|
static
|
dereference(ListenableFuture<? extends ListenableFuture<? extends V>> nested)
Returns a new ListenableFuture whose result is the product of
calling get() on the Future nested within the given Future, effectively chaining the futures one after the other. |
|
static
|
get(Future<V> future,
Class<X> exceptionClass)
Returns the result of Future.get(), converting most exceptions to a
new instance of the given checked exception type. |
|
static
|
get(Future<V> future,
long timeout,
TimeUnit unit,
Class<X> exceptionClass)
Returns the result of Future.get(long, TimeUnit), converting most
exceptions to a new instance of the given checked exception type. |
|
static
|
getUnchecked(Future<V> future)
Returns the result of calling Future.get() uninterruptibly on a
task known not to throw a checked exception. |
|
static
|
immediateCheckedFuture(V value)
Returns a CheckedFuture which has its value set immediately upon
construction. |
|
static
|
immediateFailedCheckedFuture(X exception)
Returns a CheckedFuture which has an exception set immediately upon
construction. |
|
static
|
immediateFailedFuture(Throwable throwable)
Returns a ListenableFuture which has an exception set immediately
upon construction. |
|
static
|
immediateFuture(V value)
Creates a ListenableFuture which has its value set immediately upon
construction. |
|
static
|
lazyTransform(Future<I> input,
Function<? super I,? extends O> function)
Like transform(ListenableFuture, Function) except that the
transformation function is invoked on each call to
get() on the returned future. |
|
static
|
makeChecked(ListenableFuture<V> future,
Function<Exception,X> mapper)
Creates a CheckedFuture out of a normal ListenableFuture
and a Function that maps from Exception instances into the
appropriate checked type. |
|
static
|
successfulAsList(Iterable<? extends ListenableFuture<? extends V>> futures)
Creates a new ListenableFuture whose value is a list containing the
values of all its successful input futures. |
|
static
|
successfulAsList(ListenableFuture<? extends V>... futures)
Creates a new ListenableFuture whose value is a list containing the
values of all its successful input futures. |
|
static
|
transform(ListenableFuture<I> input,
AsyncFunction<? super I,? extends O> function)
Returns a new ListenableFuture whose result is asynchronously
derived from the result of the given Future. |
|
static
|
transform(ListenableFuture<I> input,
AsyncFunction<? super I,? extends O> function,
Executor executor)
Returns a new ListenableFuture whose result is asynchronously
derived from the result of the given Future. |
|
static
|
transform(ListenableFuture<I> input,
Function<? super I,? extends O> function)
Returns a new ListenableFuture whose result is the product of
applying the given Function to the result of the given Future. |
|
static
|
transform(ListenableFuture<I> input,
Function<? super I,? extends O> function,
Executor executor)
Returns a new ListenableFuture whose result is the product of
applying the given Function to the result of the given Future. |
|
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Method Detail |
|---|
public static <V,X extends Exception> CheckedFuture<V,X> makeChecked(ListenableFuture<V> future,
Function<Exception,X> mapper)
CheckedFuture out of a normal ListenableFuture
and a Function that maps from Exception instances into the
appropriate checked type.
The given mapping function will be applied to an
InterruptedException, a CancellationException, or an
ExecutionException with the actual cause of the exception.
See Future.get() for details on the exceptions thrown.
public static <V> ListenableFuture<V> immediateFuture(@Nullable
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,X extends Exception> CheckedFuture<V,X> immediateCheckedFuture(@Nullable
V value)
CheckedFuture which has its value set immediately upon
construction.
The returned Future can't be cancelled, and its isDone()
method always returns true. Calling get() or checkedGet() will immediately return the provided value.
public static <V> ListenableFuture<V> immediateFailedFuture(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.
Error - if the throwable is an Error.public static <V,X extends Exception> CheckedFuture<V,X> immediateFailedCheckedFuture(X exception)
CheckedFuture 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, and calling checkedGet() will throw the
provided exception itself.
Error - if the throwable is an Error.
public static <I,O> ListenableFuture<O> transform(ListenableFuture<I> input,
AsyncFunction<? super I,? extends O> function)
ListenableFuture whose result is asynchronously
derived from the result of the given Future. 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:
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 =
transform(rowKeyFuture, queryFunction);
Note: If the derived Future is slow or heavyweight to create
(whether the Future itself is slow or heavyweight to complete is
irrelevant), consider supplying an executor. If you do not supply an
executor, transform will use sameThreadExecutor, which carries some
caveats for heavier operations. For example, the call to function.apply may run on an unpredictable or undesirable thread:
Future is done at the time transform is
called, transform will call function.apply inline.
Future is not yet done, transform will
schedule function.apply to be run by the thread that completes the
input Future, which may be an internal system thread such as an
RPC network thread.
function.apply, all other registered but unexecuted listeners are
prevented from running during its execution, even if those listeners are
to run in other executors.
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 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.
input - The future to transformfunction - A function to transform the result of the input future
to the result of the output future
public static <I,O> ListenableFuture<O> transform(ListenableFuture<I> input,
AsyncFunction<? super I,? extends O> function,
Executor executor)
ListenableFuture whose result is asynchronously
derived from the result of the given Future. 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:
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 =
transform(rowKeyFuture, queryFunction, executor);
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.
When the execution of function.apply is fast and lightweight
(though the Future it returns need not meet these criteria),
consider omitting
the executor or explicitly specifying sameThreadExecutor.
However, be aware of the caveats documented in the link above.
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.
public static <I,O> ListenableFuture<O> transform(ListenableFuture<I> input,
Function<? super I,? extends O> function)
ListenableFuture whose result is the product of
applying the given Function to the result of the given Future. Example:
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);
Note: If the transformation is slow or heavyweight, consider supplying an executor.
If you do not supply an executor, transform will use sameThreadExecutor, which carries some
caveats for heavier operations. For example, the call to function.apply may run on an unpredictable or undesirable thread:
Future is done at the time transform is
called, transform will call function.apply inline.
Future is not yet done, transform will
schedule function.apply to be run by the thread that completes the
input Future, which may be an internal system thread such as an
RPC network thread.
function.apply, all other registered but unexecuted listeners are
prevented from running during its execution, even if those listeners are
to run in other executors.
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. This will be run in the thread
that notifies input it is complete.
compose)
public static <I,O> ListenableFuture<O> transform(ListenableFuture<I> input,
Function<? super I,? extends O> function,
Executor executor)
ListenableFuture whose result is the product of
applying the given Function to the result of the given Future. Example:
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);
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.
When the transformation is fast and lightweight, consider omitting the executor or
explicitly specifying sameThreadExecutor. However, be aware of the
caveats documented in the link above.
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)
@Beta
public static <I,O> Future<O> lazyTransform(Future<I> input,
Function<? super I,? extends O> function)
transform(ListenableFuture, Function) except that the
transformation function is invoked on each call to
get() 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 a ListenableFuture available and
do not mind repeated, lazy function evaluation.
input - The future to transformfunction - A Function to transform the results of the provided future
to the results of the returned future.
@Beta public static <V> ListenableFuture<V> dereference(ListenableFuture<? extends ListenableFuture<? extends V>> nested)
ListenableFuture whose result is the product of
calling get() on the Future nested within the given Future, effectively chaining the futures one after the other. Example:
SettableFuture<ListenableFuture<String>> nested = SettableFuture.create();
ListenableFuture<String> dereferenced = dereference(nested);
This call has the same cancellation and execution semantics as transform(ListenableFuture, AsyncFunction), in that the returned Future attempts to keep its cancellation state in sync with both the
input Future and the nested Future. The transformation
is very lightweight and therefore takes place in the thread that called
dereference.
nested - The nested future to transform.
@Beta public static <V> ListenableFuture<List<V>> allAsList(ListenableFuture<? extends V>... futures)
ListenableFuture whose value is a list containing the
values of all its input futures, if all succeed. If any input fails, the
returned future fails.
The list of results is in the same order as the input list.
Canceling this future does not cancel any of the component futures; however, if any of the provided futures fails or is canceled, this one is, too.
futures - futures to combine
@Beta public static <V> ListenableFuture<List<V>> allAsList(Iterable<? extends ListenableFuture<? extends V>> futures)
ListenableFuture whose value is a list containing the
values of all its input futures, if all succeed. If any input fails, the
returned future fails.
The list of results is in the same order as the input list.
Canceling this future does not cancel any of the component futures; however, if any of the provided futures fails or is canceled, this one is, too.
futures - futures to combine
@Beta public static <V> ListenableFuture<List<V>> successfulAsList(ListenableFuture<? extends V>... futures)
ListenableFuture 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 contain null (which is
indistinguishable from the future having a successful value of
null).
futures - futures to combine
@Beta public static <V> ListenableFuture<List<V>> successfulAsList(Iterable<? extends ListenableFuture<? extends V>> futures)
ListenableFuture 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 contain null (which is
indistinguishable from the future having a successful value of
null).
futures - futures to combine
public static <V> void addCallback(ListenableFuture<V> future,
FutureCallback<? super V> callback)
Future'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);
}
});
Note: If the callback is slow or heavyweight, consider supplying an
executor. If you do not supply an executor, addCallback will use
sameThreadExecutor, which carries
some caveats for heavier operations. For example, the callback may run on
an unpredictable or undesirable thread:
Future is done at the time addCallback is
called, addCallback will execute the callback inline.
Future is not yet done, addCallback will
schedule the callback to be run by the thread that completes the input
Future, which may be an internal system thread such as an RPC
network thread.
For a more general interface to attach a completion listener to a
Future, see addListener.
future - The future attach the callback to.callback - The callback to invoke when future is completed.
public static <V> void addCallback(ListenableFuture<V> future,
FutureCallback<? super V> callback,
Executor executor)
Future'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, e,
new FutureCallback<QueryResult> {
public void onSuccess(QueryResult result) {
storeInCache(result);
}
public void onFailure(Throwable t) {
reportError(t);
}
});
When the callback is fast and lightweight, consider omitting the executor or
explicitly specifying sameThreadExecutor. However, be aware of the
caveats documented in the link above.
For a more general interface to attach a completion listener to a
Future, see addListener.
future - The future attach the callback to.callback - The callback to invoke when future is completed.executor - The executor to run callback when the future
completes.
@Beta
public static <V,X extends Exception> V get(Future<V> future,
Class<X> exceptionClass)
throws X extends Exception
Future.get(), converting most exceptions to a
new instance of the given checked exception type. This reduces boilerplate
for a common use of Future 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:
ExecutionException has its cause wrapped in an
X if the cause is a checked exception, an UncheckedExecutionException if the cause is a RuntimeException, or an ExecutionError if the cause is an
Error.
InterruptedException is wrapped in an X (after
restoring the interrupt).
CancellationException is propagated untouched, as is any
other RuntimeException (though get implementations are
discouraged from throwing such exceptions).
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 type String or Throwable (preferring constructors with at least one
String) and calling the constructor via reflection. If the
exception did not already have a cause, one is set by calling Throwable.initCause(Throwable) on it. If no such constructor exists, an
IllegalArgumentException is thrown.
X - if get throws any checked exception except for an ExecutionException whose cause is not itself a checked exception
UncheckedExecutionException - if get throws an ExecutionException with a RuntimeException as its cause
ExecutionError - if get throws an ExecutionException
with an Error as its cause
CancellationException - if get throws a CancellationException
IllegalArgumentException - if exceptionClass extends RuntimeException or does not have a suitable constructor
X extends Exception
@Beta
public static <V,X extends Exception> V get(Future<V> future,
long timeout,
TimeUnit unit,
Class<X> exceptionClass)
throws X extends Exception
Future.get(long, TimeUnit), converting most
exceptions to a new instance of the given checked exception type. This
reduces boilerplate for a common use of Future 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:
ExecutionException has its cause wrapped in an
X if the cause is a checked exception, an UncheckedExecutionException if the cause is a RuntimeException, or an ExecutionError if the cause is an
Error.
InterruptedException is wrapped in an X (after
restoring the interrupt).
TimeoutException is wrapped in an X.
CancellationException is propagated untouched, as is any
other RuntimeException (though get implementations are
discouraged from throwing such exceptions).
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 type String or Throwable (preferring constructors with at least one
String) and calling the constructor via reflection. If the
exception did not already have a cause, one is set by calling Throwable.initCause(Throwable) on it. If no such constructor exists, an
IllegalArgumentException is thrown.
X - if get throws any checked exception except for an ExecutionException whose cause is not itself a checked exception
UncheckedExecutionException - if get throws an ExecutionException with a RuntimeException as its cause
ExecutionError - if get throws an ExecutionException
with an Error as its cause
CancellationException - if get throws a CancellationException
IllegalArgumentException - if exceptionClass extends RuntimeException or does not have a suitable constructor
X extends Exception@Beta public static <V> V getUnchecked(Future<V> future)
Future.get() uninterruptibly on a
task known not to throw a checked exception. This makes Future 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 of ForkJoinTask.join.
Exceptions from Future.get are treated as follows:
ExecutionException has its cause wrapped in an
UncheckedExecutionException (if the cause is an Exception) or ExecutionError (if the cause is an Error).
InterruptedException causes a retry of the get
call. The interrupt is restored before getUnchecked returns.
CancellationException is propagated untouched. So is any
other RuntimeException (get implementations are
discouraged from throwing such exceptions).
InterruptedException, to pass through CancellationException, and to wrap any exception from the underlying
computation in an UncheckedExecutionException or ExecutionError.
For an uninterruptible get that preserves other exceptions, see
Uninterruptibles.getUninterruptibly(Future).
UncheckedExecutionException - if get throws an ExecutionException with an Exception as its cause
ExecutionError - if get throws an ExecutionException
with an Error as its cause
CancellationException - if get throws a CancellationException
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||