0
# HTTP Client Configuration
1

2
This document covers configuring the UrlConnectionHttpClient with various options including timeouts, TLS settings, and proxy configuration.
3

4
## Creating HTTP Clients
5

6
### Basic Client Creation
7

8
```java { .api }
9
// Create with default settings
10
public static SdkHttpClient create();
11

12
// Create with custom connection factory
13
public static SdkHttpClient create(UrlConnectionFactory connectionFactory);
14

15
// Create via builder pattern
16
public static Builder builder();
17
```
18

19
### Usage Examples
20

21
```java
22
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
23
import software.amazon.awssdk.http.SdkHttpClient;
24
import java.net.HttpURLConnection;
25
import java.time.Duration;
26

27
// Default client
28
SdkHttpClient defaultClient = UrlConnectionHttpClient.create();
29

30
// Custom connection factory
31
SdkHttpClient customClient = UrlConnectionHttpClient.create(uri -> {
32
    HttpURLConnection connection = (HttpURLConnection) uri.toURL().openConnection();
33
    connection.setConnectTimeout(5000);
34
    return connection;
35
});
36

37
// Builder-configured client
38
SdkHttpClient builderClient = UrlConnectionHttpClient.builder()
39
    .connectionTimeout(Duration.ofSeconds(10))
40
    .socketTimeout(Duration.ofSeconds(30))
41
    .build();
42
```
43

44
## Builder Configuration
45

46
The `UrlConnectionHttpClient.Builder` provides fluent configuration options:
47

48
```java { .api }
49
public interface Builder extends SdkHttpClient.Builder<UrlConnectionHttpClient.Builder> {
50
    // Timeout configuration
51
    Builder socketTimeout(Duration socketTimeout);
52
    Builder connectionTimeout(Duration connectionTimeout);
53
    
54
    // TLS configuration
55
    Builder tlsKeyManagersProvider(TlsKeyManagersProvider tlsKeyManagersProvider);
56
    Builder tlsTrustManagersProvider(TlsTrustManagersProvider tlsTrustManagersProvider);
57
    
58
    // Proxy configuration
59
    Builder proxyConfiguration(ProxyConfiguration proxyConfiguration);
60
    Builder proxyConfiguration(Consumer<ProxyConfiguration.Builder> proxyConfigurationBuilderConsumer);
61
}
62
```
63

64
### Timeout Configuration
65

66
```java
67
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
68
import software.amazon.awssdk.http.SdkHttpClient;
69
import java.time.Duration;
70

71
SdkHttpClient client = UrlConnectionHttpClient.builder()
72
    .connectionTimeout(Duration.ofSeconds(5))   // Time to establish connection
73
    .socketTimeout(Duration.ofSeconds(30))      // Time to wait for data
74
    .build();
75
```
76

77
### TLS Configuration
78

79
```java
80
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
81
import software.amazon.awssdk.http.SdkHttpClient;
82
import software.amazon.awssdk.http.TlsKeyManagersProvider;
83
import software.amazon.awssdk.http.TlsTrustManagersProvider;
84
import java.nio.file.Paths;
85

86
SdkHttpClient client = UrlConnectionHttpClient.builder()
87
    .tlsKeyManagersProvider(TlsKeyManagersProvider.fileStore(
88
        Paths.get("client-keystore.p12"), "password"))
89
    .tlsTrustManagersProvider(TlsTrustManagersProvider.systemDefault())
90
    .build();
91
```
92

93
### Proxy Configuration with Builder
94

95
```java
96
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
97
import software.amazon.awssdk.http.SdkHttpClient;
98
import java.net.URI;
99

100
SdkHttpClient client = UrlConnectionHttpClient.builder()
101
    .proxyConfiguration(proxy -> proxy
102
        .endpoint(URI.create("http://proxy.example.com:8080"))
103
        .username("proxyuser")
104
        .password("proxypass"))
105
    .build();
106
```
107

108
## Client Operations
109

110
```java { .api }
111
public final class UrlConnectionHttpClient implements SdkHttpClient {
112
    // Request preparation
113
    public ExecutableHttpRequest prepareRequest(HttpExecuteRequest request);
114
    
115
    // Client identification
116
    public String clientName();
117
    
118
    // Resource cleanup (no-op for URLConnection)
119
    public void close();
120
}
121
```
122

123
### Usage in AWS SDK
124

