0
# WorkflowClient and Service Interaction
1

2
Complete client APIs for workflow lifecycle management, including starting workflows, sending signals, executing queries and updates, and batch operations.
3

4
## Capabilities
5

6
### Workflow Client
7

8
Primary client interface for starting and managing workflows, creating activity completion clients, and interacting with the Temporal service.
9

10
```java { .api }
11
/**
12
 * Primary client interface for starting and managing workflows, creating activity completion clients, and interacting with the Temporal service.
13
 */
14
public interface WorkflowClient {
15
    // Query type constants
16
    String QUERY_TYPE_STACK_TRACE = "__stack_trace";
17
    String QUERY_TYPE_WORKFLOW_METADATA = "__temporal_workflow_metadata";
18
    String QUERY_TYPE_REPLAY_ONLY = "__replay_only";
19

20
    /**
21
     * Creates client with default options.
22
     * @param service workflow service stubs
23
     * @return workflow client instance
24
     */
25
    static WorkflowClient newInstance(WorkflowServiceStubs service);
26

27
    /**
28
     * Creates client with custom options.
29
     * @param service workflow service stubs
30
     * @param options client options
31
     * @return workflow client instance
32
     */
33
    static WorkflowClient newInstance(WorkflowServiceStubs service, WorkflowClientOptions options);
34

35
    /**
36
     * Returns client options.
37
     * @return workflow client options
38
     */
39
    WorkflowClientOptions getOptions();
40

41
    /**
42
     * Returns service stubs.
43
     * @return workflow service stubs
44
     */
45
    WorkflowServiceStubs getWorkflowServiceStubs();
46

47
    /**
48
     * Creates typed stub for new workflow.
49
     * @param workflowInterface workflow interface class
50
     * @param options workflow options
51
     * @return typed workflow stub
52
     */
53
    <T> T newWorkflowStub(Class<T> workflowInterface, WorkflowOptions options);
54

55
    /**
56
     * Creates typed stub for existing workflow.
57
     * @param workflowInterface workflow interface class
58
     * @param workflowId existing workflow ID
59
     * @return typed workflow stub
60
     */
61
    <T> T newWorkflowStub(Class<T> workflowInterface, String workflowId);
62

63
    /**
64
     * Creates typed stub with run ID.
65
     * @param workflowInterface workflow interface class
66
     * @param workflowId workflow ID
67
     * @param runId optional run ID
68
     * @return typed workflow stub
69
     */
70
    <T> T newWorkflowStub(Class<T> workflowInterface, String workflowId, Optional<String> runId);
71

72
    /**
73
     * Creates untyped stub for existing workflow.
74
     * @param workflowId workflow ID
75
     * @return untyped workflow stub
76
     */
77
    WorkflowStub newUntypedWorkflowStub(String workflowId);
78

79
    /**
80
     * Creates untyped stub for new workflow.
81
     * @param workflowType workflow type name
82
     * @param options workflow options
83
     * @return untyped workflow stub
84
     */
85
    WorkflowStub newUntypedWorkflowStub(String workflowType, WorkflowOptions options);
86

87
    /**
88
     * Creates untyped stub with optional run ID.
89
     * @param workflowId workflow ID
90
     * @param runId optional run ID
91
     * @param workflowType optional workflow type
92
     * @return untyped workflow stub
93
     */
94
    WorkflowStub newUntypedWorkflowStub(String workflowId, Optional<String> runId, Optional<String> workflowType);
95

96
    /**
97
     * Creates untyped stub from execution.
98
     * @param execution workflow execution
99
     * @param workflowType optional workflow type
100
     * @return untyped workflow stub
101
     */
102
    WorkflowStub newUntypedWorkflowStub(WorkflowExecution execution, Optional<String> workflowType);
103

104
    /**
105
     * Creates client for async activity completion.
106
     * @return activity completion client
107
     */
108
    ActivityCompletionClient newActivityCompletionClient();
109

110
    /**
111
     * Creates batch request for signal-with-start.
112
     * @return batch request builder
113
     */
114
    BatchRequest newSignalWithStartRequest();
115

116
    /**
117
     * Executes signal-with-start batch.
118
     * @param signalWithStartBatch batch request
119
     * @return workflow execution
120
     */
121
    WorkflowExecution signalWithStart(BatchRequest signalWithStartBatch);
122

123
    /**
124
     * Lists workflow executions with visibility query.
125
     * @param query visibility query
126
     * @return iterable of workflow executions
127
     */
128
    Iterable<WorkflowExecution> listExecutions(String query);
129

130
    /**
131
     * Counts workflow executions.
132
     * @param query visibility query
133
     * @return count result
134
     */
135
    CountWorkflowExecutionsResponse countWorkflows(String query);
136

137
    /**
138
     * Streams history events.
139
     * @param workflowId workflow ID
140
     * @return iterator of history events
141
     */
142
    Iterator<HistoryEvent> streamHistory(String workflowId);
143

144
    /**
145
     * Streams history for specific run.
146
     * @param workflowId workflow ID
147
     * @param runId run ID
148
     * @return iterator of history events
149
     */
150
    Iterator<HistoryEvent> streamHistory(String workflowId, String runId);
151

152
    /**
153
     * Downloads complete history.
154
     * @param workflowId workflow ID
155
     * @return workflow execution history
156
     */
157
    WorkflowExecutionHistory fetchHistory(String workflowId);
158

159
    /**
160
     * Downloads history for specific run.
161
     * @param workflowId workflow ID
162
     * @param runId run ID
163
     * @return workflow execution history
164
     */
165
    WorkflowExecutionHistory fetchHistory(String workflowId, String runId);
166

167
    /**
168
     * Updates worker build ID compatibility (Experimental).
169
     * @param taskQueue task queue name
170
     * @param operation build ID operation
171
     * @return update response
172
     */
173
    @Experimental
174
    UpdateWorkerBuildIdCompatabilityResponse updateWorkerBuildIdCompatability(String taskQueue, BuildIdOperation operation);
175

176
    /**
177
     * Gets worker build ID version sets (Experimental).
178
     * @param taskQueue task queue name
179
     * @return compatibility response
180
     */
181
    @Experimental
182
    GetWorkerBuildIdCompatabilityResponse getWorkerBuildIdCompatability(String taskQueue);
183

184
    /**
185
     * Checks task reachability (Experimental).
186
     * @param buildIds build IDs to check
187
     * @param taskQueues task queues to check
188
     * @param reachability reachability type
189
     * @return reachability response
190
     */
191
    @Experimental
192
    GetWorkerTaskReachabilityResponse getWorkerTaskReachability(Iterable<String> buildIds, Iterable<String> taskQueues, TaskReachability reachability);
193

194
    // Static workflow execution methods
195

196
    /**
197
     * Start zero argument void workflow.
198
     * @param workflow workflow function
199
     * @return workflow execution
200
     */
201
    static WorkflowExecution start(Proc workflow);
202

203
    /**
204
     * Start one argument void workflow.
205
     * @param workflow workflow function
206
     * @param arg1 workflow argument
207
     * @return workflow execution
208
     */
209
    static <A1> WorkflowExecution start(Proc1<A1> workflow, A1 arg1);
210

211
    /**
212
     * Start two argument void workflow.
213
     * @param workflow workflow function
214
     * @param arg1 first workflow argument
215
     * @param arg2 second workflow argument
216
     * @return workflow execution
217
     */
218
    static <A1, A2> WorkflowExecution start(Proc2<A1, A2> workflow, A1 arg1, A2 arg2);
219

220
    /**
221
     * Start three argument void workflow.
222
     * @param workflow workflow function
223
     * @param arg1 first workflow argument
224
     * @param arg2 second workflow argument
225
     * @param arg3 third workflow argument
226
     * @return workflow execution
227
     */
228
    static <A1, A2, A3> WorkflowExecution start(Proc3<A1, A2, A3> workflow, A1 arg1, A2 arg2, A3 arg3);
229

230
    /**
231
     * Start four argument void workflow.
232
     * @param workflow workflow function
233
     * @param arg1 first workflow argument
234
     * @param arg2 second workflow argument
235
     * @param arg3 third workflow argument
236
     * @param arg4 fourth workflow argument
237
     * @return workflow execution
238
     */
239
    static <A1, A2, A3, A4> WorkflowExecution start(Proc4<A1, A2, A3, A4> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4);
240

241
    /**
242
     * Start five argument void workflow.
243
     * @param workflow workflow function
244
     * @param arg1 first workflow argument
245
     * @param arg2 second workflow argument
246
     * @param arg3 third workflow argument
247
     * @param arg4 fourth workflow argument
248
     * @param arg5 fifth workflow argument
249
     * @return workflow execution
250
     */
251
    static <A1, A2, A3, A4, A5> WorkflowExecution start(Proc5<A1, A2, A3, A4, A5> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5);
252

253
    /**
254
     * Start six argument void workflow.
255
     * @param workflow workflow function
256
     * @param arg1 first workflow argument
257
     * @param arg2 second workflow argument
258
     * @param arg3 third workflow argument
259
     * @param arg4 fourth workflow argument
260
     * @param arg5 fifth workflow argument
261
     * @param arg6 sixth workflow argument
262
     * @return workflow execution
263
     */
264
    static <A1, A2, A3, A4, A5, A6> WorkflowExecution start(Proc6<A1, A2, A3, A4, A5, A6> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5, A6 arg6);
265

266
    /**
267
     * Start zero argument returning workflow.
268
     * @param workflow workflow function
269
     * @return workflow execution
270
     */
271
    static <R> WorkflowExecution start(Func<R> workflow);
272

273
    /**
274
     * Start one argument returning workflow.
275
     * @param workflow workflow function
276
     * @param arg1 workflow argument
277
     * @return workflow execution
278
     */
279
    static <A1, R> WorkflowExecution start(Func1<A1, R> workflow, A1 arg1);
280

281
    /**
282
     * Start two argument returning workflow.
283
     * @param workflow workflow function
284
     * @param arg1 first workflow argument
285
     * @param arg2 second workflow argument
286
     * @return workflow execution
287
     */
288
    static <A1, A2, R> WorkflowExecution start(Func2<A1, A2, R> workflow, A1 arg1, A2 arg2);
289

290
    /**
291
     * Start three argument returning workflow.
292
     * @param workflow workflow function
293
     * @param arg1 first workflow argument
294
     * @param arg2 second workflow argument
295
     * @param arg3 third workflow argument
296
     * @return workflow execution
297
     */
298
    static <A1, A2, A3, R> WorkflowExecution start(Func3<A1, A2, A3, R> workflow, A1 arg1, A2 arg2, A3 arg3);
299

300
    /**
301
     * Start four argument returning workflow.
302
     * @param workflow workflow function
303
     * @param arg1 first workflow argument
304
     * @param arg2 second workflow argument
305
     * @param arg3 third workflow argument
306
     * @param arg4 fourth workflow argument
307
     * @return workflow execution
308
     */
309
    static <A1, A2, A3, A4, R> WorkflowExecution start(Func4<A1, A2, A3, A4, R> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4);
310

311
    /**
312
     * Start five argument returning workflow.
313
     * @param workflow workflow function
314
     * @param arg1 first workflow argument
315
     * @param arg2 second workflow argument
316
     * @param arg3 third workflow argument
317
     * @param arg4 fourth workflow argument
318
     * @param arg5 fifth workflow argument
319
     * @return workflow execution
320
     */
321
    static <A1, A2, A3, A4, A5, R> WorkflowExecution start(Func5<A1, A2, A3, A4, A5, R> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5);
322

323
    /**
324
     * Start six argument returning workflow.
325
     * @param workflow workflow function
326
     * @param arg1 first workflow argument
327
     * @param arg2 second workflow argument
328
     * @param arg3 third workflow argument
329
     * @param arg4 fourth workflow argument
330
     * @param arg5 fifth workflow argument
331
     * @param arg6 sixth workflow argument
332
     * @return workflow execution
333
     */
334
    static <A1, A2, A3, A4, A5, A6, R> WorkflowExecution start(Func6<A1, A2, A3, A4, A5, A6, R> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5, A6 arg6);
335

336
    // Execute methods that return CompletableFuture
337

338
    /**
339
     * Execute zero argument void workflow.
340
     * @param workflow workflow function
341
     * @return completable future
342
     */
343
    static CompletableFuture<Void> execute(Proc workflow);
344

345
    /**
346
     * Execute one argument void workflow.
347
     * @param workflow workflow function
348
     * @param arg1 workflow argument
349
     * @return completable future
350
     */
351
    static <A1> CompletableFuture<Void> execute(Proc1<A1> workflow, A1 arg1);
352

353
    /**
354
     * Execute two argument void workflow.
355
     * @param workflow workflow function
356
     * @param arg1 first workflow argument
357
     * @param arg2 second workflow argument
358
     * @return completable future
359
     */
360
    static <A1, A2> CompletableFuture<Void> execute(Proc2<A1, A2> workflow, A1 arg1, A2 arg2);
361

362
    /**
363
     * Execute three argument void workflow.
364
     * @param workflow workflow function
365
     * @param arg1 first workflow argument
366
     * @param arg2 second workflow argument
367
     * @param arg3 third workflow argument
368
     * @return completable future
369
     */
370
    static <A1, A2, A3> CompletableFuture<Void> execute(Proc3<A1, A2, A3> workflow, A1 arg1, A2 arg2, A3 arg3);
371

372
    /**
373
     * Execute four argument void workflow.
374
     * @param workflow workflow function
375
     * @param arg1 first workflow argument
376
     * @param arg2 second workflow argument
377
     * @param arg3 third workflow argument
378
     * @param arg4 fourth workflow argument
379
     * @return completable future
380
     */
381
    static <A1, A2, A3, A4> CompletableFuture<Void> execute(Proc4<A1, A2, A3, A4> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4);
382

383
    /**
384
     * Execute five argument void workflow.
385
     * @param workflow workflow function
386
     * @param arg1 first workflow argument
387
     * @param arg2 second workflow argument
388
     * @param arg3 third workflow argument
389
     * @param arg4 fourth workflow argument
390
     * @param arg5 fifth workflow argument
391
     * @return completable future
392
     */
393
    static <A1, A2, A3, A4, A5> CompletableFuture<Void> execute(Proc5<A1, A2, A3, A4, A5> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5);
394

395
    /**
396
     * Execute six argument void workflow.
397
     * @param workflow workflow function
398
     * @param arg1 first workflow argument
399
     * @param arg2 second workflow argument
400
     * @param arg3 third workflow argument
401
     * @param arg4 fourth workflow argument
402
     * @param arg5 fifth workflow argument
403
     * @param arg6 sixth workflow argument
404
     * @return completable future
405
     */
406
    static <A1, A2, A3, A4, A5, A6> CompletableFuture<Void> execute(Proc6<A1, A2, A3, A4, A5, A6> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5, A6 arg6);
407

408
    /**
409
     * Execute zero argument returning workflow.
410
     * @param workflow workflow function
411
     * @return completable future with result
412
     */
413
    static <R> CompletableFuture<R> execute(Func<R> workflow);
414

415
    /**
416
     * Execute one argument returning workflow.
417
     * @param workflow workflow function
418
     * @param arg1 workflow argument
419
     * @return completable future with result
420
     */
421
    static <A1, R> CompletableFuture<R> execute(Func1<A1, R> workflow, A1 arg1);
422

423
    /**
424
     * Execute two argument returning workflow.
425
     * @param workflow workflow function
426
     * @param arg1 first workflow argument
427
     * @param arg2 second workflow argument
428
     * @return completable future with result
429
     */
430
    static <A1, A2, R> CompletableFuture<R> execute(Func2<A1, A2, R> workflow, A1 arg1, A2 arg2);
431

432
    /**
433
     * Execute three argument returning workflow.
434
     * @param workflow workflow function
435
     * @param arg1 first workflow argument
436
     * @param arg2 second workflow argument
437
     * @param arg3 third workflow argument
438
     * @return completable future with result
439
     */
440
    static <A1, A2, A3, R> CompletableFuture<R> execute(Func3<A1, A2, A3, R> workflow, A1 arg1, A2 arg2, A3 arg3);
441

442
    /**
443
     * Execute four argument returning workflow.
444
     * @param workflow workflow function
445
     * @param arg1 first workflow argument
446
     * @param arg2 second workflow argument
447
     * @param arg3 third workflow argument
448
     * @param arg4 fourth workflow argument
449
     * @return completable future with result
450
     */
451
    static <A1, A2, A3, A4, R> CompletableFuture<R> execute(Func4<A1, A2, A3, A4, R> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4);
452

453
    /**
454
     * Execute five argument returning workflow.
455
     * @param workflow workflow function
456
     * @param arg1 first workflow argument
457
     * @param arg2 second workflow argument
458
     * @param arg3 third workflow argument
459
     * @param arg4 fourth workflow argument
460
     * @param arg5 fifth workflow argument
461
     * @return completable future with result
462
     */
463
    static <A1, A2, A3, A4, A5, R> CompletableFuture<R> execute(Func5<A1, A2, A3, A4, A5, R> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5);
464

465
    /**
466
     * Execute six argument returning workflow.
467
     * @param workflow workflow function
468
     * @param arg1 first workflow argument
469
     * @param arg2 second workflow argument
470
     * @param arg3 third workflow argument
471
     * @param arg4 fourth workflow argument
472
     * @param arg5 fifth workflow argument
473
     * @param arg6 sixth workflow argument
474
     * @return completable future with result
475
     */
476
    static <A1, A2, A3, A4, A5, A6, R> CompletableFuture<R> execute(Func6<A1, A2, A3, A4, A5, A6, R> workflow, A1 arg1, A2 arg2, A3 arg3, A4 arg4, A5 arg5, A6 arg6);
477
}
478
```
479

