Work with Amazon S3 - AWS SDK for Java 2.x
S3 clients in the SDK

Work with Amazon S3

This section provides background information for working with Amazon S3 by using the AWS SDK for Java 2.x. This section compliments the Amazon S3 Java v2 examples presented in the Code examples section of this guide.

S3 clients in the AWS SDK for Java 2.x

The AWS SDK for Java 2.x provides different types of S3 clients. The following table shows the differences and can help you decide what is best for your use cases.

Different flavors of Amazon S3 clients
S3 Client Short description When to use Limitation/drawback

AWS CRT-based S3 client

Interface: S3AsyncClient

Builder: S3CrtAsyncClientBuilder

  • Provides the same asynchronous API operations as the Java-based S3 async client but with greater performance.

  • Requires the aws-crt dependency.

  • Supports automatic parallel transfers (multipart).

See Use a performant S3 client: AWS CRT-based S3 client.

  • Your application transfers large objects (> 8MB) and you want maximized performance.

  • You want to upload objects with unknown content length.

  • You want enhanced connection pooling and DNS load balancing, which improves throughput and performance.

  • You want improved transfer reliability in the event of a network failure. Individual failed parts are retried without restarting the transfer from the beginning.

Java-based S3 async client with multipart enabled

Interface: S3AsyncClient

Builder: S3AsyncClientBuilder

  • Provides an asynchronous API.

  • Supports automatic parallel transfers (multipart) when you enable multipart at creation time.

See Configure the Java-based S3 async client to use parallel transfers.

  • Your application transfers large objects and you want improved performance.

  • you want to upload object with unknown content length.

  • You want improved transfer reliability in the event of a network failure. Individual failed parts are retried without restarting the transfer from the beginning.

  • You need configuration options that are not available with the AWS CRT-based S3 client.

 Less performant than the AWS CRT-based S3 client.

Java-based S3 async client without multipart enabled

Interface: S3AsyncClient

Builder: S3AsyncClientBuilder

  • Provides an asynchronous API.

  • You are transferring objects that are less than 8MB.

  • You want an asynchronous API.

No performance optimization.

Java-based S3 sync client

Interface: S3Client

Builder: S3ClientBuilder

  • Provides a synchronous API.

  • You are transferring objects that are less than 8MB.

  • You want a synchronous API.

No performance optimization.
Note

From version 2.18.x and onward, the AWS SDK for Java 2.x uses virtual hosted-style addressing when including an endpoint override. This applies as long as the bucket name is a valid DNS label.

Call the forcePathStyle method with true in your client builder to force the client to use path-style addressing for buckets.

The following example shows a service client configured with an endpoint override and using path-style addressing.

S3Client client = S3Client.builder()
                          .region(Region.US_WEST_2)
                          .endpointOverride(URI.create("https://s3.us-west-2.amazonaws.com"))
                          .forcePathStyle(true)
                          .build();
Topics