0
# Server Management
1

2
Core server lifecycle management, configuration, and listener control for creating and managing HTTP servers with multiple protocols and configurations.
3

4
## Capabilities
5

6
### WebServer Interface
7

8
The main server interface that manages listeners, lifecycles, and provides server control operations.
9

10
```java { .api }
11
/**
12
 * Server that opens server sockets and handles requests through routing.
13
 */
14
interface WebServer extends RuntimeType.Api<WebServerConfig> {
15
    /**
16
     * Create a new web server from its configuration.
17
     * @param serverConfig configuration
18
     * @return a new web server
19
     */
20
    static WebServer create(WebServerConfig serverConfig);
21
    
22
    /**
23
     * Create a new webserver customizing its configuration.
24
     * @param builderConsumer consumer of configuration builder
25
     * @return a new web server
26
     */
27
    static WebServer create(Consumer<WebServerConfig.Builder> builderConsumer);
28
    
29
    /**
30
     * A new builder to set up server.
31
     * @return builder
32
     */
33
    static WebServerConfig.Builder builder();
34
    
35
    /**
36
     * Starts the server. Has no effect if server is running.
37
     * @return a started server
38
     * @throws IllegalStateException when startup fails
39
     */
40
    WebServer start();
41
    
42
    /**
43
     * Attempt to gracefully shutdown the server.
44
     * @return a stopped server
45
     */
46
    WebServer stop();
47
    
48
    /**
49
     * Returns true if the server is currently running.
50
     * @return true if server is running
51
     */
52
    boolean isRunning();
53
    
54
    /**
55
     * Returns a port number the default server socket is bound to.
56
     * @return a listen port; or -1 if unknown or not active
57
     */
58
    default int port();
59
    
60
    /**
61
     * Returns a port number an additional named server socket is bound to.
62
     * @param socketName the name of an additional named server socket
63
     * @return a listen port; or -1 if socket name is unknown or not active
64
     */
65
    int port(String socketName);
66
    
67
    /**
68
     * Returns true if TLS is configured for the default socket.
69
     * @return whether TLS is enabled for the default socket
70
     */
71
    default boolean hasTls();
72
    
73
    /**
74
     * Returns true if TLS is configured for the named socket.
75
     * @param socketName the name of a socket
76
     * @return whether TLS is enabled for the socket
77
     */
78
    boolean hasTls(String socketName);
79
    
80
    /**
81
     * Context associated with the WebServer, used as a parent for listener contexts.
82
     * @return a server context
83
     */
84
    Context context();
85
    
86
    /**
87
     * Reload TLS keystore and truststore configuration for the default socket.
88
     * @param tls new TLS configuration
89
     */
90
    default void reloadTls(Tls tls);
91
    
92
    /**
93
     * Reload TLS keystore and truststore configuration for the named socket.
94
     * @param socketName socket name to reload TLS configuration on
95
     * @param tls new TLS configuration
96
     */
97
    void reloadTls(String socketName, Tls tls);
98
}
99
```
100

101
**Constants:**
102

103
```java { .api }
104
/**
105
 * The default server socket configuration name.
106
 * Value: "@default"
107
 */
108
String DEFAULT_SOCKET_NAME = "@default";
109
```
110

111
**Usage Examples:**
112

113
```java
114
import io.helidon.webserver.WebServer;
115
import io.helidon.webserver.http.HttpRouting;
116

117
// Create server with builder pattern
118
WebServer server = WebServer.builder()
119
    .port(8080)
120
    .routing(HttpRouting.builder()
121
        .get("/health", (req, res) -> res.send("OK"))
122
        .build())
123
    .build()
124
    .start();
125

126
// Create server with configuration consumer
127
WebServer server2 = WebServer.create(config -> 
128
    config.port(8081)
129
          .addNamedRouting("admin", HttpRouting.builder()
130
              .get("/metrics", (req, res) -> res.send("metrics"))
131
              .build())
132
);
133

134
// Server lifecycle management
135
if (!server.isRunning()) {
136
    server.start();
137
}
138

139
int port = server.port(); // Get default port
140
int adminPort = server.port("admin"); // Get named socket port
141

142
boolean tlsEnabled = server.hasTls(); // Check TLS status
143

144
// Graceful shutdown
145
server.stop();
146
```
147