480
**Usage Examples:**
481

482
```java
483
public class WorkflowClientExample {
484
    public static void main(String[] args) {
485
        // Create client
486
        WorkflowServiceStubs service = WorkflowServiceStubs.newLocalServiceStubs();
487
        WorkflowClient client = WorkflowClient.newInstance(service);
488

489
        // Create typed workflow stub
490
        OrderWorkflow workflow = client.newWorkflowStub(
491
            OrderWorkflow.class,
492
            WorkflowOptions.newBuilder()
493
                .setWorkflowId("order-123")
494
                .setTaskQueue("order-processing")
495
                .setWorkflowExecutionTimeout(Duration.ofHours(1))
496
                .build()
497
        );
498

499
        // Start workflow asynchronously
500
        WorkflowExecution execution = WorkflowClient.start(workflow::processOrder, orderRequest);
501

502
        // Execute workflow synchronously
503
        CompletableFuture<OrderResult> future = WorkflowClient.execute(workflow::processOrder, orderRequest);
504
        OrderResult result = future.get();
505

506
        // Connect to existing workflow
507
        OrderWorkflow existingWorkflow = client.newWorkflowStub(OrderWorkflow.class, "order-123");
508
        OrderStatus status = existingWorkflow.getStatus();
509

510
        // Send signal
511
        existingWorkflow.updateShipping(newShippingInfo);
512

513
        // List workflows
514
        Iterable<WorkflowExecution> executions = client.listExecutions("WorkflowType='OrderWorkflow'");
515
        for (WorkflowExecution exec : executions) {
516
            System.out.println("Found workflow: " + exec.getWorkflowId());
517
        }
518
    }
519
}
520
```
521

