0
# Selenium HTTP
1

2
Selenium HTTP provides HTTP client and server abstractions specifically designed for Selenium WebDriver communication. It offers a comprehensive HTTP layer that includes client configuration, request/response handling, routing capabilities, and WebSocket support with pluggable HTTP client factories, built-in retry mechanisms, and specialized utilities for Selenium-specific tasks.
3

4
## Package Information
5

6
- **Package Name**: selenium-http
7
- **Package Type**: maven
8
- **Group ID**: org.seleniumhq.selenium
9
- **Artifact ID**: selenium-http
10
- **Language**: Java
11
- **Installation**: Include `org.seleniumhq.selenium:selenium-http:4.33.0` in your Maven dependencies
12

13
```xml
14
<dependency>
15
    <groupId>org.seleniumhq.selenium</groupId>
16
    <artifactId>selenium-http</artifactId>
17
    <version>4.33.0</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
import org.openqa.selenium.remote.http.HttpClient;
25
import org.openqa.selenium.remote.http.HttpRequest;
26
import org.openqa.selenium.remote.http.HttpResponse;
27
import org.openqa.selenium.remote.http.HttpMessage;
28
import org.openqa.selenium.remote.http.HttpMethod;
29
import org.openqa.selenium.remote.http.ClientConfig;
30
import org.openqa.selenium.remote.http.Contents;
31
import org.openqa.selenium.remote.http.HttpClientName;
32
```
33

34
## Basic Usage
35

36
```java
37
import org.openqa.selenium.remote.http.*;
38
import java.net.URL;
39

40
// Create HTTP client with default configuration
41
URL baseUrl = new URL("https://api.example.com");
42
HttpClient client = HttpClient.Factory.createDefault().createClient(baseUrl);
43

44
// Create and execute a GET request
45
HttpRequest request = new HttpRequest(HttpMethod.GET, "/users");
46
request.addHeader("Accept", "application/json");
47

48
HttpResponse response = client.execute(request);
49
System.out.println("Status: " + response.getStatus());
50
System.out.println("Response: " + Contents.string(response));
51

52
// Clean up
53
client.close();
54
```
55

56
## Architecture
57

58
The Selenium HTTP package is built around several key components:
59

60
- **HTTP Client System**: Main `HttpClient` interface with pluggable factory implementations using Java's ServiceLoader mechanism
61
- **Request/Response Model**: `HttpRequest` and `HttpResponse` classes extending a common `HttpMessage` base with header and content management
62
- **Configuration Layer**: `ClientConfig` class providing builder pattern for timeouts, proxies, SSL context, and filters
63
- **Filtering System**: `Filter` interface enabling request/response interception with built-in filters for user agents, logging, and retries
64
- **Routing Engine**: `Route` and `Routable` interfaces with URL template matching for server-side request handling
65
- **WebSocket Support**: Full WebSocket abstraction with message types and listener interface
66
- **Content Handling**: Comprehensive `Contents` utility for various content formats and conversions
67

68
## Capabilities
69

70
### HTTP Client
71

72
Core HTTP client functionality for making requests with full configuration support, connection pooling, and async execution capabilities.
73

74
```java { .api }
75
public interface HttpClient extends Closeable, HttpHandler {
76
    WebSocket openSocket(HttpRequest request, WebSocket.Listener listener);
77
    default CompletableFuture<HttpResponse> executeAsync(HttpRequest req);
78
    default void close();
79
    
80
    interface Factory {
81
        static Factory create(String name);
82
        static Factory createDefault();
83
        default HttpClient createClient(URL url);
84
        HttpClient createClient(ClientConfig config);
85
        default void cleanupIdleClients();
86
    }
87
}
88
```
89

90
[HTTP Client](./http-client.md)
91

92
### Request and Response Handling
93

94
HTTP message abstractions with header management, content handling, and query parameter support for both requests and responses.
95

96
```java { .api }
97
public class HttpRequest extends HttpMessage<HttpRequest> {
98
    public HttpRequest(HttpMethod method, String uri);
99
    public String getUri();
100
    public HttpMethod getMethod();
101
    public String getQueryParameter(String name);
102
    public HttpRequest addQueryParameter(String name, String value);
103
    public Iterable<String> getQueryParameterNames();
104
    public Iterable<String> getQueryParameters(String name);
105
}
106

107
public class HttpResponse extends HttpMessage<HttpResponse> {
108
    public boolean isSuccessful();
109
    public int getStatus();
110
    public HttpResponse setStatus(int status);
111
    public HttpResponse setTargetHost(String host);
112
    public String getTargetHost();
113
}
114
```
115

116
[Request and Response](./request-response.md)
117

118
### Client Configuration
119

120
Flexible client configuration system with builder pattern for timeouts, authentication, proxies, SSL context, and filter chains.
121

122
```java { .api }
123
public class ClientConfig {
124
    public static ClientConfig defaultConfig();
125
    public ClientConfig baseUri(URI baseUri);
126
    public ClientConfig baseUrl(URL baseUrl);
127
    public ClientConfig connectionTimeout(Duration timeout);
128
    public ClientConfig readTimeout(Duration timeout);
129
    public ClientConfig withFilter(Filter filter);
130
    public ClientConfig withRetries();
131
    public ClientConfig proxy(Proxy proxy);
132
    public ClientConfig authenticateAs(Credentials credentials);
133
    public ClientConfig sslContext(SSLContext sslContext);
134
    public ClientConfig version(String version);
135
}
136
```
137

