0
# Request Configuration
1

2
The Request interface provides a fluent API for configuring HTTP requests with comprehensive customization options including headers, timeouts, content, cookies, and HTTP methods.
3

4
## Request Interface
5

6
The core interface for configuring and sending HTTP requests.
7

8
```java { .api }
9
public interface Request {
10
    // Connection information
11
    Connection getConnection();
12
    
13
    // URI components
14
    String getScheme();
15
    Request scheme(String scheme);
16
    String getHost();
17
    Request host(String host);
18
    int getPort();
19
    Request port(int port);
20
    String getPath();
21
    Request path(String path);
22
    String getQuery();
23
    Request query(String query);
24
    URI getURI();
25
    
26
    // HTTP method and version
27
    HttpMethod getMethod();
28
    Request method(HttpMethod method);
29
    Request method(String method);
30
    HttpVersion getVersion();
31
    Request version(HttpVersion version);
32
    
33
    // Headers and cookies
34
    HttpFields getHeaders();
35
    Request headers(Consumer<HttpFields> headers);
36
    Request header(String name, String value);
37
    Request headers(HttpFields headers);
38
    List<HttpCookie> getCookies();
39
    Request cookie(HttpCookie cookie);
40
    
41
    // Timeout configuration
42
    Request timeout(long timeout, TimeUnit unit);
43
    long getTimeout();
44
    
45
    // Content
46
    Request body(Request.Content content);
47
    Request file(Path file) throws IOException;
48
    Request file(Path file, String contentType) throws IOException;
49
    
50
    // Sending
51
    ContentResponse send() throws InterruptedException, ExecutionException, TimeoutException;
52
    void send(Response.CompleteListener listener);
53
    
54
    // Listener management
55
    Request onRequestQueued(Request.QueuedListener listener);
56
    Request onRequestBegin(Request.BeginListener listener);
57
    Request onRequestHeaders(Request.HeadersListener listener);
58
    Request onRequestCommit(Request.CommitListener listener);
59
    Request onRequestContent(Request.ContentListener listener);
60
    Request onRequestSuccess(Request.SuccessListener listener);
61
    Request onRequestFailure(Request.FailureListener listener);
62
    Request onResponseBegin(Response.BeginListener listener);
63
    Request onResponseHeader(Response.HeaderListener listener);
64
    Request onResponseHeaders(Response.HeadersListener listener);
65
    Request onResponseContent(Response.ContentListener listener);
66
    Request onResponseContentDemanded(Response.DemandedContentListener listener);
67
    Request onResponseSuccess(Response.SuccessListener listener);
68
    Request onResponseFailure(Response.FailureListener listener);
69
}
70
```
71

72
## URI Configuration
73

74
Configure the target URI components of the request.
75

76
### Basic URI Configuration
77

78
```java
79
Request request = client.newRequest("https://api.example.com")
80
    .path("/users/123")
81
    .query("format=json&include=profile");
82
```
83

84
### Component-by-Component Configuration
85

86
```java
87
Request request = client.newRequest("localhost", 8080)
88
    .scheme("https")
89
    .path("/api/v1/data")
90
    .query("limit=10&offset=0");
91
```
92

93
### Query Parameter Building
94

95
```java
96
// Using Fields for structured query parameters
97
Fields queryFields = new Fields();
98
queryFields.add("category", "books");
99
queryFields.add("sort", "title");
100
queryFields.add("order", "asc");
101

102
String queryString = queryFields.toQueryString();
103
Request request = client.newRequest("https://api.example.com/search")
104
    .query(queryString);
105
```
106

107
## HTTP Method Configuration
108

109
Configure the HTTP method for the request.
110

111
### Using HttpMethod Enum
112

113
```java
114
Request request = client.newRequest("https://api.example.com/users/123")
115
    .method(HttpMethod.PUT);
116
```
117

118
### Using String Method
119

120
```java
121
Request request = client.newRequest("https://api.example.com/data")
122
    .method("PATCH");
123
```
124

125
### Common HTTP Methods
126