522
### Workflow Stub
523

524
Untyped client stub for workflow instances, supporting workflow lifecycle operations.
525

526
```java { .api }
527
/**
528
 * Untyped client stub for workflow instances, supporting workflow lifecycle operations.
529
 */
530
public interface WorkflowStub {
531
    /**
532
     * Extracts untyped stub from typed workflow stub.
533
     * @param typed typed workflow stub
534
     * @return untyped workflow stub
535
     */
536
    static WorkflowStub fromTyped(Object typed);
537

538
    /**
539
     * Starts workflow execution.
540
     * @param args workflow arguments
541
     * @return workflow execution
542
     */
543
    WorkflowExecution start(Object... args);
544

545
    /**
546
     * Gets workflow result (blocking).
547
     * @param resultClass result class
548
     * @return workflow result
549
     */
550
    <R> R getResult(Class<R> resultClass);
551

552
    /**
553
     * Type-safe version with generics.
554
     * @param resultClass result class
555
     * @param resultType generic type information
556
     * @return workflow result
557
     */
558
    <R> R getResult(Class<R> resultClass, Type resultType);
559

560
    /**
561
     * Gets workflow result with timeout.
562
     * @param timeout timeout value
563
     * @param unit timeout unit
564
     * @param resultClass result class
565
     * @return workflow result
566
     */
567
    <R> R getResult(long timeout, TimeUnit unit, Class<R> resultClass);
568

569
    /**
570
     * Gets workflow result with timeout and generics.
571
     * @param timeout timeout value
572
     * @param unit timeout unit
573
     * @param resultClass result class
574
     * @param resultType generic type information
575
     * @return workflow result
576
     */
577
    <R> R getResult(long timeout, TimeUnit unit, Class<R> resultClass, Type resultType);
578

579
    /**
580
     * Returns CompletableFuture for workflow result.
581
     * @param resultClass result class
582
     * @return completable future with result
583
     */
584
    <R> CompletableFuture<R> getResultAsync(Class<R> resultClass);
585

586
    /**
587
     * Async with generics.
588
     * @param resultClass result class
589
     * @param resultType generic type information
590
     * @return completable future with result
591
     */
592
    <R> CompletableFuture<R> getResultAsync(Class<R> resultClass, Type resultType);
593

594
    /**
595
     * Async with timeout.
596
     * @param timeout timeout value
597
     * @param unit timeout unit
598
     * @param resultClass result class
599
     * @return completable future with result
600
     */
601
    <R> CompletableFuture<R> getResultAsync(long timeout, TimeUnit unit, Class<R> resultClass);
602

603
    /**
604
     * Async with timeout and generics.
605
     * @param timeout timeout value
606
     * @param unit timeout unit
607
     * @param resultClass result class
608
     * @param resultType generic type information
609
     * @return completable future with result
610
     */
611
    <R> CompletableFuture<R> getResultAsync(long timeout, TimeUnit unit, Class<R> resultClass, Type resultType);
612

613
    /**
614
     * Sends signal to workflow.
615
     * @param signalName signal name
616
     * @param args signal arguments
617
     */
618
    void signal(String signalName, Object... args);
619

620
    /**
621
     * Queries workflow.
622
     * @param queryType query type
623
     * @param resultClass result class
624
     * @param args query arguments
625
     * @return query result
626
     */
627
    <R> R query(String queryType, Class<R> resultClass, Object... args);
628

629
    /**
630
     * Type-safe query.
631
     * @param queryType query type
632
     * @param resultClass result class
633
     * @param resultType generic type information
634
     * @param args query arguments
635
     * @return query result
636
     */
637
    <R> R query(String queryType, Class<R> resultClass, Type resultType, Object... args);
638

639
    /**
640
     * Synchronous update.
641
     * @param updateName update name
642
     * @param resultClass result class
643
     * @param args update arguments
644
     * @return update result
645
     */
646
    <R> R update(String updateName, Class<R> resultClass, Object... args);
647

648
    /**
649
     * Async update.
650
     * @param updateName update name
651
     * @param waitForStage wait stage
652
     * @param resultClass result class
653
     * @param args update arguments
654
     * @return update handle
655
     */
656
    <R> WorkflowUpdateHandle<R> startUpdate(String updateName, WorkflowUpdateStage waitForStage, Class<R> resultClass, Object... args);
657

658
    /**
659
     * Async update with options.
660
     * @param options update options
661
     * @param args update arguments
662
     * @return update handle
663
     */
664
    <R> WorkflowUpdateHandle<R> startUpdate(UpdateOptions<R> options, Object... args);
665

666
    /**
667
     * Get handle to existing update.
668
     * @param updateId update ID
669
     * @param resultClass result class
670
     * @return update handle
671
     */
672
    <R> WorkflowUpdateHandle<R> getUpdateHandle(String updateId, Class<R> resultClass);
673

674
    /**
675
     * Type-safe version.
676
     * @param updateId update ID
677
     * @param resultClass result class
678
     * @param resultType generic type information
679
     * @return update handle
680
     */
681
    <R> WorkflowUpdateHandle<R> getUpdateHandle(String updateId, Class<R> resultClass, Type resultType);
682

683
    /**
684
     * Update with start.
685
     * @param updateOptions update options
686
     * @param updateArgs update arguments
687
     * @param startArgs start arguments
688
     * @return update handle
689
     */
690
    <R> WorkflowUpdateHandle<R> startUpdateWithStart(UpdateOptions<R> updateOptions, Object[] updateArgs, Object[] startArgs);
691

692
    /**
693
     * Sync update with start.
694
     * @param updateOptions update options
695
     * @param updateArgs update arguments
696
     * @param startArgs start arguments
697
     * @return update result
698
     */
699
    <R> R executeUpdateWithStart(UpdateOptions<R> updateOptions, Object[] updateArgs, Object[] startArgs);
700

701
    /**
702
     * Signal with start.
703
     * @param signalName signal name
704
     * @param signalArgs signal arguments
705
     * @param startArgs start arguments
706
     * @return workflow execution
707
     */
708
    WorkflowExecution signalWithStart(String signalName, Object[] signalArgs, Object[] startArgs);
709

710
    /**
711
     * Requests workflow cancellation.
712
     */
713
    void cancel();
714

715
    /**
716
     * Cancellation with reason.
717
     * @param reason cancellation reason
718
     */
719
    void cancel(String reason);
720

721
    /**
722
     * Terminates workflow execution.
723
     * @param reason termination reason
724
     * @param details termination details
725
     */
726
    void terminate(String reason, Object... details);
727

728
    /**
729
     * Gets workflow execution description.
730
     * @return workflow description
731
     */
732
    WorkflowExecutionMetadata describe();
733

734
    /**
735
     * Returns workflow type name.
736
     * @return workflow type
737
     */
738
    Optional<String> getWorkflowType();
739

740
    /**
741
     * Gets workflow execution info.
742
     * @return workflow execution
743
     */
744
    WorkflowExecution getExecution();
745

746
    /**
747
     * Gets workflow options.
748
     * @return workflow options
749
     */
750
    WorkflowOptions getOptions();
751

752
    /**
753
     * Creates new stub instance with different options.
754
     * @param options new workflow options
755
     * @return new workflow stub instance
756
     */
757
    WorkflowStub newInstance(WorkflowOptions options);
758
}
759
```
760

