Long Running Operations

/**
 * Client for managing Google Long Running Operations
 * Provides polling, cancellation, and status management
 */
public class OperationsClient implements BackgroundResource {
    /** Create operations client with settings */
    public static OperationsClient create(OperationsSettings settings) throws IOException;
    
    /** Create operations client with stub */
    public static OperationsClient create(OperationsStub stub);
    
    /** Get operation by name */
    public Operation getOperation(String name);
    
    /** Get operation callable */
    public UnaryCallable<GetOperationRequest, Operation> getOperationCallable();
    
    /** List operations with name and filter */
    public ListOperationsPagedResponse listOperations(String name, String filter);
    
    /** List operations paged callable */
    public UnaryCallable<ListOperationsRequest, ListOperationsPagedResponse> listOperationsPagedCallable();
    
    /** List operations callable */
    public UnaryCallable<ListOperationsRequest, ListOperationsResponse> listOperationsCallable();
    
    /** Cancel operation by name */
    public void cancelOperation(String name);
    
    /** Cancel operation callable */
    public UnaryCallable<CancelOperationRequest, Empty> cancelOperationCallable();
    
    /** Delete operation by name */
    public void deleteOperation(String name);
    
    /** Delete operation callable */
    public UnaryCallable<DeleteOperationRequest, Empty> deleteOperationCallable();
    
    /** Wait for operation completion */
    public Operation waitOperation(WaitOperationRequest request); 
    
    /** Wait operation callable */
    public UnaryCallable<WaitOperationRequest, Operation> waitOperationCallable();
    
    /** Get client settings */
    public OperationsSettings getSettings();
    
    /** Get underlying stub */
    public OperationsStub getStub();
    
    /** Shutdown the client */
    public void shutdown();
    
    /** Check if terminated */
    public boolean isTerminated();
    
    /** Shutdown now */
    public void shutdownNow();
    
    /** Await termination */
    public boolean awaitTermination(long duration, TimeUnit unit) throws InterruptedException;
    
    /** Close the client */
    public void close();
}

/**
 * Settings for configuring OperationsClient
 * Manages authentication, transport, and call-specific settings
 */
public class OperationsSettings {
    /** Create settings from stub settings */
    public static OperationsSettings create(OperationsStubSettings stub) throws IOException;
    
    /** Create new builder */
    public static Builder newBuilder();
    
    /** Create builder with client context */
    public static Builder newBuilder(ClientContext clientContext);
    
    /** Get operation call settings */
    public UnaryCallSettings<GetOperationRequest, Operation> getOperationSettings();
    
    /** Get list operations settings */
    public PagedCallSettings<ListOperationsRequest, ListOperationsResponse, ListOperationsPagedResponse> 
        listOperationsSettings();
    
    /** Get cancel operation settings */
    public UnaryCallSettings<CancelOperationRequest, Empty> cancelOperationSettings();
    
    /** Get delete operation settings */
    public UnaryCallSettings<DeleteOperationRequest, Empty> deleteOperationSettings();
    
    /** Get wait operation settings */
    public UnaryCallSettings<WaitOperationRequest, Operation> waitOperationSettings();
    
    /** Create builder from settings */
    public Builder toBuilder();
}

/**
 * Builder for OperationsSettings with comprehensive configuration
 */
public static class OperationsSettings.Builder {
    /** Set credentials provider */
    public Builder setCredentialsProvider(CredentialsProvider credentialsProvider);
    
    /** Set transport channel provider */
    public Builder setTransportChannelProvider(TransportChannelProvider transportChannelProvider);
    
    /** Set header provider */
    public Builder setHeaderProvider(HeaderProvider headerProvider);
    
    /** Set endpoint */
    public Builder setEndpoint(String endpoint);
    
    /** Set quota project ID */
    public Builder setQuotaProjectId(String quotaProjectId);
    
    /** Get operation settings builder */
    public UnaryCallSettings.Builder<GetOperationRequest, Operation> getOperationSettings();
    
    /** Get list operations settings builder */
    public PagedCallSettings.Builder<ListOperationsRequest, ListOperationsResponse, ListOperationsPagedResponse> 
        listOperationsSettings();
    
    /** Get cancel operation settings builder */
    public UnaryCallSettings.Builder<CancelOperationRequest, Empty> cancelOperationSettings();
    
