0
# Long Running Operations
1

2
Complete client support for Google's Long Running Operations API with polling, cancellation, and status management.
3

4
## Capabilities
5

6
### OperationsClient
7

8
Primary client for managing long-running operations with comprehensive lifecycle support.
9

10
```java { .api }
11
/**
12
 * Client for managing Google Long Running Operations
13
 * Provides polling, cancellation, and status management
14
 */
15
public class OperationsClient implements BackgroundResource {
16
    /** Create operations client with settings */
17
    public static OperationsClient create(OperationsSettings settings) throws IOException;
18
    
19
    /** Create operations client with stub */
20
    public static OperationsClient create(OperationsStub stub);
21
    
22
    /** Get operation by name */
23
    public Operation getOperation(String name);
24
    
25
    /** Get operation callable */
26
    public UnaryCallable<GetOperationRequest, Operation> getOperationCallable();
27
    
28
    /** List operations with name and filter */
29
    public ListOperationsPagedResponse listOperations(String name, String filter);
30
    
31
    /** List operations paged callable */
32
    public UnaryCallable<ListOperationsRequest, ListOperationsPagedResponse> listOperationsPagedCallable();
33
    
34
    /** List operations callable */
35
    public UnaryCallable<ListOperationsRequest, ListOperationsResponse> listOperationsCallable();
36
    
37
    /** Cancel operation by name */
38
    public void cancelOperation(String name);
39
    
40
    /** Cancel operation callable */
41
    public UnaryCallable<CancelOperationRequest, Empty> cancelOperationCallable();
42
    
43
    /** Delete operation by name */
44
    public void deleteOperation(String name);
45
    
46
    /** Delete operation callable */
47
    public UnaryCallable<DeleteOperationRequest, Empty> deleteOperationCallable();
48
    
49
    /** Wait for operation completion */
50
    public Operation waitOperation(WaitOperationRequest request); 
51
    
52
    /** Wait operation callable */
53
    public UnaryCallable<WaitOperationRequest, Operation> waitOperationCallable();
54
    
55
    /** Get client settings */
56
    public OperationsSettings getSettings();
57
    
58
    /** Get underlying stub */
59
    public OperationsStub getStub();
60
    
61
    /** Shutdown the client */
62
    public void shutdown();
63
    
64
    /** Check if terminated */
65
    public boolean isTerminated();
66
    
67
    /** Shutdown now */
68
    public void shutdownNow();
69
    
70
    /** Await termination */
71
    public boolean awaitTermination(long duration, TimeUnit unit) throws InterruptedException;
72
    
73
    /** Close the client */
74
    public void close();
75
}
76
```
77

78
### OperationsSettings
79

80
Configuration settings for OperationsClient with comprehensive call settings management.
81

82
```java { .api }
83
/**
84
 * Settings for configuring OperationsClient
85
 * Manages authentication, transport, and call-specific settings
86
 */
87
public class OperationsSettings {
88
    /** Create settings from stub settings */
89
    public static OperationsSettings create(OperationsStubSettings stub) throws IOException;
90
    
91
    /** Create new builder */
92
    public static Builder newBuilder();
93
    
94
    /** Create builder with client context */
95
    public static Builder newBuilder(ClientContext clientContext);
96
    
97
    /** Get operation call settings */
98
    public UnaryCallSettings<GetOperationRequest, Operation> getOperationSettings();
99
    
100
    /** Get list operations settings */
101
    public PagedCallSettings<ListOperationsRequest, ListOperationsResponse, ListOperationsPagedResponse> 
102
        listOperationsSettings();
103
    
104
    /** Get cancel operation settings */
105
    public UnaryCallSettings<CancelOperationRequest, Empty> cancelOperationSettings();
106
    
107
    /** Get delete operation settings */
108
    public UnaryCallSettings<DeleteOperationRequest, Empty> deleteOperationSettings();
109
    
110
    /** Get wait operation settings */
111
    public UnaryCallSettings<WaitOperationRequest, Operation> waitOperationSettings();
112
    
113
    /** Create builder from settings */
114
    public Builder toBuilder();
115
}
116
```
117