761
**Usage Examples:**
762

763
```java
764
public class WorkflowStubExample {
765
    public void demonstrateWorkflowStub() {
766
        WorkflowClient client = WorkflowClient.newInstance(service);
767

768
        // Create untyped stub
769
        WorkflowStub stub = client.newUntypedWorkflowStub(
770
            "OrderWorkflow",
771
            WorkflowOptions.newBuilder()
772
                .setWorkflowId("order-456")
773
                .setTaskQueue("orders")
774
                .build()
775
        );
776

777
        // Start workflow
778
        OrderRequest request = new OrderRequest("customer-123", items);
779
        WorkflowExecution execution = stub.start(request);
780

781
        // Send signal
782
        stub.signal("addItem", new OrderItem("item-789", 1));
783

784
        // Query workflow
785
        OrderStatus status = stub.query("getStatus", OrderStatus.class);
786

787
        // Update workflow
788
        Address newAddress = new Address("123 Main St", "Seattle", "WA");
789
        stub.update("updateShippingAddress", Void.class, newAddress);
790

791
        // Get result asynchronously
792
        CompletableFuture<OrderResult> future = stub.getResultAsync(OrderResult.class);
793
        future.thenAccept(result -> {
794
            System.out.println("Order completed: " + result.getOrderId());
795
        });
796

797
        // Cancel if needed
798
        if (shouldCancel) {
799
            stub.cancel("Customer requested cancellation");
800
        }
801
    }
802
}
803
```
804