125
```java
126
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
127
import software.amazon.awssdk.services.s3.S3Client;
128
import java.time.Duration;
129

130
// Configure S3 client with custom HTTP client
131
S3Client s3Client = S3Client.builder()
132
    .httpClient(UrlConnectionHttpClient.builder()
133
        .connectionTimeout(Duration.ofSeconds(10))
134
        .socketTimeout(Duration.ofSeconds(60))
135
        .build())
136
    .build();
137
```
138

139
## Custom Connection Factory
140

141
For advanced use cases, you can provide a custom `UrlConnectionFactory`:
142

143
```java { .api }
144
@FunctionalInterface
145
public interface UrlConnectionFactory {
146
    HttpURLConnection createConnection(URI uri);
147
}
148
```
149

150
### Custom Factory Example
151

152
```java
153
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
154
import software.amazon.awssdk.http.urlconnection.UrlConnectionFactory;
155
import software.amazon.awssdk.http.SdkHttpClient;
156
import java.net.HttpURLConnection; 
157
import java.net.URI;
158

159
UrlConnectionFactory customFactory = uri -> {
160
    HttpURLConnection connection = (HttpURLConnection) uri.toURL().openConnection();
161
    
162
    // Custom configuration
163
    connection.setConnectTimeout(5000);
164
    connection.setReadTimeout(30000);
165
    connection.setRequestProperty("User-Agent", "MyApp/1.0");
166
    
167
    return connection;
168
};
169

170
SdkHttpClient client = UrlConnectionHttpClient.create(customFactory);
171
```
172

173
**Note**: When using a custom connection factory, SDK defaults for timeouts and other configurations are ignored. You must configure the `HttpURLConnection` directly.
174

175
## Exception Handling
176

177
The URL Connection HTTP Client can throw various exceptions during operation:
178

179
```java
180
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
181
import software.amazon.awssdk.http.SdkHttpClient;
182
import java.io.IOException;
183
import java.io.UncheckedIOException;
184

185
try {
186
    SdkHttpClient client = UrlConnectionHttpClient.create();
187
    
188
    // HTTP operations can throw IOException
189
    ExecutableHttpRequest request = client.prepareRequest(httpRequest);
190
    HttpExecuteResponse response = request.call();
191
    
192
} catch (UncheckedIOException e) {
193
    // Wraps IOException from underlying URLConnection
194
    IOException cause = e.getCause();
195
    // Handle network errors, timeouts, etc.
196
} catch (IOException e) {
197
    // Direct IOException from HTTP operations
198
    // Handle connection errors, response reading errors, etc.
199
}
200
```
201

202
### Common Exception Scenarios
203

204
- **Connection timeout**: When `connectionTimeout` is exceeded during connection establishment
205
- **Read timeout**: When `socketTimeout` is exceeded waiting for response data
206
- **Proxy authentication**: When proxy credentials are invalid or missing
207
- **SSL/TLS errors**: When certificate validation fails or SSL handshake problems occur
208
- **Expect 100-continue handling**: URLConnection has limitations with `Expect: 100-continue` headers
209

210
## Types
211

212
```java { .api }
213
// HTTP client builder interface
214
public interface Builder extends SdkHttpClient.Builder<UrlConnectionHttpClient.Builder> {
215
    // Fluent builder methods
216
    Builder socketTimeout(Duration socketTimeout);
217
    Builder connectionTimeout(Duration connectionTimeout);
218
    Builder tlsKeyManagersProvider(TlsKeyManagersProvider tlsKeyManagersProvider);
219
    Builder tlsTrustManagersProvider(TlsTrustManagersProvider tlsTrustManagersProvider);
220
    Builder proxyConfiguration(ProxyConfiguration proxyConfiguration);
221
    Builder proxyConfiguration(Consumer<ProxyConfiguration.Builder> proxyConfigurationBuilderConsumer);
222
    
223
    // JavaBean setter methods (for framework integration)
224
    void setSocketTimeout(Duration socketTimeout);
225
    void setConnectionTimeout(Duration connectionTimeout);
226
    void setTlsKeyManagersProvider(TlsKeyManagersProvider tlsKeyManagersProvider);
227
    void setTlsTrustManagersProvider(TlsTrustManagersProvider tlsTrustManagersProvider);
228
    void setProxyConfiguration(ProxyConfiguration proxyConfiguration);
229
    
230
    // Build method
231
    SdkHttpClient buildWithDefaults(AttributeMap serviceDefaults);
232
}
233

234
// Connection factory interface
235
@FunctionalInterface
236
public interface UrlConnectionFactory {
237
    HttpURLConnection createConnection(URI uri);
238
}
239
```