0
# Server Core APIs
1

2
The core server APIs provide the foundation for creating and managing HTTP servers, including server lifecycle, connector management, and basic configuration.
3

4
## Server Class
5

6
The `Server` class is the central component that coordinates all server functionality.
7

8
```java { .api }
9
public class Server extends Handler.Wrapper implements Attributes {
10
    // Constructors
11
    public Server();
12
    public Server(int port);
13
    public Server(InetSocketAddress addr);
14
    public Server(ThreadPool threadPool);
15
    public Server(ThreadPool threadPool, Scheduler scheduler, ByteBufferPool bufferPool);
16
    
17
    // Version and identification
18
    public static String getVersion();
19
    public URI getURI();
20
    public Context getContext();
21
    
22
    // Lifecycle management
23
    public void start() throws Exception;
24
    public void stop() throws Exception;
25
    public void join() throws InterruptedException;
26
    public boolean getStopAtShutdown();
27
    public void setStopAtShutdown(boolean stop);
28
    public long getStopTimeout();
29
    public void setStopTimeout(long stopTimeout);
30
    
31
    // Component access
32
    public ThreadPool getThreadPool();
33
    public Scheduler getScheduler();
34
    public ByteBufferPool getByteBufferPool();
35
    
36
    // Connector management
37
    public Connector[] getConnectors();
38
    public void addConnector(Connector connector);
39
    public void removeConnector(Connector connector);
40
    public void setConnectors(Connector[] connectors);
41
    
42
    // Handler management
43
    public Handler getHandler();
44
    public void setHandler(Handler handler);
45
    public Handler getDefaultHandler();
46
    public void setDefaultHandler(Handler defaultHandler);
47
    public Request.Handler getErrorHandler();
48
    public void setErrorHandler(Request.Handler errorHandler);
49
    
50
    // Request logging
51
    public RequestLog getRequestLog();
52
    public void setRequestLog(RequestLog requestLog);
53
    
54
    // Configuration
55
    public File getTempDirectory();
56
    public void setTempDirectory(File temp);
57
    public MimeTypes.Mutable getMimeTypes();
58
}
59
```
60

61
## Usage Examples
62

63
### Basic Server Setup
64

65
```java
66
// Create server with default configuration
67
Server server = new Server();
68

69
// Create server with specific port
70
Server server = new Server(8080);
71

72
// Create server with address binding
73
InetSocketAddress addr = new InetSocketAddress("localhost", 8080);
74
Server server = new Server(addr);
75

76
// Create server with custom thread pool
77
QueuedThreadPool threadPool = new QueuedThreadPool(200);
78
Server server = new Server(threadPool);
79
```
80

81
### Server Lifecycle Management
82

83
```java
84
Server server = new Server(8080);
85

86
// Configure handlers and connectors before starting
87
server.setHandler(myHandler);
88

89
try {
90
    // Start the server
91
    server.start();
92
    System.out.println("Server started on: " + server.getURI());
93
    
94
    // Wait for server to finish (blocks until stopped)
95
    server.join();
96
} catch (Exception e) {
97
    System.err.println("Server failed to start: " + e.getMessage());
98
} finally {
99
    // Ensure cleanup
100
    server.stop();
101
}
102
```
103

104
### Graceful Shutdown Configuration
105

106
```java
107
Server server = new Server(8080);
108

109
// Configure shutdown behavior
110
server.setStopAtShutdown(true);  // Stop server on JVM shutdown
111
server.setStopTimeout(30000);    // 30 second timeout for graceful stop
112

113
// Add shutdown hook for clean shutdown
114
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
115
    try {
116
        server.stop();
117
    } catch (Exception e) {
118
        System.err.println("Error during shutdown: " + e.getMessage());
119
    }
120
}));
121
```
122

123
## ServerConnector
124

125
The `ServerConnector` is the default implementation for HTTP network connections.
126

127
```java { .api }
128
public class ServerConnector extends AbstractNetworkConnector {
129
    // Constructors
130
    public ServerConnector(Server server);
131
    public ServerConnector(Server server, ConnectionFactory... factories);
132
    public ServerConnector(Server server, Executor executor, Scheduler scheduler, 
133
                          ByteBufferPool bufferPool, int acceptors, int selectors, 
134
                          ConnectionFactory... factories);
135
    
136
    // Network configuration
137
    public void setHost(String host);
138
    public String getHost();
139
    public void setPort(int port);
140
    public int getPort();
141
    public int getLocalPort();
142
    
143
    // Connection handling
144
    public int getAcceptors();
145
    public void setAcceptors(int acceptors);
146
    public SelectorManager getSelectorManager();
147
    
148
    // Socket configuration
149
    public void setReuseAddress(boolean reuseAddress);
150
    public boolean getReuseAddress();
151
    public void setInheritChannel(boolean inheritChannel);
152
    public boolean isInheritChannel();
153
    public void setAcceptedTcpNoDelay(boolean tcpNoDelay);
154
    public boolean getAcceptedTcpNoDelay();
155
    public void setAcceptedReceiveBufferSize(int size);
156
    public int getAcceptedReceiveBufferSize();
157
    public void setAcceptedSendBufferSize(int size);
158
    public int getAcceptedSendBufferSize();
159
}
160
```
161

162
## Connector Interface
163

164
Base interface for all server connectors.
165

