0
# HTTP Communication
1

2
HTTP request/response handling with full control over headers, methods, authentication, proxy settings, and connection configuration. Essential for API testing, advanced web scraping, and custom HTTP workflows.
3

4
## Capabilities
5

6
### WebRequest Class
7

8
Configuration for HTTP requests with custom headers, methods, and parameters.
9

10
```java { .api }
11
/**
12
 * HTTP request configuration and parameters
13
 */
14
public class WebRequest {
15
    /** Create GET request for URL */
16
    public WebRequest(URL url);
17
    
18
    /** Create request with specific HTTP method */
19
    public WebRequest(URL url, HttpMethod submitMethod);
20
    
21
    /** Create request with accept headers */
22
    public WebRequest(URL url, String acceptHeader, String acceptEncodingHeader);
23
    
24
    /** Get request URL */
25
    public URL getUrl();
26
    
27
    /** Set request URL */
28
    public void setUrl(URL url);
29
    
30
    /** Get HTTP method */
31
    public HttpMethod getHttpMethod();
32
    
33
    /** Set HTTP method */
34
    public void setHttpMethod(HttpMethod method);
35
    
36
    /** Get request body content */
37
    public String getRequestBody();
38
    
39
    /** Set request body content */
40
    public void setRequestBody(String requestBody);
41
    
42
    /** Set request body with encoding */
43
    public void setRequestBody(String requestBody, String charset);
44
    
45
    /** Get request parameters */
46
    public List<NameValuePair> getParameters();
47
    
48
    /** Set request parameters */
49
    public void setParameters(List<NameValuePair> parameters);
50
    
51
    /** Add request parameter */
52
    public void setRequestParameter(String name, String value);
53
    
54
    /** Get additional headers */
55
    public Map<String, String> getAdditionalHeaders();
56
    
57
    /** Set additional header */
58
    public void setAdditionalHeader(String name, String value);
59
    
60
    /** Remove header */
61
    public void removeAdditionalHeader(String name);
62
    
63
    /** Get form encoding type */
64
    public FormEncodingType getEncodingType();
65
    
66
    /** Set form encoding type */
67
    public void setEncodingType(FormEncodingType encodingType);
68
    
69
    /** Get authentication credentials */
70
    public Credentials getCredentials();
71
    
72
    /** Set authentication credentials */
73
    public void setCredentials(Credentials credentials);
74
    
75
    /** Get proxy host */
76
    public String getProxyHost();
77
    
78
    /** Set proxy host */
79
    public void setProxyHost(String proxyHost);
80
    
81
    /** Get proxy port */
82
    public int getProxyPort();
83
    
84
    /** Set proxy port */
85
    public void setProxyPort(int proxyPort);
86
    
87
    /** Get proxy credentials */
88
    public Credentials getProxyCredentials();
89
    
90
    /** Set proxy credentials */
91
    public void setProxyCredentials(Credentials credentials);
92
    
93
    /** Get connection timeout */
94
    public int getTimeout();
95
    
96
    /** Set connection timeout in milliseconds */
97
    public void setTimeout(int timeout);
98
    
99
    /** Get character encoding */
100
    public Charset getCharset();
101
    
102
    /** Set character encoding */
103
    public void setCharset(Charset charset);
104
    
105
    /** Check if request follows redirects */
106
    public boolean isFollowRedirects();
107
    
108
    /** Set whether to follow redirects */
109
    public void setFollowRedirects(boolean followRedirects);
110
    
111
    /** Get maximum redirect count */
112
    public int getMaxRedirectCount();
113
    
114
    /** Set maximum redirect count */
115
    public void setMaxRedirectCount(int maxRedirectCount);
116
}
117
```
118

119
**Usage Examples:**
120