805
### Activity Completion Client
806

807
Client for completing activities asynchronously outside the activity execution context.
808

809
```java { .api }
810
/**
811
 * Client for completing activities asynchronously outside the activity execution context.
812
 */
813
public interface ActivityCompletionClient {
814
    /**
815
     * Completes activity successfully by task token.
816
     * @param taskToken activity task token
817
     * @param result activity result
818
     */
819
    <R> void complete(byte[] taskToken, R result);
820

821
    /**
822
     * Completes with failure by task token.
823
     * @param taskToken activity task token
824
     * @param result failure exception
825
     */
826
    void completeExceptionally(byte[] taskToken, Exception result);
827

828
    /**
829
     * Reports successful cancellation by task token.
830
     * @param taskToken activity task token
831
     * @param details cancellation details
832
     */
833
    <V> void reportCancellation(byte[] taskToken, V details);
834

835
    /**
836
     * Records heartbeat by task token.
837
     * @param taskToken activity task token
838
     * @param details heartbeat details
839
     */
840
    <V> void heartbeat(byte[] taskToken, V details);
841

842
    /**
843
     * Complete by workflow and activity IDs.
844
     * @param workflowId workflow ID
845
     * @param runId optional run ID
846
     * @param activityId activity ID
847
     * @param result activity result
848
     */
849
    <R> void complete(String workflowId, Optional<String> runId, String activityId, R result);
850

851
    /**
852
     * Fail by workflow and activity IDs.
853
     * @param workflowId workflow ID
854
     * @param runId optional run ID
855
     * @param activityId activity ID
856
     * @param result failure exception
857
     */
858
    void completeExceptionally(String workflowId, Optional<String> runId, String activityId, Exception result);
859

860
    /**
861
     * Cancel by workflow and activity IDs.
862
     * @param workflowId workflow ID
863
     * @param runId optional run ID
864
     * @param activityId activity ID
865
     * @param details cancellation details
866
     */
867
    <V> void reportCancellation(String workflowId, Optional<String> runId, String activityId, V details);
868

869
    /**
870
     * Heartbeat by workflow and activity IDs.
871
     * @param workflowId workflow ID
872
     * @param runId optional run ID
873
     * @param activityId activity ID
874
     * @param details heartbeat details
875
     */
876
    <V> void heartbeat(String workflowId, Optional<String> runId, String activityId, V details);
877

878
    /**
879
     * Context-aware client (Experimental).
880
     * @param context serialization context
881
     * @return context-aware activity completion client
882
     */
883
    @Experimental
884
    ActivityCompletionClient withContext(ActivitySerializationContext context);
885
}
886
```
887

