com.google.common.util.concurrent
Class Futures

java.lang.Object
  com.google.common.util.concurrent.Futures

@Beta
public final class Futures
extends Object

Static utility methods pertaining to the Future interface.

Since:

1.0

Author:

Kevin Bourrillion, Nishant Thakkar, Sven Mawson

Method Summary

static <V> void	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 <V> void	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 <V> ListenableFuture<List<V>>	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 <V> ListenableFuture<List<V>>	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 <I,O> ListenableFuture<O>	chain(ListenableFuture<I> input, Function<? super I,? extends ListenableFuture<? extends O>> function) Deprecated. Convert your Function to a AsyncFunction, and use transform(ListenableFuture, AsyncFunction). This method is scheduled to be removed from Guava in Guava release 12.0.
static <I,O> ListenableFuture<O>	chain(ListenableFuture<I> input, Function<? super I,? extends ListenableFuture<? extends O>> function, Executor executor) Deprecated. Convert your Function to a AsyncFunction, and use transform(ListenableFuture, AsyncFunction, Executor). This method is scheduled to be removed from Guava in Guava release 12.0.
static <V,X extends Exception> V	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 <V,X extends Exception> V	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 <V> V	getUnchecked(Future<V> future) Returns the result of calling Future.get() uninterruptibly on a task known not to throw a checked exception.
static <V,X extends Exception> CheckedFuture<V,X>	immediateCheckedFuture(V value) Returns a CheckedFuture which has its value set immediately upon construction.
static <V,X extends Exception> CheckedFuture<V,X>	immediateFailedCheckedFuture(X exception) Returns a CheckedFuture which has an exception set immediately upon construction.
static <V> ListenableFuture<V>	immediateFailedFuture(Throwable throwable) Returns a ListenableFuture which has an exception set immediately upon construction.
static <V> ListenableFuture<V>	immediateFuture(V value) Creates a ListenableFuture which has its value set immediately upon construction.
static <I,O> Future<O>	lazyTransform(Future<I> future, 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 <V,X extends Exception> CheckedFuture<V,X>	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 <V> ListenableFuture<List<V>>	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 <V> ListenableFuture<List<V>>	successfulAsList(ListenableFuture<? extends V>... futures) Creates a new ListenableFuture whose value is a list containing the values of all its successful input futures.
static <I,O> ListenableFuture<O>	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 <I,O> ListenableFuture<O>	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 <I,O> ListenableFuture<O>	transform(ListenableFuture<I> future, 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 <I,O> ListenableFuture<O>	transform(ListenableFuture<I> future, 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

makeChecked

public static <V,X extends Exception> CheckedFuture<V,X> 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.

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.

Since:

9.0 (source-compatible since 1.0)

immediateFuture

public static <V> ListenableFuture<V> immediateFuture(@Nullable
                                                      V value)

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

immediateCheckedFuture

public static <V,X extends Exception> CheckedFuture<V,X> immediateCheckedFuture(@Nullable
                                                                                V value)

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

immediateFailedFuture

public static <V> ListenableFuture<V> immediateFailedFuture(Throwable throwable)

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

Throws:

Error - if the throwable is an Error.

immediateFailedCheckedFuture

public static <V,X extends Exception> CheckedFuture<V,X> immediateFailedCheckedFuture(X exception)

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

Throws:

Error - if the throwable is an Error.

chain

@Deprecated
public static <I,O> ListenableFuture<O> chain(ListenableFuture<I> input,
                                                         Function<? super I,? extends ListenableFuture<? extends O>> function)

Deprecated. Convert your Function to a AsyncFunction, and use transform(ListenableFuture, AsyncFunction). This method is scheduled to be removed from Guava in Guava release 12.0.

Returns a new 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 Function to the result of the original Future. Example:

   ListenableFuture<RowKey> rowKeyFuture = indexService.lookUp(query);
   Function<RowKey, ListenableFuture<QueryResult>> queryFunction =
       new Function<RowKey, ListenableFuture<QueryResult>>() {
         public ListenableFuture<QueryResult> apply(RowKey rowKey) {
           return dataService.read(rowKey);
         }
       };
   ListenableFuture<QueryResult> queryFuture =
       chain(rowKeyFuture, queryFunction);
 

Note: This overload of chain 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. For heavier derivations, this overload carries some caveats: First, the thread that the derivation runs in depends on whether the input Future is done at the time chain is called. In particular, if called late, chain will run the derivation in the thread that called chain. Second, derivations 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 chain function, 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 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.

Parameters:

input - The future to chain

function - A function to chain 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 chain.

chain

@Deprecated
public static <I,O> ListenableFuture<O> chain(ListenableFuture<I> input,
                                                         Function<? super I,? extends ListenableFuture<? extends O>> function,
                                                         Executor executor)

Deprecated. Convert your Function to a AsyncFunction, and use transform(ListenableFuture, AsyncFunction, Executor). This method is scheduled to be removed from Guava in Guava release 12.0.

Returns a new 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 Function to the result of the original Future. Example:

   ListenableFuture<RowKey> rowKeyFuture = indexService.lookUp(query);
   Function<RowKey, ListenableFuture<QueryResult>> queryFunction =
       new Function<RowKey, ListenableFuture<QueryResult>>() {
         public ListenableFuture<QueryResult> apply(RowKey rowKey) {
           return dataService.read(rowKey);
         }
       };
   ListenableFuture<QueryResult> queryFuture =
       chain(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 the derivation runs in depends on whether the input Future is done at the time chain is called. In particular, if called late, chain will run the derivation in the thread that called chain. Second, derivations 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 chain function, all other registered but unexecuted listeners are prevented from running, even if those listeners are to run in other executors.

Parameters:

input - The future to chain

function - A function to chain 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 chain.

transform

public static <I,O> ListenableFuture<O> 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. 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.

Parameters:

input - The future to transform

function - 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:

11.0

transform

public static <I,O> ListenableFuture<O> 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. 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.

Parameters:

input - The future to transform

function - A function to transform the result of the input future to the result of the output future

executor - Executor to run the function in.

Returns:

A future that holds result of the function (if the input succeeded) or the original input's failure (if not)

Since:

11.0

transform

public static <I,O> ListenableFuture<O> transform(ListenableFuture<I> future,
                                                  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. 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.

Parameters:

future - The future to transform

function - 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> future,
                                                  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. 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.

Parameters:

future - The future to transform

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

@Beta
public static <I,O> Future<O> lazyTransform(Future<I> future,
                                                 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.

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.

Parameters:

future - The future to transform

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

allAsList

@Beta
public static <V> ListenableFuture<List<V>> 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. 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.

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

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<List<V>> successfulAsList(ListenableFuture<? extends V>... futures)

Creates a new 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).

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

Parameters:

futures - futures to combine

Returns:

a future that provides a list of the results of the component futures

Since:

10.0

addCallback

public static <V> void 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.

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.

Parameters:

future - The future attach the callback to.

callback - The callback to invoke when future is completed.

Since:

10.0

addCallback

public static <V> void 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.

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.

Parameters:

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.

Since:

10.0

get

@Beta
public static <V,X extends Exception> V get(Future<V> future,
                                                 Class<X> exceptionClass)
             throws X extends Exception

Returns the result of 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:

• Any 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.
• Any InterruptedException is wrapped in an X (after restoring the interrupt).
• Any CancellationException is propagated untouched, as is any other RuntimeException (though get 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 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.

Throws:

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

Since:

10.0

get

@Beta
public static <V,X extends Exception> V get(Future<V> future,
                                                 long timeout,
                                                 TimeUnit unit,
                                                 Class<X> exceptionClass)
             throws X extends Exception

Returns the result of 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:

• Any 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.
• Any InterruptedException is wrapped in an X (after restoring the interrupt).
• Any TimeoutException is wrapped in an X.
• Any CancellationException is propagated untouched, as is any other RuntimeException (though get 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 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.

Throws:

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

Since:

10.0

getUnchecked

@Beta
public static <V> V getUnchecked(Future<V> future)

Returns the result of calling 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:

• Any ExecutionException has its cause wrapped in an UncheckedExecutionException (if the cause is an Exception) or ExecutionError (if the cause is an Error).
• Any InterruptedException causes a retry of the get call. The interrupt is restored before getUnchecked returns.
• Any CancellationException is propagated untouched. So is any other RuntimeException (get implementations are discouraged from throwing such exceptions).

The overall principle is to eliminate all checked exceptions: to loop to avoid 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).

Throws:

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

Since:

10.0