0
# Eclipse Jetty Server
1

2
Eclipse Jetty Server is the core HTTP server component of the Eclipse Jetty web server. It provides a comprehensive API for building HTTP servers, handling HTTP requests and responses, managing connections, and serving static and dynamic content. The server supports HTTP/1.1, HTTP/2, and HTTP/3 protocols with extensive configuration options and handler-based request processing.
3

4
## Package Information
5

6
- **Package Name**: org.eclipse.jetty:jetty-server
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add Maven dependency
10

11
```xml
12
<dependency>
13
    <groupId>org.eclipse.jetty</groupId>
14
    <artifactId>jetty-server</artifactId>
15
    <version>12.0.21</version>
16
</dependency>
17
```
18

19
## Core Imports
20

21
```java
22
// Core server classes
23
import org.eclipse.jetty.server.Server;
24
import org.eclipse.jetty.server.ServerConnector;
25
import org.eclipse.jetty.server.HttpConnectionFactory;
26
import org.eclipse.jetty.server.HttpConfiguration;
27

28
// Handler interfaces and implementations
29
import org.eclipse.jetty.server.Handler;
30
import org.eclipse.jetty.server.Request;
31
import org.eclipse.jetty.server.Response;
32
import org.eclipse.jetty.util.Callback;
33

34
// Context and resource handling
35
import org.eclipse.jetty.server.handler.ContextHandler;
36
import org.eclipse.jetty.server.handler.ResourceHandler;
37

38
// Optional components
39
import org.eclipse.jetty.server.handler.gzip.GzipHandler;
40
```
41

42
## Basic Usage
43

44
```java
45
import org.eclipse.jetty.server.Server;
46
import org.eclipse.jetty.server.ServerConnector;
47
import org.eclipse.jetty.server.Handler;
48
import org.eclipse.jetty.server.Request;
49
import org.eclipse.jetty.server.Response;
50
import org.eclipse.jetty.util.Callback;
51

52
public class SimpleJettyServer {
53
    public static void main(String[] args) throws Exception {
54
        // Create server instance
55
        Server server = new Server();
56
        
57
        // Create and configure HTTP connector
58
        ServerConnector connector = new ServerConnector(server);
59
        connector.setPort(8080);
60
        server.addConnector(connector);
61
        
62
        // Create a simple handler
63
        Handler handler = new Handler.Abstract() {
64
            @Override
65
            public boolean handle(Request request, Response response, Callback callback) 
66
                    throws Exception {
67
                response.setStatus(200);
68
                response.getHeaders().put("Content-Type", "text/plain");
69
                response.write(true, "Hello, Jetty!".getBytes(), callback);
70
                return true;
71
            }
72
        };
73
        
74
        server.setHandler(handler);
75
        
76
        // Start the server
77
        server.start();
78
        server.join(); // Wait for server to finish
79
    }
80
}
81
```
82

83
## Architecture
84

85
Eclipse Jetty Server follows a component-based architecture with these key concepts:
86

87
### Core Components
88

89
- **Server**: Central coordinator that manages connectors, handlers, and lifecycle
90
- **Connector**: Manages network connections and protocol support (HTTP/1.1, HTTP/2, HTTP/3)
91
- **Handler**: Processes HTTP requests in a chain-of-responsibility pattern
92
- **Request/Response**: Interfaces representing HTTP request and response with lifecycle callbacks
93

94
### Request Processing Flow
95

96
1. **Connection**: Connector accepts network connections and creates protocol-specific connections
97
2. **Request Parsing**: Connection parses HTTP protocol into Request objects
98
3. **Handler Chain**: Server delegates requests through handler chain for processing
99
4. **Response Generation**: Handlers generate responses through Response interface
100
5. **Completion**: Callback mechanism signals request completion and cleanup
101

102
### Threading Model
103

104
- **Acceptor Threads**: Accept new connections (configurable count)
105
- **Selector Threads**: Manage I/O operations on connections (NIO-based)
106
- **Handler Threads**: Execute request processing logic (from thread pool)
107
- **Async Support**: Non-blocking I/O with callback-based completion
108

109
## Capabilities
110

111
### Server Core
112

113
Core server functionality including server lifecycle, connector management, and basic configuration.
114

115
```java { .api }
116
public final class Server extends Handler.Wrapper implements Attributes {
117
    // Constructors
118
    public Server();
119
    public Server(int port);
120
    public Server(InetSocketAddress addr);
121
    public Server(ThreadPool threadPool);
122
    
123
    // Core server operations
124
    public static String getVersion();
125
    public URI getURI();
126
    public void join() throws InterruptedException;
127
    
128
    // Connector management
129
    public Connector[] getConnectors();
130
    public void addConnector(Connector connector);
131
    public void setConnectors(Connector[] connectors);
132
    
133
    // Handler management  
134
    public void setHandler(Handler handler);
135
    public Handler getHandler();
136
    public Request.Handler getErrorHandler();
137
    public void setErrorHandler(Request.Handler errorHandler);
138
}
139
```
140

