Instrucciones de migración paso a paso con ejemplo

En esta sección se proporciona una guía paso a paso para migrar la aplicación que usa actualmente el SDK para Java v1.x al SDK para Java 2.x. La primera parte presenta una descripción general de los pasos, seguida de un ejemplo detallado de migración.

Los pasos que se indican aquí describen la migración de un caso de uso normal, en el que la aplicación llama a Servicios de AWS mediante clientes de servicio basados en modelos. Si necesita migrar código que utilice API de nivel superior, como S3 Transfer Manager o la prefirma de CloudFront, consulte la sección bajo la tabla de contenido de Diferencias entre el AWS SDK para Java 1.x y 2.x.

El método que se describe aquí es una sugerencia. Puede utilizar otras técnicas y aprovechar las características de edición de código de su IDE para obtener el mismo resultado.

Información general sobre los pasos

1. Inicio agregando la BOM del SDK para Java 2.x

Al añadir el elemento BOM (lista de materiales) de Maven para el SDK para Java 2.x a su archivo POM, se asegura de que todas las dependencias de la v2 que necesita son de la misma versión. Su POM puede contener dependencias de v1 y v2. Esto le permite migrar el código de forma incremental en lugar de cambiarlo todo de una 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. Búsqueda de archivos para instrucciones de importación de la clase v1

Si analiza los archivos de su aplicación en busca de los SERVICE_ID utilizados en importaciones de v1, encontrará los SERVICE_ID únicos utilizados. Un SERVICE_ID es un nombre corto y único para un Servicio de AWS. Por ejemplo, cognitoidentity es el SERVICE_ID de Amazon Cognito Identity.

3. Determinación de las dependencias de Maven de la v2 a partir de las instrucciones de importación de la v1

Cuando encuentre todos los SERVICE_ID únicos de la v1, puede determinar el artefacto de Maven correspondiente a la dependencia de la v2 consultando Asignaciones de nombre del paquete a artifactId de Maven.

4. Adición de elementos de dependencia de la v2 al archivo POM

Actualice el archivo POM de Maven con los elementos de dependencia determinados en el paso 3.

5. En los archivos Java, cambio gradual de las clases de la v1 a las clases de la v2

A medida que sustituya las clases de la v1 por las de la v2, realice los cambios necesarios para que sean compatibles con la API de v2, como utilizar compiladores en lugar de constructores y utilizar fluent getters y setters.

6. Eliminación las dependencias de Maven de v1 desde el POM y las importaciones de v1 desde los archivos

Después de migrar el código para usar clases de la v2, elimine las importaciones sobrantes de la v1 de los archivos y todas las dependencias del archivo de compilación.

7. Refactorización del código para usar mejoras de la API de la v2

Una vez que el código se haya compilado correctamente y superado las pruebas, puede aprovechar las mejoras de la v2, como utilizar un cliente de HTTP diferente o paginadores para simplificar el código. Se trata de un paso opcional.

Ejemplo de migración

En este ejemplo, migramos una aplicación que usa el SDK para Java v1 y accede a varios Servicios de AWS. En el paso 5 analizaremos en detalle el siguiente método de la v1. Es un método de una clase que contiene ocho métodos y hay 32 clases en la aplicación.

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. Adición de BOM de Maven de la v2

Agregue la BOM de Maven para el SDK para Java 2.x al POM junto con cualquier otra dependencia en la sección dependencyManagement. Si el archivo POM tiene la BOM de la v1 del SDK, déjela por ahora. Se eliminará en un paso 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. Búsqueda de archivos para instrucciones de importación de la clase v1

Busque en el código de la aplicación apariciones únicas de import com.amazonaws.services. Esto nos ayuda a determinar las dependencias de la v1 que utiliza el proyecto. Si su aplicación tiene un archivo POM de Maven en la que figuran dependencias de la v1, puede utilizar esta información en su lugar.

En este ejemplo, utilizamos el comando ripgrep (rg) para buscar en la base de código.

Desde la raíz de la base de código, ejecute el comando ripgrep siguiente. Una vez que ripgrep encuentra las instrucciones de importación, se canalizan a los comandos cut, sort y uniqpara aislar los SERVICE_ID.

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

Para esta aplicación, los siguientes SERVICE_ID se registran en la consola.

autoscaling
cloudformation
ec2
identitymanagement

Esto indica que se ha utilizado al menos una vez cada uno de los siguientes nombres de paquetes en las instrucciones de import. Para nuestros propósitos, los nombres de las clases individuales no tienen importancia. Solo necesitamos localizar los SERVICE_ID que se utilizan.

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

3. Determinación de las dependencias de Maven de la v2 a partir de las instrucciones de importación de la v1

Los SERVICE_ID de la v1 que hemos aislado en el paso 2 (por ejemplo, autoscaling y cloudformation) se pueden asignar al mismo SERVICE_ID de la v2 en su mayor parte. Dado que el artifactId de Maven de la v2 coincide con el SERVICE_ID en la mayoría de los casos, usted tiene la información que necesita para añadir bloques de dependencias a su archivo POM.

En la siguiente tabla se muestra cómo podemos determinar las dependencias de la 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>

* La asignación de identitymanagement a iam es una excepción en la que el SERVICE_ID difiere según la versión. Consulte en la Asignaciones de nombre del paquete a artifactId de Maven las excepciones si Maven o Gradle no pueden resolver la dependencia de la v2.

4. Adición de elementos de dependencia de la v2 al archivo POM

