0
# HTTP Request and Response
1

2
HTTP communication layer providing request customization, response processing, header management, and connection configuration for complete control over web interactions.
3

4
## Capabilities
5

6
### Web Request Creation and Customization
7

8
Create and customize HTTP requests with headers, parameters, and request bodies.
9

10
```java { .api }
11
public class WebRequest {
12
    /**
13
     * Create a GET request to the specified URL
14
     * @param url the target URL
15
     */
16
    public WebRequest(URL url);
17
    
18
    /**
19
     * Create a request with specified URL and HTTP method
20
     * @param url the target URL
21
     * @param method the HTTP method to use
22
     */
23
    public WebRequest(URL url, HttpMethod method);
24
    
25
    /**
26
     * Get the request URL
27
     * @return the target URL for this request
28
     */
29
    public URL getUrl();
30
    
31
    /**
32
     * Get the HTTP method for this request
33
     * @return the HttpMethod (GET, POST, etc.)
34
     */
35
    public HttpMethod getHttpMethod();
36
    
37
    /**
38
     * Set the request body content
39
     * @param body the request body as a string
40
     */
41
    public void setRequestBody(String body);
42
    
43
    /**
44
     * Get the current request parameters
45
     * @return List of NameValuePair representing form parameters
46
     */
47
    public List<NameValuePair> getRequestParameters();
48
    
49
    /**
50
     * Set the request parameters (for POST forms)
51
     * @param parameters List of NameValuePair for form data
52
     */
53
    public void setRequestParameters(List<NameValuePair> parameters);
54
    
55
    /**
56
     * Get all additional headers for this request
57
     * @return Map of header names to values
58
     */
59
    public Map<String, String> getAdditionalHeaders();
60
    
61
    /**
62
     * Add or set an HTTP header
63
     * @param name the header name
64
     * @param value the header value
65
     */
66
    public void setAdditionalHeader(String name, String value);
67
}
68
```
69

70
**Usage Examples:**
71

72
```java
73
// Simple GET request
74
URL url = new URL("https://api.example.com/data");
75
WebRequest request = new WebRequest(url);
76

77
// POST request with JSON body
78
WebRequest postRequest = new WebRequest(url, HttpMethod.POST);
79
postRequest.setRequestBody("{\"name\":\"John\",\"age\":30}");
80
postRequest.setAdditionalHeader("Content-Type", "application/json");
81
postRequest.setAdditionalHeader("Authorization", "Bearer token123");
82

83
// Form POST request
84
WebRequest formRequest = new WebRequest(url, HttpMethod.POST);
85
List<NameValuePair> parameters = Arrays.asList(
86
    new NameValuePair("username", "john"),
87
    new NameValuePair("password", "secret")
88
);
89
formRequest.setRequestParameters(parameters);
90

91
// Execute request
92
Page response = webClient.getPage(request);
93
```
94

95
### Web Response Processing
96

97
Access and process HTTP responses including status codes, headers, and content.
98

99
```java { .api }
100
public class WebResponse {
101
    /**
102
     * Get the HTTP status code
103
     * @return the status code (e.g., 200, 404, 500)
104
     */
105
    public int getStatusCode();
106
    
107
    /**
108
     * Get the HTTP status message
109
     * @return the status message (e.g., "OK", "Not Found")
110
     */
111
    public String getStatusMessage();
112
    
113
    /**
114
     * Get the response content as a string
115
     * @return the response body decoded as a string
116
     */
117
    public String getContentAsString();
118
    
119
    /**
120
     * Get the response content as an input stream
121
     * @return InputStream for reading response data
122
     */
123
    public InputStream getContentAsStream();
124
    
125
    /**
126
     * Get the response content type
127
     * @return the Content-Type header value
128
     */
129
    public String getContentType();
130
    
131
    /**
132
     * Get the character encoding of the response
133
     * @return the Charset used for text content
134
     */
135
    public Charset getContentCharset();
136
    
137
    /**
138
     * Get all response headers
139
     * @return List of NameValuePair representing all headers
140
     */
141
    public List<NameValuePair> getResponseHeaders();
142
    
143
    /**
144
     * Get a specific response header value
145
     * @param name the header name to look up
146
     * @return the header value, or null if not present
147
     */
148
    public String getResponseHeaderValue(String name);
149
    
150
    /**
151
     * Get the original request that generated this response
152
     * @return the WebRequest object
153
     */
154
    public WebRequest getWebRequest();
155
}
156
```
157

