0
# GAX-gRPC
1

2
Google API Extensions for Java (gax-grpc) provides gRPC-specific functionality for Google Cloud client libraries. It builds on the core GAX library to offer transport-specific features like channel management, interceptors, and long-running operations support, enabling robust and idiomatic Google Cloud service integrations.
3

4
## Package Information
5

6
- **Package Name**: gax-grpc
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Maven Coordinates**: `com.google.api:gax-grpc:2.67.0`
10
- **Installation**: Add to your `pom.xml`:
11

12
```xml
13
<dependency>
14
    <groupId>com.google.api</groupId>
15
    <artifactId>gax-grpc</artifactId>
16
    <version>2.67.0</version>
17
</dependency>
18
```
19

20
## Core Imports
21

22
```java
23
import com.google.api.gax.grpc.GrpcCallContext;
24
import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
25
import com.google.api.gax.grpc.GrpcTransportChannel;
26
import com.google.api.gax.grpc.GrpcCallSettings;
27
```
28

29
For Long Running Operations:
30

31
```java
32
import com.google.longrunning.OperationsClient;
33
import com.google.longrunning.OperationsSettings;
34
```
35

36
## Basic Usage
37

38
```java
39
import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
40
import com.google.api.gax.grpc.GrpcTransportChannel;
41
import com.google.api.gax.grpc.GrpcCallContext;
42
import com.google.auth.oauth2.GoogleCredentials;
43

44
// Create a gRPC channel provider
45
InstantiatingGrpcChannelProvider channelProvider = 
46
    InstantiatingGrpcChannelProvider.newBuilder()
47
        .setEndpoint("your-service-endpoint.googleapis.com:443")
48
        .setCredentials(GoogleCredentials.getApplicationDefault())
49
        .build();
50

51
// Get transport channel
52
GrpcTransportChannel transportChannel = 
53
    (GrpcTransportChannel) channelProvider.getTransportChannel();
54

55
// Create call context
56
GrpcCallContext callContext = GrpcCallContext.createDefault()
57
    .withTransportChannel(transportChannel)
58
    .withTimeoutDuration(Duration.ofSeconds(30));
59
```
60

61
## Architecture
62

63
GAX-gRPC is built around several key components:
64

65
- **Channel Management**: Sophisticated connection pooling and lifecycle management with DirectPath optimization
66
- **Call Context**: Immutable context objects encapsulating channel, timeout, and retry configuration
67
- **Callable Factory**: Generates type-safe callables for different RPC patterns (unary, streaming, paged, batching)
68
- **Interceptor System**: Comprehensive interceptor support for headers, logging, and metadata handling
69
- **Long Running Operations**: Complete implementation of Google's LRO pattern with polling and cancellation
70
- **Native Image Support**: GraalVM compatibility with reflection configuration for grpc-netty-shaded
71

72
## Capabilities
73

74
### Channel Management
75

76
Comprehensive gRPC channel lifecycle management with connection pooling, load balancing, and Google Cloud optimizations including DirectPath support.
77

78
```java { .api }
79
public final class InstantiatingGrpcChannelProvider implements TransportChannelProvider {
80
    public static Builder newBuilder();
81
    public TransportChannel getTransportChannel() throws IOException;
82
    public String getEndpoint();
83
    public ChannelPoolSettings getChannelPoolSettings();
84
}
85

86
public abstract class ChannelPoolSettings {
87
    public static ChannelPoolSettings staticallySized(int size);
88
    public static Builder builder();
89
    public int getMinRpcsPerChannel();
90
    public int getMaxRpcsPerChannel();
91
    public int getMinChannelCount();
92
    public int getMaxChannelCount();
93
}
94
```
95

96
[Channel Management](./channel-management.md)
97

98
### Call Context and Configuration
99

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

102
```java { .api }
103
public final class GrpcCallContext implements ApiCallContext {
104
    public static GrpcCallContext createDefault();
105
    public static GrpcCallContext of(Channel channel, CallOptions callOptions);
106
    public GrpcCallContext withCredentials(Credentials credentials);
107
    public GrpcCallContext withTimeoutDuration(Duration timeout);
108
    public GrpcCallContext withRetrySettings(RetrySettings retrySettings);
109
    public GrpcCallContext withChannelAffinity(Integer affinity);
110
}
111

112
public class GrpcCallSettings<RequestT, ResponseT> {
113
    public static <RequestT, ResponseT> Builder<RequestT, ResponseT> newBuilder();
114
    public MethodDescriptor<RequestT, ResponseT> getMethodDescriptor();
115
    public RequestParamsExtractor<RequestT> getParamsExtractor();
116
}
117
```
118

119
[Call Context](./call-context.md)
120

121
### Callable Factory
122

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

125
```java { .api }
126
public class GrpcCallableFactory {
127
    public static <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> 
128
        createUnaryCallable(GrpcCallSettings<RequestT, ResponseT> grpcCallSettings, 
129
                           UnaryCallSettings<RequestT, ResponseT> callSettings, 
130
                           ClientContext clientContext);
131
    
132
    public static <RequestT, ResponseT> BidiStreamingCallable<RequestT, ResponseT> 
133
        createBidiStreamingCallable(GrpcCallSettings<RequestT, ResponseT> grpcCallSettings, 
134
                                   StreamingCallSettings<RequestT, ResponseT> callSettings, 
135
                                   ClientContext clientContext);
136
    
137
    public static <RequestT, ResponseT, MetadataT> OperationCallable<RequestT, ResponseT, MetadataT> 
138
        createOperationCallable(GrpcCallSettings<RequestT, Operation> grpcCallSettings, 
139
                               OperationCallSettings<RequestT, ResponseT, MetadataT> operationCallSettings, 
140
                               ClientContext clientContext, 
141
                               OperationsStub operationsStub);
142
}
143
```
144

