org.docx4j.com.google.common.util.concurrent

Class Futures

java.lang.Object

org.docx4j.com.google.common.util.concurrent.Futures

@GwtCompatible(emulated=true)
public final class Futures
extends Object

Static utility methods pertaining to the Future interface.

Many of these methods use the ListenableFuture API; consult the Guava User Guide article on ListenableFuture.

The main purpose of ListenableFuture is to help you chain together a graph of asynchronous operations. You can chain them together manually with calls to methods like Futures.transform, but you will often find it easier to use a framework. Frameworks automate the process, often adding features like monitoring, debugging, and cancellation. Examples of frameworks include:

• Dagger Producers

If you do chain your operations manually, you may want to use FluentFuture.

Since:

1.0

Author:

Kevin Bourrillion, Nishant Thakkar, Sven Mawson

Method Summary

Modifier and Type	Method and Description
static <V> V	getDone(Future<V> future) Returns the result of the input Future, which must have already completed.
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> ListenableFuture<O>	transform(ListenableFuture<I> input, Function<? super I,? extends O> function, Executor executor) Returns a new Future whose result is derived from the result of the given Future.
static <V> ListenableFuture<V>	withTimeout(ListenableFuture<V> delegate, long time, TimeUnit unit, ScheduledExecutorService scheduledExecutor) Returns a future that delegates to another but will finish early (via a TimeoutException wrapped in an ExecutionException) if the specified duration expires.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

immediateFuture

public static <V> ListenableFuture<V> immediateFuture(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.

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.

withTimeout

@Beta
 @GwtIncompatible
public static <V> ListenableFuture<V> withTimeout(ListenableFuture<V> delegate,
                                                                          long time,
                                                                          TimeUnit unit,
                                                                          ScheduledExecutorService scheduledExecutor)

Returns a future that delegates to another but will finish early (via a TimeoutException wrapped in an ExecutionException) if the specified duration expires.

The delegate future is interrupted and cancelled if it times out.

Parameters:

delegate - The future to delegate to.

time - when to timeout the future

unit - the time unit of the time parameter

scheduledExecutor - The executor service to enforce the timeout.

Since:

19.0

transform

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

Returns a new Future whose result is derived from the result of the given Future. If input fails, the returned Future fails with the same exception (and the function is not invoked). Example usage:

 ListenableFuture<QueryResult> queryFuture = ...;
 ListenableFuture<List<Row>> rowsFuture =
     transform(queryFuture, QueryResult::getRows, executor);
 

When selecting an executor, note that directExecutor is dangerous in some cases. See the discussion in the ListenableFuture.addListener documentation. All its warnings about heavyweight listeners are also applicable to heavyweight functions passed to this method.

The returned Future attempts to keep its cancellation state in sync with that of the input future. That is, if the returned Future is cancelled, it will attempt to cancel the input, and if the input is cancelled, the returned Future will receive a callback in which it will attempt to cancel itself.

An example use of this method is to convert a serializable object returned from an RPC into a POJO.

Parameters:

input - 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)

getDone

@CanIgnoreReturnValue
public static <V> V getDone(Future<V> future)
                                           throws ExecutionException

Returns the result of the input Future, which must have already completed.

The benefits of this method are twofold. First, the name "getDone" suggests to readers that the Future is already done. Second, if buggy code calls getDone on a Future that is still pending, the program will throw instead of block. This can be important for APIs like whenAllComplete(...).call(...), where it is easy to use a new input from the call implementation but forget to add it to the arguments of whenAllComplete.

If you are looking for a method to determine whether a given Future is done, use the instance method Future.isDone().

Throws:

ExecutionException - if the Future failed with an exception

CancellationException - if the Future was cancelled

IllegalStateException - if the Future is not done

Since:

20.0