0
# Jetty HTTP
1
2
Jetty HTTP is the core HTTP protocol support library for Eclipse Jetty, providing comprehensive HTTP processing capabilities including header handling, parsing, generation, compliance validation, compression utilities, content management, and path mapping. It serves as the foundation for HTTP clients and servers with optimized performance and zero-copy buffer management.
3
4
## Package Information
5
6
- **Package Name**: org.eclipse.jetty:jetty-http
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**:
10
```xml
11
<dependency>
12
<groupId>org.eclipse.jetty</groupId>
13
<artifactId>jetty-http</artifactId>
14
<version>12.0.21</version>
15
</dependency>
16
```
17
18
## Core Imports
19
20
```java
21
import org.eclipse.jetty.http.*;
22
import org.eclipse.jetty.http.pathmap.*;
23
import org.eclipse.jetty.http.compression.*;
24
import org.eclipse.jetty.http.content.*;
25
```
26
27
## Basic Usage
28
29
```java
30
import org.eclipse.jetty.http.*;
31
32
// Create and manipulate HTTP headers
33
MutableHttpFields headers = new MutableHttpFields();
34
headers.put(HttpHeader.CONTENT_TYPE, "application/json");
35
headers.put(HttpHeader.CACHE_CONTROL, "no-cache");
36
37
// Parse HTTP method and status
38
HttpMethod method = HttpMethod.fromString("POST");
39
int statusCode = HttpStatus.OK_200;
40
41
// Handle URIs
42
HttpURI uri = HttpURI.from("https://example.com/api/users?id=123");
43
String host = uri.getHost(); // "example.com"
44
String path = uri.getPath(); // "/api/users"
45
String query = uri.getQuery(); // "id=123"
46
47
// Parse cookies
48
MutableHttpFields cookieHeaders = new MutableHttpFields();
49
cookieHeaders.add(HttpHeader.COOKIE, "session=abc123; user=john");
50
CookieCutter parser = new CookieCutter();
51
parser.parseFields(cookieHeaders);
52
```
53
54
## Architecture
55
56
Jetty HTTP is organized around several key components:
57
58
- **Core HTTP Processing**: HTTP methods, status codes, headers, and protocol handling (`HttpMethod`, `HttpStatus`, `HttpField`, `HttpFields`)
59
- **Parsing and Generation**: HTTP message parsing and generation with compliance validation (`HttpParser`, `HttpGenerator`)
60
- **URI Handling**: Comprehensive URI parsing, validation, and manipulation (`HttpURI`, `UriCompliance`)
61
- **Content Management**: HTTP content handling with caching, compression, and virtual file systems (`HttpContent`, `HttpContent.Factory`)
62
- **Path Mapping**: Flexible path specification matching for routing and dispatch (`PathSpec`, `ServletPathSpec`, `PathMappings`)
63
- **Compression**: HPACK compression utilities for HTTP/2 header compression (`NBitIntegerEncoder`, `Huffman`)
64
- **Compliance**: Configurable HTTP, URI, and cookie compliance modes with violation tracking
65
66
## Capabilities
67
68
### HTTP Headers and Fields
69
70
Core HTTP header handling with optimized field collections, type-safe header enums, and efficient header value processing.
71
72
```java { .api }
73
// Header field creation and manipulation
74
HttpField field = new HttpField(HttpHeader.CONTENT_TYPE, "application/json");
75
MutableHttpFields fields = new MutableHttpFields();
76
HttpField result = fields.put(HttpHeader.CACHE_CONTROL, "no-cache");
77
78
// Header collections interface
79
interface HttpFields extends Iterable<HttpField> {
80
int size();
81
HttpField getField(String name);
82
String get(HttpHeader header);
83
boolean contains(String name, String value);
84
Stream<HttpField> stream();
85
}
86
```
87
88
[HTTP Headers and Fields](./http-headers.md)
89
90
### HTTP Methods and Status
91
92
Standard HTTP method and status code handling with safety and idempotency checks, efficient parsing, and caching.
93
94
```java { .api }
95
// HTTP methods enumeration
96
enum HttpMethod {
97
GET, POST, PUT, DELETE, HEAD, OPTIONS, TRACE, PATCH, CONNECT;
98
99
boolean isSafe();
100
boolean isIdempotent();
101
ByteBuffer asBuffer();
102
static HttpMethod fromString(String method);
103
}
104
105
// HTTP status codes and utilities
106
class HttpStatus {
107
static final int OK_200 = 200;
108
static final int NOT_FOUND_404 = 404;
109
static final int INTERNAL_SERVER_ERROR_500 = 500;
110
111
static String getMessage(int code);
112
static boolean isInformational(int code);
113
static boolean hasNoBody(int status);
114
}
115
```
116
117
[HTTP Methods and Status](./http-methods-status.md)
118
119
### URI Processing
120
121
Comprehensive URI parsing, validation, and manipulation with compliance checking and efficient immutable/mutable patterns.
122
123
```java { .api }
124
// URI interface and factories
125
interface HttpURI {
126
String getScheme();
127
String getHost();
128
int getPort();
129
String getPath();
130
String getQuery();
131
boolean isAbsolute();
132
133
static HttpURI.Immutable from(String uri);
134
static HttpURI.Mutable build(String uri);
135
}
136
137
// URI compliance validation
138
class UriCompliance {
139
static final UriCompliance DEFAULT;
140
static final UriCompliance LEGACY;
141
boolean allows(Violation violation);
142
}
143
```
144
145
[URI Processing](./uri-processing.md)
146
147
### HTTP Parsing and Generation
148
149
High-performance HTTP message parsing and generation with configurable compliance modes and efficient buffer management.
150
151
```java { .api }
152
// HTTP parsing
153
class HttpParser {
154
HttpParser(RequestHandler requestHandler);
155
HttpParser(ResponseHandler responseHandler);
156
boolean parseNext(ByteBuffer buffer);
157
boolean isComplete();
158
void reset();
159
}
160
161
// HTTP generation
162
class HttpGenerator {
163
Result generateResponse(MetaData.Response info, boolean head,
164
ByteBuffer header, ByteBuffer chunk,
165
ByteBuffer content, boolean last);
166
boolean isEnd();
167
void reset();
168
}
169
```
170
171
[HTTP Parsing and Generation](./http-parsing-generation.md)
172
173
### Cookie Handling
174
175
Complete cookie parsing and management with RFC compliance support and attribute handling.
176
177
```java { .api }
178
// Cookie interface
179
interface HttpCookie {
180
String getName();
181
String getValue();
182
String getDomain();
183
String getPath();
184
boolean isSecure();
185
boolean isHttpOnly();
186
SameSite getSameSite();
187
188
static HttpCookie from(String name, String value);
189
}
190
191
// Cookie parsing
192
interface CookieParser {
193
void parseField(HttpField field);
194
void parseFields(HttpFields fields);
195
}
196
```
197
198
[Cookie Handling](./cookie-handling.md)
199
200
### Multi-Part Processing
201
202
Multi-part content handling for form data, file uploads, and byte ranges with async processing support.
203
204
```java { .api }
205
// Multi-part content processing
206
class MultiPart {
207
String getBoundary();
208
List<Part> getParts();
209
Part getPart(String name);
210
211
interface Part {
212
String getName();
213
String getFileName();
214
HttpFields getHeaders();
215
Content.Source getContentSource();
216
}
217
}
218
219
// Form data processing
220
class MultiPartFormData {
221
CompletableFuture<Parts> parse(Content.Source source);
222
Parts from(Content.Source source);
223
}
224
```
225
226
[Multi-Part Processing](./multipart-processing.md)
227
228
### Content Management
229
230
HTTP content handling with factory patterns, caching, compression support, and virtual file systems.
231
232
```java { .api }
233
// Content interface
234
interface HttpContent {
235
HttpField getContentType();
236
HttpField getContentLength();
237
HttpField getLastModified();
238
HttpField getETag();
239
ByteBuffer getByteBuffer();
240
void release();
241
242
interface Factory {
243
HttpContent getContent(String path);
244
}
245
}
246
247
// Content factories
248
class ResourceHttpContentFactory implements HttpContent.Factory;
249
class CachingHttpContentFactory implements HttpContent.Factory;
250
class VirtualHttpContentFactory implements HttpContent.Factory;
251
```
252
253
[Content Management](./content-management.md)
254
255
### Path Mapping
256
257
Flexible path specification matching for routing and dispatch with support for servlet-style, regex, and URI template patterns.
258
259
```java { .api }
260
// Path specification interface
261
interface PathSpec extends Comparable<PathSpec> {
262
String getDeclaration();
263
boolean matches(String path);
264
MatchedPath matched(String path);
265
String getPathInfo(String path);
266
}
267
268
// Path mappings collection
269
class PathMappings<E> extends AbstractMap<PathSpec, E> {
270
MappedResource<E> getMatched(String path);
271
List<MappedResource<E>> getMatches(String path);
272
boolean put(PathSpec pathSpec, E resource);
273
}
274
275
// Servlet-style path specifications
276
class ServletPathSpec extends AbstractPathSpec {
277
ServletPathSpec(String servletPathSpec);
278
}
279
```
280
281
[Path Mapping](./path-mapping.md)
282
283
### Compression Utilities
284
285
HPACK compression utilities for HTTP/2 header compression including N-bit integer encoding and Huffman coding.
286
287
```java { .api }
288
// N-bit integer encoding/decoding
289
class NBitIntegerEncoder {
290
static int octetsNeeded(int prefix, long value);
291
static void encode(ByteBuffer buffer, int prefix, long value);
292
}
293
294
class NBitIntegerDecoder {
295
void setPrefix(int prefix);
296
int decodeInt(ByteBuffer buffer);
297
long decodeLong(ByteBuffer buffer);
298
void reset();
299
}
300
301
// Huffman coding
302
class Huffman {
303
// Huffman encoding/decoding utilities
304
}
305
```
306
307
[Compression Utilities](./compression-utilities.md)
308
309
## Common Types
310
311
```java { .api }
312
// HTTP version enumeration
313
enum HttpVersion {
314
HTTP_0_9, HTTP_1_0, HTTP_1_1, HTTP_2_0, HTTP_3_0;
315
String asString();
316
int getVersion();
317
}
318
319
// HTTP scheme enumeration
320
enum HttpScheme {
321
HTTP, HTTPS, WS, WSS;
322
String asString();
323
int getDefaultPort();
324
}
325
326
// Metadata for requests and responses
327
class MetaData implements Iterable<HttpField> {
328
HttpURI getHttpURI();
329
HttpVersion getHttpVersion();
330
HttpFields getHttpFields();
331
332
static class Request extends MetaData;
333
static class Response extends MetaData;
334
}
335
336
// Compliance violation handling
337
interface ComplianceViolation {
338
interface Listener {
339
void onComplianceViolation(Mode mode, ComplianceViolation violation, String details);
340
}
341
342
enum Mode { COMPLIANCE, LEGACY, CUSTOM }
343
}
344
345
// Content processing interface
346
interface Content {
347
interface Source {
348
// Content source for streaming processing
349
}
350
351
interface Chunk {
352
ByteBuffer getByteBuffer();
353
boolean isLast();
354
}
355
}
356
357
// Exception types
358
class BadMessageException extends HttpException.RuntimeException;
359
class ComplianceViolationException extends IllegalArgumentException;
360
class EncodingException extends Exception;
361
```