0
# Request and Response Model
1

2
Immutable HTTP message representations including requests, responses, headers, and execution models. All message objects use builder patterns for construction and provide comprehensive configuration options while maintaining thread safety.
3

4
## Capabilities
5

6
### SdkHttpRequest
7

8
Base interface for HTTP requests containing all request metadata except the body content.
9

10
```java { .api }
11
/**
12
 * Base interface for HTTP requests containing all request metadata
13
 */
14
public interface SdkHttpRequest extends SdkHttpHeaders {
15
    /**
16
     * @return HTTP protocol (http or https)
17
     */
18
    String protocol();
19
    
20
    /**
21
     * @return Request host
22
     */
23
    String host();
24
    
25
    /**
26
     * @return Request port
27
     */
28
    int port();
29
    
30
    /**
31
     * @return URL-encoded path component
32
     */
33
    String encodedPath();
34
    
35
    /**
36
     * @return Optional URL-encoded query parameters as single string
37
     */
38
    Optional<String> encodedQueryParameters();
39
    
40
    /**
41
     * @return Raw query parameters as map of parameter names to value lists
42
     */
43
    Map<String, List<String>> rawQueryParameters();
44
    
45
    /**
46
     * @return HTTP method for this request
47
     */
48
    SdkHttpMethod method();
49
    
50
    /**
51
     * @return Complete request URI constructed from components
52
     */
53
    URI getUri();
54
    
55
    /**
56
     * @return Builder for creating modified copies of this request
57
     */
58
    Builder toBuilder();
59
}
60
```
61

62
### SdkHttpFullRequest
63

64
HTTP request interface that extends SdkHttpRequest to include optional body content via ContentStreamProvider.
65

66
```java { .api }
67
/**
68
 * HTTP request with optional body content
69
 */
70
public interface SdkHttpFullRequest extends SdkHttpRequest {
71
    /**
72
     * @return Optional content stream provider for request body
73
     */
74
    Optional<ContentStreamProvider> contentStreamProvider();
75
    
76
    /**
77
     * @return Builder for creating modified copies of this request
78
     */
79
    SdkHttpFullRequest.Builder toBuilder();
80
    
81
    /**
82
     * @return New builder for constructing HTTP requests
83
     */
84
    static Builder builder();
85
}
86
```
87

88
**Usage Example:**
89

90
```java
91
// Create a POST request with JSON body
92
SdkHttpFullRequest request = SdkHttpFullRequest.builder()
93
    .method(SdkHttpMethod.POST)
94
    .protocol("https")
95
    .host("api.example.com")
96
    .port(443)
97
    .encodedPath("/v1/users")
98
    .putHeader("Content-Type", "application/json")
99
    .putHeader("Authorization", "Bearer " + token)
100
    .contentStreamProvider(ContentStreamProvider.fromUtf8String(
101
        "{\"name\":\"John\",\"email\":\"john@example.com\"}"
102
    ))
103
    .build();
104

105
// Create a GET request with query parameters
106
SdkHttpFullRequest getRequest = SdkHttpFullRequest.builder()
107
    .method(SdkHttpMethod.GET)
108
    .protocol("https")
109
    .host("api.example.com")
110
    .port(443)
111
    .encodedPath("/v1/users")
112
    .putRawQueryParameter("page", "1")
113
    .putRawQueryParameter("size", "10")
114
    .putRawQueryParameter("sort", "name")
115
    .putHeader("Accept", "application/json")
116
    .build();
117
```
118

119
### SdkHttpFullRequest.Builder
120

121
Builder interface for constructing SdkHttpFullRequest instances with fluent API.
122

