0
# Callable Factory
1

2
Factory methods for creating different types of gRPC callables including unary, streaming, paged, batching, and operation callables.
3

4
## Capabilities
5

6
### GrpcCallableFactory
7

8
Primary factory class for creating various types of gRPC callables with proper configuration and context handling.
9

10
```java { .api }
11
/**
12
 * Factory for creating gRPC callables of different types
13
 * Supports unary, streaming, paged, batching, and operation patterns
14
 */
15
public class GrpcCallableFactory {
16
    /** Create a unary callable for single request-response pattern */
17
    public static <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> createUnaryCallable(
18
        GrpcCallSettings<RequestT, ResponseT> grpcCallSettings,
19
        UnaryCallSettings<RequestT, ResponseT> callSettings,
20
        ClientContext clientContext);
21
    
22
    /** Create a paged callable for paginated responses */
23
    public static <RequestT, ResponseT, PagedListResponseT> UnaryCallable<RequestT, PagedListResponseT> 
24
        createPagedCallable(
25
            GrpcCallSettings<RequestT, ResponseT> grpcCallSettings,
26
            PagedCallSettings<RequestT, ResponseT, PagedListResponseT> callSettings,
27
            ClientContext clientContext);
28
    
29
    /** Create a batching callable for request batching */
30
    public static <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> createBatchingCallable(
31
        GrpcCallSettings<RequestT, ResponseT> grpcCallSettings,
32
        BatchingCallSettings<RequestT, ResponseT> callSettings,
33
        ClientContext clientContext);
34
    
35
    /** Create an operation callable for long-running operations */
36
    public static <RequestT, ResponseT, MetadataT> OperationCallable<RequestT, ResponseT, MetadataT> 
37
        createOperationCallable(
38
            GrpcCallSettings<RequestT, Operation> grpcCallSettings,
39
            OperationCallSettings<RequestT, ResponseT, MetadataT> operationCallSettings,
40
            ClientContext clientContext,
41
            OperationsStub operationsStub);
42
    
43
    /** Create a bidirectional streaming callable */
44
    public static <RequestT, ResponseT> BidiStreamingCallable<RequestT, ResponseT> 
45
        createBidiStreamingCallable(
46
            GrpcCallSettings<RequestT, ResponseT> grpcCallSettings,
47
            StreamingCallSettings<RequestT, ResponseT> callSettings,
48
            ClientContext clientContext);
49
    
50
    /** Create a server streaming callable */
51
    public static <RequestT, ResponseT> ServerStreamingCallable<RequestT, ResponseT> 
52
        createServerStreamingCallable(
53
            GrpcCallSettings<RequestT, ResponseT> grpcCallSettings,
54
            ServerStreamingCallSettings<RequestT, ResponseT> callSettings,
55
            ClientContext clientContext);
56
    
57
    /** Create a client streaming callable */
58
    public static <RequestT, ResponseT> ClientStreamingCallable<RequestT, ResponseT> 
59
        createClientStreamingCallable(
60
            GrpcCallSettings<RequestT, ResponseT> grpcCallSettings,
61
            StreamingCallSettings<RequestT, ResponseT> callSettings,
62
            ClientContext clientContext);
63
}
64
```
65

66
### GrpcRawCallableFactory
67

68
Factory for creating raw gRPC callables without additional GAX layers, used for low-level operations.
69

