AWS Developer Tools Blog

General Availability Release of the Migration Tool for the AWS SDK for Java 2.x

The AWS SDK for Java 1.x (v1) entered maintenance mode on July 31, 2024, and will reach end-of-support on December 31, 2025. We recommend that you migrate to the AWS SDK for Java 2.x (v2) to access new features, enhanced performance, and continued support from AWS. To help you migrate efficiently, we’ve created a migration tool that automates much of the transition process. This tool uses OpenRewrite, an open source automated code refactoring tool, to upgrade supported 1.x code to 2.x code.

You can now transform code for all service SDK clients as well as the Amazon Simple Storage Service (S3) TransferManager high-level library. The migration tool doesn’t support transforms for other high-level APIs such as DynamoDBMapper. These unsupported transforms require manual migration. For assistance with migration for those features, check out our migration guide.

In this blog post, we demonstrate the convenience of using the migration tool to begin migrating your application to 2.x, and call out limitations you may run into.

Getting started

Maven project

For a Maven project, we will use the OpenRewrite Maven plugin.

Step 1: navigate to your project directory

Open a terminal (command line) window and go to the root directory of your application.

Step 2: run the rewrite command

There are two modes you can choose: dryRun and run.

  • dryRun

In this mode, the plugin generates diff logs in the console and a patch file rewrite.patch in the target/rewrite folder. This mode does not modify the source code, so it is helpful to preview the changes that would be made.

mvn org.openrewrite.maven:rewrite-maven-plugin:${maven-plugin-version}*:dryRun \
  -Drewrite.recipeArtifactCoordinates=software.amazon.awssdk:v2-migration:${sdkversion}** \
  -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2

*Replace ${maven-plugin-version} with the latest SDK-tested version (6.17.0 at the time of GA release), as specified in the SDK Maven test configuration.
**Replace ${sdkversion} with SDK version 2.34.0 or newer. See Maven Central to find the latest version.

Your output will resemble the following:

[WARNING] These recipes would make changes to project/src/test/resources/maven/before/pom.xml:
[WARNING]     software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2
[WARNING]         software.amazon.awssdk.v2migration.UpgradeSdkDependencies
[WARNING]             org.openrewrite.java.dependencies.AddDependency: {groupId=software.amazon.awssdk, artifactId=apache-client, version=2.27.0, onlyIfUsing=com.amazonaws.ClientConfiguration}
[WARNING]             org.openrewrite.java.dependencies.AddDependency: {groupId=software.amazon.awssdk, artifactId=netty-nio-client, version=2.27.0, onlyIfUsing=com.amazonaws.ClientConfiguration}
[WARNING]             org.openrewrite.java.dependencies.ChangeDependency: {oldGroupId=com.amazonaws, oldArtifactId=aws-java-sdk-bom, newGroupId=software.amazon.awssdk, newArtifactId=bom, newVersion=2.27.0}
[WARNING]             org.openrewrite.java.dependencies.ChangeDependency: {oldGroupId=com.amazonaws, oldArtifactId=aws-java-sdk-s3, newGroupId=software.amazon.awssdk, newArtifactId=s3, newVersion=2.27.0}
[WARNING]             org.openrewrite.java.dependencies.ChangeDependency: {oldGroupId=com.amazonaws, oldArtifactId=aws-java-sdk-sqs, newGroupId=software.amazon.awssdk, newArtifactId=sqs, newVersion=2.27.0}
[WARNING] These recipes would make changes to project/src/test/resources/maven/before/src/main/java/foo/bar/Application.java:
[WARNING]     software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2
[WARNING]         software.amazon.awssdk.v2migration.S3GetObjectConstructorToFluent
[WARNING]             software.amazon.awssdk.v2migration.ConstructorToFluent
[WARNING]         software.amazon.awssdk.v2migration.S3StreamingResponseToV2
[WARNING]         software.amazon.awssdk.v2migration.ChangeSdkType
[WARNING]         software.amazon.awssdk.v2migration.ChangeSdkCoreTypes
[WARNING]             software.amazon.awssdk.v2migration.ChangeExceptionTypes
[WARNING]                 org.openrewrite.java.ChangeType: {oldFullyQualifiedTypeName=com.amazonaws.AmazonClientException, newFullyQualifiedTypeName=software.amazon.awssdk.core.exception.SdkException}
[WARNING]                 org.openrewrite.java.ChangeMethodName: {methodPattern=com.amazonaws.AmazonServiceException getRequestId(), newMethodName=requestId}
[WARNING]                 org.openrewrite.java.ChangeMethodName: {methodPattern=com.amazonaws.AmazonServiceException getErrorCode(), newMethodName=awsErrorDetails().errorCode}
[WARNING]                 org.openrewrite.java.ChangeMethodName: {methodPattern=com.amazonaws.AmazonServiceException getServiceName(), newMethodName=awsErrorDetails().serviceName}
[WARNING]                 org.openrewrite.java.ChangeMethodName: {methodPattern=com.amazonaws.AmazonServiceException getErrorMessage(), newMethodName=awsErrorDetails().errorMessage}
[WARNING]                 org.openrewrite.java.ChangeMethodName: {methodPattern=com.amazonaws.AmazonServiceException getRawResponse(), newMethodName=awsErrorDetails().rawResponse().asByteArray}
[WARNING]                 org.openrewrite.java.ChangeMethodName: {methodPattern=com.amazonaws.AmazonServiceException getRawResponseContent(), newMethodName=awsErrorDetails().rawResponse().asUtf8String}
[WARNING]                 org.openrewrite.java.ChangeType: {oldFullyQualifiedTypeName=com.amazonaws.AmazonServiceException, newFullyQualifiedTypeName=software.amazon.awssdk.awscore.exception.AwsServiceException}
[WARNING]         software.amazon.awssdk.v2migration.NewClassToBuilderPattern
[WARNING]             software.amazon.awssdk.v2migration.NewClassToBuilder
[WARNING]             software.amazon.awssdk.v2migration.V1SetterToV2
[WARNING]         software.amazon.awssdk.v2migration.V1GetterToV2
...
[WARNING]         software.amazon.awssdk.v2migration.V1BuilderVariationsToV2Builder
[WARNING]         software.amazon.awssdk.v2migration.NewClassToBuilderPattern
[WARNING]             software.amazon.awssdk.v2migration.NewClassToBuilder
[WARNING]             software.amazon.awssdk.v2migration.V1SetterToV2
[WARNING]         software.amazon.awssdk.v2migration.HttpSettingsToHttpClient
[WARNING]         software.amazon.awssdk.v2migration.WrapSdkClientBuilderRegionStr
[WARNING] Patch file available:
[WARNING]     project/src/test/resources/maven/before/target/rewrite/rewrite.patch
[WARNING] Estimate time saved: 20m
[WARNING] Run 'mvn rewrite:run' to apply the recipes.
  • run

