Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Controlador de Amazon QLDB para Java **importante** Aviso de fin del soporte: los clientes actuales podrán utilizar Amazon QLDB hasta que finalice el soporte, el 31 de julio de 2025. Para obtener más información, consulte [Migración de un registro de Amazon QLDB a Amazon Aurora](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) PostgreSQL. Para trabajar con los datos de su libro mayor, puede conectarse a Amazon QLDB desde su aplicación Java mediante un controlador proporcionado. AWS En los siguientes temas se describe cómo empezar a usar el controlador de QLDB para Java. **Topics** + [Recursos de controladores](#getting-started.java.resources) + [Requisitos previos](#getting-started.java.prereqs) + [Configuración de la región y las credenciales de AWS predeterminadas](#getting-started.java.credentials) + [Instalación](#getting-started.java.install) + [Tutorial de inicio rápido](driver-quickstart-java.md) + [Referencia de libro de recetas](driver-cookbook-java.md) ## Recursos de controladores Para obtener más información sobre la funcionalidad compatible con el controlador de Java, consulte los siguientes recursos: + Referencia de API: [2.x](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/), [1.x](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/1.1.0/index.html) + [Código fuente del controlador () GitHub](https://github.com/awslabs/amazon-qldb-driver-java) + [Ejemplo de código fuente de la aplicación (GitHub)](https://github.com/aws-samples/amazon-qldb-dmv-sample-java) + [Marco Ledger Loader () GitHub](https://github.com/awslabs/amazon-qldb-ledger-load-java) + [Ejemplos de código de Amazon Ion](ion.code-examples.md) ## Requisitos previos Antes de empezar a usar el controlador de QLDB para Java, debe hacer lo siguiente: 1. Siga las instrucciones de AWS configuración que se indican en[Acceso a Amazon QLDB](accessing.md). Esta incluye lo siguiente: 1. Inscríbase en AWS. 1. Cree un usuario con los permisos de QLDB adecuados. 1. Conceda acceso programático de desarrollo. 1. Configure un entorno de desarrollo Java descargando e instalando lo siguiente: 1. Kit de desarrollo Java SE 8, como [Amazon Corretto 8](https://docs.aws.amazon.com/corretto/latest/corretto-8-ug/downloads-list.html). 1. (Opcional) Entorno de desarrollo integrado (IDE) Java de su elección, como [Eclipse](http://www.eclipse.org) o [IntelliJ](https://www.jetbrains.com/idea/). 1. Configura tu entorno de desarrollo para AWS SDK para Java ti[Configuración de la región y las credenciales de AWS predeterminadas](#getting-started.java.credentials). A continuación, puede descargar la aplicación de ejemplo completa del tutorial, o bien instalar solo el controlador en un proyecto de Java y ejecutar ejemplos de códigos cortos. + Para instalar el controlador QLDB y AWS SDK para Java en un proyecto existente, proceda a. [Instalación](#getting-started.java.install) + Para configurar un proyecto y ejecutar ejemplos de códigos cortos que muestren las transacciones de datos básicas en un libro mayor, consulte [Tutorial de inicio rápido](driver-quickstart-java.md). + Para ver ejemplos más detallados de las operaciones de la API de datos y administración en la aplicación de ejemplo completa del tutorial, consulte [Tutorial de Java](getting-started.java.tutorial.md). ## Configuración de la región y las credenciales de AWS predeterminadas El controlador QLDB y el [AWS SDK para Java](https://aws.amazon.com/sdk-for-java)subyacente requieren que AWS proporcione credenciales a su aplicación en tiempo de ejecución. En los ejemplos de código de esta guía se supone que se usa un archivo de credenciales de AWS , tal como se describe en [Configuración de las credenciales y la región predeterminadas](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html#setup-credentials) en la *Guía para desarrolladores de AWS SDK for Java 2.x *. Como parte de estos pasos, también debe establecer su valor predeterminado Región de AWS para determinar su punto final de QLDB predeterminado. Los ejemplos de código se conectan a QLDB en su Región de AWS predeterminada. Para ver una lista completa de las regiones donde QLDB está disponible, consulte [Puntos de conexión y cuotas de Amazon QLDB](https://docs.aws.amazon.com/general/latest/gr/qldb.html) en *Referencia general de AWS*. A continuación se muestra un ejemplo de un archivo de AWS credenciales denominado`~/.aws/credentials`, en el que la tilde (`~`) representa su directorio principal. ``` [default] aws_access_key_id = your_access_key_id aws_secret_access_key = your_secret_access_key ``` Sustituya los valores de sus propias AWS credenciales por los valores *your\$1access\$1key\$1id* y*your\$1secret\$1access\$1key*. ## Instalación QLDB admite las siguientes versiones del controlador Java y AWS sus dependencias del SDK. **** | Versión de controlador | AWS SDK | Estado | Fecha de lanzamiento más reciente | | --- | --- | --- | --- | | [1.x](https://search.maven.org/artifact/software.amazon.qldb/amazon-qldb-driver-java/1.1.0/jar) | AWS SDK para Java 1.x | Lanzamiento de producción | 20 de marzo de 2020 | | [2.x](https://search.maven.org/artifact/software.amazon.qldb/amazon-qldb-driver-java/2.3.1/jar) | AWS SDK for Java 2.x | Lanzamiento de producción | 4 de junio de 2021 | Para instalar el controlador de QLDB, se recomienda utilizar un sistema de administración de dependencias, como Gradle o Maven. Por ejemplo, añada el artefacto siguiente como dependencia en su proyecto Java. ------ #### [ 2.x ] **Gradle** Agregue esta dependencia a su archivo de configuración `build.gradle`. ``` dependencies { compile group: 'software.amazon.qldb', name: 'amazon-qldb-driver-java', version: '2.3.1' } ``` **Maven** Agregue esta dependencia a su archivo de configuración `pom.xml`. ``` software.amazon.qldb amazon-qldb-driver-java 2.3.1 ``` Este artefacto incluye automáticamente el módulo AWS SDK for Java 2.x principal, las bibliotecas [de Amazon Ion](ion.md) y otras dependencias necesarias. ------ #### [ 1.x ] **Gradle** Agregue esta dependencia a su archivo de configuración `build.gradle`. ``` dependencies { compile group: 'software.amazon.qldb', name: 'amazon-qldb-driver-java', version: '1.1.0' } ``` **Maven** Agregue esta dependencia a su archivo de configuración `pom.xml`. ``` software.amazon.qldb amazon-qldb-driver-java 1.1.0 ``` Este artefacto incluye automáticamente el módulo AWS SDK para Java principal, las bibliotecas [de Amazon Ion](ion.md) y otras dependencias necesarias. **importante** **Espacio de nombres de Amazon Ion**: al importar las clases de Amazon Ion a su aplicación, debe usar el paquete que se encuentra debajo del espacio de nombres `com.amazon.ion`. AWS SDK para Java depende de otro paquete de Ion en el espacio de nombres `software.amazon.ion`, pero se trata de un paquete heredado que no es compatible con el controlador de QLDB. ------ Para ver ejemplos de códigos cortos sobre cómo ejecutar transacciones de datos básicos en un libro mayor, consulte [Referencia de libro de recetas](driver-cookbook-java.md). ### Otras bibliotecas opcionales Si lo desea, también puede agregar las bibliotecas útiles siguientes al proyecto. Estos artefactos son dependencias obligatorias en la aplicación de muestra [Tutorial de Java](getting-started.java.tutorial.md). 1. [aws-java-sdk-qldb](https://search.maven.org/artifact/com.amazonaws/aws-java-sdk-qldb/1.11.785/jar)— El módulo QLDB del. AWS SDK para Java La versión de QLDB mínima compatible actualmente es `1.11.785`. Utilice este módulo en su aplicación para interactuar directamente con las operaciones de la API de administración que se enumeran en [Referencia de la API de Amazon QLDB](api-reference.md). 1. [jackson-dataformat-ion](https://search.maven.org/artifact/com.fasterxml.jackson.dataformat/jackson-dataformat-ion/2.10.0/bundle)— El módulo de formato de datos Jackson de FasterXML para Ion. La aplicación de ejemplo requiere una versión `2.10.0` o posterior. ------ #### [ Gradle ] Agregue estas dependencias a su archivo de configuración `build.gradle`. ``` dependencies { compile group: 'com.amazonaws', name: 'aws-java-sdk-qldb', version: '1.11.785' compile group: 'com.fasterxml.jackson.dataformat', name: 'jackson-dataformat-ion', version: '2.10.0' } ``` ------ #### [ Maven ] Agregue estas dependencias a su archivo de configuración `pom.xml`. ``` com.amazonaws aws-java-sdk-qldb 1.11.785 com.fasterxml.jackson.dataformat jackson-dataformat-ion 2.10.0 ``` ------ # Controlador de Amazon QLDB para Java: tutorial de inicio rápido **importante** Aviso de fin del soporte: los clientes actuales podrán utilizar Amazon QLDB hasta que finalice el soporte, el 31 de julio de 2025. Para obtener más información, consulte [Migración de un registro de Amazon QLDB a Amazon Aurora](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) PostgreSQL. En este tutorial aprenderá a configurar una aplicación sencilla con la versión más reciente del controlador de 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](getting-started.java.tutorial.md). **Topics** + [Requisitos previos](#driver-quickstart-java.prereqs) + [Paso 1: Configuración del proyecto](#driver-quickstart-java.step-1) + [Paso 2: inicializar el controlador](#driver-quickstart-java.step-2) + [Paso 3: crear una tabla y un índice](#driver-quickstart-java.step-3) + [Paso 4: insertar un documento](#driver-quickstart-java.step-4) + [Paso 5: consulta del documento](#driver-quickstart-java.step-5) + [Paso 6: actualizar el documento](#driver-quickstart-java.step-6) + [Ejecución de la aplicación completa](#driver-quickstart-java.complete) ## Requisitos previos Antes de comenzar, asegúrese de que hace lo siguiente: 1. Si aún no lo ha hecho, complete el [Requisitos previos](getting-started.java.md#getting-started.java.prereqs) para el controlador de Java. Esto incluye la inscripción AWS, la concesión de acceso programático para el desarrollo y la instalación de un entorno de desarrollo integrado (IDE) de Java. 1. 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](ledger-management.basics.md) o [Paso 1: crear un nuevo libro mayor](getting-started-step-1.md) 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](https://maven.apache.org/index.html) 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](#driver-quickstart-java.step-2). 1. Cree una carpeta para su aplicación. ``` $ mkdir myproject $ cd myproject ``` 1. Introduzca el siguiente comando para inicializar el proyecto a partir de una plantilla de Maven. Sustituya *project-package**project-name*, y *maven-template* por sus propios valores, según proceda. ``` $ mvn archetype:generate -DgroupId=project-package \ -DartifactId=project-name \ -DarchetypeArtifactId=maven-template \ -DinteractiveMode=false ``` Para *maven-template* ello, puede utilizar la plantilla básica de Maven: `maven-archetype-quickstart` 1. Para añadir el [controlador de QLDB para Java](https://search.maven.org/artifact/software.amazon.qldb/amazon-qldb-driver-java/2.3.1/jar) como una dependencia del proyecto, navegue hasta el archivo `pom.xml` recién creado y añada el siguiente artefacto. ``` software.amazon.qldb amazon-qldb-driver-java 2.3.1 ``` Este artefacto incluye automáticamente el módulo principal [AWS SDK for Java 2.x](https://aws.amazon.com/sdk-for-java), las bibliotecas de [Amazon Ion](ion.md) y otras dependencias necesarias. El archivo `pom.xml` debe ser similar al siguiente. ``` 4.0.0 software.amazon.qldb qldb-quickstart jar 1.0-SNAPSHOT qldb-quickstart http://maven.apache.org junit junit 3.8.1 test software.amazon.qldb amazon-qldb-driver-java 2.3.1 ``` 1. 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. O bien, puede omitir el step-by-step tutorial y ejecutar la [aplicación completa](#driver-quickstart-java.complete). ## 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](ql-reference.create-index.md) son necesarios para optimizar el rendimiento de las consultas y ayudar a limitar las excepciones de conflicto de [control de concurrencia optimista (OCC)](concurrency.md). ``` // 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`. QLDB es compatible con el lenguaje de consultas [PartiQL](ql-reference.md) (compatible con SQL) y el formato de datos [Amazon Ion](ion.md) (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](ql-reference.insert.md) sentencia, puede pasar un parámetro de tipo [IonList](driver-working-with-ion.md#driver-ion-list)(definido explícitamente como tal`IonValue`) 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 parameters = new ArrayList<>(); parameters.add(ionSys.newInt(42)); parameters.add(ionSys.newString("Doe")); txn.execute("UPDATE People SET age = ? WHERE lastName = ?", parameters); }); ``` 1. 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 }); ``` 1. 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, *project-package* sustitúyalo por el `groupId` valor que utilizó para el comando de Maven. [Paso 1: Configuración del proyecto](#driver-quickstart-java.step-1) ``` 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 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`. # Controlador de Amazon QLDB para Java: libro de recetas de referencia **importante** Aviso de fin del soporte: los clientes actuales podrán utilizar Amazon QLDB hasta que finalice el soporte, el 31 de julio de 2025. Para obtener más información, consulte [Migración de un registro de Amazon QLDB a Amazon Aurora](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) PostgreSQL. Esta guía de referencia muestra los casos de uso más comunes del controlador de 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). También incluye ejemplos de código para procesar datos de Amazon Ion. Además, esta guía destaca las prácticas recomendadas 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 de QLDB para Java. **Contents** + [Importación del controlador](#cookbook-java.importing) + [Instanciación del controlador](#cookbook-java.instantiating) + [Operaciones CRUD](#cookbook-java.crud) + [Creación de tablas](#cookbook-java.crud.creating-tables) + [Creación de índices](#cookbook-java.crud.creating-indexes) + [Lectura de documentos](#cookbook-java.crud.reading) + [Inserción de documentos](#cookbook-java.crud.inserting) + [Insertar varios documentos en una instrucción](#cookbook-java.crud.inserting.multiple) + [Actualización de documentos](#cookbook-java.crud.updating) + [Eliminación de documentos](#cookbook-java.crud.deleting) + [Ejecutar varias instrucciones en una transacción](#cookbook-java.crud.multi-statement) + [Lógica de reintentos](#cookbook-java.crud.retry-logic) + [Implementación de restricciones de exclusividad](#cookbook-java.crud.uniqueness-constraints) + [Trabajar con Amazon Ion](#cookbook-java.ion) + [Importación de los paquetes de Ion](#cookbook-java.ion.importing) + [Inicialización de Ion](#cookbook-java.ion.initializing) + [Creación de objetos de Ion](#cookbook-java.ion.creating) + [Lectura de objetos de Ion](#cookbook-java.ion.reading) ## 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. ------ #### [ 2.x ] ``` import com.amazon.ion.IonStruct; import com.amazon.ion.IonSystem; import com.amazon.ion.IonValue; import com.amazon.ion.system.IonSystemBuilder; import software.amazon.awssdk.services.qldbsession.QldbSessionClient; import software.amazon.qldb.QldbDriver; import software.amazon.qldb.Result; ``` ------ #### [ 1.x ] ``` import com.amazon.ion.IonStruct; import com.amazon.ion.IonSystem; import com.amazon.ion.IonValue; import com.amazon.ion.system.IonSystemBuilder; import com.amazonaws.services.qldbsession.AmazonQLDBSessionClientBuilder; import software.amazon.qldb.PooledQldbDriver; import software.amazon.qldb.Result; ``` ------ ## 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](#cookbook-java.crud.retry-logic) 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](#cookbook-java.ion). ------ #### [ 2.x ] ``` QldbDriver qldbDriver = QldbDriver.builder() .ledger("vehicle-registration") .transactionRetryPolicy(RetryPolicy .builder() .maxRetries(3) .build()) .sessionClientBuilder(QldbSessionClient.builder()) .build(); IonSystem SYSTEM = IonSystemBuilder.standard().build(); ``` ------ #### [ 1.x ] ``` PooledQldbDriver qldbDriver = PooledQldbDriver.builder() .withLedger("vehicle-registration") .withRetryLimit(3) .withSessionClientBuilder(AmazonQLDBSessionClientBuilder.standard()) .build(); IonSystem SYSTEM = IonSystemBuilder.standard().build(); ``` ------ ## Operaciones CRUD La QLDB ejecuta operaciones de *creación, lectura, actualización y eliminación* (CRUD) 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 QLDB confirma correctamente la transacción en el 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* en 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](concurrency.md). **Transacciones creadas de forma implícita** El método [QldbDriver.execute](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/software/amazon/qldb/QldbDriver.html) acepta una función lambda que recibe una instancia de [Executor, que puede utilizar para ejecutar sentencias](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/software/amazon/qldb/Executor.html). 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](#cookbook-java.ion). **Contents** + [Creación de tablas](#cookbook-java.crud.creating-tables) + [Creación de índices](#cookbook-java.crud.creating-indexes) + [Lectura de documentos](#cookbook-java.crud.reading) + [Inserción de documentos](#cookbook-java.crud.inserting) + [Insertar varios documentos en una instrucción](#cookbook-java.crud.inserting.multiple) + [Actualización de documentos](#cookbook-java.crud.updating) + [Eliminación de documentos](#cookbook-java.crud.deleting) + [Ejecutar varias instrucciones en una transacción](#cookbook-java.crud.multi-statement) + [Lógica de reintentos](#cookbook-java.crud.retry-logic) + [Implementación de restricciones de exclusividad](#cookbook-java.crud.uniqueness-constraints) ### 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 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 }); ``` #### Uso del mapeador Jackson ``` // 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 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](ql-reference.create-index.md) 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); } }); ``` #### Uso del mapeador Jackson 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 [INSERT](ql-reference.insert.md) sentencia, puede pasar un parámetro de tipo [IonList](driver-working-with-ion.md#driver-ion-list)(definido explícitamente como tal`IonValue`) 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*. ##### ¿Por qué se requiere una conversión explícita? El método [TransactionExecutor.execute](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/software/amazon/qldb/TransactionExecutor.html) está sobrecargado. Acepta un número variable de argumentos `IonValue` (*varargs*) o un solo argumento `List`. En [ion-java](https://www.javadoc.io/doc/com.amazon.ion/ion-java/latest/index.html), `IonList` se implementa como `List`. 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`. 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 parameters = new ArrayList<>(); parameters.add(SYSTEM.newString("John")); parameters.add(SYSTEM.newString("TOYENC486FH")); txn.execute("UPDATE Person SET FirstName = ? WHERE GovId = ?", parameters); }); ``` #### Uso del mapeador Jackson ``` qldbDriver.execute(txn -> { try { final List 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** 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. ### Eliminación de documentos ``` qldbDriver.execute(txn -> { txn.execute("DELETE FROM Person WHERE GovId = ?", SYSTEM.newString("TOYENC486FH")); }); ``` #### Uso del mapeador Jackson ``` qldbDriver.execute(txn -> { try { txn.execute("DELETE FROM Person WHERE GovId = ?", MAPPER.writeValueAsIonValue("TOYENC486FH")); } catch (IOException e) { e.printStackTrace(); } }); ``` **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. ### 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 y la `4` estrategia de retroceso predeterminada es. [DefaultQldbTransactionBackoffStrategy](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/software/amazon/qldb/DefaultQldbTransactionBackoffStrategy.html) Puede establecer la configuración de reintentos por instancia de controlador y también por transacción mediante una instancia de. [RetryPolicy](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/software/amazon/qldb/RetryPolicy.html) 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: 1. Afirme que en la tabla no hay documentos existentes con un `GovId` especificado. 1. 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** 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. ## 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](https://github.com/amzn/ion-java) 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](https://github.com/FasterXML/jackson-dataformats-binary/tree/master/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. **Contents** + [Importación de los paquetes de Ion](#cookbook-java.ion.importing) + [Inicialización de Ion](#cookbook-java.ion.initializing) + [Creación de objetos de Ion](#cookbook-java.ion.creating) + [Lectura de objetos de Ion](#cookbook-java.ion.reading) ### Importación de los paquetes de Ion Añada el artefacto [ion-java](https://search.maven.org/artifact/com.amazon.ion/ion-java/1.6.1/bundle) como una dependencia en su proyecto de Java. ------ #### [ Gradle ] ``` dependencies { compile group: 'com.amazon.ion', name: 'ion-java', version: '1.6.1' } ``` ------ #### [ Maven ] ``` com.amazon.ion ion-java 1.6.1 ``` ------ Importe los siguientes paquetes Ion. ``` import com.amazon.ion.IonStruct; import com.amazon.ion.IonSystem; import com.amazon.ion.system.IonSystemBuilder; ``` #### Uso del mapeador Jackson Agregue el artefacto [jackson-dataformat-ion](https://search.maven.org/artifact/com.fasterxml.jackson.dataformat/jackson-dataformat-ion/2.10.0/bundle)como una dependencia en su proyecto de Java. La QLDB requiere una versión `2.10.0` o posterior. ------ #### [ Gradle ] ``` dependencies { compile group: 'com.fasterxml.jackson.dataformat', name: 'jackson-dataformat-ion', version: '2.10.0' } ``` ------ #### [ Maven ] ``` com.fasterxml.jackson.dataformat jackson-dataformat-ion 2.10.0 ``` ------ 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(); ``` #### Uso del mapeador Jackson ``` 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 ``` #### Uso del mapeador Jackson 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 ``` #### Uso del mapeador Jackson 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 sobre cómo trabajar con Ion, consulte la [documentación de Amazon Ion](http://amzn.github.io/ion-docs/) 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](driver-working-with-ion.md).