0
# HTTP Client
1

2
Core HTTP client functionality for making synchronous and asynchronous requests with full configuration support, connection pooling, and WebSocket capabilities.
3

4
## Capabilities
5

6
### HttpClient Interface
7

8
Main interface for making HTTP requests with support for both synchronous and asynchronous execution.
9

10
```java { .api }
11
/**
12
 * Main interface for making HTTP requests
13
 * Extends Closeable for resource management and HttpHandler for request execution
14
 */
15
public interface HttpClient extends Closeable, HttpHandler {
16
    /**
17
     * Opens a WebSocket connection using the provided request and listener
18
     * @param request HTTP request for WebSocket handshake
19
     * @param listener WebSocket event listener for handling messages
20
     * @return WebSocket instance for sending messages
21
     */
22
    WebSocket openSocket(HttpRequest request, WebSocket.Listener listener);
23
    
24
    /**
25
     * Executes HTTP request asynchronously
26
     * @param req HTTP request to execute
27
     * @return CompletableFuture containing the HTTP response
28
     */
29
    default CompletableFuture<HttpResponse> executeAsync(HttpRequest req);
30
    
31
    /**
32
     * Closes the HTTP client and releases resources
33
     * Default implementation does nothing
34
     */
35
    default void close();
36
}
37
```
38

39
**Usage Examples:**
40

41
```java
42
import org.openqa.selenium.remote.http.*;
43
import java.net.URL;
44
import java.util.concurrent.CompletableFuture;
45

46
// Create client with default factory
47
HttpClient client = HttpClient.Factory.createDefault()
48
    .createClient(new URL("https://api.example.com"));
49

50
// Synchronous request
51
HttpRequest request = new HttpRequest(HttpMethod.GET, "/users/123");
52
request.addHeader("Accept", "application/json");
53
HttpResponse response = client.execute(request);
54

55
// Asynchronous request
56
CompletableFuture<HttpResponse> future = client.executeAsync(request);
57
future.thenAccept(resp -> {
58
    System.out.println("Status: " + resp.getStatus());
59
    System.out.println("Body: " + Contents.string(resp));
60
});
61

62
// WebSocket connection
63
WebSocket socket = client.openSocket(
64
    new HttpRequest(HttpMethod.GET, "/websocket"),
65
    new WebSocket.Listener() {
66
        @Override
67
        public void onText(CharSequence data) {
68
            System.out.println("Received: " + data);
69
        }
70
    }
71
);
72

73
socket.sendText("Hello WebSocket");
74
socket.close();
75
client.close();
76
```
77

78
### HttpClient Factory
79

80
Factory interface for creating HTTP client instances with pluggable implementations using Java's ServiceLoader mechanism.
81

82
```java { .api }
83
/**
84
 * Factory interface for creating HttpClient instances
85
 * Uses ServiceLoader mechanism for pluggable implementations
86
 */
87
public interface Factory {
88
    /**
89
     * Creates factory instance by name using ServiceLoader
90
     * Looks for implementations with @HttpClientName annotation
91
     * @param name Name of the HTTP client implementation
92
     * @return Factory instance for the specified implementation
93
     * @throws IllegalArgumentException if no implementation found
94
     * @throws IllegalStateException if multiple implementations found
95
     */
96
    static Factory create(String name);
97
    
98
    /**
99
     * Creates default factory using system property 'webdriver.http.factory'
100
     * Defaults to 'jdk-http-client' if property not set
101
     * @return Default factory instance
102
     */
103
    static Factory createDefault();
104
    
105
    /**
106
     * Creates HTTP client with base URL using default configuration
107
     * @param url Base URL for all requests
108
     * @return Configured HttpClient instance
109
     */
110
    default HttpClient createClient(URL url);
111
    
112
    /**
113
     * Creates HTTP client with custom configuration
114
     * @param config Client configuration with timeouts, filters, etc.
115
     * @return Configured HttpClient instance
116
     */
117
    HttpClient createClient(ClientConfig config);
118
    
119
    /**
120
     * Closes idle client connections
121
     * Default implementation does nothing
122
     */
123
    default void cleanupIdleClients();
124
}
125
```
126

127
**Usage Examples:**
128