118
### Operations Settings Builder
119

120
Builder for configuring OperationsSettings with authentication, transport, and call settings.
121

122
```java { .api }
123
/**
124
 * Builder for OperationsSettings with comprehensive configuration
125
 */
126
public static class OperationsSettings.Builder {
127
    /** Set credentials provider */
128
    public Builder setCredentialsProvider(CredentialsProvider credentialsProvider);
129
    
130
    /** Set transport channel provider */
131
    public Builder setTransportChannelProvider(TransportChannelProvider transportChannelProvider);
132
    
133
    /** Set header provider */
134
    public Builder setHeaderProvider(HeaderProvider headerProvider);
135
    
136
    /** Set endpoint */
137
    public Builder setEndpoint(String endpoint);
138
    
139
    /** Set quota project ID */
140
    public Builder setQuotaProjectId(String quotaProjectId);
141
    
142
    /** Get operation settings builder */
143
    public UnaryCallSettings.Builder<GetOperationRequest, Operation> getOperationSettings();
144
    
145
    /** Get list operations settings builder */
146
    public PagedCallSettings.Builder<ListOperationsRequest, ListOperationsResponse, ListOperationsPagedResponse> 
147
        listOperationsSettings();
148
    
149
    /** Get cancel operation settings builder */
150
    public UnaryCallSettings.Builder<CancelOperationRequest, Empty> cancelOperationSettings();
151
    
152
    /** Get delete operation settings builder */
153
    public UnaryCallSettings.Builder<DeleteOperationRequest, Empty> deleteOperationSettings();
154
    
155
    /** Get wait operation settings builder */
156
    public UnaryCallSettings.Builder<WaitOperationRequest, Operation> waitOperationSettings();
157
    
158
    /** Build the settings */
159
    public OperationsSettings build() throws IOException;
160
}
161
```
162

163
### Operations Paged Responses
164

165
Paged response types for list operations with iteration support.
166

167
```java { .api }
168
/**
169
 * Paged response for list operations
170
 * Supports automatic pagination and iteration
171
 */
172
public static class OperationsClient.ListOperationsPagedResponse extends AbstractPagedListResponse<
173
    ListOperationsRequest, ListOperationsResponse, Operation, ListOperationsPage, 
174
    ListOperationsFixedSizeCollection> {
175
    
176
    /** Create paged response from context and response */
177
    public static ListOperationsPagedResponse createAsync(
178
        PageContext<ListOperationsRequest, ListOperationsResponse, Operation> context,
179
        ApiFuture<ListOperationsResponse> futureResponse);
180
    
181
    /** Get the underlying page */
182
    public ListOperationsPage getPage();
183
    
184
    /** Iterate over all operations across pages */
185
    public Iterable<Operation> iterateAll();
186
    
187
    /** Get expanded page iterator */
188
    public ApiFuture<ListOperationsPagedResponse> getNextPageAsync();
189
}
190

191
/**
192
 * Single page of operations list response
193
 */
194
public static class OperationsClient.ListOperationsPage extends AbstractPage<
195
    ListOperationsRequest, ListOperationsResponse, Operation, ListOperationsPage> {
196
    
197
    /** Get operations in this page */
198
    public Iterable<Operation> getValues();
199
    
200
    /** Check if has next page */
201
    public boolean hasNextPage();
202
    
203
    /** Get next page token */
204
    public String getNextPageToken();
205
    
206
    /** Get next page async */
207
    public ApiFuture<ListOperationsPage> getNextPageAsync();
208
}
209

210
/**
211
 * Fixed size collection of operations pages
212
 */
213
public static class OperationsClient.ListOperationsFixedSizeCollection extends AbstractFixedSizeCollection<
214
    ListOperationsRequest, ListOperationsResponse, Operation, ListOperationsPage,
215
    ListOperationsFixedSizeCollection> {
216
    
217
    /** Get operations across all pages */
218
    public Iterable<Operation> getValues();
219
    
220
    /** Get page iterator */
221
    public Iterator<ListOperationsPage> iterator();
222
}
223
```
224

