What's Different between the SDK for Java 1.11.x and 2.x
This section describes the main changes to be aware of when converting an application from using the AWS SDK for Java version 1.11.x to version 2.x.
High-Level Libraries
High-level libraries, such as the Amazon S3 Transfer Manager and the Amazon SQS Client-side
Buffering, are
not yet available in version 2.x. See the AWS SDK for Java 2.x changelog
If your application depends on these libraries, see Side by Side to learn how to configure your pom.xml to use both 1.11.x and
2.x. Refer to the SDK for Java 2.x changelog
Adding Version 2.x to Your Project
Maven is the recommended way to manage dependencies when using the AWS SDK for Java 2.x. To add version 2 components to your project, simply update your pom.xml file with a dependency on the SDK.
<dependencyManagement> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>bom</artifactId> <version>2.x.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>dynamodb</artifactId> </dependency> </dependencies>
Client Builders
You must create all clients using the client builder method. Constructors are no longer available.
Example of creating a client in version 1.x
AmazonDynamoDB ddbClient = AmazonDynamoDBClientBuilder.defaultClient(); AmazonDynamoDBClient ddbClient = new AmazonDynamoDBClient();
Example of creating a client in version 2.x
DynamoDbClient ddbClient = DynamoDbClient.create(); DynamoDbClient ddbClient = DynamoDbClient.builder().build();
Client Configuration
In 1.11.x, SDK client configuration was modified by setting a
ClientConfiguration
instance on the client or client builder. In
version 2.x, the client configuration is split into separate configuration classes.
The separate configuration classes enable you to configure different HTTP clients
for async versus synchronous clients
but still use the same ClientOverrideConfiguration
class.
Example of client configuration in Version 1.x
AmazonDynamoDBClientBuilder.standard() .withClientConfiguration(clientConfiguration) .build()
Example of synchronous client configuration in version 2.x
ProxyConfiguration.Builder proxyConfig = ProxyConfiguration.builder(); ApacheHttpClient.Builder httpClientBuilder = ApacheHttpClient.builder() .proxyConfiguration(proxyConfig.build()); ClientOverrideConfiguration.Builder overrideConfig = ClientOverrideConfiguration.builder(); DynamoDbClient client = DynamoDbClient.builder() .httpClientBuilder(httpClientBuilder) .overrideConfiguration(overrideConfig.build()) .build();
Example of asynchronous client configuration in version 2.x
NettyNioAsyncHttpClient.Builder httpClientBuilder = NettyNioAsyncHttpClient.builder(); ClientOverrideConfiguration.Builder overrideConfig = ClientOverrideConfiguration.builder(); ClientAsyncConfiguration.Builder asyncConfig = ClientAsyncConfiguration.builder(); DynamoDbAsyncClient client = DynamoDbAsyncClient.builder() .httpClientBuilder(httpClientBuilder) .overrideConfiguration(overrideConfig.build()) .asyncConfiguration(asyncConfig.build()) .build();
For a complete mapping of client configuration methods between 1.11.x and 2.x, see
the
AWS SDK for Java 2.x changelog
Setter Methods
In the SDK for Java 2.x, setter method names don't include the "set" or "with" prefix. For example, *.withEndpoint() is now just *.endpoint().
Example of using setting methods in 1.x
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard() .withRegion("us-east-1") .build();
Example of using setting methods in 2.x
DynamoDbClient client = DynamoDbClient.builder() .region(Region.US_EAST_1) .build();
Class Names
All client class names are now fully camel cased and no longer prefixed by "Amazon".
These changes are aligned with names used in the AWS CLI. For a full list of client
name
changes, see the AWS SDK for Java 2.x changelog
Example of class names in 1.x
AmazonDynamoDB AWSACMPCAAsyncClient
Example of class names in 2.x
DynamoDbClient AcmAsyncClient
Region Class
The SDK for Java version 1.x had multiple Region
and Regions
classes, both in the core package and in many of the service packages.
Region
and Regions
classes in version 2.x are now
collapsed into one core class, Region
.
Example Region and Regions classes in 1.x
com.amazonaws.regions.Region com.amazonaws.regions.Regions com.amazonaws.services.ec2.model.Region
Example Region class in 2.x
software.amazon.awssdk.regions.Region
For more details about changes related to using the Region
class, see
Region Changes.
Immutable POJOs
Clients and operation request and response objects are now immutable and cannot be changed after creation. To reuse a request or response variable, you must build a new object to assign to it.
Example of updating a request object in 1.x
DescribeAlarmsRequest request = new DescribeAlarmsRequest(); DescribeAlarmsResult response = cw.describeAlarms(request); request.setNextToken(response.getNextToken());
Example of updating a request object in 2.x
DescribeAlarmsRequest request = DescribeAlarmsRequest.builder().build(); DescribeAlarmsResponse response = cw.describeAlarms(request); request = DescribeAlarmsRequest.builder() .nextToken(response.nextToken()) .build();
Streaming Operations
Streaming operations such as the Amazon S3
getObject
and
putObject
methods now support
non-blocking I/O. As a result, the request and response POJOs no longer take
InputStream
as a parameter. Instead
the request object accepts RequestBody
, which is a
stream of bytes. The asynchronous client accepts AsyncRequestBody
.
Example of Amazon S3 putObject operation in 1.x
s3client.putObject(BUCKET, KEY, new File(file_path));
Example of Amazon S3 putObject operation in 2.x
s3client.putObject(PutObjectRequest.builder() .bucket(BUCKET) .key(KEY) .build(), RequestBody.of(Paths.get("myfile.in")));
In parallel, the response object accepts ResponseTransformer
for
synchronous clients and AsyncResponseTransformer
for asynchronous
clients.
Example of Amazon S3 getObject operation in 1.x
S3Object o = s3.getObject(bucket, key); S3ObjectInputStream s3is = o.getObjectContent(); FileOutputStream fos = new FileOutputStream(new File(key));
Example of Amazon S3 getObject operation in 2.x
s3client.getObject(GetObjectRequest.builder().bucket(bucket).key(key).build(), ResponseTransformer.toFile(Paths.get("key")));
Exception Changes
Exception class names, and their structures and relationships, have also changed.
software.amazon.awssdk.core.exception.SdkException
is the new base
Exception
class that all the other exceptions extend.
For a full list of the 2.x exception class names mapped to the 1.11.x exceptions, see Exception Changes Details.
Service-Specific Changes
Amazon S3 Operation Name Changes
Many of the operation names for the Amazon S3 client have changed in the SDK for Java 2.x. In version 1.x, the Amazon S3 client is not generated directly from the service API. This results in inconsistency between the SDK operations and the service API. In version 2.x, we now generate the Amazon S3 client to be more consistent with the service API.
Example of Amazon S3 client operation in 1.x
changeObjectStorageClass
Example of Amazon S3 client operation in 2.x
copyObject
Example of Amazon S3 client operation in the Amazon S3 service API
CopyObject
For a full list of the operation name mappings, see the AWS SDK for Java 2.x changelog
Cross-Region Access
For security best practices, cross-region access is no longer supported for single clients.
In version 1.x, services such as Amazon S3, Amazon SNS, and Amazon SQS allowed access to resources across Region boundaries. This is no longer allowed in version 2.x using the same client. If you need to access a resource in a different region, you must create a client in that region and retrieve the resource using the appropriate client.