0
# HTTP Headers and Fields
1

2
Comprehensive HTTP header handling with optimized field collections, type-safe header enums, efficient header value processing, and immutable/mutable field collections.
3

4
## Capabilities
5

6
### HttpHeader Enumeration
7

8
Complete enumeration of standard HTTP headers with efficient lookup and caching.
9

10
```java { .api }
11
/**
12
 * Enumeration of standard HTTP headers with efficient processing
13
 */
14
enum HttpHeader {
15
    // General headers
16
    CONNECTION, CACHE_CONTROL, DATE, PRAGMA, TRANSFER_ENCODING, UPGRADE, VIA, WARNING,
17
    
18
    // Entity headers
19
    ALLOW, CONTENT_DISPOSITION, CONTENT_ENCODING, CONTENT_LANGUAGE, 
20
    CONTENT_LENGTH, CONTENT_TYPE, EXPIRES, LAST_MODIFIED,
21
    
22
    // Request headers
23
    ACCEPT, ACCEPT_CHARSET, ACCEPT_ENCODING, ACCEPT_LANGUAGE, AUTHORIZATION, 
24
    HOST, IF_MATCH, IF_MODIFIED_SINCE, IF_NONE_MATCH, IF_RANGE, 
25
    IF_UNMODIFIED_SINCE, REFERER, USER_AGENT,
26
    
27
    // Response headers
28
    ACCEPT_RANGES, AGE, ETAG, LOCATION, PROXY_AUTHENTICATE, 
29
    RETRY_AFTER, SERVER, VARY, WWW_AUTHENTICATE,
30
    
31
    // CORS headers
32
    ACCESS_CONTROL_ALLOW_ORIGIN, ACCESS_CONTROL_ALLOW_METHODS, 
33
    ACCESS_CONTROL_ALLOW_HEADERS, ACCESS_CONTROL_ALLOW_CREDENTIALS,
34
    ACCESS_CONTROL_EXPOSE_HEADERS, ACCESS_CONTROL_MAX_AGE,
35
    
36
    // WebSocket headers
37
    SEC_WEBSOCKET_KEY, SEC_WEBSOCKET_VERSION, SEC_WEBSOCKET_ACCEPT,
38
    SEC_WEBSOCKET_PROTOCOL, SEC_WEBSOCKET_EXTENSIONS,
39
    
40
    // HTTP/2 pseudo headers
41
    C_METHOD, C_SCHEME, C_AUTHORITY, C_PATH, C_STATUS;
42
    
43
    /** Get lowercase header name */
44
    String lowerCaseName();
45
    
46
    /** Get header name as ByteBuffer */
47
    ByteBuffer toBuffer();
48
    
49
    /** Get header name as byte array */
50
    byte[] getBytes();
51
    
52
    /** Case-insensitive header name comparison */
53
    boolean is(String s);
54
    
55
    /** Check if this is an HTTP/2 pseudo header */
56
    boolean isPseudo();
57
    
58
    /** Header name cache for efficient lookup */
59
    static final Index<HttpHeader> CACHE;
60
    
61
    /** Content-related headers set */
62
    static final EnumSet<HttpHeader> CONTENT_HEADERS;
63
}
64
```
65

66
### HttpHeaderValue Enumeration
67

68
Common HTTP header values with efficient processing and CSV parsing support.
69

70
```java { .api }
71
/**
72
 * Enumeration of common HTTP header values
73
 */
74
enum HttpHeaderValue {
75
    CLOSE, CHUNKED, GZIP, DEFLATE, IDENTITY, KEEP_ALIVE, CONTINUE, 
76
    BYTES, NO_CACHE, NO_STORE, MAX_AGE, MUST_REVALIDATE, UPGRADE,
77
    WEBSOCKET, TEXT_PLAIN, APPLICATION_JSON, APPLICATION_XML;
78
    
79
    /** Get value as ByteBuffer */
80
    ByteBuffer toBuffer();
81
    
82
    /** Case-insensitive value comparison */
83
    boolean is(String s);
84
    
85
    /** Get value as string */
86
    String asString();
87
    
88
    /** Check if header has known values */
89
    static boolean hasKnownValues(HttpHeader header);
90
    
91
    /** Parse CSV header values with callback */
92
    static boolean parseCsvIndex(String value, Function<HttpHeaderValue, Boolean> found);
93
}
94
```
95

96
### HttpField Class
97

98
Immutable HTTP header field with name and value, supporting typed access and field manipulation.
99

