QLDBControlador Amazon para Java: tutorial de inicio rápido

importante

Aviso de fin de soporte: los clientes actuales podrán usar Amazon QLDB hasta que finalice el soporte, el 31 de julio de 2025. Para obtener más información, consulte Migración de un Amazon QLDB Ledger a Amazon Aurora SQL Postgre.

En este tutorial, aprenderás a configurar una aplicación sencilla con la última versión del QLDB controlador de Amazon para Java. Esta guía incluye los pasos para instalar el controlador y ejemplos breves de código 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 de Java. Esto incluye registrarse AWS, conceder acceso programático para el desarrollo e instalar un entorno de desarrollo integrado de Java (IDE).

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 para los libros de QLDB contabilidad de Amazon 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 utilizas uno IDE que tiene funciones para automatizar estos pasos de configuración, puedes pasar directamente aPaso 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. Reemplazar project-package, project-name, y maven-template con tus propios valores, según corresponda.

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

   En maven-template, puedes usar la plantilla básica de Maven: maven-archetype-quickstart

3. Para añadir el QLDBcontrolador de Java como una dependencia del proyecto, navegue hasta el pom.xml archivo 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ásicasCRUD. O bien, puede omitir el step-by-step tutorial 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

El siguiente ejemplo de código muestra 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 optimistas en materia de control de simultaneidad (OCC) conflictos.

// 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 una instrucción INSERT. QLDBadmite el lenguaje de consultas PartiQL (SQLcompatible) 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 INSERT sentencia, puede pasar un parámetro de tipo IonList(definido explícitamente como talIonValue) a la sentencia 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 una 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 el suyo IDE para compilar y ejecutar el App.java archivo.

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 CRUD operaciones básicas 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 con el groupId valor que utilizó para el comando de Maven enPaso 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
        });
    }
}

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