Controlador Amazon QLDB para Java: tutorial de inicio rápido

En este tutorial aprenderá a configurar una aplicación sencilla con la última versión del controlador Amazon QLDB para Java. En esta guía se incluyen los pasos para instalar el controlador y ejemplos de código breve de las operaciones básicas de creación, lectura, actualización y eliminación (CRUD). Para ver ejemplos más detallados que presentan estas operaciones en una aplicación de muestra completa, consulte Tutorial de Java.

Requisitos previos

Antes de comenzar, asegúrese de que hace lo siguiente:

1. Si aún no lo ha hecho, complete el Requisitos previos para el controlador Java. Esto incluye registrarse en AWS, conceder acceso programático para el desarrollo e instalar un entorno de desarrollo integrado (IDE) de Java.

2. Cree un libro mayor denominado quick-start.

   Para obtener más información sobre cómo crear un libro mayor, consulte Operaciones básicas de libros mayores de Amazon QLDB o Paso 1: crear un nuevo libro mayor en Introducción a la consola.

Paso 1: Configuración del proyecto

En primer lugar, configure su proyecto de Java. Recomendamos usar el sistema de administración de dependencias de Maven para este tutorial.

nota

Si usa un IDE con características para automatizar estos pasos de configuración, puede pasar directamente a Paso 2: inicializar el controlador.

1. Cree una carpeta para su aplicación.

   $ mkdir myproject
   $ cd myproject

2. Introduzca el siguiente comando para inicializar el proyecto a partir de una plantilla de Maven. Reemplace project-package, project-name y maven-template con sus propios valores, según corresponda.

   $ mvn archetype:generate
     -DgroupId=project-package \
     -DartifactId=project-name \
     -DarchetypeArtifactId=maven-template \
     -DinteractiveMode=false

   Para maven-template, puede usar la plantilla básica de Maven: maven-archetype-quickstart

3. Para añadir el controlador QLDB para Java como una dependencia del proyecto, navegue hasta el archivo pom.xml recién creado y añada el siguiente artefacto.

   <dependency>
       <groupId>software.amazon.qldb</groupId>
       <artifactId>amazon-qldb-driver-java</artifactId>
       <version>2.3.1</version>
   </dependency>

   Este artefacto incluye automáticamente el módulo principal AWS SDK for Java 2.x, las bibliotecas de Amazon Ion y otras dependencias necesarias. El archivo pom.xml debe ser similar al siguiente:

   <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <groupId>software.amazon.qldb</groupId>
     <artifactId>qldb-quickstart</artifactId>
     <packaging>jar</packaging>
     <version>1.0-SNAPSHOT</version>
     <name>qldb-quickstart</name>
     <url>http://maven.apache.org</url>
     <dependencies>
       <dependency>
         <groupId>junit</groupId>
         <artifactId>junit</artifactId>
         <version>3.8.1</version>
         <scope>test</scope>
       </dependency>
       <dependency>
           <groupId>software.amazon.qldb</groupId>
           <artifactId>amazon-qldb-driver-java</artifactId>
           <version>2.3.1</version>
       </dependency>
     </dependencies>
   </project>

4. Abra el archivo App.java.

   A continuación, añada gradualmente los ejemplos de código en los siguientes pasos para probar algunas operaciones básicas de CRUD. También puede saltarse el tutorial paso a paso y ejecutar la aplicación completa.

Paso 2: inicializar el controlador

Inicialice una instancia del controlador que se conecte al libro mayor denominado quick-start. Agregue el siguiente código al archivo App.java.

import java.util.*;
import com.amazon.ion.*;
import com.amazon.ion.system.*;
import software.amazon.awssdk.services.qldbsession.QldbSessionClient;
import software.amazon.qldb.*;

public final class App {
    public static IonSystem ionSys = IonSystemBuilder.standard().build();
    public static QldbDriver qldbDriver;

    public static void main(final String... args) {
        System.out.println("Initializing the driver");
        qldbDriver = QldbDriver.builder()
            .ledger("quick-start")
            .transactionRetryPolicy(RetryPolicy
                .builder()
                .maxRetries(3)
                .build())
            .sessionClientBuilder(QldbSessionClient.builder())
            .build();
    }
}

Paso 3: crear una tabla y un índice

Los siguientes ejemplos de código muestran cómo ejecutar las instrucciones CREATE TABLE y CREATE INDEX.

En el método main, agregue el siguiente código para crear una tabla con el nombre People y un índice para el campo lastName de dicha tabla. Los índices son necesarios para optimizar el rendimiento de las consultas y ayudar a limitar las excepciones de conflicto de control de concurrencia optimista (OCC).

// Create a table and an index in the same transaction
qldbDriver.execute(txn -> {
    System.out.println("Creating a table and an index");
    txn.execute("CREATE TABLE People");
    txn.execute("CREATE INDEX ON People(lastName)");
});

Paso 4: insertar un documento

El siguiente ejemplo de código muestra cómo ejecutar a instrucción INSERT. QLDB es compatible con el lenguaje de consultas PartiQL (compatible con SQL) y el formato de datos Amazon Ion (superconjunto de JSON).

Añada el siguiente código para insertar un documento en la tabla People.

// Insert a document
qldbDriver.execute(txn -> {
    System.out.println("Inserting a document");
    IonStruct person = ionSys.newEmptyStruct();
    person.put("firstName").newString("John");
    person.put("lastName").newString("Doe");
    person.put("age").newInt(32);
    txn.execute("INSERT INTO People ?", person);
});

En este ejemplo se emplea un signo de interrogación (?) como marcador de posición variable para pasar la información del documento a la instrucción. Al utilizar marcadores de posición, debe pasar un valor de tipo IonValue.

