Instruções passo a passo de migração com exemplo

Esta seção fornece um guia passo a passo para migrar a aplicação que atualmente usa o SDK para Java v1.x para o SDK para Java 2.x. A primeira parte apresenta uma visão geral das etapas seguidas por um exemplo detalhado de uma migração.

As etapas abordadas aqui descrevem a migração de um caso de uso normal, em que a aplicação chama Serviços da AWS usando clientes de serviço orientados por modelos. Se você precisar migrar código que usa APIs de nível superior, como o Gerenciador de Transferências do S3 ou a Pré-assinatura do CloudFront, consulte a seção O que é diferente entre o AWS SDK para Java 1.x e o 2.x no índice.

A abordagem descrita aqui é uma sugestão. Você pode usar outras técnicas e aproveitar os recursos de edição de código do IDE para alcançar o mesmo resultado.

Visão geral das etapas

1. Comece adicionando o BOM do SDK para Java 2.x

Ao adicionar o elemento BOM (Lista de materiais) do Maven para o SDK para Java 2.x ao arquivo POM, você garante que todas as dependências necessárias da v2 sejam da mesma versão. O POM pode conter dependências da v1 e da v2. Isso permite migrar o código de forma incremental em vez de alterá-lo de uma só vez.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>bom</artifactId>
      <version>2.27.21</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

2. Pesquisar arquivos para declarações de importação de classe da v1

Ao verificar os arquivos na aplicação em busca de SERVICE_IDs usados nas importações da v1, você encontrará os SERVICE_IDs exclusivos usados. Um SERVICE_ID é um nome curto e exclusivo de um AWS service (Serviço da AWS). Por exemplo, cognitoidentity é o SERVICE_ID do Amazon Cognito Identity.

3. Determine as dependências da v2 do Maven com base nas declarações de importação da v1

Depois de encontrar todos os SERVICE_IDs v1 exclusivos, você pode determinar o artefato do Maven correspondente para a dependência da v2 consultando Nome do pacote para mapeamentos de artifactId do Maven..

4. Adicionar elementos de dependência da v2 ao arquivo POM

Atualize o arquivo POM do Maven com os elementos de dependência determinados na etapa 3.

5. Nos arquivos Java, altere incrementalmente as classes da v1 para as classes da v2

Ao substituir as classes da v1 por classes da v2, faça as alterações necessárias para dar suporte à API da v2, como usar compiladores em vez de construtores e usar getters e setters fluentes.

6. Remova as dependências da v1 do Maven das importações do POM e da v1 dos arquivos

Depois de migrar o código para usar classes da v2, remova todas as importações da v1 restantes dos arquivos e todas as dependências do arquivo de compilação.

7. Refatorar o código para usar os aprimoramentos da API da v2

Depois que o código for compilado e aprovado nos testes, você poderá aproveitar os aprimoramentos da v2, como usar um cliente HTTP diferente ou paginadores para simplificar o código. Esta etapa é opcional.

Exemplo de migração

Neste exemplo, migramos uma aplicação que usa o SDK para Java v1 e acessa vários Serviços da AWS. Trabalhamos detalhadamente com o seguinte método da v1 na etapa 5. Esse é um método em uma classe que contém oito métodos e há 32 classes na aplicação.

