0
# Builders and Factories
1

2
gRPC Core provides internal builder implementations that serve as the foundation for creating managed channels and servers. These builders are extended by transport-specific modules to provide concrete implementations.
3

4
## Capabilities
5

6
### Managed Channel Builder
7

8
Internal implementation of the managed channel builder that provides the default channel creation logic.
9

10
```java { .api }
11
/**
12
 * Internal implementation of ManagedChannelBuilder
13
 * Located: io.grpc.internal.ManagedChannelImplBuilder
14
 */
15
class ManagedChannelImplBuilder extends ManagedChannelBuilder<ManagedChannelImplBuilder> {
16
    /**
17
     * Sets the target string for the channel
18
     * @param target The target string (e.g., "dns:///example.com:443")
19
     * @return This builder for method chaining
20
     */
21
    public ManagedChannelImplBuilder target(String target);
22
    
23
    /**
24
     * Sets the client transport factory for creating connections
25
     * @param clientTransportFactory Factory for creating client transports
26
     * @return This builder for method chaining
27
     */
28
    public ManagedChannelImplBuilder transportFactory(ClientTransportFactory clientTransportFactory);
29
    
30
    /**
31
     * Sets the default load balancing policy
32
     * @param policy The load balancing policy name
33
     * @return This builder for method chaining
34
     */
35
    public ManagedChannelImplBuilder defaultLoadBalancingPolicy(String policy);
36
    
37
    /**
38
     * Enables full stream decompression
39
     * @return This builder for method chaining
40
     */
41
    public ManagedChannelImplBuilder enableFullStreamDecompression();
42
    
43
    /**
44
     * Sets the maximum message size for inbound messages
45
     * @param maxInboundMessageSize Maximum size in bytes
46
     * @return This builder for method chaining
47
     */
48
    public ManagedChannelImplBuilder maxInboundMessageSize(int maxInboundMessageSize);
49
    
50
    /**
51
     * Sets the maximum metadata size for inbound messages
52
     * @param maxInboundMetadataSize Maximum size in bytes
53
     * @return This builder for method chaining
54
     */
55
    public ManagedChannelImplBuilder maxInboundMetadataSize(int maxInboundMetadataSize);
56
    
57
    /**
58
     * Sets the keep alive time
59
     * @param keepAliveTime The time to wait before sending keep alive
60
     * @param timeUnit Time unit for the keep alive time
61
     * @return This builder for method chaining
62
     */
63
    public ManagedChannelImplBuilder keepAliveTime(long keepAliveTime, TimeUnit timeUnit);
64
    
65
    /**
66
     * Sets the keep alive timeout
67
     * @param keepAliveTimeout Timeout for keep alive responses
68
     * @param timeUnit Time unit for the timeout
69
     * @return This builder for method chaining
70
     */
71
    public ManagedChannelImplBuilder keepAliveTimeout(long keepAliveTimeout, TimeUnit timeUnit);
72
    
73
    /**
74
     * Enables keep alive without calls
75
     * @param enable Whether to enable keep alive without active calls
76
     * @return This builder for method chaining
77
     */
78
    public ManagedChannelImplBuilder keepAliveWithoutCalls(boolean enable);
79
    
80
    /**
81
     * Sets the maximum connection idle time
82
     * @param maxConnectionIdle Time before closing idle connections
83
     * @param timeUnit Time unit for the idle time
84
     * @return This builder for method chaining
85
     */
86
    public ManagedChannelImplBuilder maxConnectionIdle(long maxConnectionIdle, TimeUnit timeUnit);
87
    
88
    /**
89
     * Sets the maximum connection age
90
     * @param maxConnectionAge Maximum age of connections
91
     * @param timeUnit Time unit for the age
92
     * @return This builder for method chaining
93
     */
94
    public ManagedChannelImplBuilder maxConnectionAge(long maxConnectionAge, TimeUnit timeUnit);
95
    
96
    /**
97
     * Sets the maximum connection age grace period
98
     * @param maxConnectionAgeGrace Grace period for connection age
99
     * @param timeUnit Time unit for the grace period
100
     * @return This builder for method chaining
101
     */
102
    public ManagedChannelImplBuilder maxConnectionAgeGrace(long maxConnectionAgeGrace, TimeUnit timeUnit);
103
    
104
    /**
105
     * Builds the managed channel
106
     * @return ManagedChannelImpl instance
107
     */
108
    public ManagedChannelImpl build();
109
}
110
```
111

112
**Usage Example:**
113