    /** Get delete operation settings builder */
    public UnaryCallSettings.Builder<DeleteOperationRequest, Empty> deleteOperationSettings();
    
    /** Get wait operation settings builder */
    public UnaryCallSettings.Builder<WaitOperationRequest, Operation> waitOperationSettings();
    
    /** Build the settings */
    public OperationsSettings build() throws IOException;
}

/**
 * Paged response for list operations
 * Supports automatic pagination and iteration
 */
public static class OperationsClient.ListOperationsPagedResponse extends AbstractPagedListResponse<
    ListOperationsRequest, ListOperationsResponse, Operation, ListOperationsPage, 
    ListOperationsFixedSizeCollection> {
    
    /** Create paged response from context and response */
    public static ListOperationsPagedResponse createAsync(
        PageContext<ListOperationsRequest, ListOperationsResponse, Operation> context,
        ApiFuture<ListOperationsResponse> futureResponse);
    
    /** Get the underlying page */
    public ListOperationsPage getPage();
    
    /** Iterate over all operations across pages */
    public Iterable<Operation> iterateAll();
    
    /** Get expanded page iterator */
    public ApiFuture<ListOperationsPagedResponse> getNextPageAsync();
}

/**
 * Single page of operations list response
 */
public static class OperationsClient.ListOperationsPage extends AbstractPage<
    ListOperationsRequest, ListOperationsResponse, Operation, ListOperationsPage> {
    
    /** Get operations in this page */
    public Iterable<Operation> getValues();
    
    /** Check if has next page */
    public boolean hasNextPage();
    
    /** Get next page token */
    public String getNextPageToken();
    
    /** Get next page async */
    public ApiFuture<ListOperationsPage> getNextPageAsync();
}

/**
 * Fixed size collection of operations pages
 */
public static class OperationsClient.ListOperationsFixedSizeCollection extends AbstractFixedSizeCollection<
    ListOperationsRequest, ListOperationsResponse, Operation, ListOperationsPage,
    ListOperationsFixedSizeCollection> {
    
    /** Get operations across all pages */
    public Iterable<Operation> getValues();
    
    /** Get page iterator */
    public Iterator<ListOperationsPage> iterator();
}

/**
 * Base stub class for Google Long Running Operations API
 * Provides low-level callable access
 */
public abstract class OperationsStub implements BackgroundResource {
    /** Get operation callable */
    public UnaryCallable<GetOperationRequest, Operation> getOperationCallable();
    
    /** List operations paged callable */
    public UnaryCallable<ListOperationsRequest, ListOperationsPagedResponse> listOperationsPagedCallable();
    
    /** List operations callable */
    public UnaryCallable<ListOperationsRequest, ListOperationsResponse> listOperationsCallable();
    
    /** Cancel operation callable */
    public UnaryCallable<CancelOperationRequest, Empty> cancelOperationCallable();
    
    /** Delete operation callable */
    public UnaryCallable<DeleteOperationRequest, Empty> deleteOperationCallable();
    
    /** Wait operation callable */
    public UnaryCallable<WaitOperationRequest, Operation> waitOperationCallable();
}

/**
 * gRPC-based implementation of OperationsStub
 * Manages gRPC channels and call configuration
 */
public class GrpcOperationsStub extends OperationsStub {
    /** Create stub with settings */
    public static GrpcOperationsStub create(OperationsStubSettings settings) throws IOException;
    
    /** Create stub with client context */
    public static GrpcOperationsStub create(ClientContext clientContext) throws IOException;
    
    /** Create stub with channel and settings */
    public static GrpcOperationsStub create(
        ClientContext clientContext, GrpcStubCallableFactory callableFactory) throws IOException;
}

/**
 * Settings for operations stubs
 * Configures transport, authentication, and callable behavior
 */
public class OperationsStubSettings extends StubSettings<OperationsStubSettings> {
    /** Create default settings */
    public static OperationsStubSettings newBuilder();
    
    /** Create builder with client context */
    public static OperationsStubSettings newBuilder(ClientContext clientContext);
    
    /** Get operation call settings */
    public UnaryCallSettings<GetOperationRequest, Operation> getOperationSettings();
    
    /** Get list operations settings */
    public PagedCallSettings<ListOperationsRequest, ListOperationsResponse, ListOperationsPagedResponse>
        listOperationsSettings();
    