70
```java { .api }
71
/**
72
 * Factory for creating raw gRPC callables
73
 * Provides direct access to gRPC functionality without GAX abstractions
74
 */
75
public class GrpcRawCallableFactory {
76
    /** Create a raw unary callable */
77
    public static <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> createUnaryCallable(
78
        MethodDescriptor<RequestT, ResponseT> methodDescriptor,
79
        Function<RequestT, RequestT> requestMutator,
80
        Function<ResponseT, ResponseT> responseMutator);
81
    
82
    /** Create a raw server streaming callable */
83
    public static <RequestT, ResponseT> ServerStreamingCallable<RequestT, ResponseT> 
84
        createServerStreamingCallable(
85
            MethodDescriptor<RequestT, ResponseT> methodDescriptor,
86
            Function<RequestT, RequestT> requestMutator,
87
            Function<ResponseT, ResponseT> responseMutator);
88
    
89
    /** Create a raw client streaming callable */
90
    public static <RequestT, ResponseT> ClientStreamingCallable<RequestT, ResponseT> 
91
        createClientStreamingCallable(
92
            MethodDescriptor<RequestT, ResponseT> methodDescriptor,
93
            Function<RequestT, RequestT> requestMutator,
94
            Function<ResponseT, ResponseT> responseMutator);
95
    
96
    /** Create a raw bidirectional streaming callable */
97
    public static <RequestT, ResponseT> BidiStreamingCallable<RequestT, ResponseT> 
98
        createBidiStreamingCallable(
99
            MethodDescriptor<RequestT, ResponseT> methodDescriptor,
100
            Function<RequestT, RequestT> requestMutator,
101
            Function<ResponseT, ResponseT> responseMutator);
102
}
103
```
104

105
### GrpcStubCallableFactory
106

107
Factory for creating stub-level callables with enhanced error handling and metadata processing.
108

109
```java { .api }
110
/**
111
 * Factory for creating stub-level callables
112
 * Provides enhanced error handling and metadata processing
113
 */
114
public class GrpcStubCallableFactory {
115
    /** Create a stub unary callable with enhanced error handling */
116
    public static <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> createUnaryCallable(
117
        ClientCall<RequestT, ResponseT> clientCall,
118
        UnaryCallSettings<RequestT, ResponseT> callSettings,
119
        ClientContext clientContext);
120
    
121
    /** Create a stub server streaming callable */
122
    public static <RequestT, ResponseT> ServerStreamingCallable<RequestT, ResponseT> 
123
        createServerStreamingCallable(
124
            ClientCall<RequestT, ResponseT> clientCall,
125
            ServerStreamingCallSettings<RequestT, ResponseT> callSettings,
126
            ClientContext clientContext);
127
    
128
    /** Create a stub client streaming callable */  
129
    public static <RequestT, ResponseT> ClientStreamingCallable<RequestT, ResponseT> 
130
        createClientStreamingCallable(
131
            ClientCall<RequestT, ResponseT> clientCall,
132
            StreamingCallSettings<RequestT, ResponseT> callSettings,
133
            ClientContext clientContext);
134
    
135
    /** Create a stub bidirectional streaming callable */
136
    public static <RequestT, ResponseT> BidiStreamingCallable<RequestT, ResponseT> 
137
        createBidiStreamingCallable(
138
            ClientCall<RequestT, ResponseT> clientCall,
139
            StreamingCallSettings<RequestT, ResponseT> callSettings,
140
            ClientContext clientContext);
141
}
142
```
143

144
### Callable Creation Helpers
145

146
Helper methods and utilities for common callable creation patterns and configurations.
147

148
```java { .api }
149
/**
150
 * Helper utilities for callable creation
151
 */
152
public class GrpcCallableFactory {
153
    /** Create a callable with automatic retries */
154
    public static <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> createRetryingCallable(
155
        UnaryCallable<RequestT, ResponseT> innerCallable,
156
        RetrySettings retrySettings,
157
        Set<StatusCode.Code> retryableCodes,
158
        ClientContext clientContext);
159
    
160
    /** Create a callable with timeout handling */
161
    public static <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> createTimeoutCallable(
162
        UnaryCallable<RequestT, ResponseT> innerCallable,
163
        Duration timeout,
164
        ClientContext clientContext);
165
    
166
    /** Create a callable with tracing */
167
    public static <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> createTracedCallable(
168
        UnaryCallable<RequestT, ResponseT> innerCallable,
169
        SpanName spanName,
170
        ClientContext clientContext);
171
}
172
```
173

174
## Callable Configuration Types
175

176
### Method Descriptor Configuration
177