import com.amazonaws.ClientConfiguration;
import com.amazonaws.regions.Region;
import com.amazonaws.regions.RegionUtils;
import com.amazonaws.services.ec2.AmazonEC2Client;
import com.amazonaws.services.ec2.model.AmazonEC2Exception;
import com.amazonaws.services.ec2.model.CreateTagsRequest;
import com.amazonaws.services.ec2.model.DescribeInstancesRequest;
import com.amazonaws.services.ec2.model.DescribeInstancesResult;
import com.amazonaws.services.ec2.model.Instance;
import com.amazonaws.services.ec2.model.InstanceStateName;
import com.amazonaws.services.ec2.model.Reservation;
import com.amazonaws.services.ec2.model.Tag;
import com.amazonaws.services.ec2.model.TerminateInstancesRequest;
...
private static List<Instance> getRunningInstances(AmazonEC2Client ec2, List<String> instanceIds) {
    List<Instance> runningInstances = new ArrayList<>();
    try {
        DescribeInstancesRequest request = new DescribeInstancesRequest()
                .withInstanceIds(instanceIds);
        DescribeInstancesResult result;
        do {
            // DescribeInstancesResponse is a paginated response, so use tokens with multiple requests.
            result = ec2.describeInstances(request);
            request.setNextToken(result.getNextToken());   // Prepare request for next page.
            for (final Reservation r : result.getReservations()) {
                for (final Instance instance : r.getInstances()) {
                    LOGGER.info("Examining instanceId: "+ instance.getInstanceId());
                    // if instance is in a running state, add it to runningInstances list.
                    if (RUNNING_STATES.contains(instance.getState().getName())) {
                        runningInstances.add(instance);
                    }
                }
            }
        } while (result.getNextToken() != null);
    } catch (final AmazonEC2Exception exception) {
        // if instance isn't found, assume its terminated and continue.
        if (exception.getErrorCode().equals(NOT_FOUND_ERROR_CODE)) {
            LOGGER.info("Instance probably terminated; moving on.");
        } else {
            throw exception;
        }
    }
    return runningInstances;
}

1. Adicionar BOM da v2 do Maven

Adicione o BOM do Maven para o SDK para Java 2.x ao POM junto com quaisquer outras dependências na seção dependencyManagement. Se o arquivo POM tiver o BOM da v1 do SDK, deixe-o por enquanto. Ele será removido em uma etapa posterior.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.example</groupId>             <!--Existing dependency in POM. -->
      <artifactId>bom</artifactId>
      <version>1.3.4</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    ...
    <dependency>
      <groupId>com.amazonaws</groupId>
      <artifactId>aws-java-sdk-bom</artifactId>  <!--Existing v1 BOM dependency. -->
      <version>1.11.1000</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    ...
    <dependency>
      <groupId>software.amazon.awssdk</groupId>  <!--Add v2 BOM dependency. -->
      <artifactId>bom</artifactId>
      <version>2.27.21</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

2. Pesquisar arquivos para declarações de importação de classe da v1

Pesquise o código da aplicação em busca de ocorrências exclusivas de import com.amazonaws.services. Isso nos ajuda a determinar as dependências da v1 usadas pelo projeto. Se a aplicação tiver um arquivo POM do Maven com dependências da v1 listadas, você poderá usar essas informações em vez disso.

Neste exemplo, usamos o comando ripgrep (rg) para pesquisar a base de código.

Da raiz da base de código, execute o comando ripgrep a seguir. Depois que ripgrep encontra as declarações de importação, elas são encaminhadas para os comandos cut, sort e uniq para isolar os SERVICE_IDs.

rg --no-filename 'import\s+com\.amazonaws\.services' | cut -d '.' -f 4 | sort | uniq

Para essa aplicação, os seguintes SERVICE_IDs são registrados no console.

autoscaling
cloudformation
ec2
identitymanagement

Isso indica que houve pelo menos uma ocorrência de cada um dos seguintes nomes de pacotes usados nas declarações import. Para nossos propósitos, os nomes das classes individuais não importam. Só precisamos encontrar os SERVICE_IDs que são usados.

com.amazonaws.services.autoscaling.*
com.amazonaws.services.cloudformation.*
com.amazonaws.services.ec2.*
com.amazonaws.services.identitymanagement.*

3. Determine as dependências da v2 do Maven com base nas declarações de importação da v1

Os SERVICE_IDs da v1 que isolamos Na Etapa 2, por exemplo, autoscaling e cloudformation, podem ser mapeados para o mesmo SERVICE_ID DA v2 na maior parte. Como o artifactId da v2 do Maven corresponde ao SERVICE_ID na maioria dos casos, você tem as informações necessárias para adicionar blocos de dependência ao arquivo POM.

A tabela a seguir mostra como podemos determinar as dependências da v2.

<dependency>
  <groupId>software.amazon.awssdk</groupId>
  <artifactId>ec2</artifactId>
</dependency>

