0
# Channel Building
1

2
Client-side channel creation and configuration using Netty transport. The `NettyChannelBuilder` provides comprehensive options for connection tuning, security configuration, and advanced Netty features.
3

4
## Capabilities
5

6
### NettyChannelBuilder Factory Methods
7

8
Create `NettyChannelBuilder` instances for different target types.
9

10
```java { .api }
11
/**
12
 * Create a channel builder for a specific host and port
13
 * @param host The target host
14
 * @param port The target port
15
 * @return NettyChannelBuilder for configuration
16
 */
17
public static NettyChannelBuilder forAddress(String host, int port);
18

19
/**
20
 * Create a channel builder for a host and port with credentials
21
 */
22
public static NettyChannelBuilder forAddress(String host, int port, ChannelCredentials creds);
23

24
/**
25
 * Create a channel builder for a socket address
26
 * @param serverAddress The target socket address
27
 * @return NettyChannelBuilder for configuration
28
 */
29
public static NettyChannelBuilder forAddress(SocketAddress serverAddress);
30

31
/**
32
 * Create a channel builder for a socket address with credentials
33
 */
34
public static NettyChannelBuilder forAddress(SocketAddress serverAddress, ChannelCredentials creds);
35

36
/**
37
 * Create a channel builder for a target string (supports service discovery)
38
 * @param target The target string (e.g., "dns:///example.com:443")
39
 * @return NettyChannelBuilder for configuration
40
 */
41
public static NettyChannelBuilder forTarget(String target);
42

43
/**
44
 * Create a channel builder for a target string with credentials
45
 */
46
public static NettyChannelBuilder forTarget(String target, ChannelCredentials creds);
47
```
48

49
**Usage Examples:**
50

51
```java
52
import io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder;
53
import io.grpc.InsecureChannelCredentials;
54

55
// Basic channel
56
NettyChannelBuilder builder = NettyChannelBuilder.forAddress("localhost", 9090);
57

58
// Channel with credentials
59
NettyChannelBuilder secureBuilder = NettyChannelBuilder.forAddress(
60
    "secure-service.example.com", 443, 
61
    InsecureChannelCredentials.create()
62
);
63

64
// Service discovery
65
NettyChannelBuilder discoveryBuilder = NettyChannelBuilder.forTarget("dns:///service.local:8080");
66
```
67

68
### Channel Type Configuration
69

70
Configure the underlying Netty channel type and factory.
71

72
```java { .api }
73
/**
74
 * Set the channel type for the client connection
75
 * @param channelType The Netty channel class to use
76
 * @return This builder for chaining
77
 */
78
public NettyChannelBuilder channelType(Class<? extends Channel> channelType);
79

80
/**
81
 * Set the channel type with transport socket type
82
 */
83
public NettyChannelBuilder channelType(
84
    Class<? extends Channel> channelType, 
85
    Class<? extends SocketAddress> transportSocketType);
86

87
/**
88
 * Set a custom channel factory
89
 * @param channelFactory Factory for creating channels
90
 * @return This builder for chaining
91
 */
92
public NettyChannelBuilder channelFactory(ChannelFactory<? extends Channel> channelFactory);
93

94
/**
95
 * Set a custom channel factory with transport socket type
96
 */
97
public NettyChannelBuilder channelFactory(
98
    ChannelFactory<? extends Channel> channelFactory, 
99
    Class<? extends SocketAddress> transportSocketType);
100
```
101

102
### Event Loop Configuration
103

104
Configure Netty event loop groups for the channel.
105

106
```java { .api }
107
/**
108
 * Set the event loop group for the channel
109
 * @param eventLoopGroup The EventLoopGroup to use (null for default)
110
 * @return This builder for chaining
111
 */
112
public NettyChannelBuilder eventLoopGroup(EventLoopGroup eventLoopGroup);
113
```
114

115
**Usage Example:**
116

117
```java
118
import io.grpc.netty.shaded.io.netty.channel.nio.NioEventLoopGroup;
119
import io.grpc.netty.shaded.io.netty.channel.socket.nio.NioSocketChannel;
120

121
EventLoopGroup eventLoopGroup = new NioEventLoopGroup(4);
122

123
NettyChannelBuilder builder = NettyChannelBuilder
124
    .forAddress("localhost", 9090)
125
    .channelType(NioSocketChannel.class)
126
    .eventLoopGroup(eventLoopGroup);
127
```
128

129
### Channel Options
130

131
Configure Netty channel options.
132

133
```java { .api }
134
/**
135
 * Set a Netty channel option
136
 * @param option The channel option to set
137
 * @param value The value for the option
138
 * @return This builder for chaining
139
 */
140
public <T> NettyChannelBuilder withOption(ChannelOption<T> option, T value);
141
```
142

143
**Usage Example:**
144

145
```java
146
import io.grpc.netty.shaded.io.netty.channel.ChannelOption;
147

148
NettyChannelBuilder builder = NettyChannelBuilder
149
    .forAddress("localhost", 9090)
150
    .withOption(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000)
151
    .withOption(ChannelOption.SO_KEEPALIVE, true);
152
```
153

154
### Security Configuration
155

156
Configure security and protocol negotiation.
157

