Configure AWS CRT-based HTTP clients
The AWS CRT-based HTTP clients include the synchronous AwsCrtHttpClient
-
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 is an implementation of the S3AsyncClientS3AsyncClient
interface and
offers several advantages.
Although both components use libraries from the AWS Common
Runtime, the AWS CRT-based HTTP clients do not use the aws-c-s3 library
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.
The following Maven pom.xml
shows the AWS CRT-based HTTP clients declared using the bill of
materials (BOM) mechanism.
<project> <properties> <aws.sdk.version>
2.27.21
</aws.sdk.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>bom</artifactId> <version>${aws.sdk.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>aws-crt-client</artifactId> </dependency> </dependencies> </project>
Visit the Maven central repository for the latest
version
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
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.
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.
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.
<project> <properties> <aws.sdk.version>
VERSION
</aws.sdk.version> </properties> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>s3</artifactId> <version>${aws.sdk.version}</version> <exclusions> <exclusion> <groupId>software.amazon.awssdk</groupId> <artifactId>netty-nio-client</artifactId> </exclusion> <exclusion> <groupId>software.amazon.awssdk</groupId> <artifactId>apache-client</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>aws-crt-client</artifactId> </dependency> </dependencies> </project>
Visit the Maven central repository for the latest VERSION
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 availableAwsCrtAsyncHttpClient
. 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.
HTTP/2 support
The HTTP/2 protocol is not yet supported in the AWS CRT-based HTTP clients, but is planned for a future release.
In the meantime, if you are using service clients that require HTTP/2 support such as
the KinesisAsyncClient
Proxy configuration example
The following code snippet shows the use of the ProxyConfiguration.Builder
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