sugerencia

Para insertar varios documentos mediante una sola instrucción INSERT, puede pasar un parámetro del tipo Ionlist (convertido explícitamente a IonValue) a la instrucción de la siguiente manera.

// people is an IonList explicitly cast as an IonValue
txn.execute("INSERT INTO People ?", (IonValue) people);

No coloque el marcador de posición variable (?) entre corchetes de doble ángulo (<<...>>) al pasar una IonList. En las instrucciones PartiQL manuales, los corchetes de doble ángulo indican una colección desordenada conocida como bolsa.

Paso 5: consulta del documento

El siguiente ejemplo de código muestra cómo ejecutar una instrucción SELECT.

Agregue el siguiente código para consultar un documento de la tabla People.

// Query the document
qldbDriver.execute(txn -> {
    System.out.println("Querying the table");
    Result result = txn.execute("SELECT * FROM People WHERE lastName = ?",
            ionSys.newString("Doe"));
    IonStruct person = (IonStruct) result.iterator().next();
    System.out.println(person.get("firstName")); // prints John
    System.out.println(person.get("lastName")); // prints Doe
    System.out.println(person.get("age")); // prints 32
});

Paso 6: actualizar el documento

El siguiente ejemplo de código muestra cómo ejecutar a instrucción UPDATE.

1. Añada el siguiente código para actualizar un documento de la tabla People actualizando age a 42.

   // Update the document
   qldbDriver.execute(txn -> {
       System.out.println("Updating the document");
       final List<IonValue> parameters = new ArrayList<>();
       parameters.add(ionSys.newInt(42));
       parameters.add(ionSys.newString("Doe"));
       txn.execute("UPDATE People SET age = ? WHERE lastName = ?", parameters);
   });

2. Vuelva a consultar el documento para ver el valor actualizado.

   // Query the updated document
   qldbDriver.execute(txn -> {
       System.out.println("Querying the table for the updated document");
       Result result = txn.execute("SELECT * FROM People WHERE lastName = ?",
               ionSys.newString("Doe"));
       IonStruct person = (IonStruct) result.iterator().next();
       System.out.println(person.get("firstName")); // prints John
       System.out.println(person.get("lastName")); // prints Doe
       System.out.println(person.get("age")); // prints 32
   });

3. Utilice Maven o su IDE para compilar y ejecutar el archivo App.java.

Ejecución de la aplicación completa

El siguiente ejemplo de código es la versión completa de la aplicación App.java. En lugar de seguir los pasos anteriores de forma individual, también puede copiar y ejecutar este ejemplo de código de principio a fin. Esta aplicación muestra algunas operaciones básicas de CRUD en el libro mayor denominado quick-start.

nota

Antes de ejecutar este código, asegúrese de no tener ya una tabla activa con el nombre People en el libro mayor quick-start.

En la primera línea, sustituya project-package por el valor groupId que utilizó para el comando de Maven en Paso 1: Configuración del proyecto .

package project-package;

import java.util.*;
import com.amazon.ion.*;
import com.amazon.ion.system.*;
import software.amazon.awssdk.services.qldbsession.QldbSessionClient;
import software.amazon.qldb.*;

public class App {
    public static IonSystem ionSys = IonSystemBuilder.standard().build();
    public static QldbDriver qldbDriver;

    public static void main(final String... args) {
        System.out.println("Initializing the driver");
        qldbDriver = QldbDriver.builder()
            .ledger("quick-start")
            .transactionRetryPolicy(RetryPolicy
                .builder()
                .maxRetries(3)
                .build())
            .sessionClientBuilder(QldbSessionClient.builder())
            .build();

        // Create a table and an index in the same transaction
        qldbDriver.execute(txn -> {
            System.out.println("Creating a table and an index");
            txn.execute("CREATE TABLE People");
            txn.execute("CREATE INDEX ON People(lastName)");
        });
        
        // Insert a document
        qldbDriver.execute(txn -> {
            System.out.println("Inserting a document");
            IonStruct person = ionSys.newEmptyStruct();
            person.put("firstName").newString("John");
            person.put("lastName").newString("Doe");
            person.put("age").newInt(32);
            txn.execute("INSERT INTO People ?", person);
        });
        
        // Query the document
        qldbDriver.execute(txn -> {
            System.out.println("Querying the table");
            Result result = txn.execute("SELECT * FROM People WHERE lastName = ?",
                    ionSys.newString("Doe"));
            IonStruct person = (IonStruct) result.iterator().next();
            System.out.println(person.get("firstName")); // prints John
            System.out.println(person.get("lastName")); // prints Doe
            System.out.println(person.get("age")); // prints 32
        });
        
        // Update the document
        qldbDriver.execute(txn -> {
            System.out.println("Updating the document");
            final List<IonValue> parameters = new ArrayList<>();
            parameters.add(ionSys.newInt(42));
            parameters.add(ionSys.newString("Doe"));
            txn.execute("UPDATE People SET age = ? WHERE lastName = ?", parameters);
        });
        
        // Query the updated document
        qldbDriver.execute(txn -> {
            System.out.println("Querying the table for the updated document");
            Result result = txn.execute("SELECT * FROM People WHERE lastName = ?",
                    ionSys.newString("Doe"));
            IonStruct person = (IonStruct) result.iterator().next();
            System.out.println(person.get("firstName")); // prints John
            System.out.println(person.get("lastName")); // prints Doe
            System.out.println(person.get("age")); // prints 42
        });
    }
}

Utilice Maven o su IDE para compilar y ejecutar el archivo App.java.