158
```java { .api }
159
/**
160
 * Set the negotiation type for the connection
161
 * @param type The negotiation type to use
162
 * @return This builder for chaining
163
 */
164
public NettyChannelBuilder negotiationType(NegotiationType type);
165

166
/**
167
 * Set a custom SSL context
168
 * @param sslContext The Netty SSL context
169
 * @return This builder for chaining
170
 */
171
public NettyChannelBuilder sslContext(SslContext sslContext);
172

173
/**
174
 * Use plaintext connection (no encryption)
175
 * @return This builder for chaining
176
 */
177
public NettyChannelBuilder usePlaintext();
178

179
/**
180
 * Use transport security (TLS encryption)
181
 * @return This builder for chaining
182
 */
183
public NettyChannelBuilder useTransportSecurity();
184
```
185

186
### Flow Control Configuration
187

188
Configure HTTP/2 flow control settings.
189

190
```java { .api }
191
/**
192
 * Set the initial flow control window size
193
 * @param initialFlowControlWindow Initial window size in bytes
194
 * @return This builder for chaining
195
 */
196
public NettyChannelBuilder initialFlowControlWindow(int initialFlowControlWindow);
197

198
/**
199
 * Set the flow control window size
200
 * @param flowControlWindow Window size in bytes
201
 * @return This builder for chaining
202
 */
203
public NettyChannelBuilder flowControlWindow(int flowControlWindow);
204
```
205

206
**Usage Example:**
207

208
```java
209
NettyChannelBuilder builder = NettyChannelBuilder
210
    .forAddress("localhost", 9090)
211
    .initialFlowControlWindow(1024 * 1024)  // 1 MB
212
    .flowControlWindow(2 * 1024 * 1024);    // 2 MB
213
```
214

215
### Message and Metadata Limits
216

217
Configure size limits for messages and metadata.
218

219
```java { .api }
220
/**
221
 * Set the maximum inbound metadata size
222
 * @param bytes Maximum metadata size in bytes
223
 * @return This builder for chaining
224
 */
225
public NettyChannelBuilder maxInboundMetadataSize(int bytes);
226

227
/**
228
 * Set soft and hard limits for inbound metadata size
229
 */
230
public NettyChannelBuilder maxInboundMetadataSize(int soft, int max);
231

232
/**
233
 * Set the maximum inbound message size
234
 * @param max Maximum message size in bytes
235
 * @return This builder for chaining
236
 */
237
public NettyChannelBuilder maxInboundMessageSize(int max);
238

239
/**
240
 * Set the maximum header list size (deprecated)
241
 * @param maxHeaderListSize Maximum header list size in bytes
242
 * @return This builder for chaining
243
 * @deprecated Use maxInboundMetadataSize(int) instead
244
 */
245
@Deprecated
246
public NettyChannelBuilder maxHeaderListSize(int maxHeaderListSize);
247
```
248

249
### Keep-Alive Configuration
250

251
Configure connection keep-alive behavior.
252

253
```java { .api }
254
/**
255
 * Set the keep-alive time
256
 * @param keepAliveTime Time between keep-alive pings
257
 * @param timeUnit Time unit for keepAliveTime
258
 * @return This builder for chaining
259
 */
260
public NettyChannelBuilder keepAliveTime(long keepAliveTime, TimeUnit timeUnit);
261

262
/**
263
 * Set the keep-alive timeout
264
 * @param keepAliveTimeout Timeout for keep-alive response
265
 * @param timeUnit Time unit for keepAliveTimeout
266
 * @return This builder for chaining
267
 */
268
public NettyChannelBuilder keepAliveTimeout(long keepAliveTimeout, TimeUnit timeUnit);
269

270
/**
271
 * Enable/disable keep-alive without active calls
272
 * @param enable Whether to send keep-alive when no calls are active
273
 * @return This builder for chaining
274
 */
275
public NettyChannelBuilder keepAliveWithoutCalls(boolean enable);
276
```
277

278
**Usage Example:**
279

280
```java
281
import java.util.concurrent.TimeUnit;
282

283
NettyChannelBuilder builder = NettyChannelBuilder
284
    .forAddress("localhost", 9090)
285
    .keepAliveTime(30, TimeUnit.SECONDS)
286
    .keepAliveTimeout(5, TimeUnit.SECONDS)
287
    .keepAliveWithoutCalls(true);
288
```
289

290
### Advanced Configuration
291

292
Advanced configuration options for specialized use cases.
293

294
```java { .api }
295
/**
296
 * Set a custom local socket picker
297
 * @param localSocketPicker Picker for local socket addresses
298
 * @return This builder for chaining
299
 */
300
public NettyChannelBuilder localSocketPicker(LocalSocketPicker localSocketPicker);
301

302
/**
303
 * Local socket picker for custom socket address selection
304
 */
305
public static class LocalSocketPicker {
306
    /**
307
     * Create a local socket address for the given remote address
308
     * @param remoteAddress The remote address being connected to
309
     * @param attrs Connection attributes
310
     * @return Local socket address or null for default
311
     */
312
    @Nullable
313
    public SocketAddress createSocketAddress(
314
        SocketAddress remoteAddress, 
315
        @EquivalentAddressGroup.Attr Attributes attrs);
316
}
317
```
318

319
## Constants
320

321
```java { .api }
322
/**
323
 * Default flow control window size (1 MiB)
324
 */
325
public static final int DEFAULT_FLOW_CONTROL_WINDOW = 1024 * 1024;
326
```