Class OperationFutureImpl<ResponseT,MetadataT> (2.17.0)

public final class OperationFutureImpl<ResponseT,MetadataT> implements OperationFuture<ResponseT,MetadataT>

An ApiFuture which tracks polling of a service. The polling is done periodically, based on the com.google.api.gax.retrying.TimedRetryAlgorithm.

This class is thread-safe.

This is public only for technical reasons, for advanced usage.

Inheritance

java.lang.Object > OperationFutureImpl<ResponseT,MetadataT>

Implements

com.google.api.gax.longrunning.OperationFuture<ResponseT,MetadataT>

Type Parameters

NameDescription
ResponseT
MetadataT

Constructors

OperationFutureImpl(RetryingFuture<OperationSnapshot> pollingFuture, ApiFuture<OperationSnapshot> initialFuture, ApiFunction<OperationSnapshot,ResponseT> responseTransformer, ApiFunction<OperationSnapshot,MetadataT> metadataTransformer)

public OperationFutureImpl(RetryingFuture<OperationSnapshot> pollingFuture, ApiFuture<OperationSnapshot> initialFuture, ApiFunction<OperationSnapshot,ResponseT> responseTransformer, ApiFunction<OperationSnapshot,MetadataT> metadataTransformer)

Creates a new operation future instance.

Parameters
NameDescription
pollingFutureRetryingFuture<OperationSnapshot>

retrying future which tracks polling of the server operation (in most cases with exponential upper bounded intervals)

initialFuturecom.google.api.core.ApiFuture<OperationSnapshot>

the initial future which started the operation on the server side

responseTransformercom.google.api.core.ApiFunction<OperationSnapshot,ResponseT>
metadataTransformercom.google.api.core.ApiFunction<OperationSnapshot,MetadataT>

OperationFutureImpl(RetryingFuture<OperationSnapshot> pollingFuture, ApiFuture<OperationSnapshot> initialFuture, ApiFunction<OperationSnapshot,ResponseT> responseTransformer, ApiFunction<OperationSnapshot,MetadataT> metadataTransformer, ApiFunction<Exception,ResponseT> exceptionTransformer)

public OperationFutureImpl(RetryingFuture<OperationSnapshot> pollingFuture, ApiFuture<OperationSnapshot> initialFuture, ApiFunction<OperationSnapshot,ResponseT> responseTransformer, ApiFunction<OperationSnapshot,MetadataT> metadataTransformer, ApiFunction<Exception,ResponseT> exceptionTransformer)
Parameters
NameDescription
pollingFutureRetryingFuture<OperationSnapshot>
initialFuturecom.google.api.core.ApiFuture<OperationSnapshot>
responseTransformercom.google.api.core.ApiFunction<OperationSnapshot,ResponseT>
metadataTransformercom.google.api.core.ApiFunction<OperationSnapshot,MetadataT>
exceptionTransformercom.google.api.core.ApiFunction<Exception,ResponseT>

Methods

addListener(Runnable listener, Executor executor)

public void addListener(Runnable listener, Executor executor)
Parameters
NameDescription
listenerRunnable
executorExecutor

cancel(boolean mayInterruptIfRunning)

public boolean cancel(boolean mayInterruptIfRunning)
Parameter
NameDescription
mayInterruptIfRunningboolean
Returns
TypeDescription
boolean

get()

public ResponseT get()
Returns
TypeDescription
ResponseT
Exceptions
TypeDescription
InterruptedException
ExecutionException

get(long timeout, TimeUnit unit)

public ResponseT get(long timeout, TimeUnit unit)
Parameters
NameDescription
timeoutlong
unitTimeUnit
Returns
TypeDescription
ResponseT
Exceptions
TypeDescription
InterruptedException
ExecutionException
TimeoutException

getInitialFuture()

public ApiFuture<OperationSnapshot> getInitialFuture()

Returns the OperationSnapshot future of the initial request which started this OperationFuture.

Returns
TypeDescription
com.google.api.core.ApiFuture<OperationSnapshot>

getMetadata()

public ApiFuture<MetadataT> getMetadata()

Gets the metadata of the operation tracked by this OperationFuture. This method returns the current poll metadata result (or the initial call metadata if it hasn't completed yet). The returned future completes once the current scheduled poll request (or the initial request if it hasn't completed yet) is executed and response is received from the server. The time when the polling request is executed is determined by the underlying polling algorithm.

Adding direct executor (same thread) callbacks to the future returned by this method is strongly not recommended, since the future is resolved under retrying future's internal lock and may affect the operation polling process. Adding separate thread callbacks is ok.

Note, some APIs may return null in metadata response message. In such cases this method may return a non-null future whose get() method will return null. This behavior is API specific an should be considered a valid case, which indicates that the recent poll request has completed, but no specific metadata was provided by the server. (i.e. most probably providing metadata for an intermediate result is not supported by the server).

In most cases this method returns a future which is not completed yet, so calling ApiFuture#get() is a potentially blocking operation. To get metadata without blocking the current thread use the #peekMetadata() method instead.

If this operation future is completed, this method always returns the metadata from the last poll request (which completed the operation future).

If this operation future failed, this method may (depending on the failure type) return a non-failing future, representing the metadata from the last poll request (which failed the operation future).

If this operation future was cancelled, this method returns a canceled metatata future as well.

In general this method behaves similarly to RetryingFuture#getAttemptResult().

Returns
TypeDescription
com.google.api.core.ApiFuture<MetadataT>

getName()

public String getName()

Returns the value of the name of the operation from the initial operation object returned from the initial call to start the operation. Blocks if the initial call to start the operation hasn't returned yet.

Returns
TypeDescription
String
Exceptions
TypeDescription
ExecutionException
InterruptedException

getPollingFuture()

public RetryingFuture<OperationSnapshot> getPollingFuture()

Returns the RetryingFuture which continues to poll OperationSnapshot.

Returns
TypeDescription
RetryingFuture<OperationSnapshot>

isCancelled()

public boolean isCancelled()
Returns
TypeDescription
boolean

isDone()

public boolean isDone()
Returns
TypeDescription
boolean

peekMetadata()

public ApiFuture<MetadataT> peekMetadata()

Peeks at the metadata of the operation tracked by this OperationFuture. If the initial future hasn't completed yet this method returns null, otherwise it returns the latest metadata returned from the server (i.e. either initial call metadata or the metadata received from the latest completed poll iteration).

If not null, the returned result is guaranteed to be an already completed future, so ApiFuture#isDone() will always be true and ApiFuture#get() will always be non-blocking.

Note, some APIs may return null in metadata response message. In such cases this method may return a non-null future whose get() method will return null. This behavior is API specific an should be considered a valid case, which indicates that the recent poll request has completed, but no specific metadata was provided by the server (i.e. most probably providing metadata for an intermediate result is not supported by the server).

This method should be used to check operation progress without blocking current thread. Since this method returns metadata from the latest completed poll, it is potentially slightly stale compared to the most recent data. To get the most recent data and/or get notified when the current scheduled poll request completes use the #getMetadata() method instead.

If this operation future is completed, this method always returns the metadata from the last poll request (which completed the operation future).

If this operation future failed, this method may (depending on the failure type) return a non-failing future, representing the metadata from the last poll request (which failed the operation future).

If this operation future was cancelled, this method returns a canceled metatata future as well.

In general this method behaves similarly to RetryingFuture#peekAttemptResult().

Returns
TypeDescription
com.google.api.core.ApiFuture<MetadataT>