0
# Request and Response
1

2
HTTP message abstractions with header management, content handling, and query parameter support for both client requests and server responses.
3

4
## Capabilities
5

6
### HttpMessage Base Class
7

8
Abstract base class providing common functionality for HTTP messages including header management, content handling, and message attributes.
9

10
```java { .api }
11
/**
12
 * Abstract base class for HTTP messages (requests and responses)
13
 * Provides header management, content handling, and attribute storage
14
 */
15
public abstract class HttpMessage<M extends HttpMessage<M>> {
16
    /**
17
     * Retrieves user-defined attribute by key
18
     * @param key Attribute name
19
     * @return Attribute value or null if not found
20
     */
21
    public Object getAttribute(String key);
22
    
23
    /**
24
     * Sets user-defined attribute
25
     * @param key Attribute name
26
     * @param value Attribute value
27
     * @return This message instance for chaining
28
     */
29
    public M setAttribute(String key, Object value);
30
    
31
    /**
32
     * Removes user-defined attribute
33
     * @param key Attribute name to remove
34
     * @return This message instance for chaining
35
     */
36
    public M removeAttribute(String key);
37
    
38
    /**
39
     * Gets all attribute names
40
     * @return Iterable of attribute names
41
     */
42
    public Iterable<String> getAttributeNames();
43
    
44
    /**
45
     * Executes action for each header name-value pair
46
     * @param action BiConsumer to process each header
47
     */
48
    public void forEachHeader(BiConsumer<String, String> action);
49
    
50
    /**
51
     * Gets all header names
52
     * @return Iterable of header names (case-insensitive)
53
     */
54
    public Iterable<String> getHeaderNames();
55
    
56
    /**
57
     * Gets all values for specific header name
58
     * @param name Header name (case-insensitive)
59
     * @return Iterable of header values
60
     */
61
    public Iterable<String> getHeaders(String name);
62
    
63
    /**
64
     * Gets first value for specific header name
65
     * @param name Header name (case-insensitive)
66
     * @return First header value or null if not found
67
     */
68
    public String getHeader(String name);
69
    
70
    /**
71
     * Sets header value, replacing any existing values
72
     * @param name Header name (case-insensitive)
73
     * @param value Header value
74
     * @return This message instance for chaining
75
     */
76
    public M setHeader(String name, String value);
77
    
78
    /**
79
     * Adds header value, preserving existing values
80
     * @param name Header name (case-insensitive)
81
     * @param value Header value to add
82
     * @return This message instance for chaining
83
     */
84
    public M addHeader(String name, String value);
85
    
86
    /**
87
     * Removes all headers with specified name
88
     * @param name Header name to remove (case-insensitive)
89
     * @return This message instance for chaining
90
     */
91
    public M removeHeader(String name);
92
    
93
    /**
94
     * Gets content encoding charset from Content-Type header
95
     * @return Charset for content encoding (defaults to UTF-8)
96
     */
97
    public Charset getContentEncoding();
98
    
99
    /**
100
     * Sets message content using supplier
101
     * @param supplier Content supplier providing InputStream
102
     * @return This message instance for chaining
103
     */
104
    public M setContent(Contents.Supplier supplier);
105
    
106
    /**
107
     * Gets message content supplier
108
     * @return Contents.Supplier for accessing message body
109
     */
110
    public Contents.Supplier getContent();
111
}
112
```
113

114
### HttpRequest
115

116
Represents an HTTP request with method, URI, query parameters, headers, and content.
117

118
```java { .api }
119
/**
120
 * HTTP request implementation extending HttpMessage base class
121
 * Supports query parameters, headers, and content
122
 */
123
public class HttpRequest extends HttpMessage<HttpRequest> {
124
    /**
125
     * Creates HTTP request with method and URI
126
     * @param method HTTP method (GET, POST, etc.)
127
     * @param uri Request URI path
128
     */
129
    public HttpRequest(HttpMethod method, String uri);
130
    
131
    /**
132
     * Gets the request URI
133
     * @return Request URI string
134
     */
135
    public String getUri();
136
    
137
    /**
138
     * Gets the HTTP method
139
     * @return HTTP method enum value
140
     */
141
    public HttpMethod getMethod();
142
    
143
    /**
144
     * Gets first value of query parameter by name
145
     * Implementation handles URL decoding automatically
146
     * @param name Parameter name (case-sensitive)
147
     * @return Parameter value or null if not found
148
     */
149
    public String getQueryParameter(String name);
150
    
151
    /**
152
     * Adds query parameter value, preserving existing values
153
     * Implementation handles URL encoding automatically
154
     * @param name Parameter name
155
     * @param value Parameter value
156
     * @return This request instance for chaining
157
     */
158
    public HttpRequest addQueryParameter(String name, String value);
159
    
160
    /**
161
     * Gets all query parameter names
162
     * @return Iterable of parameter names
163
     */
164
    public Iterable<String> getQueryParameterNames();
165
    
166
    /**
167
     * Gets all values for specific query parameter
168
     * @param name Parameter name
169
     * @return Iterable of parameter values or null if not found
170
     */
171
    public Iterable<String> getQueryParameters(String name);
172
    
173
    /**
174
     * String representation showing method and URI
175
     * @return String in format "(METHOD) URI"
176
     */
177
    public String toString();
178
}
179
```
180