<dependency>
  <groupId>software.amazon.awssdk</groupId>
  <artifactId>autoscaling</artifactId>
</dependency>

<dependency>
  <groupId>software.amazon.awssdk</groupId>
  <artifactId>cloudformation</artifactId>
</dependency>

<dependency>
  <groupId>software.amazon.awssdk</groupId>
  <artifactId>iam</artifactId>
</dependency>

* O mapeamento de identitymanagement para iam é uma exceção em que o SERVICE_ID difere entre as versões. Consulte as exceções em Nome do pacote para mapeamentos de artifactId do Maven., caso o Maven ou o Gradle não consigam resolver a dependência da v2.

4. Adicionar elementos de dependência da v2 ao arquivo POM

Na etapa 3, determinamos os quatro blocos de dependência que precisam ser adicionados ao arquivo POM. Não precisamos adicionar uma versão porque especificamos o BOM na etapa 1. Depois que as importações são adicionadas, nosso arquivo POM tem os seguintes elementos de dependência.

    ...
  <dependencies>
    ...
    <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>autoscaling</artifactId>
    </dependency>
    <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>iam</artifactId>
    </dependency>
    <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>cloudformation</artifactId>
    </dependency>
    <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>ec2</artifactId>
    </dependency>
    ...
  </dependencies>
    ...

5. Nos arquivos Java, altere incrementalmente as classes da v1 para as classes da v2

No método que estamos migrando, vemos

import com.amazonaws.ClientConfiguration;
import com.amazonaws.regions.Region;
import com.amazonaws.regions.RegionUtils;
import com.amazonaws.services.ec2.AmazonEC2Client;
import com.amazonaws.services.ec2.model.AmazonEC2Exception;
import com.amazonaws.services.ec2.model.CreateTagsRequest;
import com.amazonaws.services.ec2.model.DescribeInstancesRequest;
import com.amazonaws.services.ec2.model.DescribeInstancesResult;
import com.amazonaws.services.ec2.model.Instance;
import com.amazonaws.services.ec2.model.InstanceStateName;
import com.amazonaws.services.ec2.model.Reservation;
import com.amazonaws.services.ec2.model.Tag;
import com.amazonaws.services.ec2.model.TerminateInstancesRequest;
...
private static List<Instance> getRunningInstances(AmazonEC2Client ec2, List<String> instanceIds)
    List<Instance> runningInstances = new ArrayList<>();
    try {
        DescribeInstancesRequest request = new DescribeInstancesRequest()
                .withInstanceIds(instanceIds);
        DescribeInstancesResult result;
        do {
            // DescribeInstancesResponse is a paginated response, so use tokens with multiple re
            result = ec2.describeInstances(request);
            request.setNextToken(result.getNextToken());   // Prepare request for next page.
            for (final Reservation r : result.getReservations()) {
                for (final Instance instance : r.getInstances()) {
                    LOGGER.info("Examining instanceId: "+ instance.getInstanceId());
                    // if instance is in a running state, add it to runningInstances list.
                    if (RUNNING_STATES.contains(instance.getState().getName())) {
                        runningInstances.add(instance);
                    }
                }
            }
        } while (result.getNextToken() != null);
    } catch (final AmazonEC2Exception exception) {
        // if instance isn't found, assume its terminated and continue.
        if (exception.getErrorCode().equals(NOT_FOUND_ERROR_CODE)) {
            LOGGER.info("Instance probably terminated; moving on.");
        } else {
            throw exception;
        }
    }
    return runningInstances;
}
...

Nosso objetivo é substituir todas as importações da v1 por importações da v2. Prosseguimos com uma classe por vez.

a. Substitua a declaração de importação ou o nome da classe

Vemos que o primeiro parâmetro do método describeRunningInstances uma instância AmazonEC2Client da v1. Execute um destes procedimentos:

b. Substitua as classes do modelo da v1 por equivalentes da v2

Após a mudança para o Ec2Client da v2, se usarmos um IDE, veremos erros de compilação na declaração a seguir.

                    result = ec2.describeInstances(request);

