0
# Call Context and Configuration
1

2
Immutable context objects for configuring gRPC calls including timeouts, retries, headers, and channel affinity.
3

4
## Capabilities
5

6
### GrpcCallContext
7

8
Primary context object for gRPC calls, providing immutable configuration for channels, timeouts, retries, and metadata.
9

10
```java { .api }
11
/**
12
 * Immutable context object for gRPC calls
13
 * Encapsulates channel, timeout, retry, and metadata configuration
14
 */
15
public final class GrpcCallContext implements ApiCallContext {
16
    /** Create a default call context */
17
    public static GrpcCallContext createDefault();
18
    
19
    /** Create context with specific channel and call options */
20
    public static GrpcCallContext of(Channel channel, CallOptions callOptions);
21
    
22
    /** Create context with credentials */
23
    public GrpcCallContext withCredentials(Credentials credentials);
24
    
25
    /** Create context with transport channel */
26
    public GrpcCallContext withTransportChannel(TransportChannel inputChannel);
27
    
28
    /** Create context with timeout duration */
29
    public GrpcCallContext withTimeoutDuration(Duration timeout);
30
    
31
    /** Create context with stream wait timeout */
32
    public GrpcCallContext withStreamWaitTimeoutDuration(Duration streamWaitTimeout);
33
    
34
    /** Create context with stream idle timeout */
35
    public GrpcCallContext withStreamIdleTimeoutDuration(Duration streamIdleTimeout);
36
    
37
    /** Create context with channel affinity for sticky routing */
38
    public GrpcCallContext withChannelAffinity(Integer affinity);
39
    
40
    /** Create context with extra headers */
41
    public GrpcCallContext withExtraHeaders(Map<String, List<String>> extraHeaders);
42
    
43
    /** Create context with retry settings */
44
    public GrpcCallContext withRetrySettings(RetrySettings retrySettings);
45
    
46
    /** Create context with retryable status codes */
47
    public GrpcCallContext withRetryableCodes(Set<StatusCode.Code> retryableCodes);
48
    
49
    /** Get the gRPC channel */
50
    public Channel getChannel();
51
    
52
    /** Get the call options */
53
    public CallOptions getCallOptions();
54
    
55
    /** Get timeout duration */
56
    public Duration getTimeoutDuration();
57
    
58
    /** Get the API tracer */
59
    public ApiTracer getTracer();
60
    
61
    /** Merge with another call context */
62
    public GrpcCallContext merge(ApiCallContext inputCallContext);
63
}
64
```
65

66
### GrpcCallSettings
67

68
gRPC-specific settings for creating callables with method descriptors and parameter extraction.
69

70
```java { .api }
71
/**
72
 * gRPC-specific settings for creating callables
73
 * Contains method descriptor and parameter extraction configuration
74
 */
75
public class GrpcCallSettings<RequestT, ResponseT> {
76
    /** Create a new builder for call settings */
77
    public static <RequestT, ResponseT> Builder<RequestT, ResponseT> newBuilder();
78
    
79
    /** Create call settings with method descriptor */
80
    public static <RequestT, ResponseT> GrpcCallSettings<RequestT, ResponseT> 
81
        create(MethodDescriptor<RequestT, ResponseT> methodDescriptor);
82
    
83
    /** Get the gRPC method descriptor */
84
    public MethodDescriptor<RequestT, ResponseT> getMethodDescriptor();
85
    
86
    /** Get the request parameters extractor */
87
    public RequestParamsExtractor<RequestT> getParamsExtractor();
88
    
89
    /** Get the request mutator */
90
    public RequestMutator<RequestT> getRequestMutator();
91
    
92
    /** Check if should await response trailers */
93
    public boolean shouldAwaitTrailers();
94
    
95
    /** Create a builder from these settings */
96
    public Builder<RequestT, ResponseT> toBuilder();
97
}
98
```
99

100
### Call Settings Builder
101

102
Builder for configuring gRPC-specific call settings with method descriptors and parameter handling.
103

104
```java { .api }
105
/**
106
 * Builder for GrpcCallSettings with method and parameter configuration
107
 */
108
public static class GrpcCallSettings.Builder<RequestT, ResponseT> {
109
    /** Set the gRPC method descriptor */
110
    public Builder<RequestT, ResponseT> setMethodDescriptor(MethodDescriptor<RequestT, ResponseT> methodDescriptor);
111
    
112
    /** Set request parameters extractor for routing */
113
    public Builder<RequestT, ResponseT> setParamsExtractor(RequestParamsExtractor<RequestT> paramsExtractor);
114
    
115
    /** Set request mutator for modifying requests */
116
    public Builder<RequestT, ResponseT> setRequestMutator(RequestMutator<RequestT> requestMutator);
117
    
118
    /** Set whether to await response trailers */
119
    public Builder<RequestT, ResponseT> setAwaitTrailers(boolean awaitTrailers);
120
    
121
    /** Build the call settings */
122
    public GrpcCallSettings<RequestT, ResponseT> build();
123
}
124
```
125

126
### Call Options Utilities
127

128
Utility methods for working with gRPC CallOptions and extracting context information.
129

130
```java { .api }
131
/**
132
 * Utilities for managing gRPC CallOptions
133
 */
134
public class CallOptionsUtil {
135
    /** Put API tracer in call options */
136
    public static CallOptions putApiTracerInCallOptions(ApiTracer tracer, CallOptions options);
137
    
138
    /** Get API tracer from call options */
139
    public static ApiTracer getApiTracerFromCallOptions(CallOptions options);
140
}
141
```
142