141
[Server Core APIs](./server-core.md)
142

143
### Request and Response Processing
144

145
HTTP request and response interfaces with content handling, headers, and lifecycle management.
146

147
```java { .api }
148
public interface Request extends Attributes, Content.Source {
149
    String getId();
150
    String getMethod();
151
    HttpURI getHttpURI();
152
    HttpFields getHeaders();
153
    List<HttpCookie> getCookies();
154
    Session getSession(boolean create);
155
    Context getContext();
156
    ConnectionMetaData getConnectionMetaData();
157
    
158
    interface Handler {
159
        boolean handle(Request request, Response response, Callback callback) throws Exception;
160
    }
161
}
162

163
public interface Response extends Content.Sink {
164
    Request getRequest();
165
    int getStatus();
166
    void setStatus(int code);
167
    HttpFields.Mutable getHeaders();
168
    void write(boolean last, ByteBuffer byteBuffer, Callback callback);
169
}
170
```
171

172
[Request and Response APIs](./request-response.md)
173

174
### Handler Framework
175

176
Flexible handler system for processing HTTP requests with support for wrapping, containers, and conditional processing.
177

178
```java { .api }
179
public interface Handler extends LifeCycle, Destroyable, Request.Handler {
180
    Server getServer();
181
    void setServer(Server server);
182
    
183
    interface Container extends Handler {
184
        List<Handler> getHandlers();
185
        boolean insertHandler(Handler handler);
186
        boolean removeHandler(Handler handler);
187
    }
188
    
189
    abstract class Abstract extends AbstractLifeCycle implements Handler {
190
        protected abstract boolean handle(Request request, Response response, Callback callback) throws Exception;
191
    }
192
}
193
```
194

195
[Handler System](./handlers.md)
196

197
### Connection Management
198

199
Network connection handling with protocol factories, SSL support, and connection lifecycle management.
200

201
```java { .api }
202
public interface Connector extends LifeCycle, Container, Graceful {
203
    Server getServer();
204
    Executor getExecutor();
205
    Scheduler getScheduler();
206
    ByteBufferPool getByteBufferPool();
207
    ConnectionFactory getConnectionFactory(String protocol);
208
    Collection<ConnectionFactory> getConnectionFactories();
209
}
210

211
public class ServerConnector extends AbstractNetworkConnector {
212
    public ServerConnector(Server server);
213
    public ServerConnector(Server server, ConnectionFactory... factories);
214
    
215
    public void setPort(int port);
216
    public int getPort();
217
    public void setHost(String host);
218
    public String getHost();
219
}
220
```
221

222
[Connection Management](./connection-management.md)
223

224
### HTTP Configuration
225

226
HTTP protocol configuration including buffer sizes, timeouts, security settings, and protocol customizers.
227

228
```java { .api }
229
public class HttpConfiguration implements Dumpable {
230
    public HttpConfiguration();
231
    public HttpConfiguration(HttpConfiguration config);
232
    
233
    public void addCustomizer(Customizer customizer);
234
    public List<Customizer> getCustomizers();
235
    public int getOutputBufferSize();
236
    public void setOutputBufferSize(int outputBufferSize);
237
    public int getRequestHeaderSize();
238
    public void setRequestHeaderSize(int requestHeaderSize);
239
    public boolean getSendServerVersion();
240
    public void setSendServerVersion(boolean sendServerVersion);
241
    
242
    interface Customizer {
243
        Request customize(Request request, HttpConfiguration configuration);
244
    }
245
}
246
```
247

248
[HTTP Configuration](./configuration.md)
249

250
### Context and Resource Handling
251

252
Context-based request routing with virtual hosts, resource serving, and servlet-like contexts.
253

254
```java { .api }
255
public class ContextHandler extends Handler.Wrapper implements Attributes, AliasCheck {
256
    public String getContextPath();
257
    public void setContextPath(String contextPath);
258
    public Resource getBaseResource();
259
    public void setBaseResource(Resource resource);
260
    public List<String> getVirtualHosts();
261
    public void setVirtualHosts(String... vhosts);
262
    public ClassLoader getClassLoader();
263
    public void setClassLoader(ClassLoader classLoader);
264
}
265

266
public class ResourceHandler extends Handler.Wrapper {
267
    public Resource getBaseResource();
268
    public void setBaseResource(Resource baseResource);
269
    public List<String> getWelcomeFiles();
270
    public void setWelcomeFiles(String... welcomeFiles);
271
}
272
```
273

274
[Context and Resources](./context-resources.md)
275

276
### Session Management
277