148
### Router Interface
149

150
Generic router for handling multiple routing types and protocols within a single server instance.
151

152
```java { .api }
153
/**
154
 * Router for server. Contains routings of various types.
155
 */
156
interface Router {
157
    /**
158
     * Builder for router.
159
     * @return a new builder
160
     */
161
    static Builder builder();
162
    
163
    /**
164
     * Empty router.
165
     * @return new empty router
166
     */
167
    static Router empty();
168
    
169
    /**
170
     * Get routing of a specific type.
171
     * @param routingType type of the routing
172
     * @param defaultValue default value to use if routing not defined
173
     * @param <T> type of routing
174
     * @return routing defined or default value if not found
175
     */
176
    <T extends Routing> T routing(Class<T> routingType, T defaultValue);
177
    
178
    /**
179
     * This is called after server closes ports.
180
     */
181
    void afterStop();
182
    
183
    /**
184
     * This is called before server opens ports.
185
     */
186
    void beforeStart();
187
    
188
    /**
189
     * This is called after the server's listeners have successfully started.
190
     * @param webServer the WebServer that has successfully started
191
     */
192
    default void afterStart(WebServer webServer);
193
    
194
    /**
195
     * List of all configured routings.
196
     * @return all routings
197
     */
198
    List<? extends Routing> routings();
199
}
200
```
201

202
**Router Builder:**
203

204
```java { .api }
205
interface Router.Builder extends RouterBuilder<Builder>, io.helidon.common.Builder<Builder, Router> {
206
}
207

208
interface Router.RouterBuilder<B extends RouterBuilder<B>> {
209
    /**
210
     * Add a new routing to this router.
211
     * @param routing routing to add, such as HttpRouting
212
     * @return updated builder
213
     */
214
    B addRouting(io.helidon.common.Builder<?, ? extends Routing> routing);
215
    
216
    /**
217
     * List of all routing builders registered with this router builder.
218
     * @return routing builder list
219
     */
220
    List<io.helidon.common.Builder<?, ? extends Routing>> routings();
221
}
222
```
223

224
**Usage Examples:**
225

226
```java
227
import io.helidon.webserver.Router;
228
import io.helidon.webserver.http.HttpRouting;
229

230
// Create router with multiple routing types
231
Router router = Router.builder()
232
    .addRouting(HttpRouting.builder()
233
        .get("/api/*", (req, res) -> res.send("API"))
234
        .build())
235
    // Add other protocol routings here
236
    .build();
237

238
// Use router in server
239
WebServer server = WebServer.builder()
240
    .router(router)
241
    .build();
242
```
243

244
### Server Lifecycle Components
245

246
Supporting interfaces for server lifecycle management and context handling.
247

248
```java { .api }
249
/**
250
 * Interface for server listeners that handle connections.
251
 */
252
interface ServerListener {
253
    // Server listener methods
254
}
255

256
/**
257
 * Context for a connection to the server.
258
 */
259
interface ConnectionContext {
260
    // Connection context methods
261
}
262

263
/**
264
 * Context for a server listener.
265
 */
266
interface ListenerContext {
267
    // Listener context methods
268
}
269

270
/**
271
 * Lifecycle management for server components.
272
 */
273
interface ServerLifecycle {
274
    // Lifecycle methods
275
}
276

277
/**
278
 * Handler for server connections.
279
 */
280
interface ConnectionHandler {
281
    // Connection handler methods
282
}
283
```
284

285
### Server Utility Classes
286

287
Utility classes for server operations and management.
288

