0
# AWS SDK Java v2 Netty NIO Client
1
2
A high-performance, non-blocking HTTP client implementation for AWS SDK Java v2 applications using the Netty framework. This client enables efficient asynchronous network communication with AWS services through NIO (New I/O) operations, supporting both HTTP/1.1 and HTTP/2 protocols with advanced connection pooling, proxy support, and SSL/TLS configuration.
3
4
## Package Information
5
6
- **Package Name**: netty-nio-client
7
- **Package Type**: maven
8
- **Group ID**: software.amazon.awssdk
9
- **Artifact ID**: netty-nio-client
10
- **Language**: Java
11
- **Installation**: Include in Maven/Gradle dependencies with AWS SDK BOM
12
13
```xml
14
<dependency>
15
<groupId>software.amazon.awssdk</groupId>
16
<artifactId>netty-nio-client</artifactId>
17
</dependency>
18
```
19
20
## Core Imports
21
22
```java
23
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
24
import software.amazon.awssdk.http.nio.netty.SdkEventLoopGroup;
25
import software.amazon.awssdk.http.nio.netty.Http2Configuration;
26
import software.amazon.awssdk.http.nio.netty.ProxyConfiguration;
27
```
28
29
## Basic Usage
30
31
```java
32
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
33
import software.amazon.awssdk.http.SdkAsyncHttpClient;
34
35
// Create with default configuration
36
SdkAsyncHttpClient httpClient = NettyNioAsyncHttpClient.create();
37
38
// Create with custom configuration
39
SdkAsyncHttpClient httpClient = NettyNioAsyncHttpClient.builder()
40
.maxConcurrency(100)
41
.connectionTimeout(Duration.ofSeconds(10))
42
.readTimeout(Duration.ofSeconds(30))
43
.protocol(Protocol.HTTP2)
44
.build();
45
46
// Use with AWS service clients
47
S3AsyncClient s3Client = S3AsyncClient.builder()
48
.httpClient(httpClient)
49
.build();
50
51
// Always close resources
52
httpClient.close();
53
```
54
55
## Architecture
56
57
The Netty NIO Client is built around several key components:
58
59
- **NettyNioAsyncHttpClient**: Main HTTP client implementation with comprehensive async support
60
- **Configuration System**: Immutable configuration objects using builder patterns for HTTP/2, proxy, and event loop settings
61
- **Event Loop Management**: Efficient Netty event loop sharing and lifecycle management through SdkEventLoopGroup
62
- **Protocol Support**: Full HTTP/1.1 and HTTP/2 support with ALPN negotiation and protocol-specific optimizations
63
- **Connection Pooling**: Advanced connection pooling with configurable limits, timeouts, and idle connection management
64
- **ServiceLoader Integration**: Automatic discovery by AWS SDK through NettySdkAsyncHttpService
65
66
## Capabilities
67
68
### HTTP Client
69
70
The primary HTTP client implementation providing asynchronous HTTP communication with comprehensive configuration options for timeouts, connection pooling, and protocol settings.
71
72
```java { .api }
73
public final class NettyNioAsyncHttpClient implements SdkAsyncHttpClient {
74
public CompletableFuture<Void> execute(AsyncExecuteRequest request);
75
public void close();
76
public String clientName();
77
public static Builder builder();
78
public static SdkAsyncHttpClient create();
79
}
80
81
public interface Builder extends SdkAsyncHttpClient.Builder<Builder> {
82
Builder maxConcurrency(Integer maxConcurrency);
83
Builder readTimeout(Duration readTimeout);
84
Builder connectionTimeout(Duration connectionTimeout);
85
Builder protocol(Protocol protocol);
86
Builder eventLoopGroup(SdkEventLoopGroup eventLoopGroup);
87
NettyNioAsyncHttpClient build();
88
}
89
```
90
91
[HTTP Client Configuration](./http-client.md)
92
93
### Event Loop Management
94
95
Event loop and channel factory management for efficient resource sharing and lifecycle control across multiple HTTP clients.
96
97
```java { .api }
98
public final class SdkEventLoopGroup {
99
public EventLoopGroup eventLoopGroup();
100
public ChannelFactory<? extends Channel> channelFactory();
101
public static SdkEventLoopGroup create(EventLoopGroup eventLoopGroup);
102
public static Builder builder();
103
}
104
105
public interface Builder {
106
Builder numberOfThreads(Integer numberOfThreads);
107
Builder threadFactory(ThreadFactory threadFactory);
108
SdkEventLoopGroup build();
109
}
110
```
111
112
[Event Loop Management](./event-loop.md)
113
114
### HTTP/2 Configuration
115
116
HTTP/2 protocol-specific settings for stream management, window sizes, and connection health monitoring.
117
118
```java { .api }
119
public final class Http2Configuration implements ToCopyableBuilder<Http2Configuration.Builder, Http2Configuration> {
120
public Long maxStreams();
121
public Integer initialWindowSize();
122
public Duration healthCheckPingPeriod();
123
public static Builder builder();
124
}
125
126
public interface Builder extends CopyableBuilder<Builder, Http2Configuration> {
127
Builder maxStreams(Long maxStreams);
128
Builder initialWindowSize(Integer initialWindowSize);
129
Builder healthCheckPingPeriod(Duration healthCheckPingPeriod);
130
}
131
```
132
133
[HTTP/2 Configuration](./http2-config.md)
134
135
### Proxy Configuration
136
137
Comprehensive proxy support with automatic system property and environment variable integration for enterprise environments.
138
139
```java { .api }
140
public final class ProxyConfiguration implements ToCopyableBuilder<ProxyConfiguration.Builder, ProxyConfiguration> {
141
public String scheme();
142
public String host();
143
public int port();
144
public String username();
145
public String password();
146
public Set<String> nonProxyHosts();
147
public static Builder builder();
148
}
149
150
public interface Builder extends CopyableBuilder<Builder, ProxyConfiguration> {
151
Builder scheme(String scheme);
152
Builder host(String host);
153
Builder port(int port);
154
Builder useSystemPropertyValues(Boolean useSystemPropertyValues);
155
}
156
```
157
158
[Proxy Configuration](./proxy-config.md)
159
160
### Service Discovery
161
162
ServiceLoader integration enabling automatic HTTP client discovery by the AWS SDK without explicit configuration.
163
164
```java { .api }
165
public class NettySdkAsyncHttpService implements SdkAsyncHttpService {
166
public SdkAsyncHttpClient.Builder createAsyncHttpClientFactory();
167
}
168
```
169
170
The service is automatically registered and discovered when the netty-nio-client is on the classpath, eliminating the need for manual HTTP client configuration in many use cases.
171
172
## Types
173
174
### Core Types
175
176
```java { .api }
177
// AWS SDK Core Types
178
interface SdkAsyncHttpClient extends SdkHttpClient {
179
CompletableFuture<Void> execute(AsyncExecuteRequest request);
180
void close();
181
String clientName();
182
}
183
184
interface AsyncExecuteRequest {
185
SdkHttpRequest request();
186
AsyncRequestBody requestBody();
187
AsyncExecuteRequest.ResponseHandler responseHandler();
188
}
189
190
enum Protocol {
191
HTTP1_1, HTTP2
192
}
193
194
enum ProtocolNegotiation {
195
ALPN, ASSUME_PROTOCOL
196
}
197
198
// Netty Types
199
interface EventLoopGroup extends ScheduledExecutorService, Iterable<EventExecutor> {
200
// Netty event loop group interface
201
}
202
203
interface ChannelFactory<T extends Channel> {
204
T newChannel();
205
}
206
207
class ChannelOption<T> {
208
// Netty channel configuration options
209
}
210
211
enum SslProvider {
212
JDK, OPENSSL, OPENSSL_REFCNT
213
}
214
```
215
216
### Duration and Timeout Types
217
218
```java { .api }
219
// Standard Java duration type used throughout the API
220
class Duration {
221
static Duration ofSeconds(long seconds);
222
static Duration ofMillis(long millis);
223
static Duration ofMinutes(long minutes);
224
}
225
```
226
227
### TLS Configuration Types
228
229
```java { .api }
230
interface TlsKeyManagersProvider {
231
KeyManager[] keyManagers();
232
}
233
234
interface TlsTrustManagersProvider {
235
TrustManager[] trustManagers();
236
}
237
```