Using the Amazon SDK for Java - Amazon Simple Storage Service
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).

Using the Amazon SDK for Java

The Amazon SDK for Java provides an API for the Amazon S3 bucket and object operations. For object operations, in addition to providing the API to upload objects in a single operation, the SDK provides an API to upload large objects in parts. For more information, see Uploading and copying objects using multipart upload.

The Amazon SDK for Java gives you the option of using a high-level or low-level API.

Low-Level API

The low-level APIs correspond to the underlying Amazon S3 REST operations, such as create, update, and delete operations that apply to buckets and objects. When you upload large objects using the low-level multipart upload API, it provides greater control. For example, it lets you pause and resume multipart uploads, vary part sizes during the upload, or begin uploads when you don't know the size of the data in advance. If you don't have these requirements, use the high-level API to upload objects.

High-Level API

For uploading objects, the SDK provides a higher level of abstraction by providing the TransferManager class. The high-level API is a simpler API, where in just a few lines of code you can upload files and streams to Amazon S3. You should use this API to upload data unless you need to control the upload as described in the preceding Low-Level API section.

For smaller data size, the TransferManager API uploads data in a single operation. However, the TransferManager switches to using the multipart upload API when the data size reaches a certain threshold. When possible, the TransferManager uses multiple threads to concurrently upload the parts. If a part upload fails, the API retries the failed part upload up to three times. However, these are configurable options using the TransferManagerConfiguration class.


When you're using a stream for the source of data, the TransferManager class does not do concurrent uploads.

The Java API Organization

The following packages in the Amazon SDK for Java provide the API:

  •—Provides the APIs for creating Amazon S3 clients and working with buckets and objects. For example, it enables you to create buckets, upload objects, get objects, delete objects, and list keys.

  •—Provides the high-level API data operations.

    This high-level API is designed to simplify transferring objects to and from Amazon S3. It includes the TransferManager class, which provides asynchronous methods for working with, querying, and manipulating transfers. It also includes the TransferManagerConfiguration class, which you can use to configure the minimum part size for uploading parts and the threshold in bytes of when to use multipart uploads.

  •—Provides the low-level API classes to create requests and process responses. For example, it includes the GetObjectRequest class to describe your get object request, the ListObjectsRequest class to describe your list keys requests, and the InitiateMultipartUploadRequest class to create multipart uploads.

For more information about the Amazon SDK for Java API, see Amazon SDK for Java API Reference.

Testing the Amazon S3 Java Code Examples

The Java examples in this guide are compatible with the Amazon SDK for Java version 1.11.321. For instructions on setting up and running code samples, see Getting Started in the Amazon SDK for Java Developer Guide.