178
```java { .api }
179
/**
180
 * Configuration for gRPC method descriptors
181
 */
182
public interface MethodDescriptorConfig<RequestT, ResponseT> {
183
    /** Get the gRPC method descriptor */
184
    MethodDescriptor<RequestT, ResponseT> getMethodDescriptor();
185
    
186
    /** Get the request marshaller */
187
    MethodDescriptor.Marshaller<RequestT> getRequestMarshaller();
188
    
189
    /** Get the response marshaller */
190
    MethodDescriptor.Marshaller<ResponseT> getResponseMarshaller();
191
    
192
    /** Get the method type */
193
    MethodDescriptor.MethodType getMethodType();
194
}
195
```
196

197
### Callable Enhancement Options
198

199
```java { .api }
200
/**
201
 * Options for enhancing callables with additional functionality
202
 */
203
public static class CallableEnhancementOptions {
204
    /** Enable automatic retries */
205
    public CallableEnhancementOptions withRetries(RetrySettings retrySettings);
206
    
207
    /** Enable timeout handling */
208
    public CallableEnhancementOptions withTimeout(Duration timeout);
209
    
210
    /** Enable distributed tracing */
211
    public CallableEnhancementOptions withTracing(boolean enabled);
212
    
213
    /** Enable response metadata collection */
214
    public CallableEnhancementOptions withMetadataCollection(boolean enabled);
215
    
216
    /** Enable request/response logging */
217
    public CallableEnhancementOptions withLogging(boolean enabled);
218
}
219
```
220

221
## Usage Examples
222

223
### Basic Unary Callable Creation
224

225
```java
226
import com.google.api.gax.grpc.GrpcCallableFactory;
227
import com.google.api.gax.grpc.GrpcCallSettings;
228
import com.google.api.gax.rpc.UnaryCallSettings;
229
import com.google.api.gax.rpc.ClientContext;
230

231
// Create method descriptor (typically from generated code)
232
MethodDescriptor<MyRequest, MyResponse> methodDescriptor = 
233
    MyServiceGrpc.getMyMethodMethod();
234

235
// Create gRPC call settings
236
GrpcCallSettings<MyRequest, MyResponse> grpcSettings = 
237
    GrpcCallSettings.<MyRequest, MyResponse>newBuilder()
238
        .setMethodDescriptor(methodDescriptor)
239
        .build();
240

241
// Create unary call settings
242
UnaryCallSettings<MyRequest, MyResponse> callSettings = 
243
    UnaryCallSettings.<MyRequest, MyResponse>newUnaryCallSettingsBuilder()
244
        .setRetrySettings(retrySettings)
245
        .build();
246

247
// Create the callable
248
UnaryCallable<MyRequest, MyResponse> callable = 
249
    GrpcCallableFactory.createUnaryCallable(grpcSettings, callSettings, clientContext);
250

251
// Use the callable
252
MyResponse response = callable.call(MyRequest.newBuilder().build());
253
```
254

255
### Paged Callable Creation
256

257
```java
258
import com.google.api.gax.rpc.PagedCallSettings;
259

260
// Create paged call settings
261
PagedCallSettings<ListRequest, ListResponse, ListPagedResponse> pagedSettings = 
262
    PagedCallSettings.<ListRequest, ListResponse, ListPagedResponse>newBuilder()
263
        .setPagedListResponseFactory(new ListPagedResponseFactory())
264
        .setRetrySettings(retrySettings)
265
        .build();
266

267
// Create the paged callable
268
UnaryCallable<ListRequest, ListPagedResponse> pagedCallable = 
269
    GrpcCallableFactory.createPagedCallable(grpcSettings, pagedSettings, clientContext);
270

271
// Use the paged callable
272
for (Item item : pagedCallable.call(ListRequest.newBuilder().build()).iterateAll()) {
273
    // Process each item
274
    System.out.println(item);
275
}
276
```
277

278
### Streaming Callable Creation
279

