When an API method normally takes long time to complete, it can be designed to return * [Operation][google.longrunning.Operation] to the client, and the client can use this interface to * receive the real response asynchronously by polling the operation resource, or pass the operation * resource to another API (such as Google Cloud Pub/Sub API) to receive the response. Any API * service that returns long-running operations should implement the `Operations` interface so * developers can have a consistent client experience. * *
This class provides the ability to make remote calls to the backing service through method * calls that map to API methods. Sample code to get started: * *
*
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* Operation response = operationsClient.getOperation(name);
* }
*
*
*
* Note: close() needs to be called on the operationsClient object to clean up resources such as * threads. In the example above, try-with-resources is used, which automatically calls close(). * *
The surface of this class includes several types of Java methods for each of the API's * methods: * *
See the individual methods for example code. * *
Many parameters require resource names to be formatted in a particular way. To assist with * these names, this class includes a format method for each type of name, and additionally a parse * method to extract the individual identifiers contained within names that are returned. * *
This class can be customized by passing in a custom instance of OperationsSettings to * create(). For example: * *
To customize credentials: * *
*
* OperationsSettings operationsSettings =
* OperationsSettings.newBuilder()
* .setCredentialsProvider(FixedCredentialsProvider.create(myCredentials))
* .build();
* OperationsClient operationsClient =
* OperationsClient.create(operationsSettings);
*
*
*/
public class OperationsClient implements BackgroundResource {
private final OperationsSettings settings;
private final OperationsStub stub;
/**
* Constructs an instance of OperationsClient, using the given settings. The channels are created
* based on the settings passed in, or defaults for any settings that are not set.
*/
public static final OperationsClient create(OperationsSettings settings) throws IOException {
return new OperationsClient(settings);
}
/**
* Constructs an instance of OperationsClient, using the given stub for making calls. This is for
* advanced usage - prefer to use OperationsSettings}.
*/
public static final OperationsClient create(OperationsStub stub) {
return new OperationsClient(stub);
}
/**
* Constructs an instance of OperationsClient, using the given settings. This is protected so that
* it is easy to make a subclass, but otherwise, the static factory methods should be preferred.
*/
protected OperationsClient(OperationsSettings settings) throws IOException {
this.settings = settings;
this.stub = ((OperationsStubSettings) settings.getStubSettings()).createStub();
}
protected OperationsClient(OperationsStub stub) {
this.settings = null;
this.stub = stub;
}
public final OperationsSettings getSettings() {
return settings;
}
public OperationsStub getStub() {
return stub;
}
/**
* Gets the latest state of a long-running operation. Clients can use this method to poll the
* operation result at intervals as recommended by the API service.
*
* Sample code: * *
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* Operation response = operationsClient.getOperation(name);
* }
* Sample code: * *
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* GetOperationRequest request = GetOperationRequest.newBuilder()
* .setName(name)
* .build();
* Operation response = operationsClient.getOperation(request);
* }
* Sample code: * *
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* GetOperationRequest request = GetOperationRequest.newBuilder()
* .setName(name)
* .build();
* ApiFuture<Operation> future = operationsClient.getOperationCallable().futureCall(request);
* // Do something
* Operation response = future.get();
* }
* NOTE: the `name` binding below allows API services to override the binding to use different * resource name schemes, such as `users/*/operations`. * *
Sample code: * *
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* String filter = "";
* for (Operation element : operationsClient.listOperations(name, filter).iterateAll()) {
* // doThingsWith(element);
* }
* }
* NOTE: the `name` binding below allows API services to override the binding to use different * resource name schemes, such as `users/*/operations`. * *
Sample code: * *
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* String filter = "";
* ListOperationsRequest request = ListOperationsRequest.newBuilder()
* .setName(name)
* .setFilter(filter)
* .build();
* for (Operation element : operationsClient.listOperations(request).iterateAll()) {
* // doThingsWith(element);
* }
* }
* NOTE: the `name` binding below allows API services to override the binding to use different * resource name schemes, such as `users/*/operations`. * *
Sample code: * *
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* String filter = "";
* ListOperationsRequest request = ListOperationsRequest.newBuilder()
* .setName(name)
* .setFilter(filter)
* .build();
* ApiFuture<ListOperationsPagedResponse> future = operationsClient.listOperationsPagedCallable().futureCall(request);
* // Do something
* for (Operation element : future.get().iterateAll()) {
* // doThingsWith(element);
* }
* }
* NOTE: the `name` binding below allows API services to override the binding to use different * resource name schemes, such as `users/*/operations`. * *
Sample code: * *
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* String filter = "";
* ListOperationsRequest request = ListOperationsRequest.newBuilder()
* .setName(name)
* .setFilter(filter)
* .build();
* while (true) {
* ListOperationsResponse response = operationsClient.listOperationsCallable().call(request);
* for (Operation element : response.getOperationsList()) {
* // doThingsWith(element);
* }
* String nextPageToken = response.getNextPageToken();
* if (!Strings.isNullOrEmpty(nextPageToken)) {
* request = request.toBuilder().setPageToken(nextPageToken).build();
* } else {
* break;
* }
* }
* }
* Sample code: * *
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* operationsClient.cancelOperation(name);
* }
* Sample code: * *
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* CancelOperationRequest request = CancelOperationRequest.newBuilder()
* .setName(name)
* .build();
* operationsClient.cancelOperation(request);
* }
* Sample code: * *
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* CancelOperationRequest request = CancelOperationRequest.newBuilder()
* .setName(name)
* .build();
* ApiFuture<Void> future = operationsClient.cancelOperationCallable().futureCall(request);
* // Do something
* future.get();
* }
* Sample code: * *
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* operationsClient.deleteOperation(name);
* }
* Sample code: * *
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* DeleteOperationRequest request = DeleteOperationRequest.newBuilder()
* .setName(name)
* .build();
* operationsClient.deleteOperation(request);
* }
* Sample code: * *
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* DeleteOperationRequest request = DeleteOperationRequest.newBuilder()
* .setName(name)
* .build();
* ApiFuture<Void> future = operationsClient.deleteOperationCallable().futureCall(request);
* // Do something
* future.get();
* }
* Sample code: * *
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* WaitOperationRequest request = WaitOperationRequest.newBuilder()
* .setName(name)
* .setTimeout(Duration.ofMillis(100))
* .build();
* Operation response = operationsClient.waitOperation(request);
* }
* Sample code: * *
* try (OperationsClient operationsClient = OperationsClient.create()) {
* String name = "";
* WaitOperationRequest request = WaitOperationRequest.newBuilder()
* .setName(name)
* .setTimeout(Duration.ofMillis(100))
* .build();
* ApiFuture<Operation> future = operationsClient.waitOperationCallable().futureCall(request);
* }
*