100
```java { .api }
101
/**
102
 * Immutable HTTP header field with name and value
103
 */
104
class HttpField {
105
    /** Create field with header enum and value */
106
    HttpField(HttpHeader header, String value);
107
    
108
    /** Create field with header enum, name override, and value */
109
    HttpField(HttpHeader header, String name, String value);
110
    
111
    /** Create field with header enum and header value enum */
112
    HttpField(HttpHeader header, HttpHeaderValue value);
113
    
114
    /** Create field with string name and value */
115
    HttpField(String name, String value);
116
    
117
    /** Get header enum if known, null otherwise */
118
    HttpHeader getHeader();
119
    
120
    /** Get field name */
121
    String getName();
122
    
123
    /** Get lowercase field name */
124
    String getLowerCaseName();
125
    
126
    /** Get field value */
127
    String getValue();
128
    
129
    /** Get multi-value field as array */
130
    String[] getValues();
131
    
132
    /** Get multi-value field as list */
133
    List<String> getValueList();
134
    
135
    /** Get value as integer */
136
    int getIntValue();
137
    
138
    /** Get value as long */
139
    long getLongValue();
140
    
141
    /** Check if value contains string (case insensitive) */
142
    boolean contains(String search);
143
    
144
    /** Check if last value contains string */
145
    boolean containsLast(String search);
146
    
147
    /** Check field name (case insensitive) */
148
    boolean is(String name);
149
    
150
    /** Compare field names */
151
    boolean isSameName(HttpField field);
152
    
153
    /** Create new field with different value */
154
    HttpField withValue(String value);
155
    
156
    /** Create new field with multiple values */
157
    HttpField withValues(String... values);
158
    
159
    /** Create new field removing a value */
160
    HttpField withoutValue(String value);
161
    
162
    /** Extract parameters from header value */
163
    static String getValueParameters(String valueParams, Map<String, String> parameters);
164
    
165
    /** Remove parameters from header value */
166
    static String stripParameters(String value);
167
    
168
    /** Check if value contains search string */
169
    static boolean contains(String value, String search);
170
    
171
    /** Check if last value contains search string */
172
    static boolean containsLast(String value, String search);
173
    
174
    /** Parameter parsing tokenizer */
175
    static final QuotedStringTokenizer PARAMETER_TOKENIZER;
176
    
177
    /** Name-value parsing tokenizer */
178
    static final QuotedStringTokenizer NAME_VALUE_TOKENIZER;
179
}
180

181
/**
182
 * Optimized integer value field
183
 */
184
class IntValueHttpField extends HttpField {
185
    IntValueHttpField(HttpHeader header, String name, String value, int intValue);
186
    IntValueHttpField(HttpHeader header, String value, int intValue);
187
    IntValueHttpField(HttpHeader header, int intValue);
188
}
189

190
/**
191
 * Optimized long value field  
192
 */
193
class LongValueHttpField extends HttpField {
194
    LongValueHttpField(HttpHeader header, String name, String value, long longValue);
195
    LongValueHttpField(HttpHeader header, String value, long longValue);
196
    LongValueHttpField(HttpHeader header, long longValue);
197
}
198
```
199

200
### HttpFields Interface
201

202
Collection interface for HTTP header fields with lookup, iteration, and streaming support.
203

204
```java { .api }
205
/**
206
 * Collection of HTTP header fields
207
 */
208
interface HttpFields extends Iterable<HttpField> {
209
    /** Number of fields */
210
    int size();
211
    
212
    /** Get field by index */
213
    HttpField getField(int index);
214
    
215
    /** Get first field by name (case insensitive) */
216
    HttpField getField(String name);
217
    
218
    /** Get first field by header enum */
219
    HttpField getField(HttpHeader header);
220
    
221
    /** Get all fields with name */
222
    List<HttpField> getFields(String name);
223
    
224
    /** Get all fields with header enum */
225
    List<HttpField> getFields(HttpHeader header);
226
    
227
    /** Get first value by name */
228
    String get(String name);
229
    
230
    /** Get first value by header enum */
231
    String get(HttpHeader header);
232
    
233
    /** Get all values as list */
234
    List<String> getValuesList(String name);
235
    
236
    /** Check if field with name exists */
237
    boolean contains(String name);
238
    
239
    /** Check if field with header exists */
240
    boolean contains(HttpHeader header);
241
    
242
    /** Check if field with name and value exists */
243
    boolean contains(String name, String value);
244
    
245
    /** Get integer field value */
246
    int getIntField(String name);
247
    
248
    /** Get long field value */
249
    long getLongField(String name);
250
    
251
    /** Stream of all fields */
252
    Stream<HttpField> stream();
253
    
254
    /** Iterator over all fields */
255
    Iterator<HttpField> iterator();
256
}
257
```
258