225
## Operations Stub Layer
226

227
### OperationsStub
228

229
Base stub class for operations API with callable access.
230

231
```java { .api }
232
/**
233
 * Base stub class for Google Long Running Operations API
234
 * Provides low-level callable access
235
 */
236
public abstract class OperationsStub implements BackgroundResource {
237
    /** Get operation callable */
238
    public UnaryCallable<GetOperationRequest, Operation> getOperationCallable();
239
    
240
    /** List operations paged callable */
241
    public UnaryCallable<ListOperationsRequest, ListOperationsPagedResponse> listOperationsPagedCallable();
242
    
243
    /** List operations callable */
244
    public UnaryCallable<ListOperationsRequest, ListOperationsResponse> listOperationsCallable();
245
    
246
    /** Cancel operation callable */
247
    public UnaryCallable<CancelOperationRequest, Empty> cancelOperationCallable();
248
    
249
    /** Delete operation callable */
250
    public UnaryCallable<DeleteOperationRequest, Empty> deleteOperationCallable();
251
    
252
    /** Wait operation callable */
253
    public UnaryCallable<WaitOperationRequest, Operation> waitOperationCallable();
254
}
255
```
256

257
### GrpcOperationsStub
258

259
gRPC-specific implementation of OperationsStub with channel management.
260

261
```java { .api }
262
/**
263
 * gRPC-based implementation of OperationsStub
264
 * Manages gRPC channels and call configuration
265
 */
266
public class GrpcOperationsStub extends OperationsStub {
267
    /** Create stub with settings */
268
    public static GrpcOperationsStub create(OperationsStubSettings settings) throws IOException;
269
    
270
    /** Create stub with client context */
271
    public static GrpcOperationsStub create(ClientContext clientContext) throws IOException;
272
    
273
    /** Create stub with channel and settings */
274
    public static GrpcOperationsStub create(
275
        ClientContext clientContext, GrpcStubCallableFactory callableFactory) throws IOException;
276
}
277
```
278

279
### OperationsStubSettings
280

281
Configuration settings for operations stubs with callable settings management.
282

283
```java { .api }
284
/**
285
 * Settings for operations stubs
286
 * Configures transport, authentication, and callable behavior
287
 */
288
public class OperationsStubSettings extends StubSettings<OperationsStubSettings> {
289
    /** Create default settings */
290
    public static OperationsStubSettings newBuilder();
291
    
292
    /** Create builder with client context */
293
    public static OperationsStubSettings newBuilder(ClientContext clientContext);
294
    
295
    /** Get operation call settings */
296
    public UnaryCallSettings<GetOperationRequest, Operation> getOperationSettings();
297
    
298
    /** Get list operations settings */
299
    public PagedCallSettings<ListOperationsRequest, ListOperationsResponse, ListOperationsPagedResponse>
300
        listOperationsSettings();
301
    
302
    /** Get cancel operation settings */
303
    public UnaryCallSettings<CancelOperationRequest, Empty> cancelOperationSettings();
304
    
305
    /** Get delete operation settings */
306
    public UnaryCallSettings<DeleteOperationRequest, Empty> deleteOperationSettings();
307
    
308
    /** Get wait operation settings */
309
    public UnaryCallSettings<WaitOperationRequest, Operation> waitOperationSettings();
310
    
311
    /** Create builder from settings */
312
    public Builder toBuilder();
313
}
314
```
315

316
## Usage Examples
317

318
### Basic Operations Client Setup
319

