Importación del controlador Instanciación del controlador Operaciones CRUD Trabajar con Amazon Ion

Controlador Amazon QLDB para Java: libro de recetas de referencia

Esta guía de referencia muestra los casos de uso más comunes del controlador Amazon QLDB para Java. En él se proporcionan ejemplos de código Java que muestran cómo utilizar el controlador para ejecutar operaciones básicas de creación, lectura, actualización y eliminación (CRUD, por sus siglas en inglés). También incluye ejemplos de código para procesar datos de Amazon Ion. Además, esta guía destaca las mejores prácticas para hacer que las transacciones sean idempotentes e implementar restricciones de exclusividad.

nota

Cuando proceda, algunos pasos incluyen ejemplos de código diferentes para cada versión principal compatible del controlador QLDB para Java.

Contenido

Importación del controlador

El siguiente ejemplo de código importa el controlador, el cliente de sesión de QLDB, los paquetes de Amazon Ion y otras dependencias relacionadas.

Instanciación del controlador

El siguiente ejemplo de código crea una instancia de controlador que se conecta a un nombre de libro mayor especificado y utiliza una lógica de reintentos especificada con un límite de reintentos personalizado.

nota

En este ejemplo también se crea una instancia de un objeto del sistema Amazon Ion (IonSystem). Necesita este objeto para procesar los datos de Ion al ejecutar algunas operaciones de datos de esta referencia. Para obtener más información, consulte Trabajar con Amazon Ion.

Operaciones CRUD

La QLDB ejecuta operaciones de creación, lectura, actualización y eliminación (CRUD, por sus siglas en inglés) como parte de una transacción.

aviso

Como práctica recomendada, haga que sus transacciones de escritura sean estrictamente idempotentes.

Hacer que las transacciones sean idempotentes

Le recomendamos que haga que las transacciones de escritura sean idempotentes para evitar cualquier efecto secundario inesperado en caso de reintentos. Una transacción es idempotente si puede ejecutarse varias veces y producir resultados idénticos cada vez.

Por ejemplo, pensemos en una transacción que inserta un documento en una tabla llamada Person. La transacción debe comprobar primero si el documento ya existe o no en la tabla. Sin esta comprobación, la tabla podría terminar con documentos duplicados.

Supongamos que la QLDB confirma correctamente la transacción en el lado del servidor pero el cliente agota el tiempo de espera mientras espera una respuesta. Si la transacción no es idempotente, se podría insertar el mismo documento más de una vez en caso de volver a intentarlo.

Uso de índices para evitar escanear tablas completas

También le recomendamos que ejecute instrucciones con una frase de predicado WHERE utilizando un operador de igualdad sobre un campo indexado o un ID de documento; por ejemplo, WHERE indexedField = 123 o WHERE indexedField IN (456, 789). Sin esta búsqueda indexada, la QLDB necesita escanear las tablas, lo que puede provocar tiempos de espera de las transacciones o conflictos de control de concurrencia optimista (OCC).

Para obtener más información acerca de OCC, consulte Modelo de concurrencia de Amazon QLDB.

Transacciones creadas de forma implícita

La función QldbDriver.execute acepta una función de Lambda que recibe una instancia de Executor, que se puede utilizar para ejecutar instrucciones. La instancia de Executor envuelve una transacción creada de forma implícita.

Puede ejecutar instrucciones dentro de la función de Lambda mediante el método Executor.execute. El controlador confirma implícitamente la transacción cuando vuelve la función de Lambda.

En las siguientes secciones se muestra cómo ejecutar operaciones CRUD básicas, especificar una lógica de reintento personalizada e implementar restricciones de exclusividad.

nota

Cuando proceda, en estas secciones se proporcionan ejemplos de código sobre el procesamiento de datos de Amazon Ion mediante la biblioteca Ion integrada y la biblioteca de mapeadores Jackson Ion. Para obtener más información, consulte Trabajar con Amazon Ion.

Contenido

Creación de tablas


qldbDriver.execute(txn -> {
    txn.execute("CREATE TABLE Person");
});

Creación de índices


qldbDriver.execute(txn -> {
    txn.execute("CREATE INDEX ON Person(GovId)");
});

Lectura de documentos


// Assumes that Person table has documents as follows:
// { GovId: "TOYENC486FH", FirstName: "Brent" }