145
[Callable Factory](./callable-factory.md)
146

147
### Long Running Operations
148

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

151
```java { .api }
152
public class OperationsClient implements BackgroundResource {
153
    public static OperationsClient create(OperationsSettings settings) throws IOException;
154
    public Operation getOperation(String name);
155
    public ListOperationsPagedResponse listOperations(String name, String filter);
156
    public void cancelOperation(String name);
157
    public void deleteOperation(String name);
158
    public Operation waitOperation(WaitOperationRequest request);
159
}
160

161
public class OperationsSettings {
162
    public static Builder newBuilder();
163
    public UnaryCallSettings<GetOperationRequest, Operation> getOperationSettings();
164
    public PagedCallSettings<ListOperationsRequest, ListOperationsResponse, ListOperationsPagedResponse> 
165
        listOperationsSettings();
166
}
167
```
168

169
[Long Running Operations](./operations.md)
170

171
### Transport Channel and Status
172

173
gRPC transport channel implementation and status code handling for the GAX transport abstraction layer.
174

175
```java { .api }
176
public abstract class GrpcTransportChannel implements TransportChannel {
177
    public static String getGrpcTransportName();
178
    public static Builder newBuilder();
179
    public static GrpcTransportChannel create(ManagedChannel channel);
180
    public Channel getChannel();
181
    public boolean isDirectPath();
182
}
183

184
public abstract class GrpcStatusCode implements StatusCode {
185
    public static GrpcStatusCode of(Status.Code grpcCode);
186
    public StatusCode.Code getCode();
187
}
188
```
189

190
[Transport and Status](./transport-status.md)
191

192
### Interceptors and Metadata
193

194
Comprehensive interceptor support for headers, logging, metadata handling, and custom request/response processing.
195

196
```java { .api }
197
public interface GrpcInterceptorProvider {
198
    List<ClientInterceptor> getInterceptors();
199
}
200

201
public class GrpcResponseMetadata implements ResponseMetadata {
202
    public Map<String, List<String>> getMetadata();
203
    public List<String> getTrailersMetadata();
204
}
205

206
public class GrpcHeaderInterceptor implements ClientInterceptor {
207
    public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
208
        MethodDescriptor<ReqT, RespT> method, 
209
        CallOptions callOptions, 
210
        Channel next);
211
}
212
```
213

214
[Interceptors](./interceptors.md)
215

216
## Types
217

218
### Core Types
219

220
```java { .api }
221
// Channel provider builder with comprehensive configuration options
222
public static final class InstantiatingGrpcChannelProvider.Builder {
223
    public Builder setEndpoint(String endpoint);
224
    public Builder setCredentials(Credentials credentials);
225
    public Builder setHeaderProvider(HeaderProvider headerProvider);
226
    public Builder setChannelConfigurator(ApiFunction<ManagedChannelBuilder, ManagedChannelBuilder> channelConfigurator);
227
    public Builder setKeepAliveTime(Duration keepAliveTime);
228
    public Builder setKeepAliveTimeout(Duration keepAliveTimeout);
229
    public Builder setKeepAliveWithoutCalls(Boolean keepAliveWithoutCalls);
230
    public Builder setMaxInboundMessageSize(Integer maxInboundMessageSize);
231
    public Builder setMaxInboundMetadataSize(Integer maxInboundMetadataSize);
232
    public Builder setChannelPoolSettings(ChannelPoolSettings channelPoolSettings);
233
    public Builder setDirectPathServiceConfig(Map<String, ?> serviceConfig);
234
    public InstantiatingGrpcChannelProvider build();
235
}
236

237
// Context builder for configuring call-specific settings
238
public static final class GrpcCallContext.Builder {
239
    public Builder setChannel(Channel channel);
240
    public Builder setCallOptions(CallOptions callOptions);
241
    public Builder setTimeout(Duration timeout);
242
    public Builder setStreamWaitTimeout(Duration streamWaitTimeout);
243
    public Builder setStreamIdleTimeout(Duration streamIdleTimeout);
244
    public GrpcCallContext build();
245
}
246
```
247

248
### Operations Types
249

250
```java { .api }
251
// Settings builder for operations client configuration
252
public static class OperationsSettings.Builder {
253
    public Builder setCredentialsProvider(CredentialsProvider credentialsProvider);
254
    public Builder setTransportChannelProvider(TransportChannelProvider transportChannelProvider);
255
    public Builder setHeaderProvider(HeaderProvider headerProvider);
256
    public Builder setEndpoint(String endpoint);
257
    public Builder setQuotaProjectId(String quotaProjectId);
258
    public UnaryCallSettings.Builder<GetOperationRequest, Operation> getOperationSettings();
259
    public PagedCallSettings.Builder<ListOperationsRequest, ListOperationsResponse, ListOperationsPagedResponse> 
260
        listOperationsSettings();
261
    public UnaryCallSettings.Builder<CancelOperationRequest, Empty> cancelOperationSettings();
262
    public UnaryCallSettings.Builder<DeleteOperationRequest, Empty> deleteOperationSettings();
263
    public OperationsSettings build() throws IOException;
264
}
265
```