Class ApiFutures (2.26.0)

Version 2.26.0

• 2.38.0 (latest)
• 2.37.1
• 2.36.0
• 2.35.0
• 2.34.0
• 2.33.0
• 2.32.0
• 2.31.1
• 2.30.0
• 2.29.1
• 2.28.0
• 2.26.0
• 2.25.0
• 2.24.0
• 2.22.0
• 2.21.0
• 2.20.0
• 2.19.0
• 2.18.0
• 2.17.1
• 2.16.0
• 2.15.1
• 2.14.1
• 2.13.1
• 2.7.0
• 2.6.3
• 2.5.0
• 2.4.0
• 2.3.1
• 2.1.2

public final class ApiFutures

Static utility methods for the ApiFuture interface.

Inheritance

java.lang.Object > ApiFutures

Inherited Members

Object.clone()

Object.equals(Object)

Object.finalize()

Object.getClass()

Object.hashCode()

Object.notify()

Object.notifyAll()

Object.toString()

Object.wait()

Object.wait(long)

Object.wait(long,int)

Static Methods

<I,O>transformAsync(ApiFuture<I> input, ApiAsyncFunction<I,O> function) (deprecated)

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

Deprecated. Use <xref uid="com.google.api.core.ApiFutures.<I,O>transformAsync(com.google.api.core.ApiFuture,com.google.api.core.ApiAsyncFunction<I,O>,java.util.concurrent.Executor)" data-throw-if-not-resolved="false">#transformAsync(ApiFuture, ApiAsyncFunction, Executor), the overload that requires an executor. For identical behavior, pass com.google.common.util.concurrent.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
Name	Description
input	ApiFuture<I> The future to transform
function	ApiAsyncFunction<I,O> A function to transform the result of the input future to the result of the output future

Returns
Type	Description
ApiFuture<O>	A future that holds result of the function (if the input succeeded) or the original input's failure (if not)

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

public static ApiFuture<O> <I,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). See Also: Futures#transformAsync(ListenableFuture, AsyncFunction, Executor)

Parameters
Name	Description
input	ApiFuture<I> The future to transform
function	ApiAsyncFunction<I,O> A function to transform the result of the input future to the result of the output future
executor	Executor Executor to run the function in.

Returns
Type	Description
ApiFuture<O>	A future that holds result of the function (if the input succeeded) or the original input's failure (if not)

<V,X>catching(ApiFuture<? extends V> input, Class<X> exceptionType, ApiFunction<? super X,? extends V> callback) (deprecated)

public static ApiFuture<V> <V,X>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 com.google.common.util.concurrent.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
Name	Description
input	ApiFuture<? extends V> The primary input ApiFuture
exceptionType	Class<X> The exception type that triggers use of fallback
callback	ApiFunction<? super X,? extends V> The ApiFunction to be called if input fails with the expected exception type

Returns
Type	Description
ApiFuture<V>	A future whose result is taken either from the given input or by the callback

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

public static ApiFuture<V> <V,X>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). See Also: Futures#catching(ListenableFuture, Class, Function, Executor)

Parameters
Name	Description
input	ApiFuture<? extends V> The primary input ApiFuture
exceptionType	Class<X> The exception type that triggers use of fallback
callback	ApiFunction<? super X,? extends V> The ApiFunction to be called if input fails with the expected exception type
executor	Executor The executor that runs fallback if input fails

Returns
Type	Description
ApiFuture<V>	A future whose result is taken either from the given input or by the callback

<V,X>catchingAsync(ApiFuture<V> input, Class<X> exceptionType, ApiAsyncFunction<? super X,V> callback, Executor executor)

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

Beta

This feature is covered by the Pre-GA Offerings Terms of the Terms of Service. Pre-GA libraries might have limited support, and changes to pre-GA libraries might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

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) See Also: Futures#catchingAsync(ListenableFuture, Class, AsyncFunction, Executor)

Parameters
Name	Description
input	ApiFuture<V> The primary input ApiFuture
exceptionType	Class<X> The exception type that triggers use of fallback.
callback	ApiAsyncFunction<? super X,V> The ApiAsyncFunction to be called if input fails with the expected * exception type.
executor	Executor The executor that runs fallback if input fails

Returns
Type	Description
ApiFuture<V>	A future whose result is taken either from the given input or by the callback

<V,X>transform(ApiFuture<? extends V> input, ApiFunction<? super V,? extends X> function) (deprecated)

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

Deprecated. Use the overload that requires an executor. For identical behavior, pass com.google.common.util.concurrent.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
Name	Description
input	ApiFuture<? extends V> The future to transform
function	ApiFunction<? super V,? extends X> A Function to transform the results of the provided future to the results of the returned future

Returns
Type	Description
ApiFuture<X>	A future that holds result of the transformation

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

public static ApiFuture<X> <V,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). See Also: Futures#transform(ListenableFuture, Function, Executor)

Parameters
Name	Description
input	ApiFuture<? extends V> The future to transform
function	ApiFunction<? super V,? extends X> A Function to transform the results of the provided future to the results of the returned future.
executor	Executor Executor to run the function in.

Returns
Type	Description
ApiFuture<X>	A future that holds result of the transformation

<V>addCallback(ApiFuture<V> future, ApiFutureCallback<? super V> callback) (deprecated)

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

Deprecated. Use the overload that requires an executor. For identical behavior, pass com.google.common.util.concurrent.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
Name	Description
future	ApiFuture<V> The future attach the callback to
callback	ApiFutureCallback<? super V> The callback to invoke when future is completed

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

public static void <V>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). See Also: Futures#addCallback(ListenableFuture, FutureCallback, Executor)

Parameters
Name	Description
future	ApiFuture<V> The future attach the callback to
callback	ApiFutureCallback<? super V> The callback to invoke when future is completed
executor	Executor The executor to run callback when the future completes

<V>allAsList(Iterable<? extends ApiFuture<? extends V>> futures)

public static ApiFuture<List<V>> <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). See Also: Futures#allAsList(Iterable)

Parameter
Name	Description
futures	Iterable<? extends com.google.api.core.ApiFuture<? extends V>> Futures to combine

Returns
Type	Description
ApiFuture<List<V>>	A future that provides a list of the results of the component futures

<V>immediateCancelledFuture()

public static ApiFuture<V> <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(). See Also: Futures#immediateCancelledFuture()

Returns
Type	Description
ApiFuture<V>	A cancelled future

<V>immediateFailedFuture(Throwable throwable)

public static ApiFuture<V> <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). See Also: Futures#immediateFailedFuture(Throwable)

Parameter
Name	Description
throwable	Throwable The exception set to the ApiFuture upon construction

Returns
Type	Description
ApiFuture<V>	A future that holds an exception

<V>immediateFuture(V value)

public static ApiFuture<V> <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). See Also: Futures#immediateFuture(Object)

Parameter
Name	Description
value	V The value set to the ApiFuture upon construction

Returns
Type	Description
ApiFuture<V>	A future that holds value

<V>successfulAsList(Iterable<? extends ApiFuture<? extends V>> futures)

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

Beta

This feature is covered by the Pre-GA Offerings Terms of the Terms of Service. Pre-GA libraries might have limited support, and changes to pre-GA libraries might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

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). See Also: Futures#successfulAsList(Iterable)

Parameter
Name	Description
futures	Iterable<? extends com.google.api.core.ApiFuture<? extends V>> Futures to combine

Returns
Type	Description
ApiFuture<List<V>>	A future that provides a list of the results of the component futures