org.glassfish.jersey.internal.guava

Class Futures

java.lang.Object

org.glassfish.jersey.internal.guava.Futures

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.

Since:

1.0

Author:

Kevin Bourrillion, Nishant Thakkar, Sven Mawson

Method Summary

Modifier and Type	Method and Description
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) 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

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.

transform

public static <I,O> ListenableFuture<O> 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. 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 an inline executor, which carries some caveats for heavier operations. For example, the call to function.apply may run on an unpredictable or undesirable thread:

• If the input Future is done at the time transform is called, transform will call function.apply inline.
• If the input 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.

Also note that, regardless of which thread executes the 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.

Parameters:

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