0
# Service Integration
1

2
This document covers how the UrlConnectionHttpClient integrates with the AWS SDK through the Java ServiceLoader mechanism and how to use it with AWS services.
3

4
## Service Discovery
5

6
The URL Connection HTTP Client is automatically discoverable by the AWS SDK through Java's ServiceLoader mechanism.
7

8
```java { .api }
9
public class UrlConnectionSdkHttpService implements SdkHttpService {
10
    public SdkHttpClient.Builder createHttpClientBuilder();
11
}
12
```
13

14
### Automatic Discovery
15

16
The AWS SDK automatically discovers available HTTP client implementations at runtime:
17

18
```java
19
import software.amazon.awssdk.services.s3.S3Client;
20
import software.amazon.awssdk.regions.Region;
21

22
// The AWS SDK will automatically find and can use UrlConnectionHttpClient
23
S3Client s3 = S3Client.builder()
24
    .region(Region.US_EAST_1)
25
    .build();
26
// If no other HTTP client is on the classpath, UrlConnectionHttpClient will be used
27
```
28

29
### Service Configuration
30

31
The service is registered in `META-INF/services/software.amazon.awssdk.http.SdkHttpService`:
32

33
```
34
software.amazon.awssdk.http.urlconnection.UrlConnectionSdkHttpService
35
```
36

37
## AWS SDK Integration
38

39
### Explicit HTTP Client Configuration
40

41
```java
42
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
43
import software.amazon.awssdk.services.s3.S3Client;
44
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
45
import software.amazon.awssdk.regions.Region;
46
import java.time.Duration;
47

48
// Configure S3 client with UrlConnectionHttpClient
49
S3Client s3Client = S3Client.builder()
50
    .httpClient(UrlConnectionHttpClient.builder()
51
        .connectionTimeout(Duration.ofSeconds(10))
52
        .socketTimeout(Duration.ofSeconds(30))
53
        .build())
54
    .region(Region.US_WEST_2)
55
    .build();
56

57
// Configure DynamoDB client
58
DynamoDbClient dynamoClient = DynamoDbClient.builder()
59
    .httpClient(UrlConnectionHttpClient.create())
60
    .region(Region.US_EAST_1)
61
    .build();
62
```
63

64
### Global HTTP Client Configuration
65

66
```java
67
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
68
import software.amazon.awssdk.http.urlconnection.ProxyConfiguration;
69
import software.amazon.awssdk.http.SdkHttpClient;
70
import software.amazon.awssdk.services.s3.S3Client;
71
import software.amazon.awssdk.services.ec2.EC2Client;
72
import software.amazon.awssdk.regions.Region;
73
import java.time.Duration;
74

75
// Configure HTTP client to be shared across multiple AWS service clients
76
SdkHttpClient sharedHttpClient = UrlConnectionHttpClient.builder()
77
    .connectionTimeout(Duration.ofSeconds(15))
78
    .socketTimeout(Duration.ofSeconds(60))
79
    .proxyConfiguration(ProxyConfiguration.builder()
80
        .useSystemPropertyValues(true)
81
        .build())
82
    .build();
83

84
// Use the shared client across multiple services
85
S3Client s3 = S3Client.builder()
86
    .httpClient(sharedHttpClient)
87
    .region(Region.US_WEST_2)
88
    .build();
89

90
EC2Client ec2 = EC2Client.builder()
91
    .httpClient(sharedHttpClient)
92
    .region(Region.US_WEST_2)
93
    .build();
94

95
// Remember to close the shared client when done
96
// sharedHttpClient.close(); // Note: This is actually a no-op for UrlConnectionHttpClient
97
```
98

99
## Service-Specific Configurations
100

101
### High-Throughput Services (S3, Kinesis)
102

103
```java
104
// Optimized for high-throughput operations
105
SdkHttpClient highThroughputClient = UrlConnectionHttpClient.builder()
106
    .socketTimeout(Duration.ofMinutes(5))     // Longer timeout for large uploads
107
    .connectionTimeout(Duration.ofSeconds(10))
108
    .build();
109

110
S3Client s3 = S3Client.builder()
111
    .httpClient(highThroughputClient)
112
    .region(Region.US_EAST_1)
113
    .build();
114
```
115

116
### Low-Latency Services (DynamoDB, Lambda)
117

118
```java
119
// Optimized for low-latency operations
120
SdkHttpClient lowLatencyClient = UrlConnectionHttpClient.builder()
121
    .connectionTimeout(Duration.ofSeconds(3))
122
    .socketTimeout(Duration.ofSeconds(10))
123
    .build();
124

125
DynamoDbClient dynamodb = DynamoDbClient.builder()
126
    .httpClient(lowLatencyClient)
127
    .region(Region.US_EAST_1)
128
    .build();
129
```
130

131
### Enterprise Environment
132

