0
# Transport and Status
1
2
gRPC transport channel implementation and status code handling for the GAX transport abstraction layer.
3
4
## Capabilities
5
6
### GrpcTransportChannel
7
8
gRPC-based implementation of the GAX TransportChannel interface providing channel access and DirectPath support.
9
10
```java { .api }
11
/**
12
* gRPC-based implementation of TransportChannel
13
* Provides access to underlying gRPC channels and DirectPath optimization
14
*/
15
public abstract class GrpcTransportChannel implements TransportChannel {
16
/** Get the gRPC transport name identifier */
17
public static String getGrpcTransportName();
18
19
/** Create a new builder for transport channel */
20
public static Builder newBuilder();
21
22
/** Create transport channel from managed channel */
23
public static GrpcTransportChannel create(ManagedChannel channel);
24
25
/** Get the underlying gRPC channel */
26
public Channel getChannel();
27
28
/** Check if using DirectPath optimization */
29
public boolean isDirectPath();
30
31
/** Shutdown the transport channel */
32
public void shutdown();
33
34
/** Check if transport is shutdown */
35
public boolean isShutdown();
36
37
/** Check if transport is terminated */
38
public boolean isTerminated();
39
40
/** Shutdown transport immediately */
41
public void shutdownNow();
42
43
/** Await termination with timeout */
44
public boolean awaitTermination(long duration, TimeUnit unit) throws InterruptedException;
45
46
/** Close the transport channel */
47
public void close();
48
}
49
```
50
51
### Transport Channel Builder
52
53
Builder for creating and configuring GrpcTransportChannel instances.
54
55
```java { .api }
56
/**
57
* Builder for GrpcTransportChannel configuration
58
*/
59
public abstract static class GrpcTransportChannel.Builder {
60
/** Set the managed channel */
61
public Builder setManagedChannel(ManagedChannel managedChannel);
62
63
/** Set channel pooling settings */
64
public Builder setChannelPoolSettings(ChannelPoolSettings channelPoolSettings);
65
66
/** Set keep-alive time */
67
public Builder setKeepAliveTime(Duration keepAliveTime);
68
69
/** Set keep-alive timeout */
70
public Builder setKeepAliveTimeout(Duration keepAliveTimeout);
71
72
/** Set keep-alive without calls */
73
public Builder setKeepAliveWithoutCalls(Boolean keepAliveWithoutCalls);
74
75
/** Set interceptor provider */
76
public Builder setInterceptorProvider(GrpcInterceptorProvider interceptorProvider);
77
78
/** Build the transport channel */
79
public GrpcTransportChannel build();
80
}
81
```
82
83
### GrpcStatusCode
84
85
gRPC-specific implementation of GAX StatusCode interface for error handling and status mapping.
86
87
```java { .api }
88
/**
89
* gRPC-specific status code implementation
90
* Maps gRPC status codes to GAX StatusCode interface
91
*/
92
public abstract class GrpcStatusCode implements StatusCode {
93
/** Create status code from gRPC status code */
94
public static GrpcStatusCode of(Status.Code grpcCode);
95
96
/** Get the GAX status code */
97
public StatusCode.Code getCode();
98
99
/** Get the gRPC status code */
100
public Status.Code getGrpcCode();
101
102
/** Check if status represents a timeout */
103
public boolean isTimeout();
104
105
/** Check if status is retryable */
106
public boolean isRetryable();
107
108
/** Get string representation */
109
public String toString();
110
}
111
```
112
113
### Transport Descriptor
114
115
Descriptor providing metadata about the gRPC transport implementation.
116
117
```java { .api }
118
/**
119
* Descriptor for gRPC transport providing metadata and capabilities
120
*/
121
public class GrpcTransportDescriptor implements TransportDescriptor {
122
/** Get the transport name */
123
public String getTransportName();
124
125
/** Get supported authentication types */
126
public Set<String> getSupportedAuthTypes();
127
128
/** Check if transport supports streaming */
129
public boolean supportsStreaming();
130
131
/** Check if transport supports operation cancellation */
132
public boolean supportsCancellation();
133
134
/** Get maximum message size supported */
135
public long getMaxMessageSize();
136
137
/** Check if DirectPath is supported */
138
public boolean supportsDirectPath();
139
}
140
```
141
142
## Status Code Mapping
143
144
### Standard Status Codes
145
146
```java { .api }
147
/**
148
* Standard gRPC to GAX status code mappings
149
*/
150
public class GrpcStatusCodeMapping {
151
/** Map from gRPC Status.Code to GAX StatusCode.Code */
152
public static final Map<Status.Code, StatusCode.Code> GRPC_TO_GAX_MAPPING;
153
154
/** Map from GAX StatusCode.Code to gRPC Status.Code */
155
public static final Map<StatusCode.Code, Status.Code> GAX_TO_GRPC_MAPPING;
156
157
/** Convert gRPC status to GAX status */
158
public static StatusCode.Code toGaxCode(Status.Code grpcCode);
159
160
/** Convert GAX status to gRPC status */
161
public static Status.Code toGrpcCode(StatusCode.Code gaxCode);
162
163
/** Check if status code is retryable */
164
public static boolean isRetryable(Status.Code grpcCode);
165
166
/** Check if status code represents timeout */
167
public static boolean isTimeout(Status.Code grpcCode);
168
}
169
```
170
171
### Exception Mapping
172
173
```java { .api }
174
/**
175
* Maps gRPC exceptions to GAX exceptions
176
*/
177
public class GrpcExceptionMapping {
178
/** Convert gRPC StatusException to ApiException */
179
public static ApiException toApiException(StatusException statusException);
180
181
/** Convert gRPC StatusRuntimeException to ApiException */
182
public static ApiException toApiException(StatusRuntimeException statusRuntimeException);
183
184
/** Extract retry information from exception */
185
public static RetryInfo extractRetryInfo(Throwable exception);
186
187
/** Check if exception is retryable */
188
public static boolean isRetryable(Throwable exception);
189
}
190
```
191
192
## Transport Configuration Types
193
194
### Transport Options
195
196
```java { .api }
197
/**
198
* Configuration options for gRPC transport
199
*/
200
public static class GrpcTransportOptions {
201
/** Set maximum inbound message size */
202
public GrpcTransportOptions withMaxInboundMessageSize(int size);
203
204
/** Set maximum inbound metadata size */
205
public GrpcTransportOptions withMaxInboundMetadataSize(int size);
206
207
/** Enable keep-alive */
208
public GrpcTransportOptions withKeepAlive(Duration time, Duration timeout);
209
210
/** Enable compression */
211
public GrpcTransportOptions withCompression(String compression);
212
213
/** Set user agent */
214
public GrpcTransportOptions withUserAgent(String userAgent);
215
216
/** Enable DirectPath */
217
public GrpcTransportOptions withDirectPath(boolean enabled);
218
}
219
```
220
221
### Channel State Monitoring
222
223
```java { .api }
224
/**
225
* Utilities for monitoring gRPC channel state
226
*/
227
public class ChannelStateMonitor {
228
/** Get current channel connectivity state */
229
public static ConnectivityState getChannelState(ManagedChannel channel);
230
231
/** Wait for channel state change */
232
public static boolean waitForStateChange(
233
ManagedChannel channel,
234
ConnectivityState sourceState,
235
long timeout,
236
TimeUnit unit);
237
238
/** Check if channel is ready */
239
public static boolean isChannelReady(ManagedChannel channel);
240
241
/** Check if channel is shutdown */
242
public static boolean isChannelShutdown(ManagedChannel channel);
243
}
244
```
245
246
## Usage Examples
247
248
### Basic Transport Channel Creation
249
250
```java
251
import com.google.api.gax.grpc.GrpcTransportChannel;
252
import io.grpc.ManagedChannel;
253
import io.grpc.ManagedChannelBuilder;
254
255
// Create managed channel
256
ManagedChannel managedChannel = ManagedChannelBuilder
257
.forAddress("your-service.googleapis.com", 443)
258
.useTransportSecurity()
259
.build();
260
261
// Create transport channel
262
GrpcTransportChannel transportChannel = GrpcTransportChannel.create(managedChannel);
263
264
// Use the transport channel
265
Channel channel = transportChannel.getChannel();
266
boolean isDirectPath = transportChannel.isDirectPath();
267
```
268
269
### Transport Channel with Builder
270
271
```java
272
import com.google.api.gax.grpc.ChannelPoolSettings;
273
274
// Create transport channel with builder
275
ChannelPoolSettings poolSettings = ChannelPoolSettings.builder()
276
.setMinChannelCount(2)
277
.setMaxChannelCount(10)
278
.build();
279
280
GrpcTransportChannel transportChannel = GrpcTransportChannel.newBuilder()
281
.setManagedChannel(managedChannel)
282
.setChannelPoolSettings(poolSettings)
283
.setKeepAliveTime(Duration.ofMinutes(2))
284
.setKeepAliveTimeout(Duration.ofSeconds(30))
285
.build();
286
```
287
288
### Status Code Handling
289
290
```java
291
import com.google.api.gax.grpc.GrpcStatusCode;
292
import com.google.api.gax.rpc.StatusCode;
293
import io.grpc.Status;
294
295
// Create status code from gRPC status
296
GrpcStatusCode statusCode = GrpcStatusCode.of(Status.Code.UNAVAILABLE);
297
298
// Check status properties
299
StatusCode.Code gaxCode = statusCode.getCode();
300
boolean isRetryable = statusCode.isRetryable();
301
boolean isTimeout = statusCode.isTimeout();
302
303
// Use in exception handling
304
try {
305
// Make gRPC call
306
} catch (StatusRuntimeException e) {
307
GrpcStatusCode code = GrpcStatusCode.of(e.getStatus().getCode());
308
if (code.getCode() == StatusCode.Code.UNAVAILABLE) {
309
// Handle service unavailable
310
} else if (code.getCode() == StatusCode.Code.DEADLINE_EXCEEDED) {
311
// Handle timeout
312
}
313
}
314
```
315
316
### Exception Mapping
317
318
```java
319
import com.google.api.gax.rpc.ApiException;
320
import io.grpc.StatusException;
321
import io.grpc.StatusRuntimeException;
322
323
// Handle gRPC exceptions
324
try {
325
// Make gRPC call
326
} catch (StatusRuntimeException e) {
327
// Convert to GAX exception
328
ApiException apiException = GrpcExceptionMapping.toApiException(e);
329
330
if (apiException.isRetryable()) {
331
// Retry the operation
332
} else {
333
// Handle non-retryable error
334
throw apiException;
335
}
336
} catch (StatusException e) {
337
ApiException apiException = GrpcExceptionMapping.toApiException(e);
338
// Handle exception
339
}
340
```
341
342
### Transport Lifecycle Management
343
344
```java
345
import java.util.concurrent.TimeUnit;
346
347
// Proper shutdown sequence
348
try {
349
// Use transport channel
350
// ... perform operations ...
351
352
} finally {
353
// Graceful shutdown
354
transportChannel.shutdown();
355
356
// Wait for termination
357
if (!transportChannel.awaitTermination(30, TimeUnit.SECONDS)) {
358
// Force shutdown if graceful shutdown times out
359
transportChannel.shutdownNow();
360
361
// Wait again for force shutdown
362
if (!transportChannel.awaitTermination(5, TimeUnit.SECONDS)) {
363
System.err.println("Transport channel did not terminate gracefully");
364
}
365
}
366
}
367
```
368
369
### Channel State Monitoring
370
371
```java
372
import io.grpc.ConnectivityState;
373
374
// Monitor channel state
375
ManagedChannel channel = transportChannel.getChannel();
376
ConnectivityState currentState = ChannelStateMonitor.getChannelState(channel);
377
378
switch (currentState) {
379
case READY:
380
System.out.println("Channel is ready for calls");
381
break;
382
case CONNECTING:
383
System.out.println("Channel is connecting");
384
break;
385
case TRANSIENT_FAILURE:
386
System.out.println("Channel experienced a failure, will retry");
387
break;
388
case IDLE:
389
System.out.println("Channel is idle");
390
break;
391
case SHUTDOWN:
392
System.out.println("Channel is shutdown");
393
break;
394
}
395
396
// Wait for channel to become ready
397
boolean stateChanged = ChannelStateMonitor.waitForStateChange(
398
channel, currentState, 30, TimeUnit.SECONDS);
399
400
if (stateChanged && ChannelStateMonitor.isChannelReady(channel)) {
401
// Channel is now ready
402
System.out.println("Channel is ready for calls");
403
}
404
```
405
406
### DirectPath Configuration Check
407
408
```java
409
// Check DirectPath status
410
if (transportChannel.isDirectPath()) {
411
System.out.println("Using DirectPath optimization for Google Cloud");
412
// DirectPath provides optimized networking for Google Cloud services
413
} else {
414
System.out.println("Using standard gRPC transport");
415
}
416
417
// Get transport name
418
String transportName = GrpcTransportChannel.getGrpcTransportName();
419
System.out.println("Transport: " + transportName);
420
```