Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Use a performant S3 client: Amazon CRT-based S3 client

The Amazon CRT-based S3 client—built on top of the Amazon Common Runtime (CRT)—is an alternative S3 asynchronous client. It transfers objects to and from Amazon Simple Storage Service (Amazon S3) with enhanced performance and reliability by automatically using Amazon S3's multipart upload API and byte-range fetches.

The Amazon CRT-based S3 client improves transfer reliability in case there is a network failure. Reliability is improved by retrying individual failed parts of a file transfer without restarting the transfer from the beginning.

In addition, the Amazon CRT-based S3 client offers enhanced connection pooling and Domain Name System (DNS) load balancing, which also improves throughput.

You can use the Amazon CRT-based S3 client in place of the SDK's standard S3 asynchronous client and take advantage of its improved throughput right away.

Amazon CRT-based components in the SDK

The Amazon CRT-based S3 client, described in this topic, and the Amazon CRT-based HTTP client are different components in the SDK.

The Amazon CRT-based S3 client is an implementation of the S3AsyncClient 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 benefits.

The Amazon CRT-based HTTP client is an implementation of the SdkAsyncHttpClient interface and is used for general HTTP communication. It is an alternative to the Netty implementation of the SdkAsyncHttpClient interface and offers several advantages.

Although both components use libraries from the Amazon Common Runtime, the Amazon CRT-based S3 client uses the aws-c-s3 library and supports the S3 multipart upload API features. Since the Amazon CRT-based HTTP client is meant for general purpose use, it does not support the S3 multipart upload API features.

Add dependencies to use the Amazon CRT-based S3 client

To use the Amazon CRT-based S3 client, add the following two dependencies to your Maven project file. The example shows the minimum versions to use. Search the Maven central repository for the most recent versions of the s3 and aws-crt artifacts.

<dependency>
  <groupId>software.amazon.awssdk</groupId>
  <artifactId>s3</artifactId>
  <version>2.27.21</version>
</dependency>
<dependency>
  <groupId>software.amazon.awssdk.crt</groupId>
  <artifactId>aws-crt</artifactId>
  <version>0.30.11</version>
</dependency>

Create an instance of the Amazon CRT-based S3 client

Create an instance of the Amazon CRT-based S3 client with default settings as shown in the following code snippet.

S3AsyncClient s3AsyncClient = S3AsyncClient.crtCreate();

To configure the client, use the Amazon CRT client builder. You can switch from the standard S3 asynchronous client to Amazon CRT-based client by changing the builder method.

import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3AsyncClient;


S3AsyncClient s3AsyncClient = 
        S3AsyncClient.crtBuilder()
                     .credentialsProvider(DefaultCredentialsProvider.create())
                     .region(Region.US_WEST_2)
                     .targetThroughputInGbps(20.0)
                     .minimumPartSizeInBytes(8 * 1025 * 1024L)
                     .build();      

Use the Amazon CRT-based S3 client

Use the Amazon CRT-based S3 client to call Amazon S3 API operations. The following example demonstrates the PutObject and GetObject operations available through the Amazon SDK for Java.

import software.amazon.awssdk.core.async.AsyncRequestBody;
import software.amazon.awssdk.core.async.AsyncResponseTransformer;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import software.amazon.awssdk.services.s3.model.GetObjectResponse;
import software.amazon.awssdk.services.s3.model.PutObjectResponse;


S3AsyncClient s3Client = S3AsyncClient.crtCreate();

// Upload a local file to Amazon S3.
PutObjectResponse putObjectResponse = 
      s3Client.putObject(req -> req.bucket(<BUCKET_NAME>)
                                   .key(<KEY_NAME>),
                        AsyncRequestBody.fromFile(Paths.get(<FILE_NAME>)))
              .join();

// Download an object from Amazon S3 to a local file.
GetObjectResponse getObjectResponse = 
      s3Client.getObject(req -> req.bucket(<BUCKET_NAME>)
                                   .key(<KEY_NAME>),
                        AsyncResponseTransformer.toFile(Paths.get(<FILE_NAME>)))
              .join();
     

Configuration limitations

The Amazon CRT-based S3 client and Java-based S3 async client provide comparable features, with the Amazon CRT-based S3 client offering a performance edge. However, the Amazon CRT-based S3 client lacks configuration settings that the Java-based S3 async client has. These settings include:

For a full listing of the configuration differences, see the API reference.