888
**Usage Examples:**
889

890
```java
891
public class AsyncActivityExample {
892
    private final ActivityCompletionClient completionClient;
893

894
    public AsyncActivityExample(WorkflowClient client) {
895
        this.completionClient = client.newActivityCompletionClient();
896
    }
897

898
    // In activity implementation
899
    @Override
900
    public void startLongRunningProcess(String processId) {
901
        ActivityExecutionContext context = Activity.getExecutionContext();
902
        byte[] taskToken = context.getTaskToken();
903
        context.doNotCompleteOnReturn();
904

905
        // Start async process
906
        CompletableFuture.runAsync(() -> {
907
            try {
908
                String result = performLongRunningOperation(processId);
909
                completionClient.complete(taskToken, result);
910
            } catch (Exception e) {
911
                completionClient.completeExceptionally(taskToken, e);
912
            }
913
        });
914
    }
915

916
    // External completion by IDs
917
    public void completeExternalActivity(String workflowId, String activityId, String result) {
918
        completionClient.complete(workflowId, Optional.empty(), activityId, result);
919
    }
920

921
    // Heartbeat from external service
922
    public void sendActivityHeartbeat(String workflowId, String activityId, ProgressInfo progress) {
923
        completionClient.heartbeat(workflowId, Optional.empty(), activityId, progress);
924
    }
925
}
926
```
927