320
```java
321
import com.google.longrunning.OperationsClient;
322
import com.google.longrunning.OperationsSettings;
323
import com.google.auth.oauth2.GoogleCredentials;
324

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

328
// Create with custom settings
329
OperationsSettings settings = OperationsSettings.newBuilder()
330
    .setCredentialsProvider(FixedCredentialsProvider.create(
331
        GoogleCredentials.getApplicationDefault()))
332
    .setEndpoint("your-service.googleapis.com:443")
333
    .build();
334

335
OperationsClient customClient = OperationsClient.create(settings);
336
```
337

338
### Getting and Monitoring Operations
339

340
```java
341
import com.google.longrunning.Operation;
342
import java.util.concurrent.TimeUnit;
343

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

347
// Check operation status
348
if (operation.getDone()) {
349
    if (operation.hasError()) {
350
        System.err.println("Operation failed: " + operation.getError().getMessage());
351
    } else {
352
        System.out.println("Operation completed successfully");
353
        // operation.getResponse() contains the result
354
    }
355
} else {
356
    System.out.println("Operation still in progress: " + operation.getName());
357
    // operation.getMetadata() contains progress information
358
}
359

360
// Poll operation until completion
361
while (!operation.getDone()) {
362
    TimeUnit.SECONDS.sleep(5);
363
    operation = operationsClient.getOperation(operation.getName());
364
    System.out.println("Operation progress: " + operation.getMetadata());
365
}
366
```
367

368
### Listing Operations
369

370
```java
371
import com.google.longrunning.Operation;
372

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

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

385
// Manual pagination
386
ListOperationsPagedResponse response = operationsClient.listOperations("operations", "");
387
for (ListOperationsPage page : response.iteratePages()) {
388
    for (Operation operation : page.getValues()) {
389
        System.out.println("Operation: " + operation.getName());
390
    }
391
}
392
```
393

394
### Operation Management
395

396
```java
397
// Cancel a running operation
398
operationsClient.cancelOperation("operations/my-operation-123");
399

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

403
// Wait for operation with timeout
404
WaitOperationRequest waitRequest = WaitOperationRequest.newBuilder()
405
    .setName("operations/my-operation-123")
406
    .setTimeout(com.google.protobuf.Duration.newBuilder()
407
        .setSeconds(300) // 5 minutes
408
        .build())
409
    .build();
410

411
Operation result = operationsClient.waitOperation(waitRequest);
412
```
413

414
### Custom Operations Settings
415

416
```java
417
import com.google.api.gax.retrying.RetrySettings;
418
import java.time.Duration;
419

420
// Configure retry settings for operations
421
RetrySettings retrySettings = RetrySettings.newBuilder()
422
    .setInitialRetryDelay(Duration.ofMillis(100))
423
    .setRetryDelayMultiplier(1.3)
424
    .setMaxRetryDelay(Duration.ofMinutes(1))
425
    .setInitialRpcTimeout(Duration.ofSeconds(30))
426
    .setRpcTimeoutMultiplier(1.0)
427
    .setMaxRpcTimeout(Duration.ofSeconds(30))
428
    .setTotalTimeout(Duration.ofMinutes(10))
429
    .build();
430

431
OperationsSettings settings = OperationsSettings.newBuilder()
432
    .getOperationSettings()
433
    .setRetrySettings(retrySettings)
434
    .getParent()
435
    .build();
436

437
OperationsClient client = OperationsClient.create(settings);
438
```
439

440
### Using Operations with Custom Endpoints
441

442
```java
443
import com.google.api.gax.rpc.FixedTransportChannelProvider;
444
import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
445

446
// Configure for custom endpoint
447
InstantiatingGrpcChannelProvider channelProvider = 
448
    InstantiatingGrpcChannelProvider.newBuilder()
449
        .setEndpoint("custom-operations-service.com:443")
450
        .build();
451

452
OperationsSettings settings = OperationsSettings.newBuilder()
453
    .setTransportChannelProvider(channelProvider)
454
    .build();
455

456
OperationsClient client = OperationsClient.create(settings);
457
```