In this mode, the plugin modifies the source code on disk to apply the changes directly. Make sure you have a backup of the source code before running the command.

mvn org.openrewrite.maven:rewrite-maven-plugin:6.17.0:run \
-Drewrite.recipeArtifactCoordinates=software.amazon.awssdk:v2-migration:2.34.0 \
-Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2

After you run the command, compile your application and run tests to verify the changes. Make manual changes as necessary for unsupported transforms. See the Limitations section below for further details.

Gradle project

For a Gradle project, we will use the OpenRewrite Gradle plugin.

Step 1: go to the project directory

Open a terminal (command line) window and go to the root directory of your application.

Step 2: create a Gradle init script

Create a init.gradle file with the following content in your root project directory:

initscript {
    repositories {
        maven { url "https://plugins.gradle.org/m2" }
    }
    dependencies {
        classpath("org.openrewrite:plugin:${gradle-plugin-version}*")
    }
}

rootProject {
    plugins.apply(org.openrewrite.gradle.RewritePlugin)
    dependencies {
        rewrite("software.amazon.awssdk:v2-migration:${sdkversion}")
    }

    afterEvaluate {
        if (repositories.isEmpty()) {
            repositories {
                mavenCentral()
            }
        }
    }
}

*Replace ${gradle-plugin-version} with with latest SDK-tested version (7.15.0 at the time of GA release), as specified in the SDK Gradle test configuration.

Step 3: run the rewrite command

As with the Maven plugin, you can perform dryRun or run.

  • dryRun
gradle rewriteDryRun --init-script init.gradle \
  -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2
  • run
gradle rewriteRun --init-script init.gradle \
  -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2

Limitations

While the majority of v1 code is supported by recipes that transform to the v2 equivalent, there are some classes and methods not covered by the migration tool. You should carefully review the transformed code after the tool applies the recipes. If your code does not compile after running the tool, follow the Step-by-step instructions to manually migrate the remaining v1 code.

Unsupported features

The following features are not covered by the migration tool and require manual migration:

Partially supported S3 transforms

The following S3 components are partially covered by the migration tool and may require manual migration:

Unsupported code patterns

There are common code patterns that the migration tool does not support, such as request object constructors with parameters, service client methods with individual parameters, request timeout methods, and service client constructors with parameters.

Example: Service client constructors with parameters

Empty service client constructors will be transformed to the v2 equivalent by the migration tool. However, service client constructors with parameters are not covered by the migration tool and require manual migration.

Before (original v1 code):

AWSCredentials awsCredentials = new BasicAWSCredentials("akid", "skid");
AmazonSQS sqs = new AmazonSQSClient(awsCredentials);

After (migration tool run):

AwsCredentials awsCredentials = AwsBasicCredentials.create("akid", "skid");
// Will not compile.
SqsClient sqs = new SqsClient(awsCredentials);

In this example, the majority of the v1 code (including imports) is correctly transformed to v2, with the exception of the SqsClient constructor, which requires manual updates to a Builder as shown in the following:

AwsCredentials awsCredentials = AwsBasicCredentials.create("akid", "skid");
// Proper v2 code - manually update.
SqsClient sqs = SqsClient.builder().credentialsProvider(StaticCredentialsProvider.create(awsCredentials));

Conclusion

In this blog post, we showed you how to get started with the migration tool and discussed its limitations. To learn more, visit our Developer Guide. We would love to hear your feedback! You can reach out to us by creating a GitHub issue.