121
```java
122
import com.gargoylesoftware.htmlunit.*;
123
import com.gargoylesoftware.htmlunit.util.NameValuePair;
124
import java.net.URL;
125
import java.util.ArrayList;
126
import java.util.List;
127

128
try (WebClient webClient = new WebClient()) {
129
    // Simple GET request
130
    WebRequest getRequest = new WebRequest(new URL("https://api.example.com/data"));
131
    getRequest.setAdditionalHeader("Accept", "application/json");
132
    getRequest.setAdditionalHeader("Authorization", "Bearer token123");
133
    
134
    Page response = webClient.getPage(getRequest);
135
    
136
    // POST request with JSON data
137
    WebRequest postRequest = new WebRequest(new URL("https://api.example.com/users"), HttpMethod.POST);
138
    postRequest.setAdditionalHeader("Content-Type", "application/json");
139
    postRequest.setRequestBody("{\"name\":\"John\",\"email\":\"john@example.com\"}");
140
    
141
    Page postResponse = webClient.getPage(postRequest);
142
    
143
    // Form data POST request
144
    WebRequest formRequest = new WebRequest(new URL("https://example.com/submit"), HttpMethod.POST);
145
    List<NameValuePair> parameters = new ArrayList<>();
146
    parameters.add(new NameValuePair("username", "john"));
147
    parameters.add(new NameValuePair("password", "secret"));
148
    formRequest.setParameters(parameters);
149
    formRequest.setEncodingType(FormEncodingType.URL_ENCODED);
150
    
151
    Page formResponse = webClient.getPage(formRequest);
152
}
153
```
154

155
### WebResponse Class
156

157
HTTP response data and metadata access.
158

159
```java { .api }
160
/**
161
 * HTTP response with content and metadata
162
 */
163
public class WebResponse {
164
    /** Get HTTP status code */
165
    public int getStatusCode();
166
    
167
    /** Get HTTP status message */
168
    public String getStatusMessage();
169
    
170
    /** Get response content as string */
171
    public String getContentAsString();
172
    
173
    /** Get response content with specific encoding */
174
    public String getContentAsString(Charset charset);
175
    
176
    /** Get response content as input stream */
177
    public InputStream getContentAsStream() throws IOException;
178
    
179
    /** Get response content as byte array */
180
    public byte[] getContentAsBytes();
181
    
182
    /** Get all response headers */
183
    public List<NameValuePair> getResponseHeaders();
184
    
185
    /** Get specific response header value */
186
    public String getResponseHeaderValue(String headerName);
187
    
188
    /** Get all values for header (for multi-value headers) */
189
    public List<String> getResponseHeaderValues(String headerName);
190
    
191
    /** Get response content type */
192
    public String getContentType();
193
    
194
    /** Get response character encoding */
195
    public Charset getContentCharset();
196
    
197
    /** Get response content length */
198
    public long getContentLength();
199
    
200
    /** Get response load time in milliseconds */
201
    public long getLoadTime();
202
    
203
    /** Get original request that generated response */
204
    public WebRequest getWebRequest();
205
    
206
    /** Get response data wrapper */
207
    public WebResponseData getResponseData();
208
    
209
    /** Get response URL (may differ from request due to redirects) */
210
    public URL getWebRequest().getUrl();
211
}
212
```
213

214
**Usage Examples:**
215

216
```java
217
// Examine response details
218
WebResponse response = page.getWebResponse();
219

220
System.out.println("Status: " + response.getStatusCode() + " " + response.getStatusMessage());
221
System.out.println("Content-Type: " + response.getContentType());
222
System.out.println("Content-Length: " + response.getContentLength());
223
System.out.println("Load Time: " + response.getLoadTime() + "ms");
224

225
// Get response headers
226
List<NameValuePair> headers = response.getResponseHeaders();
227
for (NameValuePair header : headers) {
228
    System.out.println(header.getName() + ": " + header.getValue());
229
}
230

231
// Get specific headers
232
String server = response.getResponseHeaderValue("Server");
233
String setCookie = response.getResponseHeaderValue("Set-Cookie");
234

235
// Different content access methods
236
String textContent = response.getContentAsString();
237
byte[] binaryContent = response.getContentAsBytes();
238
InputStream streamContent = response.getContentAsStream();
239
```
240

241
### HttpMethod Enum
242

243
HTTP method constants for request configuration.
244