123
```java { .api }
124
/**
125
 * Builder for constructing SdkHttpFullRequest instances
126
 */
127
public interface Builder extends SdkHttpRequest.Builder {
128
    /**
129
     * Set the HTTP method for this request
130
     */
131
    Builder method(SdkHttpMethod method);
132
    
133
    /**
134
     * Set the protocol (http or https)
135
     */
136
    Builder protocol(String protocol);
137
    
138
    /**
139
     * Set the target host
140
     */
141
    Builder host(String host);
142
    
143
    /**
144
     * Set the target port
145
     */
146
    Builder port(int port);
147
    
148
    /**
149
     * Set the URL-encoded path
150
     */
151
    Builder encodedPath(String encodedPath);
152
    
153
    /**
154
     * Add a raw query parameter (will be URL-encoded)
155
     */
156
    Builder putRawQueryParameter(String parameterName, String parameterValue);
157
    
158
    /**
159
     * Add multiple values for a raw query parameter
160
     */
161
    Builder putRawQueryParameter(String parameterName, List<String> parameterValues);
162
    
163
    /**
164
     * Set all raw query parameters, replacing existing ones
165
     */
166
    Builder rawQueryParameters(Map<String, List<String>> rawQueryParameters);
167
    
168
    /**
169
     * Remove a query parameter
170
     */
171
    Builder removeQueryParameter(String parameterName);
172
    
173
    /**
174
     * Clear all query parameters
175
     */
176
    Builder clearQueryParameters();
177
    
178
    /**
179
     * Add an HTTP header
180
     */
181
    Builder putHeader(String headerName, String headerValue);
182
    
183
    /**
184
     * Add multiple values for an HTTP header
185
     */
186
    Builder putHeader(String headerName, List<String> headerValues);
187
    
188
    /**
189
     * Add all headers from a map
190
     */
191
    Builder headers(Map<String, List<String>> headers);
192
    
193
    /**
194
     * Remove an HTTP header
195
     */
196
    Builder removeHeader(String headerName);
197
    
198
    /**
199
     * Clear all HTTP headers
200
     */
201
    Builder clearHeaders();
202
    
203
    /**
204
     * Set the content stream provider for request body
205
     */
206
    Builder contentStreamProvider(ContentStreamProvider contentStreamProvider);
207
    
208
    /**
209
     * Build the SdkHttpFullRequest
210
     */
211
    SdkHttpFullRequest build();
212
}
213
```
214

215
### SdkHttpResponse
216

217
Base interface for HTTP responses containing status information and headers, but without access to the response body.
218

219
```java { .api }
220
/**
221
 * HTTP response without body access
222
 */
223
public interface SdkHttpResponse extends SdkHttpHeaders {
224
    /**
225
     * @return HTTP status code (always positive)
226
     */
227
    int statusCode();
228
    
229
    /**
230
     * @return Optional HTTP status text if provided by service
231
     */
232
    Optional<String> statusText();
233
    
234
    /**
235
     * @return true for 2xx status codes, false otherwise
236
     */
237
    boolean isSuccessful();
238
    
239
    /**
240
     * @return Builder for creating modified copies of this response
241
     */
242
    Builder toBuilder();
243
    
244
    /**
245
     * @return New builder for constructing HTTP responses
246
     */
247
    static Builder builder();
248
}
249
```
250

251
### SdkHttpFullResponse
252

253
HTTP response interface that extends SdkHttpResponse to include access to the response body stream.
254

255
```java { .api }
256
/**
257
 * HTTP response with body access
258
 */
259
public interface SdkHttpFullResponse extends SdkHttpResponse {
260
    /**
261
     * @return Optional response body stream (must be closed by caller)
262
     */
263
    Optional<AbortableInputStream> content();
264
    
265
    /**
266
     * @return Builder for creating modified copies of this response
267
     */
268
    SdkHttpFullResponse.Builder toBuilder();
269
    
270
    /**
271
     * @return New builder for constructing HTTP responses with body
272
     */
273
    static Builder builder();
274
}
275
```
276

277
### SdkHttpHeaders
278

279
Interface providing access to HTTP headers with utility methods for case-insensitive header operations.
280

281
```java { .api }
282
/**
283
 * Immutable set of HTTP headers with utility methods
284
 */
285
public interface SdkHttpHeaders {
286
    /**
287
     * @return All HTTP headers as case-insensitive sorted map
288
     */
289
    Map<String, List<String>> headers();
290
    
291
    /**
292
     * Find first matching header (case-insensitive)
293
     * @param header Header name to search for
294
     * @return First matching header value, or empty if not found
295
     */
296
    Optional<String> firstMatchingHeader(String header);
297
    
298
    /**
299
     * Get all matching headers (case-insensitive)
300
     * @param header Header name to search for
301
     * @return List of all matching header values
302
     */
303
    List<String> matchingHeaders(String header);
304
    
305
    /**
306
     * Check if any header matches the given predicate
307
     * @param predicate Predicate to test header names against
308
     * @return true if any header matches, false otherwise
309
     */
310
    boolean anyMatchingHeader(Predicate<String> predicate);
311
    
312
    /**
313
     * Iterate over all headers with a consumer function
314
     * @param consumer Function to accept header name and values
315
     */
316
    void forEachHeader(BiConsumer<String, List<String>> consumer);
317
    
318
    /**
319
     * @return Number of headers
320
     */
321
    int numHeaders();
322
}
323
```
324