143
### Request Parameter Extraction
144

145
Interface for extracting routing parameters from requests for load balancing and routing decisions.
146

147
```java { .api }
148
/**
149
 * Extracts routing parameters from requests
150
 * Used for load balancing and routing decisions
151
 */
152
public interface RequestParamsExtractor<RequestT> {
153
    /** Extract routing parameters from request */
154
    Map<String, String> extract(RequestT request);
155
}
156
```
157

158
### Request Mutation
159

160
Interface for modifying requests before they are sent, useful for adding headers or transforming data.
161

162
```java { .api }
163
/**
164
 * Mutates requests before sending
165
 * Used for adding headers, authentication, or transforming data
166
 */
167
public interface RequestMutator<RequestT> {
168
    /** Mutate the request before sending */
169
    RequestT mutate(RequestT request);
170
}
171
```
172

173
## Constants and Keys
174

175
```java { .api }
176
/**
177
 * Call context constants and keys
178
 */
179
public final class GrpcCallContext {
180
    /** CallOptions key for API tracer */
181
    public static final CallOptions.Key<ApiTracer> TRACER_KEY;
182
}
183
```
184

185
## Usage Examples
186

187
### Basic Call Context Creation
188

189
```java
190
import com.google.api.gax.grpc.GrpcCallContext;
191
import java.time.Duration;
192

193
// Create default context
194
GrpcCallContext context = GrpcCallContext.createDefault();
195

196
// Create context with timeout
197
GrpcCallContext contextWithTimeout = context
198
    .withTimeoutDuration(Duration.ofSeconds(30));
199

200
// Create context with retry settings
201
RetrySettings retrySettings = RetrySettings.newBuilder()
202
    .setInitialRetryDelay(Duration.ofMillis(100))
203
    .setMaxRetryDelay(Duration.ofSeconds(60))
204
    .setRetryDelayMultiplier(1.3)
205
    .setMaxAttempts(5)
206
    .build();
207

208
GrpcCallContext contextWithRetry = context
209
    .withRetrySettings(retrySettings)
210
    .withRetryableCodes(Set.of(StatusCode.Code.UNAVAILABLE, StatusCode.Code.DEADLINE_EXCEEDED));
211
```
212

213
### Advanced Context Configuration
214

215
```java
216
import com.google.api.gax.grpc.GrpcCallContext;
217
import io.grpc.Channel;
218
import io.grpc.CallOptions;
219
import java.util.Map;
220
import java.util.List;
221

222
// Create context with channel and options
223
Channel channel = // ... your gRPC channel
224
CallOptions callOptions = CallOptions.DEFAULT
225
    .withDeadlineAfter(30, TimeUnit.SECONDS);
226

227
GrpcCallContext context = GrpcCallContext.of(channel, callOptions);
228

229
// Add extra headers
230
Map<String, List<String>> headers = Map.of(
231
    "x-custom-header", List.of("custom-value"),
232
    "x-request-id", List.of("req-12345")
233
);
234

235
GrpcCallContext contextWithHeaders = context
236
    .withExtraHeaders(headers)
237
    .withChannelAffinity(42); // For sticky routing
238
```
239

240
### Call Settings Configuration
241

242
```java
243
import com.google.api.gax.grpc.GrpcCallSettings;
244
import io.grpc.MethodDescriptor;
245

246
// Create method descriptor (typically generated)
247
MethodDescriptor<MyRequest, MyResponse> methodDescriptor = 
248
    // ... your method descriptor
249

250
// Create call settings
251
GrpcCallSettings<MyRequest, MyResponse> callSettings = 
252
    GrpcCallSettings.<MyRequest, MyResponse>newBuilder()
253
        .setMethodDescriptor(methodDescriptor)
254
        .setParamsExtractor(request -> {
255
            // Extract routing parameters
256
            return Map.of("project_id", request.getProjectId());
257
        })
258
        .setRequestMutator(request -> {
259
            // Add authentication or transform request
260
            return request.toBuilder()
261
                .setTimestamp(System.currentTimeMillis())
262
                .build();
263
        })
264
        .build();
265
```
266

267
### Streaming Context Configuration
268

269
```java
270
import com.google.api.gax.grpc.GrpcCallContext;
271
import java.time.Duration;
272

273
// Configure context for streaming calls
274
GrpcCallContext streamingContext = GrpcCallContext.createDefault()
275
    .withStreamWaitTimeoutDuration(Duration.ofMinutes(5))
276
    .withStreamIdleTimeoutDuration(Duration.ofMinutes(2))
277
    .withTimeoutDuration(Duration.ofMinutes(10));
278
```
279

280
### Context Merging
281

282
```java
283
import com.google.api.gax.grpc.GrpcCallContext;
284

285
// Create base context
286
GrpcCallContext baseContext = GrpcCallContext.createDefault()
287
    .withTimeoutDuration(Duration.ofSeconds(30));
288

289
// Create override context
290
GrpcCallContext overrideContext = GrpcCallContext.createDefault()
291
    .withRetrySettings(retrySettings);
292

293
// Merge contexts (override takes precedence)
294
GrpcCallContext mergedContext = baseContext.merge(overrideContext);
295
```