129
```java
130
import org.openqa.selenium.remote.http.*;
131
import java.net.URL;
132

133
// Create specific HTTP client implementation
134
HttpClient.Factory factory = HttpClient.Factory.create("jdk-http-client");
135
HttpClient client = factory.createClient(new URL("https://api.example.com"));
136

137
// Create client with default factory (uses system property)
138
HttpClient defaultClient = HttpClient.Factory.createDefault()
139
    .createClient(new URL("https://api.example.com"));
140

141
// Create client with custom configuration
142
ClientConfig config = ClientConfig.defaultConfig()
143
    .baseUrl(new URL("https://api.example.com"))
144
    .connectionTimeout(Duration.ofSeconds(30))
145
    .readTimeout(Duration.ofMinutes(5))
146
    .withRetries();
147

148
HttpClient configuredClient = HttpClient.Factory.createDefault()
149
    .createClient(config);
150

151
// Cleanup idle connections
152
factory.cleanupIdleClients();
153
```
154

155
### JDK HTTP Client Implementation
156

157
Production-ready HTTP client implementation using JDK's built-in HTTP client with full WebSocket support.
158

159
```java { .api }
160
/**
161
 * JDK-based HTTP client implementation
162
 * Uses Java's built-in HTTP client for requests and WebSocket connections
163
 */
164
public class JdkHttpClient implements HttpClient {
165
    public static final Logger LOG;
166
    
167
    /**
168
     * Opens WebSocket connection using JDK WebSocket client
169
     * @param request HTTP request for WebSocket handshake
170
     * @param listener WebSocket event listener
171
     * @return WebSocket instance for communication
172
     */
173
    public WebSocket openSocket(HttpRequest request, WebSocket.Listener listener);
174
    
175
    /**
176
     * Executes HTTP request asynchronously using JDK HTTP client
177
     * @param request HTTP request to execute
178
     * @return CompletableFuture with HTTP response
179
     */
180
    public CompletableFuture<HttpResponse> executeAsync(HttpRequest request);
181
    
182
    /**
183
     * Executes HTTP request synchronously
184
     * @param req HTTP request to execute
185
     * @return HTTP response
186
     */
187
    public HttpResponse execute(HttpRequest req);
188
    
189
    /**
190
     * Closes HTTP client and releases resources
191
     */
192
    public void close();
193
    
194
    /**
195
     * Factory for creating JDK HTTP client instances
196
     * Annotated with @HttpClientName("jdk-http-client")
197
     */
198
    @AutoService(HttpClient.Factory.class)
199
    @HttpClientName("jdk-http-client")
200
    public static class Factory implements HttpClient.Factory {
201
        /**
202
         * Creates JDK HTTP client with specified configuration
203
         * @param config Client configuration
204
         * @return JdkHttpClient instance
205
         */
206
        public HttpClient createClient(ClientConfig config);
207
    }
208
}
209
```
210

211
**Usage Examples:**
212

213
```java
214
import org.openqa.selenium.remote.http.*;
215
import org.openqa.selenium.remote.http.jdk.JdkHttpClient;
216
import java.net.URL;
217

218
// Create JDK HTTP client directly
219
ClientConfig config = ClientConfig.defaultConfig()
220
    .baseUrl(new URL("https://api.example.com"))
221
    .connectionTimeout(Duration.ofSeconds(30));
222

223
JdkHttpClient.Factory factory = new JdkHttpClient.Factory();
224
HttpClient client = factory.createClient(config);
225

226
// Use via factory system
227
HttpClient.Factory defaultFactory = HttpClient.Factory.create("jdk-http-client");
228
HttpClient jdkClient = defaultFactory.createClient(config);
229

230
// Execute requests
231
HttpRequest request = new HttpRequest(HttpMethod.POST, "/data");
232
request.setContent(Contents.asJson(Map.of("key", "value")));
233
HttpResponse response = client.execute(request);
234

235
System.out.println("Response status: " + response.getStatus());
236
System.out.println("Response body: " + Contents.string(response));
237
```
238

239
## Service Loader Configuration
240

241
To create custom HTTP client implementations, implement the `HttpClient.Factory` interface and annotate with `@HttpClientName`:
242

243
```java
244
@AutoService(HttpClient.Factory.class)
245
@HttpClientName("my-custom-client")
246
public class MyCustomHttpClientFactory implements HttpClient.Factory {
247
    @Override
248
    public HttpClient createClient(ClientConfig config) {
249
        return new MyCustomHttpClient(config);
250
    }
251
}
252
```
253

254
The implementation will be automatically discovered by the ServiceLoader mechanism and can be used via:
255

256
```java
257
HttpClient.Factory factory = HttpClient.Factory.create("my-custom-client");
258
```