158
**Usage Examples:**
159

160
```java
161
Page page = webClient.getPage("https://api.example.com/data");
162
WebResponse response = page.getWebResponse();
163

164
// Check response status
165
int statusCode = response.getStatusCode();
166
String statusMessage = response.getStatusMessage();
167
if (statusCode != 200) {
168
    System.err.println("Request failed: " + statusCode + " " + statusMessage);
169
}
170

171
// Access response content
172
String contentType = response.getContentType();
173
String content = response.getContentAsString();
174

175
// Process headers
176
String serverHeader = response.getResponseHeaderValue("Server");
177
List<NameValuePair> allHeaders = response.getResponseHeaders();
178
for (NameValuePair header : allHeaders) {
179
    System.out.println(header.getName() + ": " + header.getValue());
180
}
181

182
// Stream large responses
183
try (InputStream stream = response.getContentAsStream()) {
184
    // Process stream data
185
}
186

187
// Get original request details
188
WebRequest originalRequest = response.getWebRequest();
189
URL requestUrl = originalRequest.getUrl();
190
```
191

192
### HTTP Methods
193

194
Enumeration of supported HTTP methods for request creation.
195

196
```java { .api }
197
public enum HttpMethod {
198
    GET,      // Retrieve data
199
    POST,     // Submit data
200
    PUT,      // Update/replace resource  
201
    DELETE,   // Remove resource
202
    HEAD,     // Get headers only
203
    OPTIONS,  // Check allowed methods
204
    TRACE,    // Diagnostic method
205
    PATCH     // Partial update
206
}
207
```
208

209
**Usage Examples:**
210

211
```java
212
// Different HTTP methods
213
WebRequest getRequest = new WebRequest(url, HttpMethod.GET);
214
WebRequest postRequest = new WebRequest(url, HttpMethod.POST);
215
WebRequest putRequest = new WebRequest(url, HttpMethod.PUT);
216
WebRequest deleteRequest = new WebRequest(url, HttpMethod.DELETE);
217

218
// RESTful API interactions
219
WebRequest apiGet = new WebRequest(new URL("https://api.example.com/users/123"), HttpMethod.GET);
220
WebRequest apiCreate = new WebRequest(new URL("https://api.example.com/users"), HttpMethod.POST);
221
WebRequest apiUpdate = new WebRequest(new URL("https://api.example.com/users/123"), HttpMethod.PUT);
222
WebRequest apiDelete = new WebRequest(new URL("https://api.example.com/users/123"), HttpMethod.DELETE);
223
```
224

225
### Web Connection Interface
226

227
Interface for customizing HTTP connection behavior and implementing custom connection handlers.
228

229
```java { .api }
230
public interface WebConnection {
231
    /**
232
     * Execute an HTTP request and return the response
233
     * @param request the WebRequest to execute
234
     * @return WebResponse containing the server response
235
     * @throws IOException if the request fails
236
     */
237
    WebResponse getResponse(WebRequest request) throws IOException;
238
}
239

240
public class HttpWebConnection implements WebConnection {
241
    // Standard implementation of WebConnection
242
    // Used by default in WebClient
243
}
244
```
245

246
**Usage Examples:**
247

248
```java
249
// Use default HTTP connection
250
WebConnection connection = webClient.getWebConnection();
251

252
// Custom connection implementation
253
WebConnection customConnection = new WebConnection() {
254
    @Override
255
    public WebResponse getResponse(WebRequest request) throws IOException {
256
        // Log all requests
257
        System.out.println("Requesting: " + request.getUrl());
258
        
259
        // Delegate to default implementation
260
        HttpWebConnection defaultConnection = new HttpWebConnection(webClient);
261
        return defaultConnection.getResponse(request);
262
    }
263
};
264

265
// Set custom connection
266
webClient.setWebConnection(customConnection);
267
```
268

