0
# Eclipse Jetty HTTP Client
1

2
Eclipse Jetty HTTP Client is a comprehensive, asynchronous HTTP client library for Java that provides high-performance network communication capabilities. It supports modern web protocols including HTTP/1.1, HTTP/2, and WebSocket connections, with built-in authentication mechanisms, proxy configurations, and sophisticated connection pooling strategies.
3

4
## Package Information
5

6
- **Package Name**: org.eclipse.jetty:jetty-client
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven pom.xml:
10
  ```xml
11
  <dependency>
12
    <groupId>org.eclipse.jetty</groupId>
13
    <artifactId>jetty-client</artifactId>
14
    <version>12.0.21</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.eclipse.jetty.client.HttpClient;
22
import org.eclipse.jetty.client.Request;
23
import org.eclipse.jetty.client.Response;
24
import org.eclipse.jetty.client.ContentResponse;
25
```
26

27
## Basic Usage
28

29
```java
30
import org.eclipse.jetty.client.HttpClient;
31
import org.eclipse.jetty.client.ContentResponse;
32

33
// Create and start the HTTP client
34
HttpClient httpClient = new HttpClient();
35
httpClient.start();
36

37
try {
38
    // Simple GET request (synchronous)
39
    ContentResponse response = httpClient.GET("https://api.example.com/data");
40
    System.out.println("Status: " + response.getStatus());
41
    System.out.println("Content: " + response.getContentAsString());
42
    
43
    // POST request with JSON content
44
    ContentResponse postResponse = httpClient.POST("https://api.example.com/users")
45
        .header("Content-Type", "application/json")
46
        .body(new StringRequestContent("{\"name\":\"John\",\"email\":\"john@example.com\"}"))
47
        .send();
48
        
49
    // Asynchronous request with callback
50
    httpClient.newRequest("https://api.example.com/async")
51
        .send(result -> {
52
            if (result.isSucceeded()) {
53
                Response response = result.getResponse();
54
                System.out.println("Async response status: " + response.getStatus());
55
            }
56
        });
57
        
58
} finally {
59
    // Always stop the client when done
60
    httpClient.stop();
61
}
62
```
63

64
## Architecture
65

66
The Jetty HTTP Client is built around several key components:
67

68
- **HttpClient**: Central configuration point and request factory
69
- **Request/Response Model**: Fluent API for building and handling HTTP requests/responses
70
- **Transport Layer**: Pluggable transport implementations (HTTP/1.1, HTTP/2, WebSocket)
71
- **Connection Management**: Multiple connection pool strategies for different use cases
72
- **Content Processing**: Flexible content handling for request bodies and response processing
73
- **Authentication System**: Support for Basic, Digest, and SPNEGO authentication
74
- **Protocol Handlers**: Automatic handling of redirects, authentication challenges, and upgrades
75

76
## Capabilities
77

78
### Core HTTP Operations
79

80
Essential HTTP client functionality for making GET, POST, PUT, DELETE and other HTTP requests with full request/response lifecycle management.
81

82
```java { .api }
83
public class HttpClient extends ContainerLifeCycle {
84
    public HttpClient();
85
    public void start() throws Exception;
86
    public void stop() throws Exception;
87
    
88
    public ContentResponse GET(String uri) throws InterruptedException, ExecutionException, TimeoutException;
89
    public ContentResponse GET(URI uri) throws InterruptedException, ExecutionException, TimeoutException;
90
    public Request POST(String uri);
91
    public Request POST(URI uri);
92
    public Request newRequest(String uri);
93
    public Request newRequest(URI uri);
94
    public Request newRequest(String host, int port);
95
}
96
```
97

98
[HTTP Operations](./http-operations.md)
99

100
### Request Configuration
101

102
Fluent API for configuring HTTP requests including headers, timeouts, content, cookies, and HTTP methods with comprehensive customization options.
103

104
```java { .api }
105
public interface Request {
106
    Request scheme(String scheme);
107
    Request host(String host);
108
    Request port(int port);
109
    Request path(String path);
110
    Request method(HttpMethod method);
111
    Request method(String method);
112
    Request version(HttpVersion version);
113
    Request timeout(long timeout, TimeUnit unit);
114
    Request header(String name, String value);
115
    Request cookie(HttpCookie cookie);
116
    Request body(Content content);
117
    
118
    ContentResponse send() throws InterruptedException, ExecutionException, TimeoutException;
119
    void send(Response.CompleteListener listener);
120
}
121
```
122

123
[Request Configuration](./request-configuration.md)
124

125
### Response Processing
126

127
Comprehensive response handling including status codes, headers, content processing, and streaming capabilities with multiple listener patterns.
128

129
```java { .api }
130
public interface Response {
131
    Request getRequest();
132
    HttpVersion getVersion();
133
    int getStatus();
134
    String getReason();
135
    HttpFields getHeaders();
136
    HttpFields getTrailers();
137
}
138

139
public interface ContentResponse extends Response {
140
    String getMediaType();
141
    String getEncoding();
142
    byte[] getContent();
143
    String getContentAsString();
144
}
145
```
146

