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

The AWS SDK for Java 1.x entered maintenance mode on July 31, 2024. We recommend that you migrate to the AWS SDK for Java 2.x to access new features, enhanced performance, and continued support from AWS. We understand our customers’ time is valuable, and we’ve heard customers want simpler ways to migrate. That’s why we are releasing a preview of a migration tool that assists developers in their transition to the AWS SDK Java v2. The migration tool uses OpenRewrite, an open source automated code refactoring tool, to upgrade supported 1.x code to 2.x code.

This release provides code transformation support for all service SDK clients except AmazonS3Client and high level functionalities such as TransferManager and DynamoDBMapper. We are publishing a preview release to enable customers to start using it, as it can help reduce the cost of migration. At the same time, we are actively working on expanding the number of supported workflows. See the end of this post for the list of features that haven’t yet made it into the tool at the time of this writing. For assistance with migration for those features, check out our migration guide.

In this blog post, we will demonstrate the convenience of using the migration tool to begin migrating your application to 2.x.

Getting Started

Maven project

For a Maven project, we will use the OpenRewrite Maven 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: 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. Note that you need to replace ${sdkversion} with an SDK version. See Maven Central to find the latest version.

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

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.

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:run \
  -Drewrite.recipeArtifactCoordinates=software.amazon.awssdk:v2-migration:{sdkversion} \
  -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2

After you run the command, compile your application and run tests to verify the changes.

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:latest.release")
    }
}

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

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

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

gradle rewriteRun --init-script init.gradle \ 
  -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2

Current Limitations

The current preview release doesn’t have support for every feature in the SDK. We are planning to add more support in the near future.

The following features are not supported yet:

S3 Client (partial support for putObject and getObject)
S3 Transfer Manager
S3 URI Parsing
DynamoDB object mapper
EC2 metadata utility
Waiters
IAM Policy Builder
CloudFront presigning
SDK metric publishing
S3 Event Notification

Conclusion

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

AWS Developer Tools Blog

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

Getting Started

Maven project

Step 1: go to the project directory

Step 2: run the rewrite command

Gradle project

Step 1: go to the project directory

Step 2: create a Gradle init script

Step 3: run the rewrite command

Current Limitations

Conclusion

Resources

Follow

Step 2: run the `rewrite` command

Step 3: run the `rewrite` command