Package com.google.api.core

Class ApiFutures

java.lang.Object

com.google.api.core.ApiFutures

public final class ApiFutures
extends Object

Static utility methods for the ApiFuture interface.

Method Summary

Modifier and Type	Method	Description
static <V> void	addCallback(ApiFuture<V> future, ApiFutureCallback<? super V> callback)	Deprecated. Use the overload that requires an executor.
static <V> void	addCallback(ApiFuture<V> future, ApiFutureCallback<? super V> callback, Executor executor)	Registers a callback to be run when the ApiFuture's computation is complete or, if the computation is already complete, immediately.
static <V> ApiFuture<List<V>>	allAsList(Iterable<? extends ApiFuture<? extends V>> futures)	Creates a new ApiFuture whose value is a list containing the values of all its input futures, if all succeed.
static <V,X extends Throwable> ApiFuture<V>	catching(ApiFuture<? extends V> input, Class<X> exceptionType, ApiFunction<? super X,? extends V> callback)	Deprecated. Use the overload that requires an executor.
static <V,X extends Throwable> ApiFuture<V>	catching(ApiFuture<? extends V> input, Class<X> exceptionType, ApiFunction<? super X,? extends V> callback, Executor executor)	Returns an ApiFuture whose result is taken from the given primary input or, if the primary input fails with the given exceptionType, from the result provided by the callback.
static <V,X extends Throwable> ApiFuture<V>	catchingAsync(ApiFuture<V> input, Class<X> exceptionType, ApiAsyncFunction<? super X,V> callback, Executor executor)	Returns a ApiFuture whose result is taken from the given primary input or, if the primary input fails with the given exceptionType, from the result provided by the callback.
static <V> ApiFuture<V>	immediateCancelledFuture()	Creates a ApiFuture which is cancelled immediately upon construction, so that isCancelled() always returns true.
static <V> ApiFuture<V>	immediateFailedFuture(Throwable throwable)	Returns a ApiFuture which has an exception set immediately upon construction.
static <V> ApiFuture<V>	immediateFuture(V value)	Creates a ApiFuture which has its value set immediately upon construction.
static <V> ApiFuture<List<V>>	successfulAsList(Iterable<? extends ApiFuture<? extends V>> futures)	Creates a new ApiFuture whose value is a list containing the values of all its successful input futures.
static <V,X> ApiFuture<X>	transform(ApiFuture<? extends V> input, ApiFunction<? super V,? extends X> function)	Deprecated. Use the overload that requires an executor.
static <V,X> ApiFuture<X>	transform(ApiFuture<? extends V> input, ApiFunction<? super V,? extends X> function, Executor executor)	Returns a new ApiFuture whose result is derived from the result of the given ApiFuture.
static <I,O> ApiFuture<O>	transformAsync(ApiFuture<I> input, ApiAsyncFunction<I,O> function)	Deprecated. Use transformAsync(ApiFuture, ApiAsyncFunction, Executor), the overload that requires an executor.
static <I,O> ApiFuture<O>	transformAsync(ApiFuture<I> input, ApiAsyncFunction<I,O> function, Executor executor)	Returns a new ApiFuture whose result is asynchronously derived from the result of the given ApiFuture.

Methods inherited from class java.lang.Object

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

Method Detail

addCallback

@Deprecated
public static <V> void addCallback(ApiFuture<V> future,
                                   ApiFutureCallback<? super V> callback)

Deprecated.

Use the overload that requires an executor. For identical behavior, pass MoreExecutors.directExecutor(), but consider whether another executor would be safer.

Registers a callback to be run when the ApiFuture's computation is complete or, if the computation is already complete, immediately.

Parameters:

future - The future attach the callback to

callback - The callback to invoke when future is completed

addCallback

public static <V> void addCallback(ApiFuture<V> future,
                                   ApiFutureCallback<? super V> callback,
                                   Executor executor)

Registers a callback to be run when the ApiFuture's computation is complete or, if the computation is already complete, immediately.

Note that this method is a delegate of Futures.addCallback(ListenableFuture, FutureCallback, Executor).

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

See Also:

Futures.addCallback(ListenableFuture, FutureCallback, Executor)

catching

@Deprecated
public static <V,X extends Throwable> ApiFuture<V> catching(ApiFuture<? extends V> input,
                                                                  Class<X> exceptionType,
                                                                  ApiFunction<? super X,? extends V> callback)

Deprecated.

Use the overload that requires an executor. For identical behavior, pass MoreExecutors.directExecutor(), but consider whether another executor would be safer.

Returns an ApiFuture whose result is taken from the given primary input or, if the primary input fails with the given exceptionType, from the result provided by the callback.

Parameters:

input - The primary input ApiFuture

exceptionType - The exception type that triggers use of fallback

callback - The ApiFunction to be called if input fails with the expected exception type

Returns:

A future whose result is taken either from the given input or by the callback

catching

public static <V,X extends Throwable> ApiFuture<V> catching(ApiFuture<? extends V> input,
                                                                  Class<X> exceptionType,
                                                                  ApiFunction<? super X,? extends V> callback,
                                                                  Executor executor)