928
### Workflow Options
929

930
Configuration options for workflow execution.
931

932
```java { .api }
933
/**
934
 * Configuration options for workflow execution.
935
 */
936
public final class WorkflowOptions {
937
    /**
938
     * Creates new builder.
939
     * @return new WorkflowOptions builder
940
     */
941
    public static Builder newBuilder();
942

943
    /**
944
     * Creates builder from existing options.
945
     * @param options existing options to copy
946
     * @return new builder with copied options
947
     */
948
    public static Builder newBuilder(WorkflowOptions options);
949

950
    /**
951
     * Returns default instance.
952
     * @return default WorkflowOptions
953
     */
954
    public static WorkflowOptions getDefaultInstance();
955

956
    /**
957
     * Merges annotation and options.
958
     * @param methodRetry method retry annotation
959
     * @param cronSchedule cron schedule annotation
960
     * @param options workflow options
961
     * @return merged workflow options
962
     */
963
    public static WorkflowOptions merge(MethodRetry methodRetry, CronSchedule cronSchedule, WorkflowOptions options);
964

965
    /**
966
     * Builder for WorkflowOptions.
967
     */
968
    public static final class Builder {
969
        /**
970
         * Sets workflow ID (defaults to UUID).
971
         * @param workflowId workflow ID
972
         * @return this builder
973
         */
974
        public Builder setWorkflowId(String workflowId);
975

976
        /**
977
         * Behavior for completed workflows with same ID.
978
         * @param workflowIdReusePolicy reuse policy
979
         * @return this builder
980
         */
981
        public Builder setWorkflowIdReusePolicy(WorkflowIdReusePolicy workflowIdReusePolicy);
982

983
        /**
984
         * Behavior for running workflows with same ID.
985
         * @param workflowIdConflictPolicy conflict policy
986
         * @return this builder
987
         */
988
        public Builder setWorkflowIdConflictPolicy(WorkflowIdConflictPolicy workflowIdConflictPolicy);
989

990
        /**
991
         * Time before run is automatically terminated.
992
         * @param workflowRunTimeout run timeout
993
         * @return this builder
994
         */
995
        public Builder setWorkflowRunTimeout(Duration workflowRunTimeout);
996

997
        /**
998
         * Time before entire execution is terminated.
999
         * @param workflowExecutionTimeout execution timeout
1000
         * @return this builder
1001
         */
1002
        public Builder setWorkflowExecutionTimeout(Duration workflowExecutionTimeout);
1003

1004
        /**
1005
         * Maximum workflow task execution time.
1006
         * @param workflowTaskTimeout task timeout
1007
         * @return this builder
1008
         */
1009
        public Builder setWorkflowTaskTimeout(Duration workflowTaskTimeout);
1010

1011
        /**
1012
         * Task queue for workflow tasks.
1013
         * @param taskQueue task queue name
1014
         * @return this builder
1015
         */
1016
        public Builder setTaskQueue(String taskQueue);
1017

1018
        /**
1019
         * Workflow retry configuration.
1020
         * @param retryOptions retry options
1021
         * @return this builder
1022
         */
1023
        public Builder setRetryOptions(RetryOptions retryOptions);
1024

1025
        /**
1026
         * Cron schedule for periodic execution.
1027
         * @param cronSchedule cron expression
1028
         * @return this builder
1029
         */
1030
        public Builder setCronSchedule(String cronSchedule);
1031

1032
        /**
1033
         * Additional non-indexed information.
1034
         * @param memo memo map
1035
         * @return this builder
1036
         */
1037
        public Builder setMemo(Map<String, Object> memo);
1038

1039
        /**
1040
         * Type-safe search attributes.
1041
         * @param searchAttributes typed search attributes
1042
         * @return this builder
1043
         */
1044
        public Builder setTypedSearchAttributes(SearchAttributes searchAttributes);
1045

1046
        /**
1047
         * Context propagation overrides.
1048
         * @param contextPropagators context propagators list
1049
         * @return this builder
1050
         */
1051
        public Builder setContextPropagators(List<ContextPropagator> contextPropagators);
1052

1053
        /**
1054
         * Disable local eager execution.
1055
         * @param disableEagerExecution true to disable
1056
         * @return this builder
1057
         */
1058
        public Builder setDisableEagerExecution(boolean disableEagerExecution);
1059

1060
        /**
1061
         * Delay before first workflow task.
1062
         * @param startDelay start delay duration
1063
         * @return this builder
1064
         */
1065
        public Builder setStartDelay(Duration startDelay);
1066

1067
        /**
1068
         * Fixed summary for UI (Experimental).
1069
         * @param staticSummary workflow summary
1070
         * @return this builder
1071
         */
1072
        @Experimental
1073
        public Builder setStaticSummary(String staticSummary);
1074

1075
        /**
1076
         * Fixed details for UI (Experimental).
1077
         * @param staticDetails workflow details
1078
         * @return this builder
1079
         */
1080
        @Experimental
1081
        public Builder setStaticDetails(String staticDetails);
1082

1083
        /**
1084
         * Unique start request ID (Experimental).
1085
         * @param requestId request ID
1086
         * @return this builder
1087
         */
1088
        @Experimental
1089
        public Builder setRequestId(String requestId);
1090

1091
        /**
1092
         * Terminal state callbacks (Experimental).
1093
         * @param completionCallbacks callback list
1094
         * @return this builder
1095
         */
1096
        @Experimental
1097
        public Builder setCompletionCallbacks(List<Callback> completionCallbacks);
1098

1099
        /**
1100
         * Associated links (Experimental).
1101
         * @param links link list
1102
         * @return this builder
1103
         */
1104
        @Experimental
1105
        public Builder setLinks(List<Link> links);
1106

1107
        /**
1108
         * Conflict handling options (Experimental).
1109
         * @param onConflictOptions conflict options
1110
         * @return this builder
1111
         */
1112
        @Experimental
1113
        public Builder setOnConflictOptions(OnConflictOptions onConflictOptions);
1114

1115
        /**
1116
         * Task priority settings (Experimental).
1117
         * @param priority task priority
1118
         * @return this builder
1119
         */
1120
        @Experimental
1121
        public Builder setPriority(Priority priority);
1122

1123
        /**
1124
         * Versioning override (Experimental).
1125
         * @param versioningOverride versioning override
1126
         * @return this builder
1127
         */
1128
        @Experimental
1129
        public Builder setVersioningOverride(VersioningOverride versioningOverride);
1130

1131
        /**
1132
         * Build the WorkflowOptions.
1133
         * @return configured WorkflowOptions
1134
         */
1135
        public WorkflowOptions build();
1136
    }
1137
}
1138
```
1139