114
```java
115
import io.grpc.internal.ManagedChannelImplBuilder;
116
import io.grpc.internal.ClientTransportFactory;
117

118
// Used internally by transport modules
119
ManagedChannelImplBuilder builder = new ManagedChannelImplBuilder()
120
    .target("dns:///example.com:443")
121
    .transportFactory(transportFactory)
122
    .defaultLoadBalancingPolicy("pick_first")
123
    .maxInboundMessageSize(1024 * 1024)
124
    .keepAliveTime(30, TimeUnit.SECONDS);
125

126
ManagedChannel channel = builder.build();
127
```
128

129
### Server Builder
130

131
Internal implementation of the server builder that provides the default server creation logic.
132

133
```java { .api }
134
/**
135
 * Internal implementation of ServerBuilder
136
 * Located: io.grpc.internal.ServerImplBuilder
137
 */
138
class ServerImplBuilder extends ServerBuilder<ServerImplBuilder> {
139
    /**
140
     * Sets the transport server for accepting connections
141
     * @param transportServer Server transport implementation
142
     * @return This builder for method chaining
143
     */
144
    public ServerImplBuilder transportServer(io.grpc.internal.InternalServer transportServer);
145
    
146
    /**
147
     * Sets the executor for server operations
148
     * @param executor Executor for handling server tasks
149
     * @return This builder for method chaining
150
     */
151
    public ServerImplBuilder executor(Executor executor);
152
    
153
    /**
154
     * Sets the decompressor registry
155
     * @param decompressorRegistry Registry of available decompressors
156
     * @return This builder for method chaining
157
     */
158
    public ServerImplBuilder decompressorRegistry(DecompressorRegistry decompressorRegistry);
159
    
160
    /**
161
     * Sets the compressor registry
162
     * @param compressorRegistry Registry of available compressors
163
     * @return This builder for method chaining
164
     */
165
    public ServerImplBuilder compressorRegistry(CompressorRegistry compressorRegistry);
166
    
167
    /**
168
     * Sets the maximum message size for inbound messages
169
     * @param maxInboundMessageSize Maximum size in bytes
170
     * @return This builder for method chaining
171
     */
172
    public ServerImplBuilder maxInboundMessageSize(int maxInboundMessageSize);
173
    
174
    /**
175
     * Sets the maximum metadata size for inbound messages
176
     * @param maxInboundMetadataSize Maximum size in bytes
177
     * @return This builder for method chaining
178
     */
179
    public ServerImplBuilder maxInboundMetadataSize(int maxInboundMetadataSize);
180
    
181
    /**
182
     * Sets the maximum connection idle time
183
     * @param maxConnectionIdle Time before closing idle connections
184
     * @param timeUnit Time unit for the idle time
185
     * @return This builder for method chaining
186
     */
187
    public ServerImplBuilder maxConnectionIdle(long maxConnectionIdle, TimeUnit timeUnit);
188
    
189
    /**
190
     * Sets the maximum connection age
191
     * @param maxConnectionAge Maximum age of connections
192
     * @param timeUnit Time unit for the age
193
     * @return This builder for method chaining
194
     */
195
    public ServerImplBuilder maxConnectionAge(long maxConnectionAge, TimeUnit timeUnit);
196
    
197
    /**
198
     * Sets the maximum connection age grace period
199
     * @param maxConnectionAgeGrace Grace period for connection age
200
     * @param timeUnit Time unit for the grace period
201
     * @return This builder for method chaining
202
     */
203
    public ServerImplBuilder maxConnectionAgeGrace(long maxConnectionAgeGrace, TimeUnit timeUnit);
204
    
205
    /**
206
     * Sets the permit keep alive time
207
     * @param keepAliveTime Minimum time between keep alive pings
208
     * @param timeUnit Time unit for the keep alive time
209
     * @return This builder for method chaining
210
     */
211
    public ServerImplBuilder permitKeepAliveTime(long keepAliveTime, TimeUnit timeUnit);
212
    
213
    /**
214
     * Sets whether to permit keep alive without calls
215
     * @param permit Whether to permit keep alive without active calls
216
     * @return This builder for method chaining
217
     */
218
    public ServerImplBuilder permitKeepAliveWithoutCalls(boolean permit);
219
    
220
    /**
221
     * Builds the server
222
     * @return ServerImpl instance
223
     */
224
    public ServerImpl build();
225
}
226
```
227

228
**Usage Example:**
229

230
```java
231
import io.grpc.internal.ServerImplBuilder;
232
import io.grpc.internal.InternalServer;
233

234
// Used internally by transport modules
235
ServerImplBuilder builder = new ServerImplBuilder()
236
    .transportServer(transportServer)
237
    .executor(serverExecutor)
238
    .maxInboundMessageSize(2 * 1024 * 1024)
239
    .maxConnectionIdle(5, TimeUnit.MINUTES)
240
    .permitKeepAliveTime(5, TimeUnit.SECONDS);
241

242
Server server = builder.build();
243
```
244