181
**Usage Examples:**
182

183
```java
184
import org.openqa.selenium.remote.http.*;
185

186
// Create GET request
187
HttpRequest getRequest = new HttpRequest(HttpMethod.GET, "/api/users");
188
getRequest.addHeader("Accept", "application/json");
189
getRequest.addHeader("User-Agent", "MyApp/1.0");
190

191
// Add query parameters
192
getRequest.addQueryParameter("page", "1");
193
getRequest.addQueryParameter("size", "20");
194
getRequest.addQueryParameter("filter", "active");
195
getRequest.addQueryParameter("filter", "verified"); // Multiple values
196

197
// Access query parameters
198
String page = getRequest.getQueryParameter("page"); // "1"
199
Iterable<String> filters = getRequest.getQueryParameters("filter"); // ["active", "verified"]
200

201
// Create POST request with JSON content
202
HttpRequest postRequest = new HttpRequest(HttpMethod.POST, "/api/users");
203
postRequest.setContent(Contents.asJson(Map.of(
204
    "name", "John Doe",
205
    "email", "john@example.com"
206
)));
207
postRequest.addHeader("Content-Type", "application/json");
208

209
System.out.println(postRequest); // "(POST) /api/users"
210
```
211

212
### HttpResponse
213

214
Represents an HTTP response with status code, headers, content, and target host information.
215

216
```java { .api }
217
/**
218
 * HTTP response implementation extending HttpMessage base class
219
 * Includes status code and target host tracking
220
 */
221
public class HttpResponse extends HttpMessage<HttpResponse> {
222
    /**
223
     * Attribute key for storing target host information
224
     */
225
    public static final String HTTP_TARGET_HOST = "http.target.host";
226
    
227
    /**
228
     * Checks if response status indicates success (2xx range)
229
     * @return true if status is between 200-299, false otherwise
230
     */
231
    public boolean isSuccessful();
232
    
233
    /**
234
     * Gets HTTP status code
235
     * @return Status code (default is 200)
236
     */
237
    public int getStatus();
238
    
239
    /**
240
     * Sets HTTP status code
241
     * @param status Status code to set
242
     * @return This response instance for chaining
243
     */
244
    public HttpResponse setStatus(int status);
245
    
246
    /**
247
     * Sets the host this response was received from
248
     * Stores as message attribute using HTTP_TARGET_HOST key
249
     * @param host Originating host name
250
     * @return This response instance for chaining
251
     */
252
    public HttpResponse setTargetHost(String host);
253
    
254
    /**
255
     * Gets the host this response was received from
256
     * @return Originating host name or null if not set
257
     */
258
    public String getTargetHost();
259
    
260
    /**
261
     * String representation showing status and content
262
     * @return String in format "STATUS: CONTENT"
263
     */
264
    public String toString();
265
}
266
```
267

268
**Usage Examples:**
269

270
```java
271
import org.openqa.selenium.remote.http.*;
272

273
// Create successful response
274
HttpResponse response = new HttpResponse();
275
response.setStatus(200);
276
response.setContent(Contents.asJson(Map.of(
277
    "id", 123,
278
    "name", "John Doe",
279
    "status", "active"
280
)));
281
response.addHeader("Content-Type", "application/json");
282
response.setTargetHost("api.example.com");
283

284
// Check response status
285
if (response.isSuccessful()) {
286
    System.out.println("Request succeeded");
287
    String responseBody = Contents.string(response);
288
    System.out.println("Response: " + responseBody);
289
}
290

291
// Create error response
292
HttpResponse errorResponse = new HttpResponse();
293
errorResponse.setStatus(404);
294
errorResponse.setContent(Contents.utf8String("User not found"));
295
errorResponse.addHeader("Content-Type", "text/plain");
296

297
System.out.println("Error: " + errorResponse.getStatus());
298
System.out.println("Host: " + errorResponse.getTargetHost());
299
```
300

301
### HttpMessage Base Class
302

303
Abstract base class providing common functionality for HTTP requests and responses including headers, attributes, and content management.
304

