0
# Channel Building
1

2
The `InProcessChannelBuilder` provides a fluent API for creating in-process channels that connect to servers within the same JVM process. It extends the standard gRPC channel builder with in-process specific optimizations.
3

4
## Capabilities
5

6
### Factory Methods
7

8
Create channel builders for different connection patterns.
9

10
```java { .api }
11
/**
12
 * Create a channel builder that will connect to the server with the given name.
13
 * @param name the identity of the server to connect to
14
 * @return a new builder
15
 */
16
public static InProcessChannelBuilder forName(String name);
17

18
/**
19
 * Create a channel builder that will connect to the server referenced by the given target URI.
20
 * Only intended for use with a custom name resolver.
21
 * @param target the identity of the server to connect to
22
 * @return a new builder
23
 */
24
public static InProcessChannelBuilder forTarget(String target);
25

26
/**
27
 * Create a channel builder that will connect to the server referenced by the given address.
28
 * @param address the address of the server to connect to
29
 * @return a new builder
30
 */
31
public static InProcessChannelBuilder forAddress(SocketAddress address);
32
```
33

34
**Usage Examples:**
35

36
```java
37
// Connect to named server
38
InProcessChannelBuilder builder1 = InProcessChannelBuilder.forName("test-server");
39

40
// Connect using target URI (for custom name resolvers)
41
InProcessChannelBuilder builder2 = InProcessChannelBuilder.forTarget("inprocess://my-service");
42

43
// Connect using socket address
44
InProcessSocketAddress address = new InProcessSocketAddress("service-name");
45
InProcessChannelBuilder builder3 = InProcessChannelBuilder.forAddress(address);
46
```
47

48
### Message Size Configuration
49

50
Configure message size limits and assumptions for performance optimization.
51

52
```java { .api }
53
/**
54
 * Sets the maximum size of inbound messages. Currently not enforced for in-process transport.
55
 * @param max the maximum message size in bytes
56
 * @return this builder
57
 */
58
public InProcessChannelBuilder maxInboundMessageSize(int max);
59

60
/**
61
 * Sets the maximum size of metadata allowed to be received.
62
 * @param bytes the maximum size of received metadata
63
 * @return this builder
64
 * @throws IllegalArgumentException if bytes is non-positive
65
 */
66
public InProcessChannelBuilder maxInboundMetadataSize(int bytes);
67

68
/**
69
 * Assumes RPC messages are the specified size to avoid serialization for metrics.
70
 * @param assumedMessageSize length of InProcess transport's messageSize
71
 * @return this builder
72
 * @throws IllegalArgumentException if assumedMessageSize is negative
73
 */
74
public InProcessChannelBuilder assumedMessageSize(long assumedMessageSize);
75
```
76

77
### Security Configuration
78

79
Security configuration methods (no-ops for in-process transport).
80

81
```java { .api }
82
/**
83
 * Does nothing for in-process transport.
84
 * @return this builder
85
 */
86
public InProcessChannelBuilder useTransportSecurity();
87

88
/**
89
 * Does nothing for in-process transport.
90
 * @return this builder
91
 */
92
public InProcessChannelBuilder usePlaintext();
93
```
94

95
### Keep-Alive Configuration
96

97
Keep-alive configuration methods (no-ops for in-process transport).
98

99
```java { .api }
100
/**
101
 * Does nothing for in-process transport.
102
 * @param keepAliveTime keep alive time value
103
 * @param timeUnit time unit for keep alive time
104
 * @return this builder
105
 */
106
public InProcessChannelBuilder keepAliveTime(long keepAliveTime, TimeUnit timeUnit);
107

108
/**
109
 * Does nothing for in-process transport.
110
 * @param keepAliveTimeout keep alive timeout value
111
 * @param timeUnit time unit for keep alive timeout
112
 * @return this builder
113
 */
114
public InProcessChannelBuilder keepAliveTimeout(long keepAliveTimeout, TimeUnit timeUnit);
115

116
/**
117
 * Does nothing for in-process transport.
118
 * @param enable whether to enable keep alive without calls
119
 * @return this builder
120
 */
121
public InProcessChannelBuilder keepAliveWithoutCalls(boolean enable);
122
```
123

124
### Executor Configuration
125

126
Configure custom executor services for the channel.
127

128
```java { .api }
129
/**
130
 * Provides a custom scheduled executor service.
131
 * @param scheduledExecutorService the scheduled executor service to use
132
 * @return this builder
133
 */
134
public InProcessChannelBuilder scheduledExecutorService(
135
    ScheduledExecutorService scheduledExecutorService);
136
```
137

138
### Debugging and Error Handling
139

140
Configure debugging and error propagation behavior.
141

142
```java { .api }
143
/**
144
 * Sets whether to include the cause with the status that is propagated forward.
145
 * By default, this is set to false for consistency with other transports.
146
 * @param enable whether to include cause in status
147
 * @return this builder
148
 */
149
public InProcessChannelBuilder propagateCauseWithStatus(boolean enable);
150
```
151

152
**Usage Example:**
153

154
```java
155
String serverName = "test-server";
156

157
Channel channel = InProcessChannelBuilder.forName(serverName)
158
    .maxInboundMetadataSize(4096)
159
    .assumedMessageSize(1024)
160
    .propagateCauseWithStatus(true) // For debugging
161
    .directExecutor() // Use direct executor for testing
162
    .build();
163

164
// Use the channel with gRPC stubs
165
MyServiceGrpc.MyServiceBlockingStub stub = 
166
    MyServiceGrpc.newBlockingStub(channel);
167
```
168

169
## Error Handling
170

171
- `IllegalArgumentException` - Thrown for invalid parameter values (negative sizes, null arguments)
172
- `UnsupportedOperationException` - Thrown when calling deprecated `forAddress(String, int)` method
173

174
## Thread Safety
175

176
`InProcessChannelBuilder` instances are **not thread-safe** during configuration. Each builder instance should be used by a single thread during the building phase. However, the resulting `ManagedChannel` instances are fully thread-safe and can be used concurrently by multiple threads.
177

178
## Performance Considerations
179

180
- Use `assumedMessageSize()` when you know typical message sizes to skip serialization for metrics
181
- The in-process transport automatically disables stats recording for optimal performance
182
- Custom executor services can be shared across multiple channels for resource efficiency