Returns an ApiFuture whose result is taken from the given primary input or, if the primary input fails with the given exceptionType, from the result provided by the callback.

Note that this method is a delegate of Futures.catching(ListenableFuture, Class, Function, Executor).

Parameters:

input - The primary input ApiFuture

exceptionType - The exception type that triggers use of fallback

callback - The ApiFunction to be called if input fails with the expected exception type

executor - The executor that runs fallback if input fails

Returns:

A future whose result is taken either from the given input or by the callback

See Also:

Futures.catching(ListenableFuture, Class, Function, Executor)

catchingAsync

@BetaApi
public static <V,X extends Throwable> ApiFuture<V> catchingAsync(ApiFuture<V> input,
                                                                       Class<X> exceptionType,
                                                                       ApiAsyncFunction<? super X,V> callback,
                                                                       Executor executor)

Returns a ApiFuture whose result is taken from the given primary input or, if the primary input fails with the given exceptionType, from the result provided by the callback.

Note that this method is a delegate of Futures.catchingAsync(ListenableFuture, Class, AsyncFunction, Executor)

Parameters:

input - The primary input ApiFuture

exceptionType - The exception type that triggers use of fallback.

callback - The ApiAsyncFunction to be called if input fails with the expected * exception type.

executor - The executor that runs fallback if input fails

Returns:

A future whose result is taken either from the given input or by the callback

See Also:

Futures.catchingAsync(ListenableFuture, Class, AsyncFunction, Executor)

immediateFuture

public static <V> ApiFuture<V> immediateFuture(V value)

Creates a ApiFuture which has its value set immediately upon construction.

Note that this method is a delegate of Futures.immediateFuture(Object).

Parameters:

value - The value set to the ApiFuture upon construction

Returns:

A future that holds value

See Also:

Futures.immediateFuture(Object)

immediateFailedFuture

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

Returns a ApiFuture which has an exception set immediately upon construction.

Note that this method is a delegate of Futures.immediateFailedFuture(Throwable).

Parameters:

throwable - The exception set to the ApiFuture upon construction

Returns:

A future that holds an exception

See Also:

Futures.immediateFailedFuture(Throwable)

immediateCancelledFuture

public static <V> ApiFuture<V> immediateCancelledFuture()

Creates a ApiFuture which is cancelled immediately upon construction, so that isCancelled() always returns true.

Note that this method is a delegate of Futures.immediateCancelledFuture().

Returns:

A cancelled future

See Also:

Futures.immediateCancelledFuture()

transform

@Deprecated
public static <V,X> ApiFuture<X> transform(ApiFuture<? extends V> input,
                                                 ApiFunction<? super V,? extends X> function)

Deprecated.

Use the overload that requires an executor. For identical behavior, pass MoreExecutors.directExecutor(), but consider whether another executor would be safer.

Returns a new ApiFuture whose result is derived from the result of the given ApiFuture.

Parameters:

input - 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 holds result of the transformation

transform

public static <V,X> ApiFuture<X> transform(ApiFuture<? extends V> input,
                                                 ApiFunction<? super V,? extends X> function,
                                                 Executor executor)

Returns a new ApiFuture whose result is derived from the result of the given ApiFuture.

Note that this method is a delegate of Futures.transform(ListenableFuture, Function, Executor).

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

See Also:

Futures.transform(ListenableFuture, Function, Executor)

allAsList

public static <V> ApiFuture<List<V>> allAsList(Iterable<? extends ApiFuture<? extends V>> futures)

Creates a new ApiFuture whose value is a list containing the values of all its input futures, if all succeed.

The list of results is in the same order as the input list.

Note that this method is a delegate of Futures.allAsList(Iterable).

Parameters:

futures - Futures to combine

Returns:

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

See Also:

Futures.allAsList(Iterable)

successfulAsList

@BetaApi
public static <V> ApiFuture<List<V>> successfulAsList(Iterable<? extends ApiFuture<? extends V>> futures)

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

The list of results is in the same order as the input list.

Note that this method is a delegate of Futures.successfulAsList(Iterable).

Parameters:

futures - Futures to combine

Returns:

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

See Also:

Futures.successfulAsList(Iterable)

transformAsync

@Deprecated
public static <I,O> ApiFuture<O> transformAsync(ApiFuture<I> input,
                                                      ApiAsyncFunction<I,O> function)

Deprecated.

Use transformAsync(ApiFuture, ApiAsyncFunction, Executor), the overload that requires an executor. For identical behavior, pass MoreExecutors.directExecutor(), but consider whether another executor would be safer.

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

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)

transformAsync

public static <I,O> ApiFuture<O> transformAsync(ApiFuture<I> input,
                                                      ApiAsyncFunction<I,O> function,
                                                      Executor executor)

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

Note that this method is a delegate of Futures.transformAsync(ListenableFuture, AsyncFunction, Executor).

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)

See Also:

Futures.transformAsync(ListenableFuture, AsyncFunction, Executor)