305
```java { .api }
306
/**
307
 * Abstract base class for HTTP messages (requests and responses)
308
 * Provides header management, attributes, and content handling
309
 * @param <M> The concrete message type for method chaining
310
 */
311
abstract class HttpMessage<M extends HttpMessage<M>> {
312
    /**
313
     * Gets message attribute by key
314
     * Attributes are not serialized with the message
315
     * @param key Attribute name
316
     * @return Attribute value or null if not found
317
     */
318
    public Object getAttribute(String key);
319
    
320
    /**
321
     * Sets message attribute
322
     * @param key Attribute name
323
     * @param value Attribute value
324
     * @return This message instance for chaining
325
     */
326
    public M setAttribute(String key, Object value);
327
    
328
    /**
329
     * Removes message attribute
330
     * @param key Attribute name to remove
331
     * @return This message instance for chaining
332
     */
333
    public M removeAttribute(String key);
334
    
335
    /**
336
     * Gets all attribute names
337
     * @return Iterable of attribute names
338
     */
339
    public Iterable<String> getAttributeNames();
340
    
341
    /**
342
     * Calls action for each header name-value pair
343
     * @param action BiConsumer to call for each header
344
     */
345
    public void forEachHeader(BiConsumer<String, String> action);
346
    
347
    /**
348
     * Gets all header names
349
     * @return Iterable of header names (case-insensitive)
350
     */
351
    public Iterable<String> getHeaderNames();
352
    
353
    /**
354
     * Gets all values for header by name (case-insensitive)
355
     * @param name Header name
356
     * @return Iterable of header values
357
     */
358
    public Iterable<String> getHeaders(String name);
359
    
360
    /**
361
     * Gets first header value by name (case-insensitive)
362
     * @param name Header name
363
     * @return First header value or null if not found
364
     */
365
    public String getHeader(String name);
366
    
367
    /**
368
     * Sets header value, replacing any existing values (case-insensitive)
369
     * @param name Header name
370
     * @param value Header value
371
     * @return This message instance for chaining
372
     */
373
    public M setHeader(String name, String value);
374
    
375
    /**
376
     * Adds header value, preserving existing values (case-insensitive)
377
     * @param name Header name
378
     * @param value Header value to add
379
     * @return This message instance for chaining
380
     */
381
    public M addHeader(String name, String value);
382
    
383
    /**
384
     * Removes all headers with specified name (case-insensitive)
385
     * @param name Header name to remove
386
     * @return This message instance for chaining
387
     */
388
    public M removeHeader(String name);
389
    
390
    /**
391
     * Gets content character encoding from Content-Type header
392
     * Defaults to UTF-8 if not specified or invalid
393
     * @return Charset for content encoding
394
     */
395
    public Charset getContentEncoding();
396
    
397
    /**
398
     * Sets message content using Contents.Supplier
399
     * @param supplier Content supplier providing InputStream
400
     * @return This message instance for chaining
401
     */
402
    public M setContent(Contents.Supplier supplier);
403
    
404
    /**
405
     * Gets message content supplier
406
     * @return Contents.Supplier for accessing content
407
     */
408
    public Contents.Supplier getContent();
409
}
410
```
411

412
**Usage Examples:**
413

414
```java
415
import org.openqa.selenium.remote.http.*;
416
import java.nio.charset.StandardCharsets;
417

418
// Working with headers
419
HttpRequest request = new HttpRequest(HttpMethod.POST, "/api/data");
420
request.addHeader("Accept", "application/json");
421
request.addHeader("Accept-Encoding", "gzip, deflate");
422
request.setHeader("Authorization", "Bearer token123");
423

424
// Iterate over headers
425
request.forEachHeader((name, value) -> {
426
    System.out.println(name + ": " + value);
427
});
428

429
// Check specific headers
430
if (request.getHeader("Authorization") != null) {
431
    System.out.println("Request is authenticated");
432
}
433

434
// Working with attributes (not serialized)
435
request.setAttribute("request.id", "req-123");
436
request.setAttribute("start.time", System.currentTimeMillis());
437

438
String requestId = (String) request.getAttribute("request.id");
439

440
// Content encoding
441
request.setHeader("Content-Type", "application/json; charset=ISO-8859-1");
442
Charset encoding = request.getContentEncoding(); // ISO-8859-1
443

444
// Set content with specific encoding
445
String jsonData = "{\"message\":\"Hello World\"}";
446
request.setContent(Contents.string(jsonData, StandardCharsets.UTF_8));
447
```
448

449
## HTTP Method Enum
450

451
```java { .api }
452
/**
453
 * HTTP method enumeration with all standard methods
454
 */
455
public enum HttpMethod {
456
    DELETE, GET, POST, PUT, OPTIONS, PATCH, HEAD, CONNECT, TRACE;
457
    
458
    /**
459
     * Parses HTTP method from string (case-insensitive)
460
     * @param method Method name string
461
     * @return HttpMethod enum value
462
     * @throws IllegalArgumentException if method is null or invalid
463
     */
464
    public static HttpMethod getHttpMethod(String method);
465
}
466
```
467

468
**Usage Examples:**
469

470
```java
471
// Create requests with different methods
472
HttpRequest getRequest = new HttpRequest(HttpMethod.GET, "/users");
473
HttpRequest postRequest = new HttpRequest(HttpMethod.POST, "/users");
474
HttpRequest putRequest = new HttpRequest(HttpMethod.PUT, "/users/123");
475
HttpRequest deleteRequest = new HttpRequest(HttpMethod.DELETE, "/users/123");
476

477
// Parse method from string
478
HttpMethod method = HttpMethod.getHttpMethod("PATCH"); // Case-insensitive
479
HttpRequest patchRequest = new HttpRequest(method, "/users/123");
480

481
// Invalid method throws exception
482
try {
483
    HttpMethod.getHttpMethod("INVALID"); // Throws IllegalArgumentException
484
} catch (IllegalArgumentException e) {
485
    System.err.println("Invalid HTTP method");
486
}
487
```