289
```java { .api }
290
/**
291
 * Utility for managing protocol configurations.
292
 */
293
class ProtocolConfigs {
294
    // Protocol configuration utilities
295
}
296

297
/**
298
 * Providers for server connections.
299
 */
300
class ConnectionProviders {
301
    // Connection provider utilities
302
}
303

304
/**
305
 * Executor implementation using virtual threads.
306
 */
307
class ThreadPerTaskExecutor {
308
    // Virtual thread executor implementation
309
}
310

311
/**
312
 * Factory for creating executors.
313
 */
314
class ExecutorsFactory {
315
    // Executor factory methods
316
}
317
```
318

319
### Exception Classes
320

321
Exception types for server lifecycle and connection management.
322

323
```java { .api }
324
/**
325
 * Exception to close a connection.
326
 */
327
class CloseConnectionException extends RuntimeException {
328
    public CloseConnectionException();
329
    public CloseConnectionException(String message);
330
    public CloseConnectionException(String message, Throwable cause);
331
}
332

333
/**
334
 * Exception related to server connections.
335
 */
336
class ServerConnectionException extends RuntimeException {
337
    public ServerConnectionException();
338
    public ServerConnectionException(String message);
339
    public ServerConnectionException(String message, Throwable cause);
340
}
341
```
342

343
### Support Classes
344

345
Additional support classes for server functionality.
346

347
```java { .api }
348
/**
349
 * Support for key performance indicators.
350
 */
351
class KeyPerformanceIndicatorSupport {
352
    // KPI support methods
353
}
354

355
/**
356
 * Data for proxy protocol handling.
357
 */
358
class ProxyProtocolData {
359
    // Proxy protocol data handling
360
}
361

362
/**
363
 * Handler for proxy protocol.
364
 */
365
class ProxyProtocolHandler {
366
    // Proxy protocol handling methods
367
}
368
```
369

370
## Advanced Usage
371

372
### Multiple Named Sockets
373

374
```java
375
WebServer server = WebServer.builder()
376
    .port(8080) // Default socket
377
    .addNamedSocket("admin", SocketConfig.builder()
378
        .port(8081)
379
        .tls(tlsConfig)
380
        .build())
381
    .routing(HttpRouting.builder()
382
        .get("/", (req, res) -> res.send("Main"))
383
        .build())
384
    .addNamedRouting("admin", HttpRouting.builder()
385
        .get("/health", (req, res) -> res.send("Healthy"))
386
        .build())
387
    .build();
388

389
server.start();
390

391
// Access different ports
392
int mainPort = server.port(); // 8080
393
int adminPort = server.port("admin"); // 8081
394
```
395

396
### TLS Configuration and Management
397

398
```java
399
import io.helidon.common.tls.Tls;
400

401
// Server with TLS
402
Tls tlsConfig = Tls.builder()
403
    .keystore(keystoreConfig)
404
    .truststore(truststoreConfig)
405
    .build();
406

407
WebServer server = WebServer.builder()
408
    .port(8443)
409
    .tls(tlsConfig)
410
    .routing(routing)
411
    .build()
412
    .start();
413

414
// Runtime TLS reload
415
Tls newTlsConfig = Tls.builder()
416
    .keystore(updatedKeystoreConfig)
417
    .build();
418

419
server.reloadTls(newTlsConfig); // Reload default socket TLS
420
server.reloadTls("admin", newTlsConfig); // Reload named socket TLS
421
```
422

423
### Server Context and Lifecycle
424

425
```java
426
// Access server context
427
Context serverContext = server.context();
428

429
// Custom lifecycle handling
430
Router customRouter = Router.builder()
431
    .addRouting(httpRouting)
432
    .build();
433

434
// Lifecycle callbacks are automatically called
435
WebServer server = WebServer.builder()
436
    .router(customRouter)
437
    .build();
438

439
server.start(); // Calls beforeStart(), then afterStart()
440
server.stop();  // Calls afterStop()
441
```