133
```java
134
// Enterprise configuration with proxy and custom TLS
135
SdkHttpClient enterpriseClient = UrlConnectionHttpClient.builder()
136
    .connectionTimeout(Duration.ofSeconds(30))
137
    .socketTimeout(Duration.ofMinutes(2))
138
    .proxyConfiguration(ProxyConfiguration.builder()
139
        .endpoint(URI.create("http://corporate-proxy.company.com:8080"))
140
        .username("domain\\serviceaccount")
141
        .password("password")
142
        .nonProxyHosts(Set.of("*.internal.company.com", "localhost"))
143
        .build())
144
    .tlsTrustManagersProvider(TlsTrustManagersProvider.fileStore(
145
        Paths.get("/etc/ssl/corporate-ca.jks"), "password"))
146
    .build();
147

148
// Use with multiple AWS services
149
S3Client s3 = S3Client.builder()
150
    .httpClient(enterpriseClient)
151
    .region(Region.US_EAST_1)
152
    .build();
153

154
SecretsManagerClient secrets = SecretsManagerClient.builder()
155
    .httpClient(enterpriseClient)
156
    .region(Region.US_EAST_1)
157
    .build();
158
```
159

160
## Comparison with Other HTTP Clients
161

162
### When to Use UrlConnectionHttpClient
163

164
**Best for:**
165
- Simple applications with minimal dependencies
166
- Testing and development environments
167
- Applications with low HTTP request volume
168
- Environments where startup time is critical
169
- When you want to avoid additional dependencies
170

171
**Example Use Case:**
172
```java
173
// Simple Lambda function with minimal cold start time
174
public class SimpleS3Handler implements RequestHandler<S3Event, String> {
175
    
176
    private static final S3Client s3Client = S3Client.builder()
177
        .httpClient(UrlConnectionHttpClient.create())  // Minimal overhead
178
        .build();
179
    
180
    @Override
181
    public String handleRequest(S3Event event, Context context) {
182
        // Handle S3 events with minimal dependencies
183
        return "Success";
184
    }
185
}
186
```
187

188
### Alternative HTTP Clients
189

190
```java
191
// Apache HTTP Client (more features, better performance for high volume)
192
SdkHttpClient apacheClient = ApacheHttpClient.builder()
193
    .maxConnections(100)
194
    .build();
195

196
// Netty HTTP Client (async support, better for reactive applications)  
197
SdkHttpClient nettyClient = NettyNioAsyncHttpClient.builder()
198
    .maxConcurrency(50)
199
    .build();
200
```
201

202
## Service Provider Interface
203

204
```java { .api }
205
// Main service interface
206
public interface SdkHttpService {
207
    SdkHttpClient.Builder createHttpClientBuilder();
208
}
209

210
// URL Connection implementation
211
public class UrlConnectionSdkHttpService implements SdkHttpService {
212
    @Override
213
    public SdkHttpClient.Builder createHttpClientBuilder() {
214
        return UrlConnectionHttpClient.builder();
215
    }
216
}
217
```
218

219
## Testing Integration
220

221
```java
222
import org.junit.jupiter.api.Test;
223
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
224

225
@Test
226
void testS3Integration() {
227
    // Use UrlConnectionHttpClient in tests for simplicity
228
    S3Client s3Client = S3Client.builder()
229
        .httpClient(UrlConnectionHttpClient.builder()
230
            .connectionTimeout(Duration.ofSeconds(5))
231
            .socketTimeout(Duration.ofSeconds(10))
232
            .build())
233
        .region(Region.US_EAST_1)
234
        .credentialsProvider(StaticCredentialsProvider.create(
235
            AwsBasicCredentials.create("test", "test")))
236
        .endpointOverride(URI.create("http://localhost:9000"))  // LocalStack or mock
237
        .build();
238

239
    // Test S3 operations
240
    ListBucketsResponse response = s3Client.listBuckets();
241
    assertThat(response.buckets()).isNotNull();
242
    
243
    s3Client.close();
244
}
245
```
246

247
## Types
248

249
```java { .api }
250
// Service provider interface
251
public interface SdkHttpService {
252
    SdkHttpClient.Builder createHttpClientBuilder();
253
}
254

255
// URL Connection service implementation
256
public class UrlConnectionSdkHttpService implements SdkHttpService {
257
    public SdkHttpClient.Builder createHttpClientBuilder();
258
}
259

260
// Core HTTP client interface (from AWS SDK)
261
public interface SdkHttpClient extends Closeable {
262
    ExecutableHttpRequest prepareRequest(HttpExecuteRequest request);
263
    String clientName();
264
    void close();
265
    
266
    interface Builder<B extends Builder<B>> {
267
        SdkHttpClient buildWithDefaults(AttributeMap serviceDefaults);
268
    }
269
}
270
```