280
```java
281
import com.google.api.gax.rpc.ServerStreamingCallable;
282
import com.google.api.gax.rpc.ResponseObserver;
283
import com.google.api.gax.rpc.StreamController;
284

285
// Create server streaming callable
286
ServerStreamingCallable<StreamRequest, StreamResponse> streamingCallable = 
287
    GrpcCallableFactory.createServerStreamingCallable(grpcSettings, streamingSettings, clientContext);
288

289
// Use the streaming callable
290
streamingCallable.call(
291
    StreamRequest.newBuilder().build(),
292
    new ResponseObserver<StreamResponse>() {
293
        @Override
294
        public void onStart(StreamController controller) {
295
            // Stream started
296
        }
297
        
298
        @Override
299
        public void onResponse(StreamResponse response) {
300
            // Handle each response
301
            System.out.println(response);
302
        }
303
        
304
        @Override
305
        public void onError(Throwable t) {
306
            // Handle errors
307
            System.err.println("Stream error: " + t.getMessage());
308
        }
309
        
310
        @Override
311
        public void onComplete() {
312
            // Stream completed
313
            System.out.println("Stream completed");
314
        }
315
    }
316
);
317
```
318

319
### Operation Callable Creation
320

321
```java
322
import com.google.api.gax.longrunning.OperationCallable;
323
import com.google.api.gax.longrunning.OperationCallSettings;
324
import com.google.longrunning.Operation;
325

326
// Create operation call settings
327
OperationCallSettings<CreateRequest, CreateResponse, CreateMetadata> operationSettings = 
328
    OperationCallSettings.<CreateRequest, CreateResponse, CreateMetadata>newBuilder()
329
        .setInitialCallSettings(initialCallSettings)
330
        .setResponseTransformer(ProtoOperationTransformers.ResponseTransformer.create(CreateResponse.class))
331
        .setMetadataTransformer(ProtoOperationTransformers.MetadataTransformer.create(CreateMetadata.class))
332
        .setPollingSettings(PollingSettings.newBuilder()
333
            .setInitialRetryDelay(Duration.ofSeconds(5))
334
            .setRetryDelayMultiplier(1.5)
335
            .setMaxRetryDelay(Duration.ofMinutes(5))
336
            .setInitialRpcTimeout(Duration.ofMinutes(2))
337
            .setRpcTimeoutMultiplier(1.0)
338
            .setMaxRpcTimeout(Duration.ofMinutes(2))
339
            .setTotalTimeout(Duration.ofHours(24))
340
            .build())
341
        .build();
342

343
// Create the operation callable
344
OperationCallable<CreateRequest, CreateResponse, CreateMetadata> operationCallable = 
345
    GrpcCallableFactory.createOperationCallable(
346
        grpcSettings, operationSettings, clientContext, operationsStub);
347

348
// Use the operation callable
349
OperationFuture<CreateResponse, CreateMetadata> future = 
350
    operationCallable.futureCall(CreateRequest.newBuilder().build());
351

352
// Wait for completion
353
CreateResponse response = future.get();
354
```
355

356
### Batching Callable Creation
357

358
```java
359
import com.google.api.gax.batching.BatchingSettings;
360
import com.google.api.gax.batching.FlowControlSettings;
361

362
// Create batching settings
363
BatchingSettings batchingSettings = BatchingSettings.newBuilder()
364
    .setElementCountThreshold(100L)
365
    .setRequestByteThreshold(1024L * 1024L) // 1MB
366
    .setDelayThreshold(Duration.ofMillis(10))
367
    .setFlowControlSettings(FlowControlSettings.newBuilder()
368
        .setMaxOutstandingElementCount(1000L)
369
        .setMaxOutstandingRequestBytes(10L * 1024L * 1024L) // 10MB
370
        .build())
371
    .build();
372

373
BatchingCallSettings<BatchRequest, BatchResponse> batchingCallSettings = 
374
    BatchingCallSettings.<BatchRequest, BatchResponse>newBuilder()
375
        .setBatchingSettings(batchingSettings)
376
        .setBatchingDescriptor(new MyBatchingDescriptor())
377
        .build();
378

379
// Create the batching callable
380
UnaryCallable<BatchRequest, BatchResponse> batchingCallable = 
381
    GrpcCallableFactory.createBatchingCallable(grpcSettings, batchingCallSettings, clientContext);
382
```