qldbDriver.execute(txn -> {
    Result result = txn.execute("SELECT * FROM Person WHERE GovId = 'TOYENC486FH'");
    IonStruct person = (IonStruct) result.iterator().next();
    System.out.println(person.get("GovId")); // prints TOYENC486FH
    System.out.println(person.get("FirstName")); // prints Brent
});

Uso de parámetros de consulta

En el siguiente ejemplo de código, se utiliza un parámetro de consulta de tipo Ion.


qldbDriver.execute(txn -> {
    Result result = txn.execute("SELECT * FROM Person WHERE GovId = ?",
            SYSTEM.newString("TOYENC486FH"));
    IonStruct person = (IonStruct) result.iterator().next();
    System.out.println(person.get("GovId")); // prints TOYENC486FH
    System.out.println(person.get("FirstName")); // prints Brent
});

En el siguiente ejemplo de código se utilizan varios parámetros de consulta.


qldbDriver.execute(txn -> {
    Result result = txn.execute("SELECT * FROM Person WHERE GovId = ? AND FirstName = ?",
            SYSTEM.newString("TOYENC486FH"),
            SYSTEM.newString("Brent"));
    IonStruct person = (IonStruct) result.iterator().next();
    System.out.println(person.get("GovId")); // prints TOYENC486FH
    System.out.println(person.get("FirstName")); // prints Brent
});

En el siguiente ejemplo de código, se utiliza una lista de parámetros de consulta.


qldbDriver.execute(txn -> {
    final List<IonValue> parameters = new ArrayList<>();
    parameters.add(SYSTEM.newString("TOYENC486FH"));
    parameters.add(SYSTEM.newString("ROEE1"));
    parameters.add(SYSTEM.newString("YH844"));
    Result result = txn.execute("SELECT * FROM Person WHERE GovId IN (?,?,?)", parameters);
    IonStruct person = (IonStruct) result.iterator().next();
    System.out.println(person.get("GovId")); // prints TOYENC486FH
    System.out.println(person.get("FirstName")); // prints Brent
});


// Assumes that Person table has documents as follows:
// {GovId: "TOYENC486FH", FirstName: "Brent" }

qldbDriver.execute(txn -> {
    try {
        Result result = txn.execute("SELECT * FROM Person WHERE GovId = 'TOYENC486FH'");
        Person person = MAPPER.readValue(result.iterator().next(), Person.class);
        System.out.println(person.getFirstName()); // prints Brent
        System.out.println(person.getGovId()); // prints TOYENC486FH
    } catch (IOException e) {
        e.printStackTrace();
    }
});

Uso de parámetros de consulta

En el siguiente ejemplo de código, se utiliza un parámetro de consulta de tipo Ion.


qldbDriver.execute(txn -> {
    try {
        Result result = txn.execute("SELECT * FROM Person WHERE GovId = ?",
                MAPPER.writeValueAsIonValue("TOYENC486FH"));
        Person person = MAPPER.readValue(result.iterator().next(), Person.class);
        System.out.println(person.getFirstName()); // prints Brent
        System.out.println(person.getGovId()); // prints TOYENC486FH
    } catch (IOException e) {
        e.printStackTrace();
    }
});

En el siguiente ejemplo de código se utilizan varios parámetros de consulta.


qldbDriver.execute(txn -> {
    try {
        Result result = txn.execute("SELECT * FROM Person WHERE GovId = ? AND FirstName = ?",
                MAPPER.writeValueAsIonValue("TOYENC486FH"),
                MAPPER.writeValueAsIonValue("Brent"));
        Person person = MAPPER.readValue(result.iterator().next(), Person.class);
        System.out.println(person.getFirstName()); // prints Brent
        System.out.println(person.getGovId()); // prints TOYENC486FH
    } catch (IOException e) {
        e.printStackTrace();
    }
});

En el siguiente ejemplo de código, se utiliza una lista de parámetros de consulta.


qldbDriver.execute(txn -> {
    try {
        final List<IonValue> parameters = new ArrayList<>();
        parameters.add(MAPPER.writeValueAsIonValue("TOYENC486FH"));
        parameters.add(MAPPER.writeValueAsIonValue("ROEE1"));
        parameters.add(MAPPER.writeValueAsIonValue("YH844"));
        Result result = txn.execute("SELECT * FROM Person WHERE GovId IN (?,?,?)", parameters);
        Person person = MAPPER.readValue(result.iterator().next(), Person.class);
        System.out.println(person.getFirstName()); // prints Brent
        System.out.println(person.getGovId()); // prints TOYENC486FH
    } catch (IOException e) {
        e.printStackTrace();
    }
});

