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
|
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: This overload of transform is designed for cases in which
the work of creating the derived Future is fast and lightweight,
as the method does not accept an Executor in which to perform the
the work. (The created Future itself need not complete quickly.)
For heavier operations, this overload carries some caveats: First, the
thread that function.apply runs in depends on whether the input
Future is done at the time transform is called. In
particular, if called late, transform will run the operation in
the thread that called transform. Second, function.apply
may run in an internal thread of the system responsible for the input
Future, such as an RPC network thread. Finally, during the
execution of a sameThreadExecutor function.apply, all
other registered but unexecuted listeners are prevented from running, 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.
Note: For cases in which the work of creating the derived future is
fast and lightweight, consider the other overload or
explicit use of sameThreadExecutor. For heavier derivations, this
choice carries some caveats: First, the thread that function.apply
runs in depends on whether the input Future is done at the time
transform is called. In particular, if called late, transform will run the operation in the thread that called transform. Second, function.apply may run in an internal thread
of the system responsible for the input Future, such as an RPC
network thread. Finally, during the execution of a sameThreadExecutor function.apply, all other registered but
unexecuted listeners are prevented from running, even if those listeners
are to run in other executors.
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: This overload of transform is designed for cases in which
the transformation is fast and lightweight, as the method does not accept
an Executor in which to perform the the work. For heavier
transformations, this overload carries some caveats: First, the thread
that the transformation runs in depends on whether the input Future is done at the time transform is called. In particular, if
called late, transform will perform the transformation in the
thread that called transform. Second, transformations may run in
an internal thread of the system responsible for the input Future,
such as an RPC network thread. Finally, during the execution of a sameThreadExecutor transformation, all other registered but unexecuted
listeners are prevented from running, 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.
Note: For cases in which the transformation is fast and lightweight,
consider the
other overload or explicit use of MoreExecutors.sameThreadExecutor(). For heavier transformations, this
choice carries some caveats: First, the thread that the transformation
runs in depends on whether the input Future is done at the time
transform is called. In particular, if called late, transform will perform the transformation in the thread that called
transform. Second, transformations may run in an internal thread
of the system responsible for the input Future, such as an RPC
network thread. Finally, during the execution of a sameThreadExecutor transformation, all other registered but unexecuted
listeners are prevented from running, even if those listeners are to run
in other executors.
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<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: This overload of addCallback is designed for cases in
which the callack is fast and lightweight, as the method does not accept
an Executor in which to perform the the work. For heavier
callbacks, this overload carries some caveats: First, the thread that the
callback runs in depends on whether the input Future is done at the
time addCallback is called and on whether the input Future
is ever cancelled. In particular, addCallback may execute the
callback in the thread that calls addCallback or Future.cancel. Second, callbacks may run in an internal thread of the
system responsible for the input Future, such as an RPC network
thread. Finally, during the execution of a sameThreadExecutor
callback, all other registered but unexecuted listeners are prevented from
running, even if those listeners are to run in other executors.
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 the other overload
or explicit use of sameThreadExecutor. For heavier callbacks, this choice carries some
caveats: First, the thread that the callback runs in depends on whether
the input Future is done at the time addCallback is called
and on whether the input Future is ever cancelled. In particular,
addCallback may execute the callback in the thread that calls
addCallback or Future.cancel. Second, callbacks may run in
an internal thread of the system responsible for the input Future,
such as an RPC network thread. Finally, during the execution of a sameThreadExecutor callback, all other registered but unexecuted
listeners are prevented from running, even if those listeners are to run
in other executors.
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 | |||||||||