138
[Client Configuration](./client-config.md)
139

140
### WebSocket Support
141

142
WebSocket client functionality with message types (text, binary, close) and event-driven listener interface for real-time communication.
143

144
```java { .api }
145
public interface WebSocket extends Closeable {
146
    WebSocket send(Message message);
147
    default WebSocket sendText(CharSequence data);
148
    default WebSocket sendBinary(byte[] data);
149
    void close();
150
    
151
    interface Listener extends Consumer<Message> {
152
        default void onBinary(byte[] data);
153
        default void onClose(int code, String reason);
154
        default void onText(CharSequence data);
155
        default void onError(Throwable cause);
156
    }
157
}
158
```
159

160
[WebSocket Support](./websocket.md)
161

162
### Content Handling
163

164
Comprehensive content utilities for converting between different formats (strings, bytes, JSON) with charset support and streaming capabilities.
165

166
```java { .api }
167
public class Contents {
168
    public static Supplier empty();
169
    public static Supplier utf8String(CharSequence value);
170
    public static Supplier string(CharSequence value, Charset charset);
171
    public static Supplier bytes(byte[] bytes);
172
    public static byte[] bytes(Supplier supplier);
173
    public static String utf8String(Supplier supplier);
174
    public static String string(Supplier supplier, Charset charset);
175
    public static String string(HttpMessage<?> message);
176
    public static Reader utf8Reader(Supplier supplier);
177
    public static Reader reader(Supplier supplier, Charset charset);
178
    public static Reader reader(HttpMessage<?> message);
179
    public static Supplier asJson(Object obj);
180
    public static <T> T fromJson(HttpMessage<?> message, Type typeOfT);
181
    public static String string(File input) throws IOException;
182
    
183
    public interface Supplier extends java.util.function.Supplier<InputStream>, AutoCloseable {
184
        int length();
185
        void close() throws IOException;
186
    }
187
}
188
```
189

190
[Content Handling](./content-handling.md)
191

192
### Filtering System
193

194
HTTP request/response filtering system using decorator pattern with built-in filters for user agents, logging, and automatic retries.
195

196
```java { .api }
197
@FunctionalInterface
198
public interface Filter extends Function<HttpHandler, HttpHandler> {
199
    Filter andThen(Filter next);
200
    HttpHandler andFinally(HttpHandler end);
201
    Routable andFinally(Routable end);
202
}
203
```
204

205
[Filtering System](./filtering.md)
206

207
### Routing System
208

209
Server-side HTTP request routing with URL template matching, parameter extraction, and nested route support for building HTTP servers.
210

211
```java { .api }
212
public abstract class Route implements HttpHandler, Routable {
213
    public HttpHandler fallbackTo(Supplier<HttpHandler> handler);
214
    public final HttpResponse execute(HttpRequest req);
215
    protected abstract HttpResponse handle(HttpRequest req);
216
    
217
    public static PredicatedConfig matching(Predicate<HttpRequest> predicate);
218
    public static TemplatizedRouteConfig delete(String template);
219
    public static TemplatizedRouteConfig get(String template);
220
    public static TemplatizedRouteConfig post(String template);
221
    public static TemplatizedRouteConfig options(String template);
222
    public static NestedRouteConfig prefix(String prefix);
223
    public static Route combine(Routable first, Routable... others);
224
}
225
```
226

227
[Routing System](./routing.md)
228

229
## Common Types
230

231
```java { .api }
232
public abstract class HttpMessage<M extends HttpMessage<M>> {
233
    public Object getAttribute(String key);
234
    public M setAttribute(String key, Object value);
235
    public M removeAttribute(String key);
236
    public Iterable<String> getAttributeNames();
237
    public void forEachHeader(BiConsumer<String, String> action);
238
    public Iterable<String> getHeaderNames();
239
    public Iterable<String> getHeaders(String name);
240
    public String getHeader(String name);
241
    public M setHeader(String name, String value);
242
    public M addHeader(String name, String value);
243
    public M removeHeader(String name);
244
    public Charset getContentEncoding();
245
    public M setContent(Contents.Supplier supplier);
246
    public Contents.Supplier getContent();
247
}
248

249
public enum HttpMethod {
250
    DELETE, GET, POST, PUT, OPTIONS, PATCH, HEAD, CONNECT, TRACE;
251
    
252
    public static HttpMethod getHttpMethod(String method);
253
}
254

255
public enum HttpHeader {
256
    CacheControl, ContentLength, ContentType, Expires, Host, UserAgent, XForwardedFor;
257
    
258
    public String getName();
259
}
260

261
@FunctionalInterface
262
public interface HttpHandler {
263
    HttpResponse execute(HttpRequest req) throws UncheckedIOException;
264
    default HttpHandler with(Filter filter);
265
}
266

267
public interface Routable extends HttpHandler {
268
    boolean matches(HttpRequest req);
269
    default Routable with(Filter filter);
270
}
271

272
public class ConnectionFailedException extends WebDriverException {
273
    public ConnectionFailedException(String message);
274
    public ConnectionFailedException(String message, Throwable cause);
275
}
276

277
@Retention(RetentionPolicy.RUNTIME)
278
@Target(ElementType.TYPE)
279
public @interface HttpClientName {
280
    String value();
281
}
282
```