nota

Cuando ejecuta una consulta sin una búsqueda indexada, se invoca un escaneo completo de la tabla. En este ejemplo, se recomienda tener un índice en el campo GovId para optimizar el rendimiento. Sin un índice en GovId, las consultas pueden tener más latencia y, además, provocar excepciones de conflictos de OCC o tiempos de espera de las transacciones.

Inserción de documentos

El siguiente ejemplo de código inserta los tipos de datos de Ion.


qldbDriver.execute(txn -> {
    // Check if a document with GovId:TOYENC486FH exists
    // This is critical to make this transaction idempotent
    Result result = txn.execute("SELECT * FROM Person WHERE GovId = ?",
            SYSTEM.newString("TOYENC486FH"));
    // Check if there is a result
    if (!result.iterator().hasNext()) {
        IonStruct person = SYSTEM.newEmptyStruct();
        person.put("GovId").newString("TOYENC486FH");
        person.put("FirstName").newString("Brent");
        // Insert the document
        txn.execute("INSERT INTO Person ?", person);
    }
});

El siguiente ejemplo de código inserta los tipos de datos de Ion.


qldbDriver.execute(txn -> {
    try {
        // Check if a document with GovId:TOYENC486FH exists
        // This is critical to make this transaction idempotent
        Result result = txn.execute("SELECT * FROM Person WHERE GovId = ?",
                MAPPER.writeValueAsIonValue("TOYENC486FH"));
        // Check if there is a result
        if (!result.iterator().hasNext()) {
            // Insert the document
            txn.execute("INSERT INTO Person ?",
                    MAPPER.writeValueAsIonValue(new Person("Brent", "TOYENC486FH")));
        }
    } catch (IOException e) {
        e.printStackTrace();
    }
});

Esta transacción inserta un documento en la tabla Person. Antes de insertar, compruebe primero si el documento ya existe en la tabla. Esta comprobación hace que la transacción sea de naturaleza idempotente. Incluso si realiza esta transacción varias veces, no provocará ningún efecto secundario no deseado.

nota

En este ejemplo, se recomienda tener un índice en el campo GovId para optimizar el rendimiento. Sin un índice en GovId, las instrucciones pueden tener más latencia y, además, provocar excepciones de conflictos de OCC o tiempos de espera de las transacciones.

Insertar varios documentos en una instrucción