278
HTTP session management with creation, invalidation, and attribute storage.
279

280
```java { .api }
281
public interface Session extends Attributes {
282
    String getId();
283
    Context getContext();
284
    long getCreationTime();
285
    long getLastAccessedTime();
286
    void setMaxInactiveInterval(int interval);
287
    int getMaxInactiveInterval();
288
    void invalidate();
289
    boolean isNew();
290
}
291
```
292

293
[Session Management](./session-management.md)
294

295
### Request Logging
296

297
Comprehensive request logging with customizable formats, file rotation, and SLF4J integration.
298

299
```java { .api }
300
public interface RequestLog {
301
    void log(Request request, Response response);
302
    
303
    interface Writer {
304
        void write(String requestEntry) throws IOException;
305
    }
306
}
307

308
public class CustomRequestLog extends ContainerLifeCycle implements RequestLog {
309
    public CustomRequestLog(RequestLog.Writer writer, String format);
310
    public void setLogFormat(String format);
311
    public String getLogFormat();
312
}
313
```
314

315
[Request Logging](./request-logging.md)
316

317
### Security and SSL
318

319
SSL/TLS support, security customizers, and connection encryption.
320

321
```java { .api }
322
public class SslConnectionFactory extends AbstractConnectionFactory 
323
        implements ConnectionFactory.Detecting, ConnectionFactory.Configuring {
324
    public SslConnectionFactory(SslContextFactory.Server sslContextFactory, String nextProtocol);
325
    public SslContextFactory.Server getSslContextFactory();
326
}
327

328
public class SecureRequestCustomizer implements HttpConfiguration.Customizer {
329
    public void setSniRequired(boolean sniRequired);
330
    public void setStsMaxAge(long stsMaxAge);
331
    public void setStsIncludeSubDomains(boolean stsIncludeSubDomains);
332
}
333
```
334

335
[Security and SSL](./security-ssl.md)
336

337
### Utility Handlers
338

339
Specialized handlers for common functionality like GZIP compression, CORS, statistics, and error handling.
340

341
```java { .api }
342
public class GzipHandler extends Handler.Wrapper implements GzipFactory {
343
    public int getMinGzipSize();
344
    public void setMinGzipSize(int minGzipSize);
345
    public int getCompressionLevel();
346
    public void setCompressionLevel(int compressionLevel);
347
    public Set<String> getIncludedMimeTypes();
348
    public void setIncludedMimeTypes(String... types);
349
}
350

351
public class StatisticsHandler extends EventsHandler {
352
    public int getRequests();
353
    public int getRequestsActive();
354
    public long getBytesReceived();
355
    public long getBytesSent();
356
}
357
```
358

359
[Utility Handlers](./utility-handlers.md)
360

361
## Types
362

363
```java { .api }
364
// Core callback interface for async operations
365
public interface Callback {
366
    void succeeded();
367
    void failed(Throwable x);
368
    
369
    static Callback NOOP = new Callback() {
370
        public void succeeded() {}
371
        public void failed(Throwable x) {}
372
    };
373
}
374

375
// HTTP URI representation
376
public interface HttpURI {
377
    String getScheme();
378
    String getHost();
379
    int getPort();
380
    String getPath();
381
    String getQuery();
382
    String getFragment();
383
}
384

385
// HTTP fields for headers
386
public interface HttpFields extends Iterable<HttpField> {
387
    HttpField getField(String name);
388
    String get(String name);
389
    List<String> getValuesList(String name);
390
    int size();
391
    
392
    interface Mutable extends HttpFields {
393
        HttpField put(String name, String value);
394
        HttpField add(String name, String value);
395
        boolean remove(String name);
396
        void clear();
397
    }
398
}
399

400
// Context for request processing
401
public interface Context extends Attributes, Decorator, Executor {
402
    String getContextPath();
403
    ClassLoader getClassLoader();
404
    Resource getBaseResource();
405
    List<String> getVirtualHosts();
406
    MimeTypes getMimeTypes();
407
    void run(Runnable runnable);
408
    Request.Handler getErrorHandler();
409
}
410

411
// Thread pool interface
412
public interface ThreadPool extends Executor {
413
    void join() throws InterruptedException;
414
    int getThreads();
415
    int getIdleThreads();
416
    boolean isLowOnThreads();
417
}
418

419
// Graceful shutdown interface
420
public interface Graceful {
421
    CompletableFuture<Void> shutdown();
422
    boolean isShutdown();
423
}
424

425
// Resource abstraction
426
public interface Resource {
427
    String getName();
428
    boolean exists();
429
    boolean isDirectory();
430
    long length();
431
    long lastModified();
432
    InputStream newInputStream() throws IOException;
433
    ReadableByteChannel newReadableByteChannel() throws IOException;
434
}
435
```