269
### Name-Value Pairs
270

271
Utility class for handling HTTP parameters and headers.
272

273
```java { .api }
274
public class NameValuePair {
275
    /**
276
     * Create a name-value pair
277
     * @param name the parameter/header name
278
     * @param value the parameter/header value
279
     */
280
    public NameValuePair(String name, String value);
281
    
282
    /**
283
     * Get the name
284
     * @return the name portion
285
     */
286
    public String getName();
287
    
288
    /**
289
     * Get the value
290
     * @return the value portion
291
     */
292
    public String getValue();
293
}
294
```
295

296
**Usage Examples:**
297

298
```java
299
// Create form parameters
300
List<NameValuePair> formData = Arrays.asList(
301
    new NameValuePair("username", "john"),
302
    new NameValuePair("email", "john@example.com"),
303
    new NameValuePair("age", "30")
304
);
305

306
// Use with POST request
307
WebRequest postRequest = new WebRequest(url, HttpMethod.POST);
308
postRequest.setRequestParameters(formData);
309

310
// Process response headers
311
WebResponse response = webClient.getPage(postRequest).getWebResponse();
312
List<NameValuePair> headers = response.getResponseHeaders();
313
for (NameValuePair header : headers) {
314
    if ("Set-Cookie".equalsIgnoreCase(header.getName())) {
315
        System.out.println("Cookie: " + header.getValue());
316
    }
317
}
318
```
319

320
### HTTP Status Handling
321

322
Exception handling for HTTP error status codes.
323

324
```java { .api }
325
public class FailingHttpStatusCodeException extends RuntimeException {
326
    /**
327
     * Get the HTTP status code that caused the exception
328
     * @return the HTTP status code
329
     */
330
    public int getStatusCode();
331
    
332
    /**
333
     * Get the HTTP status message
334
     * @return the status message from the server
335
     */
336
    public String getStatusMessage();
337
    
338
    /**
339
     * Get the complete web response
340
     * @return the WebResponse that triggered this exception
341
     */
342
    public WebResponse getResponse();
343
}
344
```
345

346
**Usage Examples:**
347

348
```java
349
try {
350
    // This might throw on 4xx/5xx status codes if configured to do so
351
    HtmlPage page = webClient.getPage("https://example.com/missing-page");
352
} catch (FailingHttpStatusCodeException e) {
353
    int statusCode = e.getStatusCode();
354
    String statusMessage = e.getStatusMessage();
355
    WebResponse response = e.getResponse();
356
    
357
    System.err.println("HTTP Error: " + statusCode + " " + statusMessage);
358
    System.err.println("Response content: " + response.getContentAsString());
359
}
360

361
// Configure whether to throw exceptions on HTTP errors
362
webClient.getOptions().setThrowExceptionOnFailingStatusCode(true); // Default is true
363
```
364

365
### Advanced Request Customization
366

367
Advanced techniques for customizing HTTP requests.
368

369
**Usage Examples:**
370

371
```java
372
// Complex API request with authentication and custom headers
373
WebRequest apiRequest = new WebRequest(new URL("https://api.example.com/secure-data"), HttpMethod.POST);
374

375
// Add authentication
376
apiRequest.setAdditionalHeader("Authorization", "Bearer " + authToken);
377

378
// Set content type and accept headers
379
apiRequest.setAdditionalHeader("Content-Type", "application/json");
380
apiRequest.setAdditionalHeader("Accept", "application/json");
381

382
// Add custom headers for API versioning
383
apiRequest.setAdditionalHeader("API-Version", "2.1");
384
apiRequest.setAdditionalHeader("User-Agent", "MyApp/1.0 (Java)");
385

386
// Set JSON request body
387
String jsonBody = "{\"query\":\"search term\",\"limit\":50,\"offset\":0}";
388
apiRequest.setRequestBody(jsonBody);
389

390
// Execute and process JSON response
391
Page responsePage = webClient.getPage(apiRequest);
392
WebResponse response = responsePage.getWebResponse();
393

394
if (response.getStatusCode() == 200) {
395
    String jsonResponse = response.getContentAsString();
396
    // Parse JSON response as needed
397
}
398
```