166
```java { .api }
167
public interface Connector extends LifeCycle, Container, Graceful {
168
    // Server association
169
    Server getServer();
170
    void setServer(Server server);
171
    
172
    // Core components
173
    Executor getExecutor();
174
    Scheduler getScheduler();
175
    ByteBufferPool getByteBufferPool();
176
    
177
    // Protocol factories
178
    ConnectionFactory getConnectionFactory(String protocol);
179
    ConnectionFactory getConnectionFactory(Class<? extends Connection> factoryType);
180
    Collection<ConnectionFactory> getConnectionFactories();
181
    void addConnectionFactory(ConnectionFactory factory);
182
    void removeConnectionFactory(String protocol);
183
    void setDefaultProtocol(String protocol);
184
    String getDefaultProtocol();
185
    List<String> getProtocols();
186
    
187
    // Statistics and monitoring
188
    long getBytesIn();
189
    long getBytesOut();
190
    long getConnections();
191
    long getMessagesIn();
192
    long getMessagesOut();
193
    long getConnectionsOpen();
194
    long getConnectionsOpenMax();
195
    Duration getConnectionsOpenMax();
196
}
197
```
198

199
## Usage Examples
200

201
### Connector Configuration
202

203
```java
204
Server server = new Server();
205

206
// Create HTTP connector
207
ServerConnector httpConnector = new ServerConnector(server);
208
httpConnector.setHost("localhost");
209
httpConnector.setPort(8080);
210
httpConnector.setAcceptors(2);  // Number of acceptor threads
211

212
// Create HTTPS connector  
213
HttpConfiguration httpsConfig = new HttpConfiguration();
214
httpsConfig.addCustomizer(new SecureRequestCustomizer());
215

216
SslContextFactory.Server sslContextFactory = new SslContextFactory.Server();
217
sslContextFactory.setKeyStorePath("keystore.jks");
218
sslContextFactory.setKeyStorePassword("password");
219

220
ServerConnector httpsConnector = new ServerConnector(server,
221
    new SslConnectionFactory(sslContextFactory, "http/1.1"),
222
    new HttpConnectionFactory(httpsConfig));
223
httpsConnector.setPort(8443);
224

225
// Add connectors to server
226
server.setConnectors(new Connector[]{httpConnector, httpsConnector});
227
```
228

229
### Multiple Protocol Support
230

231
```java
232
Server server = new Server();
233

234
HttpConfiguration config = new HttpConfiguration();
235

236
// HTTP/1.1 and HTTP/2 connector
237
ServerConnector connector = new ServerConnector(server,
238
    new HttpConnectionFactory(config),
239
    new HTTP2ServerConnectionFactory(config));
240
    
241
connector.setPort(8080);
242
server.addConnector(connector);
243
```
244

245
## Network Connectors
246

247
### AbstractNetworkConnector
248

249
Base class for network-based connectors.
250

251
```java { .api }
252
public abstract class AbstractNetworkConnector extends AbstractConnector implements NetworkConnector {
253
    // Network interface configuration
254
    public void setHost(String host);
255
    public String getHost();
256
    public void setPort(int port);
257
    public int getPort();
258
    public int getLocalPort();
259
    
260
    // Lifecycle
261
    public void open() throws IOException;
262
    public void close() throws IOException;
263
    public boolean isOpen();
264
}
265
```
266

267
### NetworkConnector Interface
268

269
```java { .api }
270
public interface NetworkConnector extends Connector, Closeable {
271
    void open() throws IOException;
272
    void close() throws IOException;
273
    boolean isOpen();
274
    int getLocalPort();
275
    String getHost();
276
    int getPort();
277
    void setHost(String host);
278
    void setPort(int port);
279
}
280
```
281

282
## Special Connectors
283

284
### LocalConnector
285

286
In-memory connector for testing and embedded usage.
287

288
```java { .api }
289
public class LocalConnector extends AbstractConnector {
290
    public LocalConnector(Server server);
291
    public LocalConnector(Server server, ConnectionFactory... factories);
292
    
293
    // Request execution
294
    public LocalEndPoint executeRequest(String rawRequest);
295
    public String getResponse(String rawRequest);
296
    public String getResponse(String rawRequest, boolean head, long time, TimeUnit unit);
297
}
298
```
299

300
### Usage Example
301

302
```java
303
// Create server with local connector for testing
304
Server server = new Server();
305
LocalConnector localConnector = new LocalConnector(server);
306
server.addConnector(localConnector);
307

308
server.setHandler(new Handler.Abstract() {
309
    @Override
310
    public boolean handle(Request request, Response response, Callback callback) throws Exception {
311
        response.setStatus(200);
312
        response.getHeaders().put("Content-Type", "text/plain");
313
        response.write(true, "Hello Test!".getBytes(), callback);
314
        return true;
315
    }
316
});
317

318
server.start();
319

320
// Execute request directly
321
String response = localConnector.getResponse("GET / HTTP/1.1\r\nHost: localhost\r\n\r\n");
322
System.out.println("Response: " + response);
323
```
324

325
## Components Interface
326

327
Provides access to core server components.
328

329
```java { .api }
330
public interface Components {
331
    ByteBufferPool getByteBufferPool();
332
    Scheduler getScheduler();
333
    Executor getExecutor();
334
    InvocationType getInvocationType();
335
}
336
```