En el paso 3, hemos determinado los cuatro bloques de dependencia que deben añadirse al archivo POM. No necesitamos añadir una versión porque especificamos la BOM en el paso 1. Una vez agregadas las importaciones, nuestro archivo POM tiene los siguientes elementos de dependencia.

    ...
  <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. En los archivos Java, cambio gradual de las clases de la v1 a las clases de la v2

En el 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;
}
...

Nuestro objetivo es sustituir todas las importaciones de la v1 por las de la v2. Procedemos clase por clase.

a. Reemplace la instrucción de importación o el nombre de clase

Vemos que el primer parámetro del método describeRunningInstances es una instancia de AmazonEC2Client v1. Realice una de las siguientes acciones:

b. Reemplazo de las clases del modelo de v1 por equivalentes de v2

Tras el cambio a Ec2Client v2, si utilizamos un IDE, aparecen errores de compilación en la siguiente instrucción.

                    result = ec2.describeInstances(request);

El error de compilación se debe al uso de una instancia de DescribeInstancesRequest de la v1 como parámetro del método Ec2Client describeInstances de la v2. Para corregirlo, aplique las siguientes instrucciones de sustitución o importación.

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

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

c. Cambie los constructores de v1 por constructores de v2.

Siguen apareciendo errores de compilación porque no hay constructores en clases de la v2. Para corregirlo, realice el siguiente cambio.

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

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

d. Reemplace los objetos de respuesta de *Result de v1 con los equivalentes de *Response de v2

Una diferencia constante entre v1 y v2 es que todos los objetos de respuesta de v2 terminan en *Response en lugar de *Result. Reemplace la importación de DescribeInstancesResult de v1 por la importación de v2, DescribeInstancesResponse.

d. Realización de cambios en la API

La siguiente instrucción necesita algunos cambios.

request.setNextToken(result.getNextToken());

En la v2, los métodos setter no utilizan set o prefix. Los métodos Getter con prefijo con get también han desaparecido del SDK para Java 2.x

Las clases de modelos, como la instancia de request, son inmutables en la v2, por lo que debemos crear una DescribeInstancesRequest nueva con un compilador.

En la v2, la instrucción pasa a ser la siguiente.

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

d. Repita hasta que el método se compile con clases de la v2

Continúe con el resto del código. Sustituya las importaciones de la v1 por las de la v2 y corrija los errores de compilación. Consulte la Referencia de la API de la v2 y la Referencia de diferencias si es necesario.

Después de migrar este método individual, tendremos el siguiente código de la 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;
    }
...

Dado que estamos migrando un único método en un archivo Java con ocho métodos, tenemos una combinación de importaciones de la v1 y v2 a medida que avanzamos en el archivo. Hemos añadido las seis últimas instrucciones de importación a medida que dábamos los pasos.

Después de migrar todo el código, no habrá más instrucciones de importación de v1.

6. Eliminación las dependencias de Maven de v1 desde el POM y las importaciones de v1 desde los archivos

Tras migrar todo el código de la v1 del archivo, tenemos las siguientes instrucciones de importación del SDK de la 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;

Después de migrar todos los archivos de nuestra aplicación, ya no necesitamos las dependencias de la v1 en nuestro archivo POM. Elimine la BOM de la v1 de la sección dependencyManagement, si la está utilizando, y todos los bloques de dependencias de la v1.

7. Refactorización del código para usar mejoras de la API de la v2

Para el fragmento de código que hemos estado migrando, podemos usar opcionalmente un paginador de v2 y dejar que el SDK administre las solicitudes de datos adicionales basadas en tokens.

Podemos sustituir toda la cláusula do por lo siguiente.

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

Asignaciones de nombre del paquete a artifactId de Maven

Al migrar el proyecto de Maven o Gradle de la v1 del SDK para Java a la v2, debe determinar qué dependencias desea añadir al archivo de compilación. El método descrito en los Instrucciones de migración paso a paso con ejemplo (paso 3) utiliza los nombres de paquetes de las instrucciones de importación como punto de partida para determinar las dependencias (como artifactId) que se van a añadir al archivo de compilación.

Puede usar la información de este tema para asignar los nombres de paquetes de la v1 a los artifactId de la v2.

Convención de nomenclatura común utilizada en nombres de paquetes y artifactId de Maven

La siguiente tabla muestra la convención de nomenclatura común que utilizan los SDK para un SERVICE_ID determinado. Un SERVICE_ID es un identificador único para un Servicio de AWS. Por ejemplo, el SERVICE_ID del servicio de Amazon S3 es s3 y cognitoidentity es el SERVICE_ID de Amazon Cognito Identity.

Diferencias de SERVICE_ID

En v1

En algunos casos, el SERVICE_ID presenta diferencias entre el nombre del paquete y el artifactId del mismo servicio. Por ejemplo, la fila de métricas de CloudWatch de la siguiente tabla muestra que metrics es el SERVICE_ID del nombre del paquete, pero cloudwatchmetrics es el SERVICE_ID del artifactId.

En v2

No hay diferencias en el SERVICE_ID utilizado en los nombres de paquetes y artifactId.

Entre v1 y v2.

En la mayoría de los servicios, el SERVICE_ID de la v2 es el mismo que el SERVICE_ID de la v1, tanto en los nombres de paquetes como en los artifactId. Un ejemplo de esto es el SERVICE_ID cognitoedentity que se muestra en la tabla anterior. Sin embargo, algunos SERVICE_ID difieren entre los SDK, como se muestra en la tabla siguiente.

Un SERVICE_ID en negrita en las columnas de la v1 indica que es diferente del SERVICE_ID utilizado en la v2.