259
### MutableHttpFields Class
260

261
Mutable collection of HTTP fields with add, put, and remove operations.
262

263
```java { .api }
264
/**
265
 * Mutable collection of HTTP fields
266
 */
267
class MutableHttpFields implements HttpFields {
268
    /** Create empty fields collection */
269
    MutableHttpFields();
270
    
271
    /** Create with initial capacity */
272
    MutableHttpFields(int capacity);
273
    
274
    /** Copy constructor */
275
    MutableHttpFields(HttpFields fields);
276
    
277
    /** Add or replace field (returns previous field if any) */
278
    HttpField put(String name, String value);
279
    
280
    /** Add or replace field by header enum */
281
    HttpField put(HttpHeader header, String value);
282
    
283
    /** Add or replace existing field */
284
    HttpField put(HttpField field);
285
    
286
    /** Add field (allows duplicates) */
287
    HttpField add(String name, String value);
288
    
289
    /** Add field by header enum */
290
    HttpField add(HttpHeader header, String value);  
291
    
292
    /** Add existing field */
293
    HttpField add(HttpField field);
294
    
295
    /** Remove all fields with name */
296
    boolean remove(String name);
297
    
298
    /** Remove all fields with header enum */
299
    boolean remove(HttpHeader header);
300
    
301
    /** Remove specific field */
302
    HttpField remove(HttpField field);
303
    
304
    /** Remove all fields */
305
    void clear();
306
    
307
    /** Ensure capacity for fields */
308
    int ensureCapacity(int capacity);
309
}
310
```
311

312
### ImmutableHttpFields Class
313

314
Immutable collection of HTTP fields with builder pattern.
315

316
```java { .api }
317
/**
318
 * Immutable collection of HTTP fields
319
 */
320
class ImmutableHttpFields implements HttpFields {
321
    /** Create builder for immutable fields */
322
    static Builder builder();
323
    
324
    /** Create from field array */
325
    static ImmutableHttpFields of(HttpField... fields);
326
    
327
    /** Build from field array */
328
    static ImmutableHttpFields build(HttpField... fields);
329
    
330
    /**
331
     * Builder for immutable HTTP fields
332
     */
333
    static class Builder {
334
        Builder add(String name, String value);
335
        Builder add(HttpHeader header, String value);
336
        Builder add(HttpField field);
337
        Builder put(String name, String value);
338
        Builder put(HttpHeader header, String value);
339
        Builder put(HttpField field);
340
        ImmutableHttpFields build();
341
    }
342
}
343
```
344

345
### EmptyHttpFields Class
346

347
Singleton empty fields collection for efficiency.
348

349
```java { .api }
350
/**
351
 * Immutable empty HTTP fields collection
352
 */
353
class EmptyHttpFields implements HttpFields {
354
    /** Singleton instance */
355
    static final EmptyHttpFields INSTANCE;
356
}
357
```
358

359
**Usage Examples:**
360

361
```java
362
import org.eclipse.jetty.http.*;
363

364
// Create and manipulate mutable fields
365
MutableHttpFields headers = new MutableHttpFields();
366
headers.put(HttpHeader.CONTENT_TYPE, "application/json");
367
headers.add(HttpHeader.ACCEPT, "application/json");
368
headers.add(HttpHeader.ACCEPT, "text/plain");
369

370
// Access field values
371
String contentType = headers.get(HttpHeader.CONTENT_TYPE);
372
List<String> acceptValues = headers.getValuesList("Accept");
373

374
// Check field existence
375
boolean hasAuth = headers.contains(HttpHeader.AUTHORIZATION);
376
boolean hasJsonType = headers.contains("Content-Type", "application/json");
377

378
// Create immutable fields
379
ImmutableHttpFields immutable = ImmutableHttpFields.builder()
380
    .add(HttpHeader.USER_AGENT, "MyApp/1.0")
381
    .put(HttpHeader.CONNECTION, "keep-alive")
382
    .build();
383

384
// Work with individual fields
385
HttpField field = new HttpField(HttpHeader.CACHE_CONTROL, "max-age=3600, public");
386
boolean isPublic = field.contains("public");
387
String[] directives = field.getValues();
388

389
// Specialized integer/long fields for performance
390
HttpField contentLength = new LongValueHttpField(HttpHeader.CONTENT_LENGTH, 1024);
391
HttpField maxAge = new IntValueHttpField(HttpHeader.AGE, 300);
392
```