0
# Channel Management
1
2
Comprehensive gRPC channel lifecycle management with connection pooling, load balancing, and Google Cloud optimizations including DirectPath support.
3
4
## Capabilities
5
6
### InstantiatingGrpcChannelProvider
7
8
Primary TransportChannelProvider that creates and manages gRPC ManagedChannels with sophisticated configuration options.
9
10
```java { .api }
11
/**
12
* Primary channel provider for creating gRPC ManagedChannels
13
* Supports connection pooling, DirectPath, and comprehensive configuration
14
*/
15
public final class InstantiatingGrpcChannelProvider implements TransportChannelProvider {
16
/** Create a new builder for channel provider configuration */
17
public static Builder newBuilder();
18
19
/** Get the transport name identifier */
20
public String getTransportName();
21
22
/** Create and return the configured transport channel */
23
public TransportChannel getTransportChannel() throws IOException;
24
25
/** Get the configured endpoint */
26
public String getEndpoint();
27
28
/** Get keep-alive time duration setting */
29
public Duration getKeepAliveTimeDuration();
30
31
/** Get keep-alive timeout duration setting */
32
public Duration getKeepAliveTimeoutDuration();
33
34
/** Get keep-alive without calls setting */
35
public Boolean getKeepAliveWithoutCalls();
36
37
/** Get maximum inbound metadata size setting */
38
public Integer getMaxInboundMetadataSize();
39
40
/** Get channel pool configuration settings */
41
public ChannelPoolSettings getChannelPoolSettings();
42
43
/** Create a new builder from this provider */
44
public Builder toBuilder();
45
}
46
```
47
48
### Channel Provider Builder
49
50
Comprehensive builder for configuring gRPC channel providers with all available options.
51
52
```java { .api }
53
/**
54
* Builder for InstantiatingGrpcChannelProvider with comprehensive configuration
55
*/
56
public static final class InstantiatingGrpcChannelProvider.Builder {
57
/** Set the service endpoint URL */
58
public Builder setEndpoint(String endpoint);
59
60
/** Set credentials for authentication */
61
public Builder setCredentials(Credentials credentials);
62
63
/** Set the header provider for request headers */
64
public Builder setHeaderProvider(HeaderProvider headerProvider);
65
66
/** Set channel configurator for advanced ManagedChannelBuilder customization */
67
public Builder setChannelConfigurator(ApiFunction<ManagedChannelBuilder, ManagedChannelBuilder> channelConfigurator);
68
69
/** Set keep-alive time for connections */
70
public Builder setKeepAliveTime(Duration keepAliveTime);
71
72
/** Set keep-alive timeout for connections */
73
public Builder setKeepAliveTimeout(Duration keepAliveTimeout);
74
75
/** Set whether to send keep-alive pings without active calls */
76
public Builder setKeepAliveWithoutCalls(Boolean keepAliveWithoutCalls);
77
78
/** Set maximum inbound message size */
79
public Builder setMaxInboundMessageSize(Integer maxInboundMessageSize);
80
81
/** Set maximum inbound metadata size */
82
public Builder setMaxInboundMetadataSize(Integer maxInboundMetadataSize);
83
84
/** Set channel pool settings for connection pooling */
85
public Builder setChannelPoolSettings(ChannelPoolSettings channelPoolSettings);
86
87
/** Set DirectPath service configuration */
88
public Builder setDirectPathServiceConfig(Map<String, ?> serviceConfig);
89
90
/** Set quota project ID for billing */
91
public Builder setQuotaProjectId(String quotaProjectId);
92
93
/** Set custom client interceptor provider */
94
public Builder setInterceptorProvider(GrpcInterceptorProvider interceptorProvider);
95
96
/** Build the configured channel provider */
97
public InstantiatingGrpcChannelProvider build();
98
}
99
```
100
101
### ChannelPoolSettings
102
103
Configuration for sophisticated channel pool management with dynamic scaling capabilities.
104
105
```java { .api }
106
/**
107
* Settings for channel pool behavior and scaling
108
* Supports dynamic scaling based on RPC load
109
*/
110
public abstract class ChannelPoolSettings {
111
/** Create a statically sized channel pool */
112
public static ChannelPoolSettings staticallySized(int size);
113
114
/** Create a new builder for channel pool settings */
115
public static Builder builder();
116
117
/** Get minimum RPCs per channel threshold */
118
public int getMinRpcsPerChannel();
119
120
/** Get maximum RPCs per channel threshold */
121
public int getMaxRpcsPerChannel();
122
123
/** Get minimum number of channels in pool */
124
public int getMinChannelCount();
125
126
/** Get maximum number of channels in pool */
127
public int getMaxChannelCount();
128
129
/** Get initial number of channels to create */
130
public int getInitialChannelCount();
131
132
/** Check if preemptive refresh is enabled */
133
public boolean isPreemptiveRefreshEnabled();
134
135
/** Create a builder from these settings */
136
public Builder toBuilder();
137
}
138
```
139
140
### Channel Pool Builder
141
142
Builder for configuring channel pool behavior with fine-grained control over scaling parameters.
143
144
```java { .api }
145
/**
146
* Builder for ChannelPoolSettings with scaling configuration
147
*/
148
public abstract static class ChannelPoolSettings.Builder {
149
/** Set minimum RPCs per channel before scaling up */
150
public Builder setMinRpcsPerChannel(int minRpcsPerChannel);
151
152
/** Set maximum RPCs per channel before scaling up */
153
public Builder setMaxRpcsPerChannel(int maxRpcsPerChannel);
154
155
/** Set minimum number of channels to maintain */
156
public Builder setMinChannelCount(int minChannelCount);
157
158
/** Set maximum number of channels allowed */
159
public Builder setMaxChannelCount(int maxChannelCount);
160
161
/** Set initial number of channels to create */
162
public Builder setInitialChannelCount(int initialChannelCount);
163
164
/** Enable or disable preemptive refresh of channels */
165
public Builder setPreemptiveRefreshEnabled(boolean preemptiveRefreshEnabled);
166
167
/** Build the channel pool settings */
168
public ChannelPoolSettings build();
169
}
170
```
171
172
### Channel Factory
173
174
Factory interface for creating custom ManagedChannels with specific configurations.
175
176
```java { .api }
177
/**
178
* Factory interface for custom channel creation
179
*/
180
public interface ChannelFactory {
181
/** Create a ManagedChannel with the given configuration */
182
ManagedChannel createChannel(String endpoint, Map<String, ?> channelArgs);
183
}
184
```
185
186
### Channel Primer
187
188
Interface for preparing channels before use, typically for pre-loading or warming up connections.
189
190
```java { .api }
191
/**
192
* Interface for preparing ManagedChannels for requests
193
* Used for connection warming and pre-loading
194
*/
195
public interface ChannelPrimer {
196
/** Prepare the given channel for use */
197
void primeChannel(ManagedChannel managedChannel);
198
}
199
```
200
201
## Usage Examples
202
203
### Basic Channel Provider Setup
204
205
```java
206
import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
207
import com.google.auth.oauth2.GoogleCredentials;
208
209
// Create basic channel provider
210
InstantiatingGrpcChannelProvider provider =
211
InstantiatingGrpcChannelProvider.newBuilder()
212
.setEndpoint("translate.googleapis.com:443")
213
.setCredentials(GoogleCredentials.getApplicationDefault())
214
.build();
215
216
// Get the transport channel
217
TransportChannel channel = provider.getTransportChannel();
218
```
219
220
### Advanced Channel Pool Configuration
221
222
```java
223
import com.google.api.gax.grpc.ChannelPoolSettings;
224
import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
225
226
// Configure sophisticated channel pooling
227
ChannelPoolSettings poolSettings = ChannelPoolSettings.builder()
228
.setMinChannelCount(2)
229
.setMaxChannelCount(10)
230
.setMinRpcsPerChannel(5)
231
.setMaxRpcsPerChannel(100)
232
.setPreemptiveRefreshEnabled(true)
233
.build();
234
235
InstantiatingGrpcChannelProvider provider =
236
InstantiatingGrpcChannelProvider.newBuilder()
237
.setEndpoint("your-service.googleapis.com:443")
238
.setChannelPoolSettings(poolSettings)
239
.setKeepAliveTime(Duration.ofMinutes(2))
240
.setKeepAliveTimeout(Duration.ofSeconds(30))
241
.build();
242
```
243
244
### Custom Channel Configuration
245
246
```java
247
import io.grpc.ManagedChannelBuilder;
248
import io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder;
249
250
// Advanced channel configuration with custom configurator
251
InstantiatingGrpcChannelProvider provider =
252
InstantiatingGrpcChannelProvider.newBuilder()
253
.setEndpoint("your-service.googleapis.com:443")
254
.setChannelConfigurator(channelBuilder -> {
255
return ((NettyChannelBuilder) channelBuilder)
256
.maxInboundMessageSize(4 * 1024 * 1024) // 4MB
257
.usePlaintext(); // For testing only
258
})
259
.build();
260
```
261
262
### DirectPath Configuration for Google Cloud
263
264
```java
265
import java.util.Map;
266
import java.util.HashMap;
267
268
// Configure DirectPath for optimized Google Cloud connections
269
Map<String, Object> directPathConfig = new HashMap<>();
270
directPathConfig.put("loadBalancingConfig",
271
List.of(Map.of("grpclb", Map.of("serviceName", "your-service"))));
272
273
InstantiatingGrpcChannelProvider provider =
274
InstantiatingGrpcChannelProvider.newBuilder()
275
.setEndpoint("your-service.googleapis.com:443")
276
.setDirectPathServiceConfig(directPathConfig)
277
.build();
278
```