245
### Client Transport Factory
246

247
Abstract factory interface for creating client transports.
248

249
```java { .api }
250
/**
251
 * Factory interface for creating client transports
252
 * Located: io.grpc.internal.ClientTransportFactory
253
 */
254
interface ClientTransportFactory {
255
    /**
256
     * Creates a new client transport for the given server address
257
     * @param serverAddress The server address to connect to
258
     * @param options Transport-specific options
259
     * @return New ClientTransport instance
260
     */
261
    ClientTransport newClientTransport(
262
        SocketAddress serverAddress,
263
        ClientTransportOptions options
264
    );
265
    
266
    /**
267
     * Gets the scheduled executor service for this factory
268
     * @return ScheduledExecutorService used by transports
269
     */
270
    ScheduledExecutorService getScheduledExecutorService();
271
    
272
    /**
273
     * Swaps the channel credentials for this factory
274
     * @param channelCreds New channel credentials
275
     * @return New factory instance with updated credentials
276
     */
277
    ClientTransportFactory swapChannelCredentials(ChannelCredentials channelCreds);
278
    
279
    /**
280
     * Swaps the call credentials for this factory
281
     * @param callCreds New call credentials
282
     * @return New factory instance with updated credentials
283
     */
284
    ClientTransportFactory swapCallCredentials(CallCredentials callCreds);
285
    
286
    /**
287
     * Closes the factory and releases resources
288
     */
289
    void close();
290
}
291
```
292

293
### Client Transport Options
294

295
Configuration options for client transports.
296

297
```java { .api }
298
/**
299
 * Options for configuring client transports
300
 * Located: io.grpc.internal.ClientTransportOptions
301
 */
302
class ClientTransportOptions {
303
    /**
304
     * Gets the authority to use for the connection
305
     * @return Authority string
306
     */
307
    public String getAuthority();
308
    
309
    /**
310
     * Gets the user agent string
311
     * @return User agent for the connection
312
     */
313
    public String getUserAgent();
314
    
315
    /**
316
     * Gets the attributes for the transport
317
     * @return Transport attributes
318
     */
319
    public Attributes getAttributes();
320
    
321
    /**
322
     * Gets the eager transport creation flag
323
     * @return true if transport should be created eagerly
324
     */
325
    public boolean getEagerTransportCreation();
326
    
327
    /**
328
     * Gets the HTTP connect timeout
329
     * @return Connect timeout duration
330
     */
331
    public long getHttpConnectTimeoutNanos();
332
    
333
    /**
334
     * Creates a new builder for transport options
335
     * @return ClientTransportOptions.Builder instance
336
     */
337
    public static Builder newBuilder();
338
    
339
    /**
340
     * Builder for ClientTransportOptions
341
     */
342
    public static class Builder {
343
        public Builder setAuthority(String authority);
344
        public Builder setUserAgent(String userAgent);
345
        public Builder setAttributes(Attributes attributes);
346
        public Builder setEagerTransportCreation(boolean eagerTransportCreation);
347
        public Builder setHttpConnectTimeoutNanos(long httpConnectTimeoutNanos);
348
        public ClientTransportOptions build();
349
    }
350
}
351
```
352

353
## Factory Usage Patterns
354

355
### Extending Transport Factories
356

357
Transport modules typically extend or implement these interfaces:
358

359
```java
360
// Netty transport example
361
public class NettyChannelBuilder extends AbstractManagedChannelImplBuilder<NettyChannelBuilder> {
362
    @Override
363
    protected ClientTransportFactory buildTransportFactory() {
364
        return new NettyTransportFactory(
365
            transportCreationParamsFilter,
366
            channelz,
367
            keepAliveManager,
368
            flowControlWindow,
369
            maxHeaderListSize
370
        );
371
    }
372
}
373
```
374

375
### Factory Lifecycle
376

377
1. **Creation**: Transport-specific builders create factory instances
378
2. **Configuration**: Factories are configured with credentials and options
379
3. **Transport Creation**: Factories create transport instances per connection
380
4. **Resource Management**: Factories manage shared resources like thread pools
381
5. **Cleanup**: Factories are closed when channels/servers shut down
382

383
## Error Handling
384

385
Builders and factories handle errors through:
386

387
- **Validation**: Invalid configurations throw `IllegalArgumentException`
388
- **State Checking**: Operations on closed resources throw `IllegalStateException`
389
- **Transport Errors**: Connection failures are propagated as gRPC Status errors
390
- **Resource Cleanup**: Automatic cleanup of resources on shutdown