O erro de compilação resulta do uso de uma instância de DescribeInstancesRequest da v1 como parâmetro para o método Ec2Client describeInstances da v2. Para corrigir, faça as seguintes declarações de substituição ou importação.

import com.amazonaws.services.ec2.model.DescribeInstancesRequest

import software.amazon.awssdk.services.ec2.model.DescribeInstancesRequest

c. Altere os compiladores da v1 para compiladores da v2.

Ainda vemos erros de compilação porque não há construtores nas classes da v2. Para corrigir isso, faça a alteração a seguir.

final DescribeInstancesRequest request = new DescribeInstancesRequest()
        .withInstanceIds(instanceIdsCopy);

final DescribeInstancesRequest request = DescribeInstancesRequest.builder()
        .instanceIds(instanceIdsCopy)
        .build();

d. Substitua objetos de resposta *Result da v1 por *Response equivalentes da v2

Uma diferença consistente entre a v1 e a v2 é que todos os objetos de resposta na v2 terminam com *Response em vez de *Result. Substitua a importação DescribeInstancesResult da v1 pela importação DescribeInstancesResponse da v2.

d. Fazer alterações na API

A declaração a seguir precisa de algumas alterações.

request.setNextToken(result.getNextToken());

Na v2, os métodos de setter não usam o set nem com prefix. Métodos getter com prefixo get também foram incluídos no SDK para Java 2.x

Classes de modelo, como a instância request, são imutáveis na v2, então precisamos criar uma DescribeInstancesRequest com um compilador.

Na v2, a declaração se torna a seguinte.

request = DescribeInstancesRequest.builder()
        .nextToken(result.nextToken())
        .build();

d. Repita até que o método seja compilado com classes da v2

Continue com o restante do código. Substitua as importações da v1 pelas importações da v2 e corrija os erros de compilação. Consulte a Referência da API da v2 e a Referência O que mudou, conforme necessário.

Depois de migrarmos esse único método, temos o seguinte código da v2.

import com.amazonaws.ClientConfiguration;
import com.amazonaws.regions.Region;
import com.amazonaws.regions.RegionUtils;
import com.amazonaws.services.ec2.AmazonEC2Client;
import com.amazonaws.services.ec2.model.AmazonEC2Exception;
import com.amazonaws.services.ec2.model.CreateTagsRequest;
import com.amazonaws.services.ec2.model.InstanceStateName;
import com.amazonaws.services.ec2.model.Tag;
import com.amazonaws.services.ec2.model.TerminateInstancesRequest;

import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.DescribeInstancesRequest;
import software.amazon.awssdk.services.ec2.model.DescribeInstancesResponse;
import software.amazon.awssdk.services.ec2.model.Ec2Exception;
import software.amazon.awssdk.services.ec2.model.Instance;
import software.amazon.awssdk.services.ec2.model.Reservation;
...
private static List<Instance> getRunningInstances(Ec2Client ec2, List<String> instanceIds) {
    List<Instance> runningInstances = new ArrayList<>();
        try {
            DescribeInstancesRequest request = DescribeInstancesRequest.builder()
                    .instanceIds(instanceIds)
                    .build();
            DescribeInstancesResponse result;
            do {
                // DescribeInstancesResponse is a paginated response, so use tokens with multiple re
                result = ec2.describeInstances(request);
                request = DescribeInstancesRequest.builder()   // Prepare request for next page.
                        .nextToken(result.nextToken())
                        .build();
                for (final Reservation r : result.reservations()) {
                    for (final Instance instance : r.instances()) {
                        // if instance is in a running state, add it to runningInstances list.
                        if (RUNNING_STATES.contains(instance.state().nameAsString())) {
                            runningInstances.add(instance);
                        }
                    }
                }
            } while (result.nextToken() != null);
        } catch (final Ec2Exception exception) {
            // if instance isn't found, assume its terminated and continue.
            if (exception.awsErrorDetails().errorCode().equals(NOT_FOUND_ERROR_CODE)) {
                    LOGGER.info("Instance probably terminated; moving on.");
            } else {
                throw exception;
            }
        }
        return runningInstances;
    }
...