325
**Usage Example:**
326

327
```java
328
// Working with response headers
329
SdkHttpResponse response = // ... received from HTTP call
330

331
// Check content type
332
Optional<String> contentType = response.firstMatchingHeader("Content-Type");
333
if (contentType.isPresent() && contentType.get().startsWith("application/json")) {
334
    // Handle JSON response
335
}
336

337
// Get all cache control directives
338
List<String> cacheControl = response.matchingHeaders("Cache-Control");
339

340
// Check for specific headers
341
boolean hasETag = response.anyMatchingHeader(header -> 
342
    header.equalsIgnoreCase("ETag"));
343

344
// Iterate all headers
345
response.forEachHeader((name, values) -> {
346
    System.out.println(name + ": " + String.join(", ", values));
347
});
348
```
349

350
### HTTP Method Enumeration
351

352
```java { .api }
353
/**
354
 * Enumeration of supported HTTP methods
355
 */
356
public enum SdkHttpMethod {
357
    GET, POST, PUT, DELETE, HEAD, PATCH, OPTIONS
358
}
359
```
360

361
### HTTP Status Utilities
362

363
```java { .api }
364
/**
365
 * HTTP status code families for response categorization
366
 */
367
public enum HttpStatusFamily {
368
    INFORMATIONAL(100, 199),
369
    SUCCESSFUL(200, 299), 
370
    REDIRECTION(300, 399),
371
    CLIENT_ERROR(400, 499),
372
    SERVER_ERROR(500, 599),
373
    OTHER(0, 99);
374
    
375
    /**
376
     * Get the status family for a given status code
377
     * @param statusCode HTTP status code
378
     * @return Corresponding HttpStatusFamily
379
     */
380
    public static HttpStatusFamily of(int statusCode);
381
}
382

383
/**
384
 * Common HTTP status code constants
385
 */
386
public final class HttpStatusCode {
387
    public static final int OK = 200;
388
    public static final int CREATED = 201;
389
    public static final int ACCEPTED = 202;
390
    public static final int NO_CONTENT = 204;
391
    public static final int MOVED_PERMANENTLY = 301;
392
    public static final int FOUND = 302;
393
    public static final int NOT_MODIFIED = 304;
394
    public static final int BAD_REQUEST = 400;
395
    public static final int UNAUTHORIZED = 401;
396
    public static final int FORBIDDEN = 403;
397
    public static final int NOT_FOUND = 404;
398
    public static final int METHOD_NOT_ALLOWED = 405;
399
    public static final int CONFLICT = 409;
400
    public static final int INTERNAL_SERVER_ERROR = 500;
401
    public static final int BAD_GATEWAY = 502;
402
    public static final int SERVICE_UNAVAILABLE = 503;
403
    public static final int GATEWAY_TIMEOUT = 504;
404
}
405
```
406

407
### Execution Request/Response Model
408

409
HTTP execution model for synchronous client operations.
410

411
```java { .api }
412
/**
413
 * Request object for synchronous HTTP execution
414
 */
415
public final class HttpExecuteRequest {
416
    /**
417
     * @return The HTTP request to execute
418
     */
419
    public SdkHttpRequest httpRequest();
420
    
421
    /**
422
     * @return Optional content stream provider for request body
423
     */
424
    public Optional<ContentStreamProvider> contentStreamProvider();
425
    
426
    /**
427
     * @return Optional metrics collector for this request
428
     */
429
    public Optional<MetricCollector> metricCollector();
430
    
431
    /**
432
     * @return New builder for HTTP execution requests
433
     */
434
    public static Builder builder();
435
    
436
    public interface Builder {
437
        Builder request(SdkHttpRequest request);
438
        Builder contentStreamProvider(ContentStreamProvider contentStreamProvider);
439
        Builder metricCollector(MetricCollector metricCollector);
440
        HttpExecuteRequest build();
441
    }
442
}
443

444
/**
445
 * Response object for synchronous HTTP execution
446
 */
447
public final class HttpExecuteResponse {
448
    /**
449
     * @return The HTTP response
450
     */
451
    public SdkHttpResponse httpResponse();
452
    
453
    /**
454
     * @return Optional response body stream (must be closed by caller)
455
     */
456
    public Optional<AbortableInputStream> responseBody();
457
    
458
    /**
459
     * @return New builder for HTTP execution responses
460
     */
461
    public static Builder builder();
462
    
463
    public interface Builder {
464
        Builder response(SdkHttpResponse response);
465
        Builder responseBody(AbortableInputStream responseBody);
466
        HttpExecuteResponse build();
467
    }
468
}
469
```
470

