Manage long-running operations

Google Cloud APIs use long-running operations (LROs) for calls expected to take significant time to complete (for example, provisioning a Compute Engine instance or initializing a Dataflow pipeline). These APIs don't keep an active long-lived connection or block while the task runs. For LRO APIs, the Cloud Client Libraries for Java returns a future for you to check 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 suffix Async (for example, createClusterAsync) or OperationCallable (for example, createClusterOperationCallable).
  • LRO APIs return either an OperationFuture or OperationCallable.

The following snippet shows the two variations, using Java-Dataproc as an example:

// Async suffix (#1) returns OperationFuture (#2)
public final OperationFuture<Cluster, ClusterOperationMetadata> createClusterAsync(CreateClusterRequest request)

// OperationCallable suffix (#1) returns OperationCallable (#2)
public final OperationCallable<CreateClusterRequest, Cluster, ClusterOperationMetadata> createClusterOperationCallable()

These are two variations for the same API and not two different APIs (both calls create a Managed Service for Apache Spark cluster). The Async variant is recommended.

High-level flow of an LRO

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

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

From your perspective, the call runs in the background until a response is received. The polling calls and timeout configurations have default values that are pre-configured by the service team based on the expected time for their APIs. These configurations control many factors, such as 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 LRO using OperationFuture.

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

try (ClusterControllerClient clusterControllerClient = ClusterControllerClient.create()) {
  CreateClusterRequest request =
      CreateClusterRequest.newBuilder().build();
  OperationFuture<Cluster,