127
```java
128
// GET (default for newRequest)
129
Request getRequest = client.newRequest("https://api.example.com/users");
130

131
// POST (also available via client.POST())
132
Request postRequest = client.newRequest("https://api.example.com/users")
133
    .method(HttpMethod.POST);
134

135
// PUT
136
Request putRequest = client.newRequest("https://api.example.com/users/123")
137
    .method(HttpMethod.PUT);
138

139
// DELETE
140
Request deleteRequest = client.newRequest("https://api.example.com/users/123")
141
    .method(HttpMethod.DELETE);
142

143
// PATCH
144
Request patchRequest = client.newRequest("https://api.example.com/users/123")
145
    .method(HttpMethod.PATCH);
146
```
147

148
## Header Configuration
149

150
Configure HTTP headers for the request.
151

152
### Adding Individual Headers
153

154
```java
155
Request request = client.newRequest("https://api.example.com/data")
156
    .header("Authorization", "Bearer " + token)
157
    .header("Content-Type", "application/json")
158
    .header("Accept", "application/json")
159
    .header("User-Agent", "MyApp/1.0");
160
```
161

162
### Using Consumer for Headers
163

164
```java
165
Request request = client.newRequest("https://api.example.com/data")
166
    .headers(headers -> {
167
        headers.add("Authorization", "Bearer " + token);
168
        headers.add("Content-Type", "application/json");
169
        headers.add("Accept", "application/json");
170
        headers.add("X-Custom-Header", "custom-value");
171
    });
172
```
173

174
### Setting All Headers at Once
175

176
```java
177
HttpFields headers = HttpFields.build()
178
    .add("Authorization", "Bearer " + token)
179
    .add("Content-Type", "application/json")
180
    .add("Accept", "application/json");
181

182
Request request = client.newRequest("https://api.example.com/data")
183
    .headers(headers);
184
```
185

186
## Cookie Configuration
187

188
Configure cookies for the request.
189

190
### Adding Individual Cookies
191

192
```java
193
HttpCookie sessionCookie = HttpCookie.build("JSESSIONID", "ABC123")
194
    .path("/")
195
    .secure(true)
196
    .build();
197
    
198
HttpCookie userCookie = HttpCookie.build("userId", "12345")
199
    .path("/")
200
    .build();
201

202
Request request = client.newRequest("https://api.example.com/data")
203
    .cookie(sessionCookie)
204
    .cookie(userCookie);
205
```
206

207
### Creating Cookies with Builder
208

209
```java
210
HttpCookie cookie = HttpCookie.build("preferences", "theme=dark;lang=en")
211
    .domain(".example.com")
212
    .path("/")
213
    .maxAge(Duration.ofDays(30))
214
    .secure(true)
215
    .httpOnly(true)
216
    .sameSite(HttpCookie.SameSite.STRICT)
217
    .build();
218

219
Request request = client.newRequest("https://api.example.com/user/profile")
220
    .cookie(cookie);
221
```
222

223
## Timeout Configuration
224

225
Configure request timeout settings.
226

227
### Request Timeout
228

229
```java
230
// Timeout in milliseconds
231
Request request = client.newRequest("https://api.example.com/data")
232
    .timeout(5000, TimeUnit.MILLISECONDS);
233

234
// Timeout in seconds
235
Request request = client.newRequest("https://api.example.com/data")
236
    .timeout(30, TimeUnit.SECONDS);
237

238
// Timeout in minutes
239
Request request = client.newRequest("https://api.example.com/long-running")
240
    .timeout(5, TimeUnit.MINUTES);
241
```
242

243
### No Timeout
244

245
```java
246
Request request = client.newRequest("https://api.example.com/data")
247
    .timeout(0, TimeUnit.MILLISECONDS); // No timeout
248
```
249

250
## HTTP Version Configuration
251

252
Configure the HTTP protocol version.
253