1140
### Workflow Client Options
1141

1142
Configuration options for the WorkflowClient.
1143

1144
```java { .api }
1145
/**
1146
 * Configuration options for the WorkflowClient.
1147
 */
1148
public final class WorkflowClientOptions {
1149
    /**
1150
     * Creates new builder.
1151
     * @return new WorkflowClientOptions builder
1152
     */
1153
    public static Builder newBuilder();
1154

1155
    /**
1156
     * Creates builder from existing options.
1157
     * @param options existing options to copy
1158
     * @return new builder with copied options
1159
     */
1160
    public static Builder newBuilder(WorkflowClientOptions options);
1161

1162
    /**
1163
     * Builder for WorkflowClientOptions.
1164
     */
1165
    public static final class Builder {
1166
        /**
1167
         * Workflow client namespace.
1168
         * @param namespace namespace name
1169
         * @return this builder
1170
         */
1171
        public Builder setNamespace(String namespace);
1172

1173
        /**
1174
         * Data converter for payload serialization.
1175
         * @param dataConverter data converter
1176
         * @return this builder
1177
         */
1178
        public Builder setDataConverter(DataConverter dataConverter);
1179

1180
        /**
1181
         * Context propagators for tracing/logging.
1182
         * @param contextPropagators context propagators
1183
         * @return this builder
1184
         */
1185
        public Builder setContextPropagators(List<ContextPropagator> contextPropagators);
1186

1187
        /**
1188
         * Interceptors for workflow calls.
1189
         * @param interceptors workflow interceptors
1190
         * @return this builder
1191
         */
1192
        public Builder setInterceptors(WorkflowClientInterceptor... interceptors);
1193

1194
        /**
1195
         * Identity for workflow client.
1196
         * @param identity client identity
1197
         * @return this builder
1198
         */
1199
        public Builder setIdentity(String identity);
1200

1201
        /**
1202
         * Binary checksum for workflow compatibility.
1203
         * @param binaryChecksum binary checksum
1204
         * @return this builder
1205
         */
1206
        public Builder setBinaryChecksum(String binaryChecksum);
1207

1208
        /**
1209
         * Build the WorkflowClientOptions.
1210
         * @return configured WorkflowClientOptions
1211
         */
1212
        public WorkflowClientOptions build();
1213
    }
1214
}
1215
```