Para insertar varios documentos mediante una sola instrucción INSERT, puede pasar un parámetro del tipo Ion list (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.

El método TransactionExecutor.execute está sobrecargado. Acepta un número variable de argumentos IonValue (varargs) o un solo argumento List<IonValue>. En ion-java, IonList se implementa como List<IonValue>.

Java utiliza de forma predeterminada la implementación de método más específica cuando se llama a un método sobrecargado. En este caso, al pasar un parámetro IonList, el valor predeterminado es el método que toma un List<IonValue>. Cuando se invoca, la implementación de este método pasa los elementos IonValue de la lista como valores distintos. Por lo tanto, para invocar el método varargs en su lugar, debe convertir explícitamente un parámetro IonList a IonValue.

Actualización de documentos


qldbDriver.execute(txn -> {
    final List<IonValue> parameters = new ArrayList<>();
    parameters.add(SYSTEM.newString("John"));
    parameters.add(SYSTEM.newString("TOYENC486FH"));
    txn.execute("UPDATE Person SET FirstName = ? WHERE GovId = ?", parameters);
});


qldbDriver.execute(txn -> {
    try {
        final List<IonValue> parameters = new ArrayList<>();
        parameters.add(MAPPER.writeValueAsIonValue("John"));
        parameters.add(MAPPER.writeValueAsIonValue("TOYENC486FH"));
        txn.execute("UPDATE Person SET FirstName = ? WHERE GovId = ?", parameters);
    } catch (IOException e) {
        e.printStackTrace();
    }
});

nota

Eliminación de documentos


qldbDriver.execute(txn -> {
    txn.execute("DELETE FROM Person WHERE GovId = ?",
            SYSTEM.newString("TOYENC486FH"));
});


qldbDriver.execute(txn -> {
    try {
        txn.execute("DELETE FROM Person WHERE GovId = ?",
                MAPPER.writeValueAsIonValue("TOYENC486FH"));
    } catch (IOException e) {
        e.printStackTrace();
    }
});

nota

Ejecutar varias instrucciones en una transacción


// This code snippet is intentionally trivial. In reality you wouldn't do this because you'd
// set your UPDATE to filter on vin and insured, and check if you updated something or not.
public static boolean InsureCar(QldbDriver qldbDriver, final String vin) {
    final IonSystem ionSystem = IonSystemBuilder.standard().build();
    final IonString ionVin = ionSystem.newString(vin);

    return qldbDriver.execute(txn -> {
        Result result = txn.execute(
                "SELECT insured FROM Vehicles WHERE vin = ? AND insured = FALSE",
                ionVin);
        if (!result.isEmpty()) {
            txn.execute("UPDATE Vehicles SET insured = TRUE WHERE vin = ?", ionVin);
            return true;
        }
        return false;
    });
}

Lógica de reintentos

El método del controlador execute tiene un mecanismo de reintento integrado que reintenta la transacción si se produce una excepción que se pueda volver a intentar (como tiempos de espera o conflictos de OCC).

2.x

El número máximo de reintentos y la estrategia de retardo se pueden configurar.

El límite de reintentos predeterminado es 4 y la estrategia de retardo predeterminada es DefaultQldbTransactionBackoffStrategy. Puede establecer la configuración de reintentos por instancia de controlador y también por transacción mediante una instancia de RetryPolicy.

El siguiente ejemplo de código especifica la lógica de reintentos con un límite de reintentos personalizado y una estrategia de retardo personalizada para una instancia del controlador.


public void retry() {
    QldbDriver qldbDriver = QldbDriver.builder()
            .ledger("vehicle-registration")
            .transactionRetryPolicy(RetryPolicy.builder()
                    .maxRetries(2)
                    .backoffStrategy(new CustomBackOffStrategy()).build())
            .sessionClientBuilder(QldbSessionClient.builder())
            .build();
}

private class CustomBackOffStrategy implements BackoffStrategy {

    @Override
    public Duration calculateDelay(RetryPolicyContext retryPolicyContext) {
        return Duration.ofMillis(1000 * retryPolicyContext.retriesAttempted());
    }
}

El siguiente ejemplo de código especifica la lógica de reintentos con un límite de reintentos personalizado y una estrategia de retardo personalizada para una transacción particular. Esta configuración execute anula la lógica de reintentos establecida para la instancia del controlador.


public void retry() {
    Result result = qldbDriver.execute(txn -> { txn.execute("SELECT * FROM Person WHERE GovId = ?",
            SYSTEM.newString("TOYENC486FH")); },
            RetryPolicy.builder()
                    .maxRetries(2)
                    .backoffStrategy(new CustomBackOffStrategy())
                    .build());
}

private class CustomBackOffStrategy implements BackoffStrategy {

    // Configuring a custom backoff which increases delay by 1s for each attempt.
    @Override
    public Duration calculateDelay(RetryPolicyContext retryPolicyContext) {
        return Duration.ofMillis(1000 * retryPolicyContext.retriesAttempted());
    }
}

1.x

El número máximo de reintentos se puede configurar. Puede configurar el límite de reintentos estableciendo la propiedad retryLimit al inicializar PooledQldbDriver.

El límite de reintentos predeterminado es de 4.

Implementación de restricciones de exclusividad

QLDB no admite índices únicos, pero puede implementar este comportamiento en su aplicación.

Suponga que desea implementar una restricción de exclusividad en el campo GovId de la tabla Person. Para ello, puede escribir una transacción que haga lo siguiente:

Afirmar que en la tabla no hay documentos existentes con un GovId especificado.
Insertar el documento si se aprueba la afirmación.

Si una transacción competidora supera la afirmación simultáneamente, solo una de las transacciones se confirmará correctamente. La otra transacción fallará y se producirá una excepción de conflicto de OCC.

En el siguiente ejemplo de código, se muestra cómo implementar esta lógica de restricción de exclusividad.


qldbDriver.execute(txn -> {
    Result result = txn.execute("SELECT * FROM Person WHERE GovId = ?",
            SYSTEM.newString("TOYENC486FH"));
    // Check if there is a result
    if (!result.iterator().hasNext()) {
        IonStruct person = SYSTEM.newEmptyStruct();
        person.put("GovId").newString("TOYENC486FH");
        person.put("FirstName").newString("Brent");
        // Insert the document
        txn.execute("INSERT INTO Person ?", person);
    }
});

nota

Trabajar con Amazon Ion

En QLDB, los datos de Amazon Ion se pueden procesar de varias formas. Puede utilizar los métodos integrados de la biblioteca Ion para crear y modificar documentos de forma flexible según sea necesario. O bien, puede utilizar el módulo de formato de datos Jackson de FasterXML para Ion a fin de mapear los documentos de Ion a modelos de objetos Java simples y antiguos (POJO).

En las siguientes secciones se proporcionan ejemplos de código del procesamiento de datos de Ion mediante ambas técnicas.

Contenido

Importación de los paquetes de Ion

Añada el artefacto ion-java como una dependencia en su proyecto de Java.

Importe los siguientes paquetes Ion.


import com.amazon.ion.IonStruct;
import com.amazon.ion.IonSystem;
import com.amazon.ion.system.IonSystemBuilder;

Añada el artefacto jackson-dataformat-ion como una dependencia en su proyecto de Java. La QLDB requiere una versión 2.10.0 o posterior.

Importe los siguientes paquetes Ion.


import com.amazon.ion.IonReader;
import com.amazon.ion.IonStruct;
import com.amazon.ion.system.IonReaderBuilder;
import com.amazon.ion.system.IonSystemBuilder;

import com.fasterxml.jackson.dataformat.ion.IonObjectMapper;
import com.fasterxml.jackson.dataformat.ion.ionvalue.IonValueMapper;

Inicialización de Ion


IonSystem SYSTEM = IonSystemBuilder.standard().build();


IonObjectMapper MAPPER = new IonValueMapper(IonSystemBuilder.standard().build());

Creación de objetos de Ion

El siguiente ejemplo de código crea un objeto de Ion mediante la interfaz IonStruct y sus métodos integrados.


IonStruct ionStruct = SYSTEM.newEmptyStruct();

ionStruct.put("GovId").newString("TOYENC486FH");
ionStruct.put("FirstName").newString("Brent");

System.out.println(ionStruct.toPrettyString()); // prints a nicely formatted copy of ionStruct

Suponga que tiene una clase de modelo mapeada en JSON llamada Person, de la siguiente manera.


import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;

public static class Person {
    private final String firstName;
    private final String govId;

    @JsonCreator
    public Person(@JsonProperty("FirstName") final String firstName,
                  @JsonProperty("GovId") final String govId) {
        this.firstName = firstName;
        this.govId = govId;
    }

    @JsonProperty("FirstName")
    public String getFirstName() {
        return firstName;
    }

    @JsonProperty("GovId")
    public String getGovId() {
        return govId;
    }
}

El siguiente ejemplo de código crea un objeto IonStruct a partir de una instancia de Person.


IonStruct ionStruct = (IonStruct) MAPPER.writeValueAsIonValue(new Person("Brent", "TOYENC486FH"));

Lectura de objetos de Ion

El siguiente ejemplo de código imprime cada campo de la instancia ionStruct.


// ionStruct is an instance of IonStruct
System.out.println(ionStruct.get("GovId")); // prints TOYENC486FH
System.out.println(ionStruct.get("FirstName")); // prints Brent

El siguiente ejemplo de código lee un objeto IonStruct y lo asigna a una instancia de Person.


// ionStruct is an instance of IonStruct
IonReader reader = IonReaderBuilder.standard().build(ionStruct);
Person person = MAPPER.readValue(reader, Person.class);
System.out.println(person.getFirstName()); // prints Brent
System.out.println(person.getGovId()); // prints TOYENC486FH

Para obtener más información acerca de cómo trabajar con Ion, consulte la documentación de Amazon Ion en GitHub. Para ver más ejemplos de código sobre cómo trabajar con Ion en QLDB, consulte Uso de tipos de datos de Amazon Ion en Amazon QLDB.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Tutorial de inicio rápido

controlador .NET