147
[Response Processing](./response-processing.md)
148

149
### Content Management
150

151
Flexible content handling for request bodies and response processing, supporting strings, byte arrays, streams, files, forms, and multipart data.
152

153
```java { .api }
154
public class StringRequestContent extends BytesRequestContent;
155
public class BytesRequestContent extends ByteBufferRequestContent;
156
public class InputStreamRequestContent implements Request.Content;
157
public class PathRequestContent implements Request.Content;
158
public class FormRequestContent implements Request.Content;
159
public class MultiPartRequestContent implements Request.Content;
160
```
161

162
[Content Management](./content-management.md)
163

164
### Authentication
165

166
Support for HTTP authentication mechanisms including Basic, Digest, and SPNEGO/Kerberos with credential storage and automatic challenge handling.
167

168
```java { .api }
169
public interface AuthenticationStore {
170
    void addAuthentication(Authentication authentication);
171
    void removeAuthentication(Authentication authentication);
172
    AuthenticationResult findAuthenticationResult(URI uri);
173
}
174

175
public class BasicAuthentication implements Authentication;
176
public class DigestAuthentication implements Authentication;
177
public class SPNEGOAuthentication implements Authentication;
178
```
179

180
[Authentication](./authentication.md)
181

182
### Proxy Configuration
183

184
Comprehensive proxy support including HTTP, SOCKS4, and SOCKS5 proxies with authentication and per-destination configuration.
185

186
```java { .api }
187
public class ProxyConfiguration {
188
    public void addProxy(Proxy proxy);
189
    public boolean removeProxy(Proxy proxy);
190
    public List<Proxy> getProxies();
191
}
192

193
public class HttpProxy extends ProxyConfiguration.Proxy;
194
public class Socks4Proxy extends ProxyConfiguration.Proxy;
195
public class Socks5Proxy extends ProxyConfiguration.Proxy;
196
```
197

198
[Proxy Configuration](./proxy-configuration.md)
199

200
### Connection Pooling
201

202
Multiple connection pool strategies for optimizing connection reuse and performance including duplex, multiplex, round-robin, and random selection pools.
203

204
```java { .api }
205
public interface ConnectionPool {
206
    Connection acquire(boolean create);
207
    boolean release(Connection connection);
208
    boolean remove(Connection connection);
209
}
210

211
public class DuplexConnectionPool implements ConnectionPool;
212
public class MultiplexConnectionPool implements ConnectionPool;
213
public class RoundRobinConnectionPool implements ConnectionPool;
214
```
215

216
[Connection Pooling](./connection-pooling.md)
217

218
## Types
219

220
### Core Types
221

222
```java { .api }
223
public interface Request {
224
    interface Listener extends EventListener {
225
        default void onQueued(Request request) {}
226
        default void onBegin(Request request) {}
227
        default void onHeaders(Request request) {}
228
        default void onCommit(Request request) {}
229
        default void onContent(Request request, ByteBuffer content) {}
230
        default void onSuccess(Request request) {}
231
        default void onFailure(Request request, Throwable failure) {}
232
    }
233
    
234
    interface Content {
235
        String getContentType();
236
        long getLength();
237
        boolean isReproducible();
238
    }
239
}
240

241
public interface Response {
242
    interface Listener extends EventListener {
243
        default void onBegin(Response response) {}
244
        default void onHeader(Response response, HttpField field) {}
245
        default void onHeaders(Response response) {}
246
        default void onContent(Response response, ByteBuffer content) {}
247
        default void onSuccess(Response response) {}
248
        default void onFailure(Response response, Throwable failure) {}
249
        default void onComplete(Result result) {}
250
    }
251
    
252
    interface CompleteListener extends Listener {
253
        void onComplete(Result result);
254
    }
255
}
256

257
public interface Result {
258
    Request getRequest();
259
    Response getResponse();
260
    Throwable getRequestFailure();
261
    Throwable getResponseFailure();
262
    boolean isSucceeded();
263
    boolean isFailed();
264
}
265
```
266

267
### HTTP Types
268

269
```java { .api }
270
// From org.eclipse.jetty.http package (external dependency)
271
public enum HttpMethod { GET, POST, PUT, DELETE, HEAD, OPTIONS, TRACE, CONNECT, PATCH }
272
public enum HttpVersion { HTTP_1_0, HTTP_1_1, HTTP_2, HTTP_3 }
273
public class HttpFields implements Iterable<HttpField> {}
274
public class HttpField {}
275
public class HttpCookie {}
276
```
277

278
### Configuration Types
279

280
```java { .api }
281
public class Origin {
282
    public Origin(String scheme, String host, int port);
283
    public String getScheme();
284
    public String getHost();
285
    public int getPort();
286
}
287

288
public class ProxyConfiguration.Proxy {
289
    public Origin.Address getAddress();
290
    public boolean isSecure();
291
    public Set<String> getIncludedAddresses();
292
    public Set<String> getExcludedAddresses();
293
}
294
```