Usar a ferramenta de migração Limitações atuais

Ferramenta de migração do AWS SDK para Java

O AWS SDK para Java fornece uma ferramenta de migração que ajuda a automatizar a migração do código do SDK para Java 1.x (V1) para 2.x (V2). A ferramenta usa o OpenRewrite, uma ferramenta de refatoração de código-fonte e código aberto, para fazer a migração. O OpenRewrite usa regras de modificação de código (chamadas de “receitas”) para atualizar automaticamente o código-fonte da sintaxe e dos padrões da V1 para a V2.

A ferramenta permite regras de modificação de código para clientes de serviços do SDK e para a biblioteca de alto nível do Gerenciador de Transferências do S3. As regras de modificação de código para outras APIs de alto nível, como da V1 da API DynamoDBMapper para a V2 da API de cliente avançado do DynamoDB não são compatíveis.

Consulte mais detalhes sobre limitações no final desta página. Consulte exemplos detalhados de padrões de código comuns sem suporte com etapas de migração manual em Padrões de código sem suporte.

Usar a ferramenta de migração

Migrar um projeto Maven

Siga as instruções abaixo para migrar seu projeto baseado no Maven do SDK para Java 1.x usando a ferramenta de plug-in OpenRewrite Maven.

Acesse o diretório-raiz do projeto Maven

Abra uma janela de terminal (linha de comando) e acesse o diretório-raiz da aplicação baseada no Maven.

Execute o comando rewrite-maven-plugin do plugin

É possível escolher entre dois modos (metas do Maven): dryRun e run.

dryRun Modo

No modo dryRun, o plug-in gera logs de diferenças na saída do console e um arquivo de patch chamado rewrite.patch na pasta target/rewrite. Esse modo permite que você visualize as alterações que seriam feitas, já que nenhuma alteração é feita nos arquivos de código-fonte.

O exemplo a seguir mostra como invocar o plug-in no modo 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

*Substitua <rewrite-plugin-version> pelo valor de rewriteMavenPluginVersion exibido neste arquivo de teste.

**Substitua <sdkversion> por uma versão 2.x do SDK. Confira a versão mais recente em Maven Central.

Importante

Use a versão de rewrite-maven-plugin mostrada no arquivo de teste, pois outras versões podem não funcionar.

A saída do console do modo dryRun deve ser semelhante à saída a seguir.


[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 Modo

Quando você executa o plug-in no modo run, ele modifica o código-fonte no disco para aplicar as alterações. Faça backup do código-fonte antes de executar o comando.

O exemplo a seguir mostra como invocar o plug-in no modo 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

*Substitua <rewrite-plugin-version> pelo rewriteMavenPluginVersionvalue exibido neste arquivo de teste.

**Substitua <sdkversion> por uma versão 2.x do SDK. Confira a versão mais recente em Maven Central.

Depois de executar o comando, faça uma compilação da aplicação e realize testes para verificar as alterações.

Migrar um projeto Gradle

Siga as instruções abaixo para migrar seu projeto baseado no Gradle do SDK para Java 1.x usando a ferramenta de plug-in OpenRewrite Gradle.

Acesse o diretório-raiz do projeto Gradle

Abra uma janela de terminal (linha de comando) e acesse o diretório-raiz da aplicação baseada no Gradle.

Criar um script de inicialização do Gradle

Crie um arquivo init.gradle com o conteúdo a seguir no diretório.


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

*Substitua <rewrite-plugin-version> pela versão exibida neste arquivo de teste.

Execute o comando rewrite

Assim como no plug-in Maven, você pode executar o plug-in Gradle no modo dryRun or run.

Modo dryRun

O exemplo a seguir mostra como invocar o plug-in no modo dryRun.


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

Modo run

O exemplo a seguir mostra como invocar o plug-in no modo run.


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

Limitações atuais

Embora a migração seja compatível com a maioria dos códigos da V1 por meio de regras de modificação de código que são atualizadas para o equivalente da V2, algumas classes e métodos não são abordados. Referente a essas classes e métodos, siga as instruções passo a passo para migrar o código manualmente.

Para algumas regras de modificação de código incompatíveis, a ferramenta de migração pode adicionar um comentário que comece com:


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

Após o comentário, a ferramenta gera um esboço genérico da versão V2 do método ou da classe. Por exemplo, na saída a seguir, a ferramenta de migração tentou migrar o método setBucketLifecycleConfiguration do cliente V1 do S3:


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

Os links na lista abaixo abrem informações de migração para ajudar você a migrar o código manualmente.

Diferenças do clientes do S3 entre a versão 1 e a versão 2 do AWS SDK para Java
Gerenciador de Transferências do S3 (TransferManager)
Mapeamento de objetos do DynamoDB (DynamoDBMapper)
Utilitário de metadados do EC2 (EC2MetadataUtils)
Waiters (AmazonDynamoDBWaiters)
Compilador de Políticas do IAM (Policy)
Pré-assinatura do CloudFront (CloudFrontUrlSigner, CloudFrontCookieSigner)
Notificações de Eventos do S3 (S3EventNotification)
Publicação de métricas do SDK (documentação da 1.x, documentação da 2.x)
Padrões de código incompatíveis: exemplos detalhados de padrões de código comuns que exigem migração manual

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Como migrar

Padrões de código do incompatíveis