# AWS SDK for Java migration tool The AWS SDK for Java provides a migration tool that helps automate the migration of SDK for Java 1.x (V1) code to 2.x (V2). The tool uses [OpenRewrite](https://docs.openrewrite.org/)—an open source, source code refactoring tool—to perform the migration. OpenRewrite uses code modification rules (called "recipes") to automatically update your source code from V1 to V2 syntax and patterns. The tool supports code modification rules for SDK service clients and the [S3 Transfer Manager](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/transfer/TransferManager.html) high-level library. Code modification rules for other high-level APIs such as V1's [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html) to V2's [DynamoDB Enhanced Client API](dynamodb-enhanced-client.md) are not supported. For more details on limitations, see the [end of this page](#migration-tool-limitations). For detailed examples of common unsupported code patterns with manual migration steps, see [Unsupported code patterns](migration-tool-unsupported-patterns.md). ## Use the migration tool ### Migrate a Maven project Follow the instructions below to migrate your SDK for Java 1.x Maven-based project by using the [OpenRewrite Maven plugin](https://docs.openrewrite.org/reference/rewrite-maven-plugin) tool. 1. Navigate to your Maven project's root directory Open a terminal (command line) window and navigate to the root directory of your Maven-based application. 1. Run the plugin's `rewrite-maven-plugin` command You can choose from two modes (Maven goals): `dryRun` and `run`. **`dryRun`**** mode** In the `dryRun` mode, the plugin generates diff logs in the console output and a patch file named `rewrite.patch` in the `target/rewrite` folder. This mode allows you to preview the changes that would be made, since no changes are made to source code files. The following example show how to invoke the plugin in `dryRun` mode. ``` mvn org.openrewrite.maven:rewrite-maven-plugin:*:dryRun \ -Drewrite.recipeArtifactCoordinates=software.amazon.awssdk:v2-migration:** \ -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2 ``` \$1Replace ** with the `rewriteMavenPluginVersion` value that you see in this [test file](https://github.com/aws/aws-sdk-java-v2/blob/3a01289246f1f4ac814a354051d00030e53ef968/test/v2-migration-tests/src/test/java/software/amazon/awssdk/v2migrationtests/MavenTestBase.java#L54). \$1\$1Replace ** with a 2.x SDK version. Visit [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/v2-migration) to check for the latest version. **Important** Be sure to use the version of the `rewrite-maven-plugin` shown in the [test file](https://github.com/aws/aws-sdk-java-v2/blob/3a01289246f1f4ac814a354051d00030e53ef968/test/v2-migration-tests/src/test/java/software/amazon/awssdk/v2migrationtests/MavenTestBase.java#L54) because other versions may not work. Your console output from the `dryRun` mode should resemble the following output. ``` [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`**** mode** When you run the plugin in `run` mode, it modifies the source code on disk to apply the changes. Make sure you have a backup of the source code before running the command. The following example show how to invoke the plugin in `run` mode. ``` mvn org.openrewrite.maven:rewrite-maven-plugin:*:run \ -Drewrite.recipeArtifactCoordinates=software.amazon.awssdk:v2-migration:** \ -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2 ``` \$1Replace ** with the `rewriteMavenPluginVersionvalue` that you see in this [test file](https://github.com/aws/aws-sdk-java-v2/blob/3a01289246f1f4ac814a354051d00030e53ef968/test/v2-migration-tests/src/test/java/software/amazon/awssdk/v2migrationtests/MavenTestBase.java#L54). \$1\$1Replace ** with a 2.x SDK version. Visit [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/v2-migration) to check for the latest version. After you run the command, compile your application and run tests to verify the changes. ### Migrate a Gradle project Follow the instructions below to migrate your SDK for Java 1.x Gradle-based project by using the [OpenRewrite Gradle plugin](https://docs.openrewrite.org/reference/gradle-plugin-configuration) tool. 1. Navigate to your Gradle project's root directory Open a terminal (command line) window and navigate to the root directory of your Gradle-based application. 1. Create a Gradle init script Create a `init.gradle` file with the following content in the directory. ``` initscript { repositories { maven { url "https://plugins.gradle.org/m2" } } dependencies { classpath("org.openrewrite:plugin:*") } } rootProject { plugins.apply(org.openrewrite.gradle.RewritePlugin) dependencies { rewrite("software.amazon.awssdk:v2-migration:latest.release") } afterEvaluate { if (repositories.isEmpty()) { repositories { mavenCentral() } } } } ``` \$1Replace ** with the version that you see in this [test file](https://github.com/aws/aws-sdk-java-v2/blob/master/test/v2-migration-tests/src/test/resources/software/amazon/awssdk/v2migrationtests/gradle/before/init.gradle#L6). 1. Run the `rewrite` command As with the Maven plugin, you can run the Gradle plugin in `dryRun` or `run` mode. **`dryRun` mode** The following example show how to invoke the plugin in `dryRun` mode. ``` gradle rewriteDryRun --init-script init.gradle \ -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2 ``` **`run` mode** The following example show how to invoke the plugin in `run` mode. ``` gradle rewriteRun --init-script init.gradle \ -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2 ``` ## Current limitations While the migration upports most V1 code through code modification rules that update to the V2 equivalent, some classes and methods aren't covered. For these classes and methods, follow the [step-by-step instructions](migration-steps.md) to manually migrate your code. For some unsupported code modification rules, the migration tool may add a comment that begins with: ``` /*AWS SDK for Java v2 migration: Transform for ... ``` Following the comment, the tool outputs a generic stub of the V2 version of the method or class. For example, in the following output, the migration tool attempted to migrate the V1 S3 client's `setBucketLifecycleConfiguration` method: ``` /*AWS SDK for Java v2 migration: Transform for setBucketLifecycleConfiguration method not supported. Please manually migrate your code by using builder pattern, update from BucketLifecycleConfiguration.Rule to LifecycleRule, StorageClass to TransitionStorageClass, and adjust imports and names.*/ s3.putBucketLifecycleConfiguration( PutBucketLifecycleConfigurationRequest.builder() .bucket(bucketName) .lifecycleConfiguration(BucketLifecycleConfiguration.builder() .build()) .build()); ``` The links in the list below, take you to migration information to help you manually migrate the code. + [S3 client differences between version 1 and version 2 of the AWS SDK for Java](migration-s3-client.md) + [S3 Transfer Manager](migration-s3-transfer-manager.md) (TransferManager) + [DynamoDB object mapping](migration-ddb-mapper.md) (DynamoDBMapper) + [EC2 metadata utility](migration-imds.md) (EC2MetadataUtils) + [Waiters](migration-waiters.md) (AmazonDynamoDBWaiters) + [IAM Policy Builder](migration-iam-policy-builder.md) (Policy) + [CloudFront presigning](migration-cloudfront-presigning.md) (CloudFrontUrlSigner, CloudFrontCookieSigner) + [S3 Event Notifications](migration-s3-event-notification.md) (S3EventNotification) + SDK metric publishing ([1.x documentation](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/generating-sdk-metrics.html), [2.x documentation](metrics.md)) + [Unsupported code patterns](migration-tool-unsupported-patterns.md)–Detailed examples of common code patterns that require manual migration # Unsupported code patterns of the migration tool The migration tool automatically converts most v1 code to v2. However, some code patterns require manual migration. This topic provides detailed examples of the most common unsupported patterns and shows you how to manually convert them. The following list of patterns is not exhaustive. If your code doesn't compile after running the migration tool, follow the [step-by-step migration instructions](migration-steps.md) to manually migrate the remaining v1 code. ## Request object constructors with parameters For request POJOs (excluding Amazon S3), the migration tool transforms only setter methods. The tool does not support constructors with parameters. **Supported pattern: Request object using setters (no constructor parameters)** Before (original v1 code): ``` import com.amazonaws.services.sqs.model.SendMessageRequest; SendMessageRequest request = new SendMessageRequest().withMessageBody("Hello World"); request.setQueueUrl("https://sqs.us-west-2.amazonaws.com/0123456789012/demo-queue"); ``` After (migration tool result): ``` import software.amazon.awssdk.services.sqs.model.SendMessageRequest; SendMessageRequest request = SendMessageRequest.builder() .messageBody("Hello World").build(); request = request.toBuilder() .queueUrl("https://sqs.us-west-2.amazonaws.com/0123456789012/demo-queue").build(); ``` **Unsupported pattern: Request object constructor with parameters** The migration tool cannot convert constructors with parameters: Before manual migration, but after migration tool: ``` import software.amazon.awssdk.services.sqs.model.SendMessageRequest; // Import updated to v2. // This pattern requires manual migration. SendMessageRequest request = new SendMessageRequest( "https://sqs.us-west-2.amazonaws.com/0123456789012/demo-queue", "Hello World"); ``` The migration tool transforms the import to v2, but the constructor code remains unchanged and requires manual updates to use the builder pattern. After manual migration: ``` import software.amazon.awssdk.services.sqs.model.SendMessageRequest; SendMessageRequest request = SendMessageRequest.builder() .messageBody("Hello World") .queueUrl("https://sqs.us-west-2.amazonaws.com/0123456789012/demo-queue") .build(); ``` ## Service client methods with individual parameters The migration tool cannot convert service client methods that take individual parameters instead of request objects (excluding Amazon S3). Before (v1 code): ``` import com.amazonaws.services.sqs.AmazonSQS; import com.amazonaws.services.sqs.AmazonSQSClient; AmazonSQS sqs = new AmazonSQSClient(); // The following v1 method takes individual parameters. sqs.sendMessage("https://sqs.us-west-2.amazonaws.com/0123456789012/demo-queue", "Hello World"); ``` After (migration tool result–does not compile): ``` import software.amazon.awssdk.services.sqs.SqsClient; // Import updated to v2. // No import statement for the v2 request POJO. SqsClient sqs = SqsClient.builder().build(); // Does not compile–v2 methods only accept request POJOs. sqs.sendMessage("https://sqs.us-west-2.amazonaws.com/0123456789012/demo-queue", "Hello World"); ``` You must manually update the method arguments to use a request object: ``` import software.amazon.awssdk.services.sqs.SqsClient; import software.amazon.awssdk.services.sqs.model.SendMessageRequest; // Add manually. SqsClient sqs = SqsClient.builder().build(); // Corrected v2 code. SendMessageRequest request = SendMessageRequest.builder() .queueUrl("https://sqs.us-west-2.amazonaws.com/0123456789012/demo-queue") .messageBody("Hello World") .build(); sqs.sendMessage(request); ``` ## Request timeout methods The migration tool does not convert methods that set timeouts on request objects. Before (v1 code): ``` import com.amazonaws.services.sqs.model.SendMessageRequest; SendMessageRequest request = new SendMessageRequest(); request.setSdkRequestTimeout(7); ``` After (migration tool result–does not compile): ``` import software.amazon.awssdk.services.sqs.model.SendMessageRequest; // Import updated to v2. SendMessageRequest request = SendMessageRequest.builder().build(); // Does not compile. request.setSdkRequestTimeout(7); ``` You must manually migrate to use v2's `overrideConfiguration` method: ``` import software.amazon.awssdk.services.sqs.model.SendMessageRequest; import java.time.Duration; SendMessageRequest request = SendMessageRequest.builder().build(); // Corrected v2 code. request = request.toBuilder() .overrideConfiguration(o -> o.apiCallTimeout(Duration.ofSeconds(7))) .build(); ``` ## Service client constructors with parameters The migration tool converts empty service client constructors but cannot convert constructors that accept parameters like credentials or configuration. Before (v1 code): ``` import com.amazonaws.auth.AWSCredentials; import com.amazonaws.auth.BasicAWSCredentials; import com.amazonaws.services.sqs.AmazonSQS; import com.amazonaws.services.sqs.AmazonSQSClient; AWSCredentials awsCredentials = new BasicAWSCredentials("akid", "skid"); AmazonSQS sqs = new AmazonSQSClient(awsCredentials); ``` After (migration tool result–does not compile): ``` import software.amazon.awssdk.auth.credentials.AwsCredentials; import software.amazon.awssdk.auth.credentials.AwsBasicCredentials; import software.amazon.awssdk.services.sqs.SqsClient; // Import updated to v2. AwsCredentials awsCredentials = AwsBasicCredentials.create("akid", "skid"); // Does not compile. SqsClient sqs = new SqsClient(awsCredentials); ``` You must manually update the service client constructor to use the builder pattern: ``` import software.amazon.awssdk.auth.credentials.AwsCredentials; import software.amazon.awssdk.auth.credentials.AwsBasicCredentials; import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider; // Add manually. import software.amazon.awssdk.services.sqs.SqsClient; AwsCredentials awsCredentials = AwsBasicCredentials.create("akid", "skid"); // Corrected v2 code. SqsClient sqs = SqsClient.builder() .credentialsProvider(StaticCredentialsProvider.create(awsCredentials)) .build(); ```