AWS SDK for Java 移行ツール

AWS SDK for Java は、SDK for Java 1.x (V1) コードの 2.x (V2) への移行を自動化する移行ツールを提供します。このツールは、オープンソースのソースコードリファクタリングツールである OpenRewrite を使用して移行を実行します。OpenRewrite はコード変更ルール (「レシピ」と呼ばれます) を使用して、ソースコードを V1 から V2 の構文とパターンに自動的に更新します。

このツールは、SDK サービスクライアントと S3 Transfer Manager の高レベルライブラリのコード変更ルールをサポートしています。V1 の DynamoDBMapper から V2 の DynamoDB 拡張クライアント API など、他の高レベル API のコード変更ルールはサポートされていません。

制限の詳細については、このページの最後の部分を参照してください。サポートされていない一般的なコードパターンの詳細と手動による移行手順については、「サポートされていないコードパターン」を参照してください。

移行ツールを使用する

Maven プロジェクトを移行する

OpenRewrite Maven プラグインツールを使用して SDK for Java 1.x Maven ベースのプロジェクトを移行するには、次の手順に従ってください。

Maven プロジェクトのルートディレクトリに移動します。

ターミナル (コマンドライン) ウィンドウを開き、Maven ベースのアプリケーションのルートディレクトリに移動します。

プラグインの rewrite-maven-plugin コマンドを実行する

dryRun と run の、2 つのモード (Maven の目標) から選択できます。

dryRun モード

dryRun モードでは、プラグインはコンソール出力に差分ログを生成し、 target/rewrite フォルダに rewrite.patch という名前のパッチファイルを生成します。このモードでは、ソースコードファイルに変更を加えないため、どのような変更が行われるかをプレビューできます。

次の例は、dryRun モードでプラグインを呼び出す方法を示しています。


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

*<rewrite-plugin-version> を、このテストファイルに表示される rewriteMavenPluginVersion 値に置き換えます。

**<sdkversion> を 2.x SDK バージョンに置き換えます。Maven Central に移動し、最新バージョンを確認します。

重要

他のバージョンでは機能しない可能性があるため、テストファイルに表示される rewrite-maven-plugin のバージョンを使用してください。

dryRun モードからのコンソール出力は次のようになります。


[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 モード

プラグインを run モードで実行すると、ディスク上のソースコードが変更され、変更が適用されます。コマンドを実行する前に、ソースコードのバックアップがあることを確認してください。

次の例は、run モードでプラグインを呼び出す方法を示しています。


mvn org.openrewrite.maven:rewrite-maven-plugin:<rewrite-plugin-version>*:run \
  -Drewrite.recipeArtifactCoordinates=software.amazon.awssdk:v2-migration:<sdkversion>** \
  -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2

*<rewrite-plugin-version> を、このテストファイルに表示される rewriteMavenPluginVersionvalue に置き換えます。

**<sdkversion> を 2.x SDK バージョンに置き換えます。Maven Central に移動し、最新バージョンを確認します。

コマンドを実行したら、アプリケーションをコンパイルし、テストを実行して変更を検証します。

Gradle プロジェクトの移行

OpenRewrite Gradle プラグインツールを使用して SDK for Java 1.x Gradle ベースのプロジェクトを移行するには、次の手順に従ってください。

プロジェクトのルートディレクトリに移動します。

ターミナル (コマンドライン) ウィンドウを開き、Gradle ベースのアプリケーションのルートディレクトリに移動します。

Gradle init スクリプトを作成する

ディレクトリに次の内容で init.gradle ファイルを作成します。


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

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

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

*<rewrite-plugin-version> を、このテストファイルに表示されるバージョンに置き換えます。

rewrite コマンドの実行

Maven プラグインと同様に、Gradle プラグインを dryRun または run モードで実行できます。

dryRun モード

次の例は、dryRun モードでプラグインを呼び出す方法を示しています。
```
gradle rewriteDryRun --init-script init.gradle \
  -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2
```
run モード

次の例は、run モードでプラグインを呼び出す方法を示しています。
```
gradle rewriteRun --init-script init.gradle \
  -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2
```

現在の制限事項

移行では、コード変更ルールによってほとんどの V1 コードを V2 の同等コードに移行できますが、一部のクラスとメソッドは移行できません。これらのクラスとメソッドについては、ステップバイステップの手順に従って、コードを手動で移行します。

サポートされていないコード変更ルールによっては、移行ツールに次の文で始まるコメントが表示される場合があります。


/*AWS SDK for Java v2 migration: Transform for ...

コメントの後、ツールにはメソッドまたはクラスの V2 バージョンの汎用スタブが出力されます。たとえば、次の出力では、移行ツールが V1 S3 クライアントの setBucketLifecycleConfiguration メソッドの移行を試行しました。


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

以下のリストから、コードを手動で移行するための移行情報に移動できます。

AWS SDK for Java のバージョン 1 とバージョン 2 の S3 クライアントの違い
S3 Transfer Manager (TransferManager)
DynamoDB オブジェクトマッピング (DynamoDBMapper)
EC2 メタデータユーティリティ (EC2MetadataUtils)
ウェイター (AmazonDynamoDBWaiters)
IAM Policy Builder (Policy)
CloudFront 事前署名 (CloudFrontUrlSigner、CloudFrontCookieSigner)
S3 イベント通知 (S3EventNotification)
SDK メトリクスの公開 (1.x ドキュメント、2.x ドキュメント)
サポートされていないコードパターン – 手動移行を必要とする一般的なコードパターンの詳細な例

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

移行方法

サポートされていないコードパターン