245
```java { .api }
246
/**
247
 * HTTP method enumeration
248
 */
249
public enum HttpMethod {
250
    /** OPTIONS method for preflight requests */
251
    OPTIONS,
252
    
253
    /** GET method for retrieving data */
254
    GET,
255
    
256
    /** HEAD method for headers only */
257
    HEAD,
258
    
259
    /** POST method for sending data */
260
    POST,
261
    
262
    /** PUT method for updating resources */
263
    PUT,
264
    
265
    /** DELETE method for removing resources */
266
    DELETE,
267
    
268
    /** TRACE method for debugging */
269
    TRACE,
270
    
271
    /** PATCH method for partial updates */
272
    PATCH;
273
}
274
```
275

276
### WebConnection Interface
277

278
Interface for HTTP connection handling and custom implementations.
279

280
```java { .api }
281
/**
282
 * Interface for HTTP connection handling
283
 */
284
public interface WebConnection {
285
    /** Execute HTTP request and return response */
286
    WebResponse getResponse(WebRequest request) throws IOException;
287
    
288
    /** Close connection and cleanup resources */
289
    void close() throws IOException;
290
}
291
```
292

293
### HttpWebConnection Class
294

295
Default HTTP connection implementation with Apache HttpClient.
296

297
```java { .api }
298
/**
299
 * Default HTTP connection implementation using Apache HttpClient
300
 */
301
public class HttpWebConnection implements WebConnection {
302
    /** Create connection with default settings */
303
    public HttpWebConnection(WebClient webClient);
304
    
305
    /** Execute HTTP request */
306
    public WebResponse getResponse(WebRequest request) throws IOException;
307
    
308
    /** Get underlying HTTP client */
309
    public CloseableHttpClient getHttpClient();
310
    
311
    /** Set connection timeout */
312
    public void setTimeout(int timeout);
313
    
314
    /** Get connection timeout */
315
    public int getTimeout();
316
    
317
    /** Set socket timeout */
318
    public void setSocketTimeout(int socketTimeout);
319
    
320
    /** Get socket timeout */
321
    public int getSocketTimeout();
322
    
323
    /** Set connection request timeout */
324
    public void setConnectionRequestTimeout(int connectionRequestTimeout);
325
    
326
    /** Get connection request timeout */
327
    public int getConnectionRequestTimeout();
328
    
329
    /** Set maximum connections per route */
330
    public void setMaxConnectionsPerHost(int maxConnectionsPerHost);
331
    
332
    /** Get maximum connections per route */
333
    public int getMaxConnectionsPerHost();
334
    
335
    /** Set total maximum connections */
336
    public void setMaxTotalConnections(int maxTotalConnections);
337
    
338
    /** Get total maximum connections */
339
    public int getMaxTotalConnections();
340
    
341
    /** Set cookie store */
342
    public void setCookieStore(CookieStore cookieStore);
343
    
344
    /** Get cookie store */
345
    public CookieStore getCookieStore();
346
    
347
    /** Set credentials provider */
348
    public void setCredentialsProvider(CredentialsProvider credentialsProvider);
349
    
350
    /** Get credentials provider */
351
    public CredentialsProvider getCredentialsProvider();
352
    
353
    /** Close connection */
354
    public void close() throws IOException;
355
}
356
```
357

358
### MockWebConnection Class
359

360
Mock HTTP connection for testing and simulation.
361

362
```java { .api }
363
/**
364
 * Mock HTTP connection for testing and simulation
365
 */
366
public class MockWebConnection implements WebConnection {
367
    /** Create mock connection */
368
    public MockWebConnection();
369
    
370
    /** Set response for specific URL */
371
    public void setResponse(URL url, String content);
372
    
373
    /** Set response with status code */
374
    public void setResponse(URL url, String content, int statusCode, String statusMessage, String contentType, Charset charset);
375
    
376
    /** Set WebResponse for URL */
377
    public void setResponse(URL url, WebResponse response);
378
    
379
    /** Set default response for any unmatched URL */
380
    public void setDefaultResponse(String content);
381
    
382
    /** Set default response with details */
383
    public void setDefaultResponse(String content, int statusCode, String statusMessage, String contentType);
384
    
385
    /** Set default WebResponse */
386
    public void setDefaultResponse(WebResponse response);
387
    
388
    /** Get response for request */
389
    public WebResponse getResponse(WebRequest request) throws IOException;
390
    
391
    /** Get requested URLs in order */
392
    public List<URL> getRequestedUrls();
393
    
394
    /** Get last requested URL */
395
    public URL getLastRequestedUrl();
396
    
397
    /** Get request count for URL */
398
    public int getRequestCount(URL url);
399
    
400
    /** Clear all requests and responses */
401
    public void reset();
402
    
403
    /** Close connection */
404
    public void close() throws IOException;
405
}
406
```
407