    /** Get cancel operation settings */
    public UnaryCallSettings<CancelOperationRequest, Empty> cancelOperationSettings();
    
    /** Get delete operation settings */
    public UnaryCallSettings<DeleteOperationRequest, Empty> deleteOperationSettings();
    
    /** Get wait operation settings */
    public UnaryCallSettings<WaitOperationRequest, Operation> waitOperationSettings();
    
    /** Create builder from settings */
    public Builder toBuilder();
}

import com.google.longrunning.OperationsClient;
import com.google.longrunning.OperationsSettings;
import com.google.auth.oauth2.GoogleCredentials;

// Create operations client with default settings
OperationsClient operationsClient = OperationsClient.create();

// Create with custom settings
OperationsSettings settings = OperationsSettings.newBuilder()
    .setCredentialsProvider(FixedCredentialsProvider.create(
        GoogleCredentials.getApplicationDefault()))
    .setEndpoint("your-service.googleapis.com:443")
    .build();

OperationsClient customClient = OperationsClient.create(settings);

import com.google.longrunning.Operation;
import java.util.concurrent.TimeUnit;

// Get operation by name
Operation operation = operationsClient.getOperation("operations/my-operation-123");

// Check operation status
if (operation.getDone()) {
    if (operation.hasError()) {
        System.err.println("Operation failed: " + operation.getError().getMessage());
    } else {
        System.out.println("Operation completed successfully");
        // operation.getResponse() contains the result
    }
} else {
    System.out.println("Operation still in progress: " + operation.getName());
    // operation.getMetadata() contains progress information
}

// Poll operation until completion
while (!operation.getDone()) {
    TimeUnit.SECONDS.sleep(5);
    operation = operationsClient.getOperation(operation.getName());
    System.out.println("Operation progress: " + operation.getMetadata());
}

import com.google.longrunning.Operation;

// List all operations
for (Operation operation : operationsClient.listOperations("", "").iterateAll()) {
    System.out.println("Operation: " + operation.getName() + 
                      ", Done: " + operation.getDone());
}

// List operations with filter
String filter = "done=false AND metadata.@type=type.googleapis.com/MyMetadata";
for (Operation operation : operationsClient.listOperations("operations", filter).iterateAll()) {
    System.out.println("Active operation: " + operation.getName());
}

// Manual pagination
ListOperationsPagedResponse response = operationsClient.listOperations("operations", "");
for (ListOperationsPage page : response.iteratePages()) {
    for (Operation operation : page.getValues()) {
        System.out.println("Operation: " + operation.getName());
    }
}

// Cancel a running operation
operationsClient.cancelOperation("operations/my-operation-123");

// Delete a completed operation
operationsClient.deleteOperation("operations/my-operation-123");

// Wait for operation with timeout
WaitOperationRequest waitRequest = WaitOperationRequest.newBuilder()
    .setName("operations/my-operation-123")
    .setTimeout(com.google.protobuf.Duration.newBuilder()
        .setSeconds(300) // 5 minutes
        .build())
    .build();

Operation result = operationsClient.waitOperation(waitRequest);

import com.google.api.gax.retrying.RetrySettings;
import java.time.Duration;

// Configure retry settings for operations
RetrySettings retrySettings = RetrySettings.newBuilder()
    .setInitialRetryDelay(Duration.ofMillis(100))
    .setRetryDelayMultiplier(1.3)
    .setMaxRetryDelay(Duration.ofMinutes(1))
    .setInitialRpcTimeout(Duration.ofSeconds(30))
    .setRpcTimeoutMultiplier(1.0)
    .setMaxRpcTimeout(Duration.ofSeconds(30))
    .setTotalTimeout(Duration.ofMinutes(10))
    .build();

OperationsSettings settings = OperationsSettings.newBuilder()
    .getOperationSettings()
    .setRetrySettings(retrySettings)
    .getParent()
    .build();

OperationsClient client = OperationsClient.create(settings);

import com.google.api.gax.rpc.FixedTransportChannelProvider;
import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;

// Configure for custom endpoint
InstantiatingGrpcChannelProvider channelProvider = 
    InstantiatingGrpcChannelProvider.newBuilder()
        .setEndpoint("custom-operations-service.com:443")
        .build();

OperationsSettings settings = OperationsSettings.newBuilder()
    .setTransportChannelProvider(channelProvider)
    .build();

OperationsClient client = OperationsClient.create(settings);