0
# Server Building
1

2
The `InProcessServerBuilder` provides a fluent API for creating in-process servers that can be identified by name or address. It extends the standard gRPC server builder with in-process specific configurations and optimizations.
3

4
## Capabilities
5

6
### Factory Methods
7

8
Create server builders for different identification patterns.
9

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

18
/**
19
 * Create a server builder which listens on the given address.
20
 * @param listenAddress The SocketAddress this server will listen on
21
 * @return a new builder
22
 */
23
public static InProcessServerBuilder forAddress(SocketAddress listenAddress);
24

25
/**
26
 * Generates a new server name that is unique each time.
27
 * @return a unique server name (UUID string)
28
 */
29
public static String generateName();
30
```
31

32
**Usage Examples:**
33

34
```java
35
// Create named server
36
InProcessServerBuilder builder1 = InProcessServerBuilder.forName("my-service");
37

38
// Create server with socket address
39
InProcessSocketAddress address = new InProcessSocketAddress("service-name");
40
InProcessServerBuilder builder2 = InProcessServerBuilder.forAddress(address);
41

42
// Generate unique name for testing
43
String uniqueName = InProcessServerBuilder.generateName();
44
InProcessServerBuilder builder3 = InProcessServerBuilder.forName(uniqueName);
45
```
46

47
### Metadata Configuration
48

49
Configure metadata size limits for the server.
50

51
```java { .api }
52
/**
53
 * Sets the maximum size of metadata allowed to be received.
54
 * @param bytes the maximum size of received metadata
55
 * @return this builder
56
 * @throws IllegalArgumentException if bytes is non-positive
57
 */
58
public InProcessServerBuilder maxInboundMetadataSize(int bytes);
59
```
60

61
### Executor Configuration
62

63
Configure custom executor services and deadline handling.
64

65
```java { .api }
66
/**
67
 * Provides a custom scheduled executor service.
68
 * @param scheduledExecutorService the scheduled executor service to use
69
 * @return this builder
70
 */
71
public InProcessServerBuilder scheduledExecutorService(
72
    ScheduledExecutorService scheduledExecutorService);
73

74
/**
75
 * Provides a custom deadline ticker for creating incoming Deadlines.
76
 * Intended for unit tests that fake out the clock. DO NOT use in production.
77
 * @param ticker the deadline ticker to use
78
 * @return this builder
79
 */
80
public InProcessServerBuilder deadlineTicker(Deadline.Ticker ticker);
81
```
82

83
### Unsupported Security Configuration
84

85
Security-related methods that are not supported for in-process transport.
86

87
```java { .api }
88
/**
89
 * TLS is not supported in InProcessServer.
90
 * @param certChain certificate chain file
91
 * @param privateKey private key file
92
 * @return this builder
93
 * @throws UnsupportedOperationException always thrown
94
 */
95
public InProcessServerBuilder useTransportSecurity(File certChain, File privateKey);
96
```
97

98
**Complete Usage Example:**
99

100
```java
101
import io.grpc.inprocess.InProcessServerBuilder;
102
import io.grpc.Server;
103
import java.util.concurrent.TimeUnit;
104

105
// Generate unique name for testing
106
String serverName = InProcessServerBuilder.generateName();
107

108
// Build and start server
109
Server server = InProcessServerBuilder.forName(serverName)
110
    .addService(new MyGrpcServiceImpl()) // Add your gRPC service implementations
111
    .addService(new AnotherServiceImpl())
112
    .maxInboundMetadataSize(8192) // Set metadata size limit
113
    .directExecutor() // Use direct executor for testing
114
    .build();
115

116
// Start the server
117
server.start();
118

119
// Server is now available for in-process connections using serverName
120

121
// Shutdown gracefully
122
server.shutdown();
123
try {
124
    if (!server.awaitTermination(5, TimeUnit.SECONDS)) {
125
        server.shutdownNow();
126
    }
127
} catch (InterruptedException e) {
128
    server.shutdownNow();
129
    Thread.currentThread().interrupt();
130
}
131
```
132

133
**Testing Pattern:**
134

135
```java
136
import org.junit.jupiter.api.AfterEach;
137
import org.junit.jupiter.api.BeforeEach;
138
import org.junit.jupiter.api.Test;
139

140
public class MyServiceTest {
141
    private Server server;
142
    private Channel channel;
143
    private String serverName;
144

145
    @BeforeEach
146
    void setUp() throws Exception {
147
        // Generate unique server name for each test
148
        serverName = InProcessServerBuilder.generateName();
149
        
150
        // Create and start server
151
        server = InProcessServerBuilder.forName(serverName)
152
            .directExecutor()
153
            .addService(new MyServiceImpl())
154
            .build()
155
            .start();
156
        
157
        // Create client channel
158
        channel = InProcessChannelBuilder.forName(serverName)
159
            .directExecutor()
160
            .build();
161
    }
162

163
    @AfterEach
164
    void tearDown() throws Exception {
165
        if (channel instanceof ManagedChannel) {
166
            ((ManagedChannel) channel).shutdownNow();
167
        }
168
        if (server != null) {
169
            server.shutdownNow();
170
        }
171
    }
172

173
    @Test
174
    void testMyService() {
175
        MyServiceGrpc.MyServiceBlockingStub stub = 
176
            MyServiceGrpc.newBlockingStub(channel);
177
        
178
        MyResponse response = stub.myMethod(
179
            MyRequest.newBuilder().setMessage("test").build()
180
        );
181
        
182
        assertThat(response.getResult()).isEqualTo("expected");
183
    }
184
}
185
```
186

187
## Error Handling
188

189
- `IllegalArgumentException` - Thrown for invalid parameter values (non-positive metadata size, null arguments)
190
- `UnsupportedOperationException` - Thrown when calling deprecated `forPort()` method or `useTransportSecurity()`
191
- `IOException` - Can be thrown during server startup if name registration fails
192

193
## Server Lifecycle
194

195
1. **Creation**: Use factory methods to create builder
196
2. **Configuration**: Set services, executors, and limits
197
3. **Build**: Call `build()` to create server instance
198
4. **Start**: Call `start()` to register server and accept connections
199
5. **Shutdown**: Call `shutdown()` followed by `awaitTermination()` for graceful shutdown
200

201
## Thread Safety
202

203
`InProcessServerBuilder` instances are **not thread-safe** during configuration. Each builder instance should be used by a single thread during the building phase. However, the resulting `Server` instances are fully thread-safe and can handle concurrent requests from multiple threads.
204

205
## Performance Considerations
206

207
- Use `generateName()` for test servers to avoid naming conflicts
208
- The in-process transport automatically disables stats recording for optimal performance
209
- Custom executor services can be shared across multiple servers for resource efficiency
210
- Set appropriate metadata size limits to prevent excessive memory usage