408
**Usage Examples:**
409

410
```java
411
// Mock HTTP responses for testing
412
MockWebConnection mockConnection = new MockWebConnection();
413

414
// Set up mock responses
415
mockConnection.setResponse(new URL("https://api.example.com/users"), 
416
    "[{\"id\":1,\"name\":\"John\"},{\"id\":2,\"name\":\"Jane\"}]",
417
    200, "OK", "application/json", StandardCharsets.UTF_8);
418

419
mockConnection.setResponse(new URL("https://api.example.com/error"), 
420
    "{\"error\":\"Not found\"}", 404, "Not Found", "application/json", StandardCharsets.UTF_8);
421

422
// Default response for unmatched URLs
423
mockConnection.setDefaultResponse("Page not found", 404, "Not Found", "text/plain");
424

425
// Use mock connection
426
webClient.setWebConnection(mockConnection);
427

428
// Make requests - will return mocked responses
429
HtmlPage page = webClient.getPage("https://api.example.com/users");
430
String content = page.getWebResponse().getContentAsString();
431

432
// Check what was requested
433
List<URL> requestedUrls = mockConnection.getRequestedUrls();
434
System.out.println("Requested URLs: " + requestedUrls);
435
```
436

437
### Authentication Classes
438

439
```java { .api }
440
/**
441
 * Authentication credentials
442
 */
443
public class UsernamePasswordCredentials implements Credentials {
444
    /** Create credentials with username and password */
445
    public UsernamePasswordCredentials(String userName, String password);
446
    
447
    /** Create credentials with domain */
448
    public UsernamePasswordCredentials(String userName, String password, String workstation, String domain);
449
    
450
    /** Get username */
451
    public String getUserName();
452
    
453
    /** Get password */
454
    public String getPassword();
455
    
456
    /** Get workstation */
457
    public String getWorkstation();
458
    
459
    /** Get domain */
460
    public String getDomain();
461
}
462

463
/**
464
 * Default credentials provider
465
 */
466
public class DefaultCredentialsProvider implements CredentialsProvider {
467
    /** Create empty credentials provider */
468
    public DefaultCredentialsProvider();
469
    
470
    /** Add credentials for host and realm */
471
    public void addCredentials(String userName, String password, String host, int port, String realm);
472
    
473
    /** Add credentials for host */
474
    public void addCredentials(String userName, String password, String host, int port);
475
    
476
    /** Add credentials for realm */
477
    public void addCredentials(String userName, String password, String realm);
478
    
479
    /** Add general credentials */
480
    public void addCredentials(String userName, String password);
481
    
482
    /** Remove credentials */
483
    public void removeCredentials(AuthScope authScope);
484
    
485
    /** Clear all credentials */
486
    public void clear();
487
    
488
    /** Get credentials for scope */
489
    public Credentials getCredentials(AuthScope authScope);
490
}
491
```
492

493
### Proxy Configuration
494

