Google Cloud APIs use long-running operations (LROs) for calls expected totake significant time to complete (for example, provisioning aCompute Engine instance or initializing a Dataflow pipeline).These APIs don't keep an active long-lived connection or block while the taskruns. For LRO APIs, the Cloud Client Libraries for Java returns afuture for you tocheck later.

Determining if an API is an LRO

There are two main ways to determine if an API is an LRO:

• LRO APIs either have the suffixAsync (for example,createClusterAsync) orOperationCallable (for example,createClusterOperationCallable).
• LRO APIs return either anOperationFuture orOperationCallable.

The following snippet shows the two variations, usingJava-Dataproc as anexample:

// Async suffix (#1) returns OperationFuture (#2)publicfinalOperationFuture<Cluster,ClusterOperationMetadata>createClusterAsync(CreateClusterRequestrequest)// OperationCallable suffix (#1) returns OperationCallable (#2)publicfinalOperationCallable<CreateClusterRequest,Cluster,ClusterOperationMetadata>createClusterOperationCallable()

These are two variations for the same API and not two different APIs(both calls create a Dataproc cluster). TheAsync variant isrecommended.

High-level flow of an LRO

LRO APIs are essentially an initial request call followed by a series of smallpolling calls. The initial call sends the request and creates an "operation" onthe server. All subsequent polling calls to the server track the status of theoperation. If the operation is finished, the response is returned.Otherwise, an incomplete status is returned and the client library determineswhether to poll again.

By default, the client handles the polling logic, and you don't need toconfigure the polling mechanism unless you have specific requirements.

From your perspective, the call runs in the background untila response is received. The polling calls and timeout configurations havedefault values that are pre-configured by the service team based on theexpected time for their APIs. These configurations control many factors, suchas how often to poll and how long to wait before giving up.

The Cloud Client Libraries for Java provide an interface for interacting with the LROusingOperationFuture.

The following snippet shows how to call an operation and to wait for a response,usingJava-Dataproc as an example:

try(ClusterControllerClientclusterControllerClient=ClusterControllerClient.create()){CreateClusterRequestrequest=CreateClusterRequest.newBuilder().build();OperationFuture<Cluster,ClusterOperationMetadata>future=clusterControllerClient.createClusterAsync(request);// Blocks until there is a responseClusterresponse=future.get();}catch(CancellationExceptione){// Exceeded the timeout without the Operation completing.// Library is no longer polling for the Operation's status.}

Default LRO values

You can find the default values within each client'sStubSettings class. TheinitDefaults() method initializes the LRO settings inside the nestedBuilder class.

For example, inJava-Aiplatform v3.24.0, thedeployModel LRO call has thefollowing default parameters:

OperationTimedPollAlgorithm.create(RetrySettings.newBuilder().setInitialRetryDelayDuration(Duration.ofMillis(5000L)).setRetryDelayMultiplier(1.5).setMaxRetryDelayDuration(Duration.ofMillis(45000L)).setTotalTimeoutDuration(Duration.ofMillis(300000L)).setInitialRpcTimeoutDuration(Duration.ZERO)// not used.setRpcTimeoutMultiplier(1.0)// not used.setMaxRpcTimeoutDuration(Duration.ZERO)// not used.build()));

ClusterControllerSettings.BuildersettingsBuilder=ClusterControllerSettings.newBuilder();// Create a new OperationTimedPollAlgorithm objectTimedRetryAlgorithmtimedRetryAlgorithm=OperationTimedPollAlgorithm.create(RetrySettings.newBuilder().setInitialRetryDelayDuration(Duration.ofMillis(500L)).setRetryDelayMultiplier(1.5).setMaxRetryDelayDuration(Duration.ofMillis(5000L)).setTotalTimeoutDuration(Duration.ofHours(24L)).build());// Set the new polling settings for the specific LRO APIsettingsBuilder.createClusterOperationSettings().setPollingAlgorithm(timedRetryAlgorithm);ClusterControllerClientclusterControllerClient=ClusterControllerClient.create(settingsBuilder.build());