# Configure HTTP clients in the AWS SDK for Java 2.x
You can change the HTTP client to use for your service client as well as change the default configuration for HTTP clients with the AWS SDK for Java 2.x. This section discusses HTTP clients and settings for the SDK.
## HTTP clients available in the SDK for Java
### Synchronous clients
Synchronous HTTP clients in the SDK for Java implement the [SdkHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/SdkHttpClient.html) interface. A synchronous service client, such as the `S3Client` or the `DynamoDbClient`, requires the use of a synchronous HTTP client. The AWS SDK for Java offers three synchronous HTTP clients.
**ApacheHttpClient (default)**
[ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html) is the default HTTP client for synchronous service clients. For information about configuring the `ApacheHttpClient`, see [Configure the Apache-based HTTP client](http-configuration-apache.md).
**AwsCrtHttpClient**
[AwsCrtHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html) provides high throughput and non-blocking IO. It is built on the AWS Common Runtime (CRT) Http Client. For information about configuring the `AwsCrtHttpClient` and using it with service clients, see [Configure AWS CRT-based HTTP clients](http-configuration-crt.md).
**UrlConnectionHttpClient**
To minimize the number of jars and third-party libraries you application uses, you can use the [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html). For information about configuring the `UrlConnectionHttpClient`, see [Configure the URLConnection-based HTTP client](http-configuration-url.md).
**Apache5HttpClient**
[Apache5HttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache5/Apache5HttpClient.html) is an updated version of `ApacheHttpClient` that is built on the *Apache 5.x HttpClient. Version 5.x * is the version actively maintained by Apache, and improves on the the previous version used by `ApacheHttpClient` by bringing modern Java ecosystem compatibility including virtual thread support for Java 21, and enhanced logging flexibility through SLF4J. `Apache5HttpClient` will replace `ApacheHttpClient` as the default synchronous client in a future version of the AWS SDK for Java 2.x. It has an identical API and features, making it ideal as a drop-in replacement. For information about configuring the `Apache5HttpClient`, see [Configure the Apache 5.x based HTTP client](http-configuration-apache5.md).
### Asynchronous clients
Asynchronous HTTP clients in the SDK for Java implement the [SdkAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/async/SdkAsyncHttpClient.html) interface. An asynchronous service client, such as the `S3AsyncClient` or the `DynamoDbAsyncClient`, requires the use of an asynchronous HTTP client. The AWS SDK for Java offers two asynchronous HTTP clients.
**NettyNioAsyncHttpClient (default)**
[NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html) is the default HTTP client used by asynchronous clients. For information about configuring the `NettyNioAsyncHttpClient`, see [Configure the Netty-based HTTP client](http-configuration-netty.md).
**AwsCrtAsyncHttpClient**
The [AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html) is based on the AWS Common Runtime (CRT) HTTP Client. For information about configuring the `AwsCrtAsyncHttpClient`, see [Configure AWS CRT-based HTTP clients](http-configuration-crt.md).
## HTTP client recommendations
Several factors come into play when you choose an HTTP client implementation. Use the following information to help you decide.
### HTTP client comparison
The following table provides detailed information for each HTTP client.
| HTTP client | Sync or async | When to use | Limitation/drawback |
| --- | --- | --- | --- |
| Apache-based HTTP client *(default sync HTTP client)* | Sync | Use it if you prefer low latency over high throughput | Slower startup time compared to other HTTP clients |
| URLConnection-based HTTP client | Sync | Use it if you have a hard requirement for limiting third-party dependencies | Does not support the HTTP PATCH method, required by some APIS like Amazon APIGateway Update operations |
| AWS CRT-based sync HTTP client1 | Sync | • Use it if your application is running in AWS Lambda • Use it if you prefer high throughput over low latency • Use it if you prefer sync SDK clients | The following Java system properties are not supported: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/http-configuration.html) |
| Netty-based HTTP client *(default async HTTP client)* | Async | • Use it if your application relies on Java system properties for TLS configuration (such as `javax.net.ssl.keyStore`) | Slower startup time compared to other HTTP clients |
| AWS CRT-based async HTTP client1 | Async | • Use it if your application is running in AWS Lambda• Use it if you prefer high throughput over low latency• Use it if you prefer async SDK clients | The following Java system properties are not supported: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/http-configuration.html) |
1Because of their added benefits, we recommend that you use the AWS CRT-based HTTP clients if possible.
## Smart configuration defaults
The AWS SDK for Java 2.x (version 2.17.102 or later) offers a smart configuration defaults feature. This feature optimizes two HTTP client properties along with other properties that don't affect the HTTP client.
The smart configuration defaults set sensible values for the `connectTimeoutInMillis` and `tlsNegotiationTimeoutInMillis` properties based on a defaults mode value that you provide. You choose the defaults mode value based on your application's characteristics.
For more information about smart configuration defaults and how to choose the defaults mode value that is best suited for your applications, see the [AWS SDKs and Tools Reference Guide](https://docs.aws.amazon.com/sdkref/latest/guide/feature-smart-config-defaults.html).
Following are four ways to set the defaults mode for your application.
------
#### [ Service client ]
Use the service client builder to configure the defaults mode directly on the service client. The following example sets the defaults mode to `auto` for the `DynamoDbClient`.
```
DynamoDbClient ddbClient = DynamoDbClient.builder()
.defaultsMode(DefaultsMode.AUTO)
.build();
```
------
#### [ System property ]
You can use the `aws.defaultsMode` system property to specify the defaults mode. If you set the system property in Java, you need to set the property before initializing any service client.
The following example shows you how to set the defaults mode to `auto` using a system property set in Java.
```
System.setProperty("aws.defaultsMode", "auto");
```
The following example demonstrates how you set the defaults mode to `auto` using a `-D` option of the `java` command.
```
java -Daws.defaultsMode=auto
```
------
#### [ Environment variable ]
Set a value for environment variable `AWS_DEFAULTS_MODE` to select the defaults mode for your application.
The following information shows the command to run to set the value for the defaults mode to `auto` using an environment variable.
| Operating system | Command to set environment variables |
| --- | --- |
| Linux, macOS, or Unix | export AWS\$1DEFAULTS\$1MODE=auto |
| Windows | set AWS\$1DEFAULTS\$1MODE=auto |
------
#### [ AWS config file ]
You can add a `defaults_mode` configuration property to the shared AWS `config` file as the following example shows.
```
[default]
defaults_mode = auto
```
------
If you set the defaults mode globally with the system property, environment variable, or AWS config file, you can override the settings when you build an HTTP client.
When you build an HTTP client with the `httpClientBuilder()` method, settings apply only to the instance that you are building. An example of this is shown [here](http-configuration-netty.md#http-config-netty-one-client). The Netty-based HTTP client in this example overrides any default mode values set globally for `connectTimeoutInMillis` and `tlsNegotiationTimeoutInMillis`.
# Configure the Apache-based HTTP client
Synchronous service clients in the AWS SDK for Java 2.x use an Apache-based HTTP client, [ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html) by default. The SDK's `ApacheHttpClient` is based on the Apache [HttpClient](https://hc.apache.org/httpcomponents-client-4.5.x/index.html).
The SDK also offers the [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html), which loads more quickly, but has fewer features. For information about configuring the `UrlConnectionHttpClient`, see [Configure the URLConnection-based HTTP client](http-configuration-url.md).
To see the full set of configuration options available to you for the `ApacheHttpClient`, see [ApacheHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.Builder.html) and [ProxyConfiguration.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ProxyConfiguration.Builder.html).
## Access the `ApacheHttpClient`
In most situations, you use the `ApacheHttpClient` without any explicit configuration. You declare your service clients and the SDK will configure the `ApacheHttpClient` with standard values for you.
If you want to explicitly configure the `ApacheHttpClient` or use it with multiple service clients, you need to make it available for configuration.
### No configuration needed
When you declare a dependency on a service client in Maven, the SDK adds a *runtime* dependency on the `apache-client` artifact. This makes the `ApacheHttpClient` class available to your code at runtime, but not at compile time. If you are not configuring the Apache-based HTTP client, you do not need to specify a dependency for it.
In the following XML snippet of a Maven `pom.xml` file, the dependency declared with `s3` automatically brings in the Apache-based HTTP client. You don't need to declare a dependency specifically for it.
```
software.amazon.awssdk
bom
2.27.21
pom
import
software.amazon.awssdk
s3
```
With these dependencies, you cannot make any explicit HTTP configuration changes, because the `ApacheHttpClient` library is only on the runtime classpath.
### Configuration needed
To configure the `ApacheHttpClient`, you need to add a dependency on the `apache-client` library at *compile* time.
Refer to the following example of a Maven `pom.xml` file to configure the `ApacheHttpClient`.
```
software.amazon.awssdk
bom
2.27.21
pom
import
software.amazon.awssdk
s3
software.amazon.awssdk
apache-client
```
## Use and configure the `ApacheHttpClient`
You can configure an instance of `ApacheHttpClient` along with building a service client, or you can configure a single instance to share across multiple service clients.
With either approach, you use the `[ApacheHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.Builder.html)` to configure the properties for the Apache-based HTTP client.
### Best practice: dedicate an `ApacheHttpClient` instance to a service client
If you need to configure an instance of the `ApacheHttpClient`, we recommend that you build the dedicated `ApacheHttpClient` instance. You can do so by using the `httpClientBuilder` method of the service client's builder. This way, the lifecycle of the HTTP client is managed by the SDK, which helps avoid potential memory leaks if the `ApacheHttpClient` instance is not closed down when it's no longer needed.
The following example creates an `S3Client` and configures the embedded instance of `ApacheHttpClient` with `maxConnections` and `connectionTimeout` values. The HTTP instance is created using the `httpClientBuilder` method of `S3Client.Builder`.
**Imports**
```
import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**Code**
```
S3Client s3Client = S3Client // Singleton: Use the s3Client for all requests.
.builder()
.httpClientBuilder(ApacheHttpClient.builder()
.maxConnections(100)
.connectionTimeout(Duration.ofSeconds(5))
).build();
// Perform work with the s3Client.
s3Client.close(); // Requests completed: Close all service clients.
```
### Alternative approach: share an `ApacheHttpClient` instance
To help keep resource and memory usage lower for your application, you can configure an `ApacheHttpClient` and share it across multiple service clients. The HTTP connection pool will be shared, which lowers resource usage.
**Note**
When an `ApacheHttpClient` instance is shared, you must close it when it is ready to be disposed. The SDK will not close the instance when the service client is closed.
The following example configures an Apache-based HTTP client that is used by two service clients. The configured `ApacheHttpClient` instance is passed to the `httpClient` method of each builder. When the service clients and the HTTP client are no longer needed, the code explicitly closes them. The code closes the HTTP client last.
**Imports**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
```
**Code**
```
SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()
.maxConnections(100).build();
// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client =
S3Client.builder()
.httpClient(apacheHttpClient).build();
DynamoDbClient dynamoDbClient =
DynamoDbClient.builder()
.httpClient(apacheHttpClient).build();
// Perform work with the s3Client and dynamoDbClient.
// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
apacheHttpClient.close(); // Explicitly close apacheHttpClient.
```
## Proxy configuration example
The following code snippet uses the [proxy configuration builder for the Apache HTTP client](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ProxyConfiguration.Builder.html).
```
SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.endpoint(URI.create("http://example.com:1234"))
.username("username")
.password("password")
.addNonProxyHost("localhost")
.addNonProxyHost("host.example.com")
.build())
.build();
```
The equivalent Java system properties for the proxy configuration are shown in the following command line snippet.
```
$ java -Dhttp.proxyHost=example.com -Dhttp.proxyPort=1234 -Dhttp.proxyUser=username \
-Dhttp.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App
```
The equivalent setup that uses environment variables is:
```
// Set the following environment variables.
// $ export HTTP_PROXY="http://username:password@example.com:1234"
// $ export NO_PROXY="localhost|host.example.com"
// Set the 'useSystemPropertyValues' to false on the proxy configuration.
SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build();
// Run the application.
// $ java -cp ... App
```
**Note**
The Apache HTTP client does not currently support HTTPS proxy system properties or the HTTPS\$1PROXY environment variable.
# Configure the URLConnection-based HTTP client
The AWS SDK for Java 2.x offers a lighter-weight `[UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)` HTTP client in comparison to the default `ApacheHttpClient`. The `UrlConnectionHttpClient` is based on Java's `[URLConnection](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/net/URLConnection.html)`.
The `UrlConnectionHttpClient` loads more quickly than the Apache-based HTTP client, but has fewer features. Because it loads more quickly, it is a [good solution](lambda-optimize-starttime.md) for Java AWS Lambda functions.
The `UrlConnectionHttpClient` has several [configurable options](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.Builder.html) that you can access.
**Note**
The `UrlConnectionHttpClient` does not support the HTTP PATCH method.
A handful of AWS API operations require PATCH requests. Those operation names usually start with `Update*`. The following are several examples.
[Several `Update*` operations](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_Operations.html) in the AWS Security Hub CSPM API and also the [BatchUpdateFindings](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_BatchUpdateFindings.html) operation
All Amazon API Gateway API [`Update*` operations](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html)
If you might use the `UrlConnectionHttpClient`, first refer to the API Reference for the AWS service that you're using. Check to see if the operations you need use the PATCH operation.
## Access the `UrlConnectionHttpClient`
To configure and use the `UrlConnectionHttpClient`, you declare a dependency on the `url-connection-client` Maven artifact in your `pom.xml` file.
Unlike the `ApacheHttpClient`, the `UrlConnectionHttpClient` is not automatically added to your project, so use must specifically declare it.
The following example of a `pom.xml` file shows the dependencies required to use and configure the HTTP client.
```
software.amazon.awssdk
bom
2.27.21
pom
import
software.amazon.awssdk
url-connection-client
```
## Use and configure the `UrlConnectionHttpClient`
You can configure an instance of `UrlConnectionHttpClient` along with building a service client, or you can configure a single instance to share across multiple service clients.
With either approach, you use the [UrlConnectionHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.Builder.html) to configure the properties for the URLConnection-based HTTP client.
### Best practice: dedicate an `UrlConnectionHttpClient` instance to a service client
If you need to configure an instance of the `UrlConnectionHttpClient`, we recommend that you build the dedicated `UrlConnectionHttpClient` instance. You can do so by using the `httpClientBuilder` method of the service client's builder. This way, the lifecycle of the HTTP client is managed by the SDK, which helps avoid potential memory leaks if the `UrlConnectionHttpClient` instance is not closed down when it's no longer needed.
The following example creates an `S3Client` and configures the embedded instance of `UrlConnectionHttpClient` with `socketTimeout` and `proxyConfiguration` values. The `proxyConfiguration` method takes a Java lambda expression of type ` Consumer<[ProxyConfiguration.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/ProxyConfiguration.Builder.html)>`.
**Imports**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import java.net.URI;
import java.time.Duration;
```
**Code**
```
// Singleton: Use the s3Client for all requests.
S3Client s3Client =
S3Client.builder()
.httpClientBuilder(UrlConnectionHttpClient.builder()
.socketTimeout(Duration.ofMinutes(5))
.proxyConfiguration(proxy -> proxy.endpoint(URI.create("http://proxy.mydomain.net:8888"))))
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
// Perform work with the s3Client.
s3Client.close(); // Requests completed: Close the s3client.
```
### Alternative approach: share an `UrlConnectionHttpClient` instance
To help keep resource and memory usage lower for your application, you can configure an `UrlConnectionHttpClient` and share it across multiple service clients. The HTTP connection pool will be shared, which lowers resource usage.
**Note**
When an `UrlConnectionHttpClient` instance is shared, you must close it when it is ready to be disposed. The SDK will not close the instance when the service client is closed.
The following example configures an URLConnection-based HTTP client that is used by two service clients. The configured `UrlConnectionHttpClient` instance is passed to the `httpClient` method of each builder. When the service clients and the HTTP client are no longer needed, the code explicitly closes them. The code closes the HTTP client last.
**Imports**
```
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.urlconnection.ProxyConfiguration;
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.net.URI;
import java.time.Duration;
```
**Code**
```
SdkHttpClient urlHttpClient = UrlConnectionHttpClient.create();
// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client =
S3Client.builder()
.httpClient(urlHttpClient)
.defaultsMode(DefaultsMode.IN_REGION)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
DynamoDbClient dynamoDbClient =
DynamoDbClient.builder()
.httpClient(urlHttpClient)
.defaultsMode(DefaultsMode.IN_REGION)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
// Perform work with the s3Client and dynamoDbClient.
// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
urlHttpClient.close();
```
#### Use `URLConnectionHttpClient` and `ApacheHttpClient` together
When you use the `UrlConnectionHttpClient` in your application, you must supply each service client with either a `URLConnectionHttpClient` instance or a `ApacheHttpClient` instance using the service client builder's `httpClientBuilder` method.
An exception occurs if your program uses multiple service clients and both of the following are true:
+ One service client is configured to use a `UrlConnectionHttpClient` instance
+ Another service client uses the default `ApacheHttpClient` without explicitly building it with the `httpClient()` or `httpClientBuilder()` methods
The exception will state that multiple HTTP implementations were found on the classpath.
The following example code snippet leads to an exception.
```
// The dynamoDbClient uses the UrlConnectionHttpClient
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.httpClient(UrlConnectionHttpClient.create())
.build();
// The s3Client below uses the ApacheHttpClient at runtime, without specifying it.
// An SdkClientException is thrown with the message that multiple HTTP implementations were found on the classpath.
S3Client s3Client = S3Client.create();
// Perform work with the s3Client and dynamoDbClient.
dynamoDbClient.close();
s3Client.close();
```
Avoid the exception by explicitly configuring the `S3Client` with an `ApacheHttpClient`.
```
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.httpClient(UrlConnectionHttpClient.create())
.build();
S3Client s3Client = S3Client.builder()
.httpClient(ApacheHttpClient.create()) // Explicitly build the ApacheHttpClient.
.build();
// Perform work with the s3Client and dynamoDbClient.
dynamoDbClient.close();
s3Client.close();
```
**Note**
To explicitly create the `ApacheHttpClient`, you must [add a dependency](http-configuration-apache.md#http-apache-dependency) on the `apache-client` artifact in your Maven project file.
## Proxy configuration example
The following code snippet uses the [proxy configuration builder for the URL connection HTTP client](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/ProxyConfiguration.Builder.html).
```
SdkHttpClient urlHttpClient = UrlConnectionHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.endpoint(URI.create("http://example.com:1234"))
.username("username")
.password("password")
.addNonProxyHost("localhost")
.addNonProxyHost("host.example.com")
.build())
.build();
```
The equivalent Java system properties for the proxy configuration are shown in the following command line snippet.
```
$ java -Dhttp.proxyHost=example.com -Dhttp.proxyPort=1234 -Dhttp.proxyUser=username \
-Dhttp.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App
```
The equivalent setup that uses environment variables is:
```
// Set the following environment variables.
// $ export HTTP_PROXY="http://username:password@example.com:1234"
// $ export NO_PROXY="localhost|host.example.com"
// Set the 'useSystemPropertyValues' to false on the proxy configuration.
SdkHttpClient apacheHttpClient = UrlConnectionHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build();
// Run the application.
// $ java -cp ... App
```
**Note**
The URLConnection-based HTTP client does not currently support HTTPS proxy system properties or the HTTPS\$1PROXY environment variable.
# Configure the Netty-based HTTP client
The default HTTP client for asynchronous operations in the AWS SDK for Java 2.x is the Netty-based [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html). The Netty-based client is based on the asynchronous event-driven network framework of the [Netty project](https://netty.io/).
As an alternative HTTP client, you can use the new [AWS CRT-based HTTP client](http-configuration-crt.md). This topic shows you how to configure the `NettyNioAsyncHttpClient`.
## Access the `NettyNioAsyncHttpClient`
In most situations, you use the `NettyNioAsyncHttpClient` without any explicit configuration in asynchronous programs. You declare your asynchronous service clients and the SDK will configure the `NettyNioAsyncHttpClient` with standard values for you.
If you want to explicitly configure the `NettyNioAsyncHttpClient` or use it with multiple service clients, you need to make it available for configuration.
### No configuration needed
When you declare a dependency on a service client in Maven, the SDK adds a *runtime* dependency on the `netty-nio-client` artifact. This makes the `NettyNioAsyncHttpClient` class available to your code at runtime, but not at compile time. If you are not configuring the Netty-based HTTP client, you don't need to specify a dependency for it.
In the following XML snippet of a Maven `pom.xml` file, the dependency declared with `dynamodb-enhanced` transitively brings in the Netty-based HTTP client. You don't need to declare a dependency specifically for it.
```
software.amazon.awssdk
bom
2.27.21
pom
import
software.amazon.awssdk
dynamodb-enhanced
```
With these dependencies, you cannot make any HTTP configuration changes, since the `NettyNioAsyncHttpClient` library is only on the runtime classpath.
### Configuration needed
To configure the `NettyNioAsyncHttpClient`, you need to add a dependency on the `netty-nio-client` artifact at *compile* time.
Refer to the following example of a Maven `pom.xml` file to configure the `NettyNioAsyncHttpClient`.
```
software.amazon.awssdk
bom
2.27.21
pom
import
software.amazon.awssdk
dynamodb-enhanced
software.amazon.awssdk
netty-nio-client
```
## Use and configure the `NettyNioAsyncHttpClient`
You can configure an instance of `NettyNioAsyncHttpClient` along with building a service client, or you can configure a single instance to share across multiple service clients.
With either approach, you use the [NettyNioAsyncHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.Builder.html) to configure the properties for the Netty-based HTTP client instance.
### Best practice: dedicate a `NettyNioAsyncHttpClient` instance to a service client
If you need to configure an instance of the `NettyNioAsyncHttpClient`, we recommend that you build a dedicated `NettyNioAsyncHttpClient` instance. You can do so by using the `httpClientBuilder` method of the service client's builder. This way, the lifecycle of the HTTP client is managed by the SDK, which helps avoid potential memory leaks if the `NettyNioAsyncHttpClient` instance is not closed down when it's no longer needed.
The following example creates a `DynamoDbAsyncClient` instance that is used by a `DynamoDbEnhancedAsyncClient` instance. The `DynamoDbAsyncClient` instance contains the `NettyNioAsyncHttpClient` instance with `connectionTimeout` and `maxConcurrency` values. The HTTP instance is created using `httpClientBuilder` method of `DynamoDbAsyncClient.Builder`.
**Imports**
```
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient;
import software.amazon.awssdk.enhanced.dynamodb.extensions.AutoGeneratedTimestampRecordExtension;
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
import java.time.Duration;
```
**Code**
```
// DynamoDbAsyncClient is the lower-level client used by the enhanced client.
DynamoDbAsyncClient dynamoDbAsyncClient =
DynamoDbAsyncClient
.builder()
.httpClientBuilder(NettyNioAsyncHttpClient.builder()
.connectionTimeout(Duration.ofMillis(5_000))
.maxConcurrency(100)
.tlsNegotiationTimeout(Duration.ofMillis(3_500)))
.defaultsMode(DefaultsMode.IN_REGION)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
// Singleton: Use dynamoDbAsyncClient and enhancedClient for all requests.
DynamoDbEnhancedAsyncClient enhancedClient =
DynamoDbEnhancedAsyncClient
.builder()
.dynamoDbClient(dynamoDbAsyncClient)
.extensions(AutoGeneratedTimestampRecordExtension.create())
.build();
// Perform work with the dynamoDbAsyncClient and enhancedClient.
// Requests completed: Close dynamoDbAsyncClient.
dynamoDbAsyncClient.close();
```
### Alternative approach: share a `NettyNioAsyncHttpClient` instance
To help keep resource and memory usage lower for your application, you can configure a `NettyNioAsyncHttpClient` and share it across multiple service clients. The HTTP connection pool will be shared, which lowers resource usage.
**Note**
When a `NettyNioAsyncHttpClient` instance is shared, you must close it when it is ready to be disposed. The SDK will not close the instance when the service client is closed.
The following example configures a Netty-based HTTP client that is used by two service clients. The configured `NettyNioAsyncHttpClient` instance is passed to the `httpClient` method of each builder. When the service clients and the HTTP client are no longer needed, the code explicitly closes them. The code closes the HTTP client last.
**Imports**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
```
**Code**
```
// Create a NettyNioAsyncHttpClient shared instance.
SdkAsyncHttpClient nettyHttpClient = NettyNioAsyncHttpClient.builder().maxConcurrency(100).build();
// Singletons: Use the s3AsyncClient, dbAsyncClient, and enhancedAsyncClient for all requests.
S3AsyncClient s3AsyncClient =
S3AsyncClient.builder()
.httpClient(nettyHttpClient)
.build();
DynamoDbAsyncClient dbAsyncClient =
DynamoDbAsyncClient.builder()
.httpClient(nettyHttpClient)
.defaultsMode(DefaultsMode.IN_REGION)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
DynamoDbEnhancedAsyncClient enhancedAsyncClient =
DynamoDbEnhancedAsyncClient.builder()
.dynamoDbClient(dbAsyncClient)
.extensions(AutoGeneratedTimestampRecordExtension.create())
.build();
// Perform work with s3AsyncClient, dbAsyncClient, and enhancedAsyncClient.
// Requests completed: Close all service clients.
s3AsyncClient.close();
dbAsyncClient.close()
nettyHttpClient.close(); // Explicitly close nettyHttpClient.
```
## Configure ALPN protocol negotiation
ALPN (Application-Layer Protocol Negotiation) is a TLS extension that allows the application layer to negotiate which protocol should be performed over a secure connection in a manner that avoids additional round trips and provides better performance.
To enable the Netty-based HTTP client to use ALPN, call the builder methods as shown in the following snippet:
```
import software.amazon.awssdk.http.Protocol;
import software.amazon.awssdk.http.ProtocolNegotiation;
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
import software.amazon.awssdk.services.transcribestreaming.TranscribeStreamingAsyncClient;
// Configure the Netty-based HTTP client to use the ALPN protocol.
SdkAsyncHttpClient nettyClient = NettyNioAsyncHttpClient.builder()
.protocol(Protocol.HTTP2)
.protocolNegotiation(ProtocolNegotiation.ALPN)
.build();
// Use the Netty-based HTTP client with a service client.
TranscribeStreamingAsyncClient transcribeClient = TranscribeStreamingAsyncClient.builder()
.httpClient(nettyClient)
.build();
```
ALPN protocol negotiation currently works with only with the HTTP/2 protocol as shown in the previous snippet.
## Proxy configuration example
The following code snippet uses the [proxy configuration builder for the Netty HTTP client](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/ProxyConfiguration.Builder.html).
```
SdkAsyncHttpClient nettyHttpClient = NettyNioAsyncHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.scheme("https")
.host("myproxy")
.port(1234)
.username("username")
.password("password")
.nonProxyHosts(Set.of("localhost", "host.example.com"))
.build())
.build();
```
The equivalent Java system properties for the proxy configuration are shown in the following command line snippet.
```
$ java -Dhttps.proxyHost=myproxy -Dhttps.proxyPort=1234 -Dhttps.proxyUser=username \
-Dhttps.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App
```
**Important**
To use any of the HTTPS proxy system properties, the `scheme` property must be set in code to `https`. If the scheme property is not set in code, the scheme defaults to HTTP and the SDK looks only for `http.*` system properties.
The equivalent setup that uses environment variables is:
```
// Set the following environment variables.
// $ export HTTPS_PROXY="https://username:password@myproxy:1234"
// $ export NO_PROXY="localhost|host.example.com"
// Set the 'useSystemPropertyValues' to false on the proxy configuration.
SdkAsyncHttpClient nettyHttpClient = NettyNioAsyncHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build();
// Run the application.
// $ java -cp ... App
```
# Configure AWS CRT-based HTTP clients
The AWS CRT-based HTTP clients include the synchronous [AwsCrtHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html) and asynchronous [AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html). The AWS CRT-based HTTP clients provide the following HTTP client benefits:
+ Faster SDK startup time
+ Smaller memory footprint
+ Reduced latency time
+ Connection health management
+ DNS load balancing
**AWS CRT-based components in the SDK**
The AWS CRT-based* HTTP* clients, described in this topic, and the AWS CRT-based *S3* client are different components in the SDK.
The synchronous and asynchronous **AWS CRT-based HTTP clients** are implementations SDK HTTP client interfaces and are used for general HTTP communication. They are alternatives to the other synchronous or asynchronous HTTP clients in the SDK with additional benefits.
The **[AWS CRT-based S3 client](crt-based-s3-client.md)** is an implementation of the [S3AsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3AsyncClient.html) interface and is used for working with the Amazon S3 service. It is an alternative to the Java-based implementation of the `S3AsyncClient` interface and offers several advantages.
Although both components use libraries from the [AWS Common Runtime](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html), the AWS CRT-based HTTP clients do not use the [aws-c-s3 library](https://github.com/awslabs/aws-c-s3) and do not support the [S3 multipart upload API](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html) features. The AWS CRT-based S3 client, by contrast, was purpose-built to support the S3 multipart upload API features.
## Access the AWS CRT-based HTTP clients
Before you can use the AWS CRT-based HTTP clients, add the `aws-crt-client` artifact with a minimum version of 2.22.0 to your project's dependencies.
Use one of the following options to set up your Maven `pom.xml` file.
**Note**
You might choose to use the *Platform-specific jar option* if you need to keep the size of the runtime dependencies smaller, for example if your application runs in an AWS Lambda function.
------
#### [ Uber-jar option ]
By default, the `aws-crt-client` uses an uber-jar of AWS CRT artifacts that contains binaries for several platforms, including Linux, Windows, and macOS.
```
2.29.10*
software.amazon.awssdk
bom
${aws.sdk.version}
pom
import
software.amazon.awssdk
aws-crt-client
```
\$1Replace the version shown in red with the version of the Java SDK that you want to use. Find the latest on [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
------
#### [ Platform-specific jar option ]
To restrict the Java runtime to platform-specific version of the AWS CRT library, make the following changes to the *Uber-jar option*.
+ Add an `exclusions` element to the SDK's `aws-crt-client` artifact. This exclusion prevents the SDK from transitively using the AWS CRT uber-jar.
+ Add a dependency element for the specific AWS CRT platform version you need. See the **Steps to determine the AWS CRT artifact version** below for how you can determine the correct version.
```
2.29.101
software.amazon.awssdk
bom
${aws.sdk.java.version}
pom
import
software.amazon.awssdk
aws-crt-client
software.amazon.awssdk.crt
aws-crt
software.amazon.awssdk.crt
aws-crt
0.31.32
linux-x86_643
```
1Replace the version shown in red with the version of the Java SDK that you want to use. Find the latest on [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
2Replace the version of `software.amazon.awssdk.crt:aws-crt` that would be provided by the *Uber-jar option*. See the following **Steps to determine the AWS CRT artifact version**.
3Replace the `classifier` value with one for your platform. Refer to the AWS CRT for Java GitHub page for a [listing of available values](https://github.com/awslabs/aws-crt-java?tab=readme-ov-file#platform-specific-jars).
**Steps to determine the AWS CRT artifact version**
Use the following steps to determine the AWS CRT artifact version that is compatible with the version of the SDK for Java that you are using.
1. Set up your `pom.xml` file as shown in the *Uber-jar option*. This setup allows you to see what version of `software.amazon.awssdk.crt:aws-crt` the SDK brings in by default.
1. At the root of the project (in the same directory as the `pom.xml` file), run the following Maven command:
```
mvn dependency:tree -Dincludes=software.amazon.awssdk.crt:aws-crt
```
Maven might perform other actions, but at the end you should see console output of the `software.amazon.awssdk.crt:aws-crt` dependency that the SDK transitively uses. The following snippet shows sample output based on an SDK version of `2.29.10`:
```
[INFO] org.example:yourProject:jar:1.0-SNAPSHOT
[INFO] \- software.amazon.awssdk:aws-crt-client:jar:2.29.10:compile
[INFO] \- software.amazon.awssdk.crt:aws-crt:jar:0.31.3:compile
```
1. Use the version that the console shows for the `software.amazon.awssdk.crt:aws-crt` artifact. In this case, add `0.31.3` to your `pom.xml` file.
------
## Use and configure an AWS CRT-based HTTP client
You can configure an AWS CRT-based HTTP client along with building a service client, or you can configure a single instance to share across multiple service clients.
With either approach, you use a builder to [configure the properties](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.Builder.html) for the AWS CRT-based HTTP client instance.
### Best practice: dedicate an instance to a service client
If you need to configure an instance of an AWS CRT-based HTTP client, we recommend that you dedicate the instance by building it along with the service client . You can do so by using the `httpClientBuilder` method of the service client's builder. This way, the lifecycle of the HTTP client is managed by the SDK, which helps avoid potential memory leaks if the AWS CRT-based HTTP client instance is not closed down when it's no longer needed.
The following example creates an S3 service client and configures an AWS CRT-based HTTP client with `connectionTimeout` and `maxConcurrency` values.
------
#### [ Synchronous client ]
**Imports**
```
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**Code**
```
// Singleton: Use s3Client for all requests.
S3Client s3Client = S3Client.builder()
.httpClientBuilder(AwsCrtHttpClient
.builder()
.connectionTimeout(Duration.ofSeconds(3))
.maxConcurrency(100))
.build();
// Perform work with the s3Client.
// Requests completed: Close the s3Client.
s3Client.close();
```
------
#### [ Asynchronous client ]
**Imports**
```
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;
```
**Code**
```
// Singleton: Use s3AsyncClient for all requests.
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
.httpClientBuilder(AwsCrtAsyncHttpClient
.builder()
.connectionTimeout(Duration.ofSeconds(3))
.maxConcurrency(100))
.build();
// Perform work with the s3AsyncClient.
// Requests completed: Close the s3AsyncClient.
s3AsyncClient.close();
```
------
### Alternative approach: share an instance
To help keep resource and memory usage lower for your application, you can configure an AWS CRT-based HTTP client and share it across multiple service clients. The HTTP connection pool will be shared, which lowers resource usage.
**Note**
When an AWS CRT-based HTTP client instance is shared, you must close it when it is ready to be disposed. The SDK will not close the instance when the service client is closed.
The following example configures an AWS CRT-based HTTP client instance with `connectionTimeout` and `maxConcurrency` values. The configured instance is passed to the `httpClient` method of each service client's builder. When the service clients and the HTTP client are no longer needed, they are explicitly closed. The HTTP client is closed last.
------
#### [ Synchronous client ]
**Imports**
```
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**Code**
```
// Create an AwsCrtHttpClient shared instance.
SdkHttpClient crtHttpClient = AwsCrtHttpClient.builder()
.connectionTimeout(Duration.ofSeconds(3))
.maxConcurrency(100)
.build();
// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client = S3Client.builder()
.httpClient(crtHttpClient)
.credentialsProvider(EnvironmentVariableCredentialsProvider.crea
.defaultsMode(DefaultsMode.IN_REGION)
.region(Region.US_EAST_1)
.build();
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.httpClient(crtHttpClient)
.credentialsProvider(EnvironmentVariableCredentialsProvider.crea
.defaultsMode(DefaultsMode.IN_REGION)
.region(Region.US_EAST_1)
.build();
// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
crtHttpClient.close(); // Explicitly close crtHttpClient.
```
------
#### [ Asynchronous client ]
**Imports**
```
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;
```
**Code**
```
// Create an AwsCrtAsyncHttpClient shared instance.
SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()
.connectionTimeout(Duration.ofSeconds(3))
.maxConcurrency(100)
.build();
// Singletons: Use the s3AsyncClient and dynamoDbAsyncClient for all requests.
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
.httpClient(crtAsyncHttpClient)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.defaultsMode(DefaultsMode.IN_REGION)
.region(Region.US_EAST_1)
.build();
DynamoDbAsyncClient dynamoDbAsyncClient = DynamoDbAsyncClient.builder()
.httpClient(crtAsyncHttpClient)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.defaultsMode(DefaultsMode.IN_REGION)
.region(Region.US_EAST_1)
.build();
// Requests completed: Close all service clients.
s3AsyncClient.close();
dynamoDbAsyncClient.close();
crtAsyncHttpClient.close(); // Explicitly close crtAsyncHttpClient.
```
------
## Set an AWS CRT-based HTTP client as the default
You can setup your Maven build file to have the SDK use an AWS CRT-based HTTP client as the default HTTP client for service clients.
You do this by adding an `exclusions` element with the default HTTP client dependencies to each service client artifact.
In the following `pom.xml` example, the SDK uses an AWS CRT-based HTTP client for S3 services. If the service client in your code is an `S3AsyncClient`, the SDK uses `AwsCrtAsyncHttpClient`. If the service client is an S3Client, the SDK uses `AwsCrtHttpClient`. With this setup the default Netty-based asynchronous HTTP client and the default Apache-based synchronous HTTP are not available.
```
VERSION
software.amazon.awssdk
s3
${aws.sdk.version}
software.amazon.awssdk
netty-nio-client
software.amazon.awssdk
apache-client
software.amazon.awssdk
aws-crt-client
```
Visit the Maven central repository for the latest [https://central.sonatype.com/artifact/software.amazon.awssdk/bom](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) value.
**Note**
If multiple service clients are declared in a `pom.xml` file, all require the `exclusions` XML element.
### Use a Java system property
To use the AWS CRT-based HTTP clients as the default HTTP for your application, you can set the Java system property `software.amazon.awssdk.http.async.service.impl` to a value of `software.amazon.awssdk.http.crt.AwsCrtSdkHttpService`.
To set during application startup, run a command similar to the following.
```
java app.jar -Dsoftware.amazon.awssdk.http.async.service.impl=\
software.amazon.awssdk.http.crt.AwsCrtSdkHttpService
```
Use the following code snippet to set the system property in your application code.
```
System.setProperty("software.amazon.awssdk.http.async.service.impl",
"software.amazon.awssdk.http.crt.AwsCrtSdkHttpService");
```
**Note**
You need to add a dependency on the `aws-crt-client` artifact in your `poml.xml` file when you use a system property to configure the use of the AWS CRT-based HTTP clients.
## Advanced configuration of AWS CRT-based HTTP clients
You can use various configuration settings of the AWS CRT-based HTTP clients, including connection health configuration and maximum idle time. You can review the configuration [options available](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.Builder.html) for the `AwsCrtAsyncHttpClient`. You can configure the same options for the `AwsCrtHttpClient`.
### Connection health configuration
You can configure connection health configuration for the AWS CRT-based HTTP clients by using the `connectionHealthConfiguration` method on the HTTP client builder.
The following example creates an S3 service client that uses a AWS CRT-based HTTP client instance configured with connection health configuration and a maximum idle time for connections.
------
#### [ Synchronous client ]
**Imports**
```
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**Code**
```
// Singleton: Use the s3Client for all requests.
S3Client s3Client = S3Client.builder()
.httpClientBuilder(AwsCrtHttpClient
.builder()
.connectionHealthConfiguration(builder -> builder
.minimumThroughputInBps(32000L)
.minimumThroughputTimeout(Duration.ofSeconds(3)))
.connectionMaxIdleTime(Duration.ofSeconds(5)))
.build();
// Perform work with s3Client.
// Requests complete: Close the service client.
s3Client.close();
```
------
#### [ Asynchronous client ]
**Imports**
```
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;
```
**Code**
```
// Singleton: Use the s3AsyncClient for all requests.
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
.httpClientBuilder(AwsCrtAsyncHttpClient
.builder()
.connectionHealthConfiguration(builder -> builder
.minimumThroughputInBps(32000L)
.minimumThroughputTimeout(Duration.ofSeconds(3)))
.connectionMaxIdleTime(Duration.ofSeconds(5)))
.build();
// Perform work with s3AsyncClient.
// Requests complete: Close the service client.
s3AsyncClient.close();
```
------
## Proxy configuration example
The following code snippet shows the use of the [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/ProxyConfiguration.Builder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/ProxyConfiguration.Builder.html) that you use to configure proxy setting in code.
------
#### [ Synchronous client ]
**Imports**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.http.crt.ProxyConfiguration;
```
**Code**
```
SdkHttpClient crtHttpClient = AwsCrtHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.scheme("https")
.host("myproxy")
.port(1234)
.username("username")
.password("password")
.nonProxyHosts(Set.of("localhost", "host.example.com"))
.build())
.build();
```
------
#### [ Asynchronous client ]
**Imports**
```
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.http.crt.ProxyConfiguration;
```
**Code**
```
SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.scheme("https")
.host("myproxy")
.port(1234)
.username("username")
.password("password")
.nonProxyHosts(Set.of("localhost", "host.example.com"))
.build())
.build();
```
------
The equivalent Java system properties for the proxy configuration are shown in the following command line snippet.
```
$ java -Dhttps.proxyHost=myproxy -Dhttps.proxyPort=1234 -Dhttps.proxyUser=username \
-Dhttps.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App
```
**Important**
To use any of the HTTPS proxy system properties, the `scheme` property must be set in code to `https`. If the scheme property is not set in code, the scheme defaults to HTTP and the SDK looks only for `http.*` system properties.
The equivalent setup that uses environment variables is:
```
// Set the following environment variables.
// $ export HTTPS_PROXY="https://username:password@myproxy:1234"
// $ export NO_PROXY="localhost|host.example.com"
// Set the 'useSystemPropertyValues' to false on the proxy configuration.
SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.scheme("https")
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build();
// Run the application.
// $ java -cp ... App
```
# Configure HTTP proxies
You can configure HTTP proxies by using code, by setting Java system properties, or by setting environment variables.
## Configure in code
You configure proxies in code with a client-specific `ProxyConfiguration` builder when you build the service client. The following code shows an example proxy configuration for an Apache-based HTTP client that is used by an Amazon S3 service client.
```
SdkHttpClient httpClient1 = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.endpoint(URI.create("http://proxy.example.com"))
.username("username")
.password("password")
.addNonProxyHost("localhost")
.build())
.build();
S3Client s3Client = S3Client.builder()
.httpClient(httpClient)
.build();
```
The section for each HTTP client in this topic shows a proxy configuration example.
+ [Apache HTTP client](http-configuration-apache.md#http-configuration-apache-proxy-conf-ex)
+ [URLConnection-based HTTP client](http-configuration-url.md#http-configuration-url-proxy-conf-ex)
+ [Netty-based HTTP client](http-configuration-netty.md#http-config-netty-proxy-ex)
+ [AWS CRT-based HTTP client](http-configuration-crt.md#http-config-crt-proxy-ex)
## Configure HTTP proxies with external settings
Even if you don't explicitly use a `ProxyConfiguration` builder in code, the SDK looks for external settings to configure a default proxy configuration.
By default, the SDK first searches for JVM system properties. If even one property is found, the SDK uses the value and any other system property values. If no system properties are available, the SDK looks for proxy environment variables.
The SDK can use the following Java system properties and environment variables.
**Java system properties**
| System property | Description | HTTP client support |
| --- | --- | --- |
| http.proxyHost | Host name of the HTTP proxy server | All |
| http.proxyPort | Port number of the HTTP proxy server | All |
| http.proxyUser | Username for HTTP proxy authentication | All |
| http.proxyPassword | Password for HTTP proxy authentication | All |
| http.nonProxyHosts | List of hosts that should be reached directly, bypassing the proxy. [This list is also valid when HTTPS is used](https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html). | All |
| https.proxyHost | Host name of the HTTPS proxy server | Netty, CRT |
| https.proxyPort | Port number of the HTTPS proxy server | Netty, CRT |
| https.proxyUser | Username for HTTPS proxy authentication | Netty, CRT |
| https.proxyPassword | Password for HTTPS proxy authentication | Netty, CRT |
**Environment variables**
| Environment variable | Description | HTTP client support |
| --- | --- | --- |
| HTTP\$1PROXY1 | A valid URL with a scheme of HTTP | All |
| HTTPS\$1PROXY1 | A valid URL with a scheme of HTTPS | Netty, CRT |
| NO\$1PROXY2 | List of hosts that should be reached directly, bypassing the proxy. The list is valid for both HTTP and HTTPS. | All |
### View key and footnotes
**All** - All HTTP clients offered by the SDK–`UrlConnectionHttpClient`, `ApacheHttpClient`, `NettyNioAsyncHttpClient`, `AwsCrtAsyncHttpClient`.
**Netty** - The Netty-based HTTP client (`NettyNioAsyncHttpClient`).
**CRT** - The AWS CRT-based HTTP clients, (`AwsCrtHttpClient` and `AwsCrtAsyncHttpClient`).
1The environment variable queried, whether `HTTP_PROXY` or `HTTPS_PROXY`, depends on the scheme setting in the client's `ProxyConfiguration`. The default scheme is HTTP. The following snippet shows how to change the scheme to HTTPS used for environment variable resolution.
```
SdkHttpClient httpClient = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.scheme("https")
.build())
.build();
```
2The `NO_PROXY` environment variable supports a mix of "\$1" and "," separators between host names. Host names may include the "\$1" wildcard.
## Use a combination of settings
You can use a combination of HTTP proxy settings in code, system properties, and environment variables.
**Example – configuration provided by a system property and by code**
```
// Command line with the proxy password set as a system property.
$ java -Dhttp.proxyPassword=SYS_PROP_password -cp ... App
// Since the 'useSystemPropertyValues' setting is 'true' (the default), the SDK will supplement
// the proxy configuration in code with the 'http.proxyPassword' value from the system property.
SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.endpoint(URI.create("http://localhost:1234"))
.username("username")
.build())
.build();
// Use the apache HTTP client with proxy configuration.
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.httpClient(apacheHttpClient)
.build();
```
The SDK resolves the following proxy settings.
```
Host = localhost
Port = 1234
Password = SYS_PROP_password
UserName = username
Non ProxyHost = null
```
**Example – both system properties and environment variables are available**
Each HTTP client's `ProxyConfiguration` builder offers settings named `useSystemPropertyValues` and `useEnvironmentVariablesValues`. By default, both setting are `true`. When `true`, the SDK automatically uses values from system properties or environment variables for options that are not provided by the `ProxyConfiguration` builder.
System properties take precedence over environment variables. If an HTTP proxy system property is found, the SDK retrieves ***all*** values from system properties and none from environment variables. If you want to prioritize environment variables over system properties, set `useSystemPropertyValues` to `false`.
For this example, the following settings are available a runtime:
```
// System properties
http.proxyHost=SYS_PROP_HOST.com
http.proxyPort=2222
http.password=SYS_PROP_PASSWORD
http.user=SYS_PROP_USER
// Environment variables
HTTP_PROXY="http://EnvironmentUser:EnvironmentPassword@ENV_VAR_HOST:3333"
NO_PROXY="environmentnonproxy.host,environmentnonproxy2.host:1234"
```
The service client is created with one of the following statements. None of the statements explicitly set a proxy setting.
```
DynamoDbClient client = DynamoDbClient.create();
DynamoDbClient client = DynamoDbClient.builder().build();
DynamoDbClient client = DynamoDbClient.builder()
.httpClient(ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.build())
.build())
.build();
```
The following proxy settings are resolved by the SDK:
```
Host = SYS_PROP_HOST.com
Port = 2222
Password = SYS_PROP_PASSWORD
UserName = SYS_PROP_USER
Non ProxyHost = null
```
Because the service client has default proxy settings, the SDK searches for system properties and then environment variables. Since system properties settings take precedence over environment variables, the SDK uses only system properties.
If the use of system properties is changed to `false` as shown in the following code, the SDK resolves only the environment variables.
```
DynamoDbClient client = DynamoDbClient.builder()
.httpClient(ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build())
.build();
```
The resolved proxy settings using HTTP are:
```
Host = ENV_VAR_HOST
Port = 3333
Password = EnvironmentPassword
UserName = EnvironmentUser
Non ProxyHost = environmentnonproxy.host, environmentnonproxy2.host:1234
```
# Configure the Apache 5.x based HTTP client
## Access the Apache5HttpClient
In order to use the `Apache5HttpClient` you must add a dependency on **apache5-client** and explicitly configure `Apache5HttpClient` on your service clients.
```
software.amazon.awssdk
bom
2.41.0*
pom
import
software.amazon.awssdk
s3
software.amazon.awssdk
apache5-client
```
\$1Replace the version shown in red with the version of the Java SDK that you want to use. Find the latest on [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
### Use and configure the `Apache5HttpClient`
You can configure an instance of `Apache5HttpClient` along with building a service client, or you can configure a single instance to share across multiple service clients.
With either approach, you use the [Apache5HttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache5/Apache5HttpClient.Builder.html) to configure the properties for the Apache 5 based HTTP client.
#### Best practice: dedicate an Apache5HttpClient instance to a service client
If you need to configure an instance of the `Apache5HttpClient`, we recommend that you build the dedicated `Apache5HttpClient` instance. You can do so by using the httpClientBuilder method of the service client's builder. This way, the lifecycle of the HTTP client is managed by the SDK, which helps avoid potential memory leaks if the `Apache5HttpClient` instance is not closed down when it's no longer needed.
The following example creates an S3Client and configures the embedded instance of `Apache5HttpClient` with maxConnections and connectionTimeout values. The HTTP instance is created using the `httpClientBuilder` method of `S3Client.Builder`.
**Imports**
```
import software.amazon.awssdk.http.apache5.Apache5HttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**Code**
```
S3Client s3Client = S3Client // Singleton: Use the s3Client for all requests.
.builder()
.httpClientBuilder(Apache5HttpClient.builder()
.maxConnections(100)
.connectionTimeout(Duration.ofSeconds(5))
)
.build();
// Perform work with the s3Client.
s3Client.close(); // Requests completed: Close all service clients.
```
#### Alternative approach: share an `Apache5HttpClient` instance
To help keep resource and memory usage lower for your application, you can configure an `Apache5HttpClient` and share it across multiple service clients. The HTTP connection pool will be shared, which lowers resource usage.
**Note**
When an `Apache5HttpClient` instance is shared, you must close it when it is ready to be disposed. The SDK will not close the instance when the service client is closed.
The following example configures an Apache-based HTTP client that is used by two service clients. The configured `ApacheHttpClient` instance is passed to the httpClient method of each builder. When the service clients and the HTTP client are no longer needed, the code explicitly closes them. The code closes the HTTP client last.
**Imports**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.apache5.Apache5HttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
```
**Code**
```
SdkHttpClient apache5HttpClient = Apache5HttpClient.builder()
.maxConnections(100).build();
// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client =
S3Client.builder()
.httpClient(apache5HttpClient).build();
DynamoDbClient dynamoDbClient =
DynamoDbClient.builder()
.httpClient(apache5HttpClient).build();
// Perform work with the s3Client and dynamoDbClient.
// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
apache5HttpClient.close(); // Explicitly close apache5HttpClient.
```