254
```java
255
// HTTP/1.1 (default)
256
Request request = client.newRequest("https://api.example.com/data")
257
    .version(HttpVersion.HTTP_1_1);
258

259
// HTTP/2
260
Request request = client.newRequest("https://api.example.com/data")
261
    .version(HttpVersion.HTTP_2);
262

263
// HTTP/1.0
264
Request request = client.newRequest("https://api.example.com/data")
265
    .version(HttpVersion.HTTP_1_0);
266
```
267

268
## Content Configuration
269

270
Configure request body content. See [Content Management](./content-management.md) for detailed content options.
271

272
### String Content
273

274
```java
275
Request request = client.newRequest("https://api.example.com/users")
276
    .method(HttpMethod.POST)
277
    .content(new StringRequestContent("application/json", jsonData));
278
```
279

280
### File Content
281

282
```java
283
Path file = Paths.get("/path/to/file.json");
284
Request request = client.newRequest("https://api.example.com/upload")
285
    .method(HttpMethod.POST)
286
    .file(file);
287
```
288

289
## Request Listeners
290

291
Configure listeners to monitor request lifecycle events.
292

293
### Request Event Listeners
294

295
```java
296
Request request = client.newRequest("https://api.example.com/data")
297
    .onRequestQueued(req -> System.out.println("Request queued"))
298
    .onRequestBegin(req -> System.out.println("Request begun"))
299
    .onRequestHeaders(req -> System.out.println("Request headers sent"))
300
    .onRequestSuccess(req -> System.out.println("Request succeeded"))
301
    .onRequestFailure((req, failure) -> System.err.println("Request failed: " + failure));
302
```
303

304
### Response Event Listeners
305

306
```java
307
Request request = client.newRequest("https://api.example.com/data")
308
    .onResponseBegin(resp -> System.out.println("Response begun"))
309
    .onResponseHeaders(resp -> System.out.println("Response headers received"))
310
    .onResponseContent((resp, content) -> {
311
        System.out.println("Received " + content.remaining() + " bytes");
312
    })
313
    .onResponseSuccess(resp -> System.out.println("Response succeeded"))
314
    .onResponseFailure((resp, failure) -> System.err.println("Response failed: " + failure));
315
```
316

317
## Advanced Configuration Examples
318

319
### Complete REST API Request
320

321
```java
322
String jsonPayload = "{\"name\":\"John Doe\",\"email\":\"john@example.com\"}";
323

324
ContentResponse response = client.newRequest("https://api.example.com/users")
325
    .method(HttpMethod.POST)
326
    .header("Authorization", "Bearer " + authToken)
327
    .header("Content-Type", "application/json")
328
    .header("Accept", "application/json")
329
    .header("User-Agent", "MyApp/1.2.3")
330
    .timeout(10, TimeUnit.SECONDS)
331
    .content(new StringRequestContent(jsonPayload))
332
    .send();
333
```
334

335
### File Upload with Custom Headers
336

337
```java
338
Path uploadFile = Paths.get("/path/to/document.pdf");
339

340
ContentResponse response = client.newRequest("https://api.example.com/upload")
341
    .method(HttpMethod.POST)
342
    .header("Authorization", "Bearer " + authToken)
343
    .header("Content-Type", "application/pdf")
344
    .header("X-File-Name", uploadFile.getFileName().toString())
345
    .header("X-File-Size", String.valueOf(Files.size(uploadFile)))
346
    .timeout(5, TimeUnit.MINUTES)
347
    .file(uploadFile)
348
    .send();
349
```
350

351
### Request with Custom Validation
352

353
```java
354
Request request = client.newRequest("https://api.example.com/sensitive-data")
355
    .header("Authorization", "Bearer " + authToken)
356
    .onRequestBegin(req -> {
357
        // Validate authorization before sending
358
        if (!isValidToken(authToken)) {
359
            throw new IllegalStateException("Invalid authorization token");
360
        }
361
    })
362
    .onResponseHeaders(resp -> {
363
        // Validate response headers
364
        String contentType = resp.getHeaders().get("Content-Type");
365
        if (!"application/json".equals(contentType)) {
366
            throw new IllegalStateException("Unexpected content type: " + contentType);
367
        }
368
    });
369

370
ContentResponse response = request.send();
371
```