Como estamos migrando um único método em um arquivo Java com oito métodos, temos uma combinação de importações da v1 e da v2 à medida que trabalhamos no arquivo. Adicionamos as últimas seis declarações de importação à medida que executamos as etapas.

Depois de migrarmos todo o código, não haverá mais declarações de importação v1.

6. Remova as dependências da v1 do Maven das importações do POM e da v1 dos arquivos

Depois de migrarmos todo o código da v1 no arquivo, temos as seguintes declarações de importação do SDK da v2.

import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.regions.ServiceMetadata;
import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.CreateTagsRequest;
import software.amazon.awssdk.services.ec2.model.DescribeInstancesRequest;
import software.amazon.awssdk.services.ec2.model.DescribeInstancesResponse;
import software.amazon.awssdk.services.ec2.model.Ec2Exception;
import software.amazon.awssdk.services.ec2.model.Instance;
import software.amazon.awssdk.services.ec2.model.InstanceStateName;
import software.amazon.awssdk.services.ec2.model.Reservation;
import software.amazon.awssdk.services.ec2.model.Tag;
import software.amazon.awssdk.services.ec2.model.TerminateInstancesRequest;

Depois de migrarmos todos os arquivos na aplicação, não precisaremos mais das dependências da v1 no arquivo POM. Remova o BOM v1 da seção dependencyManagement, caso esteja usando, e todos os blocos de dependência da v1.

7. Refatorar o código para usar os aprimoramentos da API da v2

Para o trecho que estamos migrando, podemos usar um paginador da v2 e deixar o SDK gerenciar as solicitações baseadas em tokens para obter mais dados, caso desejarmos.

Podemos substituir toda a cláusula do pela seguinte.

                DescribeInstancesIterable responses = ec2.describeInstancesPaginator(request);

                responses.reservations().stream()
                        .forEach(reservation -> reservation.instances()
                                .forEach(instance -> {
                                    if (RUNNING_STATES.contains(instance.state().nameAsString())) {
                                        runningInstances.put(instance.instanceId(), instance);
                                    }
                                }));

Nome do pacote para mapeamentos de artifactId do Maven.

Ao migrar o projeto Maven ou Gradle da v1 do SDK para Java para a v2, você precisa descobrir quais dependências adicionar ao arquivo de compilação. A abordagem descrita em Instruções passo a passo de migração com exemplo (etapa 3) usa os nomes dos pacotes nas declarações de importação como ponto de partida para determinar as dependências (como artifactIds) que devem ser adicionadas ao arquivo de compilação.

Você pode usar as informações deste tópico para mapear os nomes dos pacotes da v1 para os artifactIds da v2.

Convenção de nomenclatura comum usada em nomes de pacotes e artifactIds do Maven

A tabela a seguir mostra a convenção de nomenclatura comum que os SDKs usam para determinado SERVICE_ID. Um SERVICE_ID é um identificador exclusivo de um AWS service (Serviço da AWS). Por exemplo, o SERVICE_ID do serviço Amazon S3 é s3 e o SERVICE_ID do Amazon Cognito Identity é cognitoidentity.

Diferenças de SERVICE_ID

Na v1

Em alguns casos, o SERVICE_ID difere entre o nome do pacote e o artifactId do mesmo serviço. Por exemplo, a linha de métricas do CloudWatch da tabela a seguir mostra que metrics é o SERVICE_ID no nome do pacote, mas cloudwatchmetrics é o SERVICE_ID do artifactId.

Na v2

Não há diferenças no SERVICE_ID usado em nomes de pacotes e artifactIds.

Entre a v1 e a v2

Para a maioria dos serviços, o SERVICE_ID na v2 é o mesmo que o SERVICE_ID na v1 nos nomes dos pacotes e nos artifactIds. Um exemplo disso é o SERVICE_ID cognitoedentity, conforme mostrado na tabela anterior. Porém, alguns SERVICE_IDs diferem entre os SDKs, conforme mostrado na tabela a seguir.

Um SERVICE_ID em negrito em qualquer uma das colunas da v1 indica que ele é diferente do SERVICE_ID usado na v2.