What's different between the AWS SDK for Java 1.x and 2.x (original) (raw)

This section describes the main changes to be aware of when converting an application from using the AWS SDK for Java version 1.x to version 2.x.

Package name change

A noticeable change from the SDK for Java 1.x to the SDK for Java 2.x is the package name change. Package names begin with software.amazon.awssdk in SDK 2.x, whereas the SDK 1.x uses com.amazonaws.

These same names differentiate Maven artifacts from SDK 1.x to SDK 2.x. Maven artifacts for the SDK 2.x use the software.amazon.awssdk groupId, whereas the SDK 1.x uses the com.amazonaws groupId.

There are a few times when your code requires a com.amazonaws dependency for a project that otherwise uses only SDK 2.x artifacts. One example of this is when you work with server-side AWS Lambda. This was shown in the Set up an Apache Maven project section earlier in this guide.

Note

Several package names in the SDK 1.x contain v2. The use ofv2 in this case usually means that code in the package is targeted to work with version 2 of the service.

Since the full package name begins with com.amazonaws, these are SDK 1.x components. Examples of these package names in the SDK 1.x are:

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.x components to your project, update your pom.xml file with a dependency on the SDK. 

<dependencyManagement>
    <dependencies>
        <dependency>
          <groupId>software.amazon.awssdk</groupId>
          <artifactId>bom</artifactId>
          <version>2.27.21</version>
          <type>pom</type>
          <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>dynamodb</artifactId>
    </dependency>
</dependencies>

You can also use version 1.x and 2.x side-by-side as you migrate your project to version 2.x.

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();

Setter and getter methods

In the AWS SDK for Java 2.x, setter method names don’t include theset or with prefix. For example, *.withEndpoint() is now *.endpoint().

Getter method names do not use the get prefix.

Example of using setter methods in 1.x
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard()
                .withRegion("us-east-1")
                .build();
Example of using setter methods in 2.x
DynamoDbClient client = DynamoDbClient.builder()
                .region(Region.US_EAST_1)
                .build();
Example of using getter methods in 1.x
String token = request.getNextToken();
Example of using getter methods in 2.x
String token = request.nextToken();

Model class names

Model class names that represent service responses end with Response in v2 instead of Result that v1 uses.

Example of class names that represent a response in v1
CreateApiKeyResult
AllocateAddressResult
Example of class names that represent a response in v2
CreateApiKeyResponse
AllocateAddressResponse

Migration status of libraries and utilities

SDK for Java libraries and utilities

The following table lists the migration status of libraries and utilities for the SDK for Java.

The following table lists libraries that are released separately but work with the SDK for Java 2.x.

1The encryption client for Amazon S3 is available by using the following Maven dependency.

<dependency>
    <groupId>software.amazon.encryption.s3</groupId>
    <artifactId>amazon-s3-encryption-client-java</artifactId>
    <version>3.x</version>
</dependency>

2The AWS Database Encryption Client for DynamoDB is available by using the following Maven dependency.

<dependency> 
    <groupId>software.amazon.cryptography</groupId>
    <artifactId>aws-database-encryption-sdk-dynamodb</artifactId>
    <version>3.x</version>
</dependency>

Migration details for libraries and utilities