471
### AsyncExecuteRequest
472

473
Request object for asynchronous HTTP execution containing all parameters needed for async operations.
474

475
```java { .api }
476
/**
477
 * Request object containing the parameters necessary to make an asynchronous HTTP request
478
 */
479
@SdkPublicApi
480
public final class AsyncExecuteRequest {
481
    /**
482
     * @return The HTTP request to execute
483
     */
484
    public SdkHttpRequest request();
485
    
486
    /**
487
     * @return The publisher of request body content
488
     */
489
    public SdkHttpContentPublisher requestContentPublisher();
490
    
491
    /**
492
     * @return The response handler for processing the async response
493
     */
494
    public SdkAsyncHttpResponseHandler responseHandler();
495
    
496
    /**
497
     * @return Optional metrics collector for this request
498
     */
499
    public Optional<MetricCollector> metricCollector();
500
    
501
    /**
502
     * @return True if the operation is full duplex (request and response sent/received simultaneously)
503
     */
504
    public boolean fullDuplex();
505
    
506
    /**
507
     * @return The SDK HTTP execution attributes associated with this request
508
     */
509
    public SdkHttpExecutionAttributes httpExecutionAttributes();
510
    
511
    /**
512
     * @return New builder for async execution requests
513
     */
514
    public static Builder builder();
515
    
516
    public interface Builder {
517
        /**
518
         * Set the HTTP request to be executed by the client
519
         */
520
        Builder request(SdkHttpRequest request);
521
        
522
        /**
523
         * Set the publisher of the request content
524
         */
525
        Builder requestContentPublisher(SdkHttpContentPublisher requestContentPublisher);
526
        
527
        /**
528
         * Set the response handler for the response
529
         */
530
        Builder responseHandler(SdkAsyncHttpResponseHandler responseHandler);
531
        
532
        /**
533
         * Set the MetricCollector to be used by the HTTP client to report metrics
534
         */
535
        Builder metricCollector(MetricCollector metricCollector);
536
        
537
        /**
538
         * Indicate if the request is for a full duplex operation (request and response sent/received simultaneously)
539
         */
540
        Builder fullDuplex(boolean fullDuplex);
541
        
542
        /**
543
         * Put an HTTP execution attribute into the collection of HTTP execution attributes for this request
544
         */
545
        <T> Builder putHttpExecutionAttribute(SdkHttpExecutionAttribute<T> attribute, T value);
546
        
547
        /**
548
         * Sets the additional HTTP execution attributes collection for this request.
549
         * This will override attributes configured through putHttpExecutionAttribute()
550
         */
551
        Builder httpExecutionAttributes(SdkHttpExecutionAttributes executionAttributes);
552
        
553
        AsyncExecuteRequest build();
554
    }
555
}
556
```
557

558
### Common Header Constants
559

560
```java { .api }
561
/**
562
 * Common HTTP header name constants
563
 */
564
public final class Header {
565
    public static final String ACCEPT = "Accept";
566
    public static final String ACCEPT_CHARSET = "Accept-Charset";
567
    public static final String ACCEPT_ENCODING = "Accept-Encoding";
568
    public static final String ACCEPT_LANGUAGE = "Accept-Language";
569
    public static final String AUTHORIZATION = "Authorization";
570
    public static final String CACHE_CONTROL = "Cache-Control";
571
    public static final String CONNECTION = "Connection";
572
    public static final String CONTENT_ENCODING = "Content-Encoding";
573
    public static final String CONTENT_LENGTH = "Content-Length";
574
    public static final String CONTENT_TYPE = "Content-Type";
575
    public static final String DATE = "Date";
576
    public static final String ETAG = "ETag";
577
    public static final String EXPIRES = "Expires";
578
    public static final String HOST = "Host";
579
    public static final String IF_MATCH = "If-Match";
580
    public static final String IF_MODIFIED_SINCE = "If-Modified-Since";
581
    public static final String IF_NONE_MATCH = "If-None-Match";
582
    public static final String IF_UNMODIFIED_SINCE = "If-Unmodified-Since";
583
    public static final String LAST_MODIFIED = "Last-Modified";
584
    public static final String LOCATION = "Location";
585
    public static final String RANGE = "Range";
586
    public static final String SERVER = "Server";
587
    public static final String USER_AGENT = "User-Agent";
588
    public static final String WWW_AUTHENTICATE = "WWW-Authenticate";
589
}
590
```