495
```java { .api }
496
/**
497
 * Proxy configuration
498
 */
499
public class ProxyConfig {
500
    /** Create proxy configuration */
501
    public ProxyConfig(String proxyHost, int proxyPort);
502
    
503
    /** Create proxy with authentication */
504
    public ProxyConfig(String proxyHost, int proxyPort, String username, String password);
505
    
506
    /** Create proxy with scheme */
507
    public ProxyConfig(String proxyHost, int proxyPort, String scheme);
508
    
509
    /** Get proxy host */
510
    public String getProxyHost();
511
    
512
    /** Get proxy port */
513
    public int getProxyPort();
514
    
515
    /** Get proxy scheme */
516
    public String getProxyScheme();
517
    
518
    /** Get proxy username */
519
    public String getProxyUsername();
520
    
521
    /** Get proxy password */
522
    public String getProxyPassword();
523
    
524
    /** Check if proxy auto-detect is enabled */
525
    public boolean isProxyAutoDetect();
526
    
527
    /** Set proxy auto-detect */
528
    public void setProxyAutoDetect(boolean proxyAutoDetect);
529
    
530
    /** Get SOCKS proxy settings */
531
    public boolean isSocksProxy();
532
    
533
    /** Set SOCKS proxy */
534
    public void setSocksProxy(boolean socksProxy);
535
}
536
```
537

538
### HTTP Status Constants
539

540
```java { .api }
541
/**
542
 * Common HTTP status codes
543
 */
544
public static final int HTTP_OK = 200;
545
public static final int HTTP_CREATED = 201;
546
public static final int HTTP_ACCEPTED = 202;
547
public static final int HTTP_NO_CONTENT = 204;
548

549
public static final int HTTP_MOVED_PERMANENTLY = 301;
550
public static final int HTTP_FOUND = 302;
551
public static final int HTTP_SEE_OTHER = 303;
552
public static final int HTTP_NOT_MODIFIED = 304;
553
public static final int HTTP_TEMPORARY_REDIRECT = 307;
554
public static final int HTTP_PERMANENT_REDIRECT = 308;
555

556
public static final int HTTP_BAD_REQUEST = 400;
557
public static final int HTTP_UNAUTHORIZED = 401;
558
public static final int HTTP_FORBIDDEN = 403;
559
public static final int HTTP_NOT_FOUND = 404;
560
public static final int HTTP_METHOD_NOT_ALLOWED = 405;
561
public static final int HTTP_CONFLICT = 409;
562
public static final int HTTP_GONE = 410;
563

564
public static final int HTTP_INTERNAL_SERVER_ERROR = 500;
565
public static final int HTTP_NOT_IMPLEMENTED = 501;
566
public static final int HTTP_BAD_GATEWAY = 502;
567
public static final int HTTP_SERVICE_UNAVAILABLE = 503;
568
public static final int HTTP_GATEWAY_TIMEOUT = 504;
569
```
570

571
### SSL Configuration
572

573
```java { .api }
574
/**
575
 * SSL configuration for HTTPS connections
576
 */
577
public class SSLContextBuilder {
578
    /** Create SSL context builder */
579
    public static SSLContextBuilder create();
580
    
581
    /** Load trust material from keystore */
582
    public SSLContextBuilder loadTrustMaterial(KeyStore truststore, TrustStrategy trustStrategy);
583
    
584
    /** Load key material */
585
    public SSLContextBuilder loadKeyMaterial(KeyStore keystore, char[] keyPassword);
586
    
587
    /** Build SSL context */
588
    public SSLContext build();
589
}
590

591
/**
592
 * Trust all certificates strategy (for testing only)
593
 */
594
public class TrustAllStrategy implements TrustStrategy {
595
    /** Accept all certificates */
596
    public boolean isTrusted(X509Certificate[] chain, String authType);
597
}
598
```
599

600
**Usage Examples:**
601

602
```java
603
// Custom SSL configuration (accept all certificates - testing only)
604
webClient.getOptions().setUseInsecureSSL(true);
605

606
// Or with custom SSL context
607
SSLContext sslContext = SSLContextBuilder.create()
608
    .loadTrustMaterial(null, new TrustAllStrategy())
609
    .build();
610

611
// Authentication example
612
DefaultCredentialsProvider credentialsProvider = new DefaultCredentialsProvider();
613
credentialsProvider.addCredentials("username", "password", "example.com", 80, "Protected Area");
614
webClient.setCredentialsProvider(credentialsProvider);
615

616
// Proxy with authentication
617
ProxyConfig proxyConfig = new ProxyConfig("proxy.example.com", 8080, "proxyuser", "proxypass");
618
webClient.getOptions().setProxyConfig(proxyConfig);
619
```