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.
# Tutorial 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.
En esta implementación de la aplicación de ejemplo del tutorial, utilizará el controlador Amazon QLDB con AWS SDK para Java el para crear un libro mayor de QLDB y rellenarlo con datos de ejemplo.
Mientras realiza este tutorial, puede consultar la [Referencia de la API de AWS SDK para Java](https://docs.aws.amazon.com/sdk-for-java/latest/reference/). Para las operaciones de datos transaccionales, puede consultar el [controlador de QLDB para la referencia de la API de Java.](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/index.html)
**nota**
Cuando proceda, algunos pasos del tutorial incluyen comandos o ejemplos de código diferentes para cada versión principal compatible del controlador de QLDB para Java.
**Topics**
+ [Instalación de la aplicación de ejemplo Java de Amazon QLDB](sample-app.java.md)
+ [Paso 1: Crear un nuevo libro mayor](getting-started.java.step-1.md)
+ [Paso 2: probar la conectividad con el libro mayor](getting-started.java.step-2.md)
+ [Paso 3: cree tablas, índices y datos de muestra](getting-started.java.step-3.md)
+ [Paso 4: consultar las tablas en un libro mayor](getting-started.java.step-4.md)
+ [Paso 5: modificar los documentos de un libro mayor](getting-started.java.step-5.md)
+ [Paso 6: ver el historial de revisiones de un documento](getting-started.java.step-6.md)
+ [Paso 7: verificar un documento en un libro mayor](getting-started.java.step-7.md)
+ [Paso 8: exportar y validar los datos del diario en un libro mayor](getting-started.java.step-8.md)
+ [Paso 9 (opcional): limpiar recursos](getting-started.java.step-9.md)
# Instalación de la aplicación de ejemplo Java de Amazon QLDB
**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 esta sección se describe cómo instalar y ejecutar la aplicación de ejemplo de Amazon QLDB proporcionada para step-by-step el tutorial de Java. El caso de uso de esta aplicación de ejemplo es una base de datos del Departamento de Vehículos Automóviles (DMV) que rastrea la información histórica completa de las matriculaciones de vehículos.
[La aplicación de ejemplo del DMV para Java es de código abierto y se encuentra en el GitHub repositorio aws-samples/ -java. amazon-qldb-dmv-sample](https://github.com/aws-samples/amazon-qldb-dmv-sample-java)
## Requisitos previos
Antes de comenzar, asegúrese de completar el controlador de QLDB para Java [Requisitos previos](getting-started.java.md#getting-started.java.prereqs). Esta incluye lo siguiente:
1. AWS Inscríbase en.
1. Cree un usuario con los permisos de QLDB adecuados. Para completar todos los pasos de este tutorial, necesitará acceso administrativo completo a su recurso de libro mayor a través de la API de QLDB.
1. Si está utilizando un IDE que no sea AWS Cloud9, instale Java y conceda acceso programático para el desarrollo.
## Instalación
Los siguientes pasos describen cómo descargar y configurar la aplicación de muestra en un entorno de desarrollo local. O bien, puede automatizar la configuración de la aplicación de muestra utilizándola AWS Cloud9 como IDE y una CloudFormation plantilla para aprovisionar los recursos de desarrollo.
### Entorno de desarrollo local
Estas instrucciones describen cómo descargar e instalar la aplicación de ejemplo Java de QLDB usando sus propios recursos y entorno de desarrollo.
**Para descargar y ejecutar la aplicación de muestra**
1. Introduzca el siguiente comando desde el que desea clonar la aplicación de muestra GitHub.
------
#### [ 2.x ]
```
git clone https://github.com/aws-samples/amazon-qldb-dmv-sample-java.git
```
------
#### [ 1.x ]
```
git clone -b v1.2.0 https://github.com/aws-samples/amazon-qldb-dmv-sample-java.git
```
------
Este paquete incluye la configuración de Gradle y el código completo de [Tutorial de Java](getting-started.java.tutorial.md).
1. Cargue y ejecute la aplicación proporcionada.
+ Si usa Eclipse:
1. Inicie Eclipse y, en el menú de **Eclipse**, seleccione **Archivo**, **Importar** y, a continuación, **Proyecto de Gradle existente**.
1. En el directorio raíz del proyecto, busque y seleccione el directorio de aplicación que contiene el archivo `build.gradle`. A continuación, seleccione **Finalizar** para usar la configuración predeterminada de Gradle para la importación.
1. Puede ejecutar el programa `ListLedgers` a modo de ejemplo. Abra el menú contextual (clic derecho) del archivo `ListLedgers.java` y seleccione **Ejecutar como aplicación Java**.
+ Si usa IntelliJ:
1. Inicie IntelliJ y, en el menú de **IntelliJ**, seleccione **Archivo** y, a continuación, **Abrir**.
1. En el directorio raíz del proyecto, busque y seleccione el directorio de aplicación que contiene el archivo `build.gradle`. A continuación, seleccione **Aceptar**. Mantenga la configuración predeterminada y vuelva a seleccionar **Aceptar**.
1. Puede ejecutar el programa `ListLedgers` a modo de ejemplo. Abra el menú contextual (haga clic con el botón derecho) del `ListLedgers.java` archivo y seleccione **Ejecutar 'ListLedgers'**.
1. Continúe a [Paso 1: Crear un nuevo libro mayor](getting-started.java.step-1.md) para iniciar el tutorial y crear un libro mayor.
### AWS Cloud9
Estas instrucciones describen cómo automatizar la configuración de la aplicación de ejemplo de registro de vehículos de Amazon QLDB para Java, usando [AWS Cloud9](https://aws.amazon.com/cloud9) como IDE. En esta guía, usará una plantilla de [CloudFormation](https://aws.amazon.com/cloudformation) para aprovisionar sus recursos de desarrollo.
Para obtener más información al respecto AWS Cloud9, consulte la Guía del [AWS Cloud9 usuario](https://docs.aws.amazon.com/cloud9/latest/user-guide/). Para obtener más información sobre CloudFormation, consulte la [Guía del usuario de AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/).
**Topics**
+ [Parte 1: aprovisione sus recursos](#sample-app.java.cfn-ac9.step-1)
+ [Parte 2: configure el IDE](#sample-app.java.cfn-ac9.step-2)
+ [Parte 3: ejecute la aplicación de ejemplo QLDB DMV](#sample-app.java.cfn-ac9.step-3)
#### Parte 1: aprovisione sus recursos
En este primer paso, debe CloudFormation aprovisionar los recursos necesarios para configurar su entorno de desarrollo con la aplicación de ejemplo Amazon QLDB.
**Para abrir la CloudFormation consola y cargar la plantilla de aplicación de ejemplo QLDB**
1. [Inicie sesión Consola de administración de AWS y abra la CloudFormation consola en /cloudformation. https://console.aws.amazon.com](https://console.aws.amazon.com/cloudformation/)
Cambie a una región compatible con QLDB. Para obtener una lista completa, 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*. La siguiente captura de pantalla Consola de administración de AWS muestra el este de EE. UU. (Virginia del Norte) como seleccionado. Región de AWS
![\[Consola de administración de AWS mostrando EE.UU. Este (Norte de Virginia) como seleccionado Región de AWS.\]](http://docs.aws.amazon.com/es_es/qldb/latest/developerguide/images/cfn-ac9/aws-region-us-east-1.png)
1. En la CloudFormation consola, selecciona **Crear pila** y, a continuación, selecciona **Con nuevos recursos (estándar)**.
1. En la página **Crear pila**, en **Especificar plantilla**, elija **URL de Amazon S3**.
1. Introduzca la siguiente URL y seleccione **Siguiente**.
```
https://amazon-qldb-assets.s3.amazonaws.com/templates/QLDB-DMV-SampleApp.yml
```
1. Introduzca un **nombre de pila** (por ejemplo, **qldb-sample-app**) y elija **Siguiente**.
1. Puede añadir las etiquetas que desee y mantener las opciones predeterminadas. A continuación, elija **Siguiente**.
1. Revise la configuración de su pila y seleccione **Crear pila**. Es posible que el CloudFormation script tarde unos minutos en finalizar.
Este script aprovisiona su AWS Cloud9 entorno con una instancia de Amazon Elastic Compute Cloud (Amazon EC2) asociada que utilizará para ejecutar la aplicación de ejemplo de QLDB en este tutorial. También clona el repositorio [aws-samples/ amazon-qldb-dmv-sample -java](https://github.com/aws-samples/amazon-qldb-dmv-sample-java/) desde su entorno de desarrollo. GitHub AWS Cloud9
#### Parte 2: configure el IDE
En este paso, terminará de configurar el entorno de desarrollo en la nube. Debe descargar y ejecutar un script de shell proporcionado para configurar su AWS Cloud9 IDE con las dependencias de la aplicación de muestra.
**Para configurar su entorno AWS Cloud9**
1. Abra la AWS Cloud9 consola en [https://console.aws.amazon.com/cloud9/](https://console.aws.amazon.com/cloud9/).
1. En **Sus entornos**, busque la tarjeta de entorno denominada **QLDB DMV Sample Application** y seleccione **Open IDE**. Es posible que su entorno tarde un minuto en cargarse a medida que se lanza la EC2 instancia subyacente.
Su AWS Cloud9 entorno está preconfigurado con las dependencias del sistema que necesita para ejecutar el tutorial. En el panel de navegación **Entorno** de la consola, confirme que ve una carpeta con el nombre `QLDB DMV Sample Application`. La siguiente captura de pantalla de la consola AWS Cloud9 muestra el panel de carpetas del entorno QLDB DMV Sample Application.
![\[AWS Cloud9 consola que muestra el panel de carpetas del entorno QLDB DMV Sample Application.\]](http://docs.aws.amazon.com/es_es/qldb/latest/developerguide/images/cfn-ac9/cloud9-folders.png)
Si no ve ningún panel de navegación, active la pestaña **Entorno**, en la parte izquierda de la consola. Si no ve ninguna carpeta en el panel, active **Mostrar raíz del entorno** en el icono de configuración (![\[Settings icon\]](http://docs.aws.amazon.com/es_es/qldb/latest/developerguide/images/settings.png)).
1. En el panel inferior de la consola, debería ver una ventana de terminal de `bash` abierta. Si no lo ve, seleccione **Nueva terminal** en el menú **Ventana** de la parte superior de la consola.
1. A continuación, descargue y ejecute un script de configuración para instalar OpenJDK 8 y, si procede, consulte la ramificación correspondiente del repositorio de Git. En la AWS Cloud9 terminal que creó en el paso anterior, ejecute los dos comandos siguientes en orden:
------
#### [ 2.x ]
```
aws s3 cp s3://amazon-qldb-assets/setup-scripts/dmv-setup-v2.sh .
```
```
sh dmv-setup-v2.sh
```
------
#### [ 1.x ]
```
aws s3 cp s3://amazon-qldb-assets/setup-scripts/dmv-setup.sh .
```
```
sh dmv-setup.sh
```
------
Al finalizar, debería ver el siguiente mensaje en la terminal:
```
** DMV Sample App setup completed , enjoy!! **
```
1. Dedique un momento a buscar el código de la aplicación de ejemplo AWS Cloud9, especialmente en la siguiente ruta de directorio:`src/main/java/software/amazon/qldb/tutorial`.
#### Parte 3: ejecute la aplicación de ejemplo QLDB DMV
En este paso, aprenderá a ejecutar las tareas de aplicación de ejemplo del DMV de Amazon QLDB utilizando. AWS Cloud9 Para ejecutar el código de ejemplo, vuelva a su AWS Cloud9 terminal o cree una nueva ventana de terminal, tal y como hizo en la *segunda parte: Configurar* su IDE.
**Para ejecutar las aplicaciones de ejemplo**
1. Ejecute el siguiente comando en su terminal para pasar al directorio raíz del proyecto:
```
cd ~/environment/amazon-qldb-dmv-sample-java
```
Asegúrese de ejecutar los ejemplos en la siguiente ruta de directorio.
```
/home/ec2-user/environment/amazon-qldb-dmv-sample-java/
```
1. El siguiente comando muestra la sintaxis de Gradle para ejecutar cada tarea.
```
./gradlew run -Dtutorial=Task
```
Por ejemplo, ejecuta el siguiente comando para enumerar todos los libros de contabilidad de tu región Cuenta de AWS y la actual.
```
./gradlew run -Dtutorial=ListLedgers
```
1. Continúe a [Paso 1: Crear un nuevo libro mayor](getting-started.java.step-1.md) para iniciar el tutorial y crear un libro mayor.
1. (Opcional) Tras completar el tutorial, limpie los recursos de CloudFormation si ya no los necesita.
1. Abre la CloudFormation consola en [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/) y elimina la pila que creaste en la *primera parte: Aprovisiona tus recursos*.
1. Elimine también la AWS Cloud9 pila que la CloudFormation plantilla creó para usted.
# Paso 1: Crear un nuevo libro mayor
**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 paso, creará un nuevo libro mayor de Amazon QLDB denominado `vehicle-registration`.
**Creación de un nuevo libro mayor**
1. Revise el siguiente archivo (`Constants.java`), que contiene valores constantes que utilizan todos los demás programas de este tutorial.
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonSystem;
import com.amazon.ion.system.IonSystemBuilder;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.dataformat.ion.IonObjectMapper;
import com.fasterxml.jackson.dataformat.ion.ionvalue.IonValueMapper;
/**
* Constant values used throughout this tutorial.
*/
public final class Constants {
public static final int RETRY_LIMIT = 4;
public static final String LEDGER_NAME = "vehicle-registration";
public static final String STREAM_NAME = "vehicle-registration-stream";
public static final String VEHICLE_REGISTRATION_TABLE_NAME = "VehicleRegistration";
public static final String VEHICLE_TABLE_NAME = "Vehicle";
public static final String PERSON_TABLE_NAME = "Person";
public static final String DRIVERS_LICENSE_TABLE_NAME = "DriversLicense";
public static final String VIN_INDEX_NAME = "VIN";
public static final String PERSON_GOV_ID_INDEX_NAME = "GovId";
public static final String VEHICLE_REGISTRATION_LICENSE_PLATE_NUMBER_INDEX_NAME = "LicensePlateNumber";
public static final String DRIVER_LICENSE_NUMBER_INDEX_NAME = "LicenseNumber";
public static final String DRIVER_LICENSE_PERSONID_INDEX_NAME = "PersonId";
public static final String JOURNAL_EXPORT_S3_BUCKET_NAME_PREFIX = "qldb-tutorial-journal-export";
public static final String USER_TABLES = "information_schema.user_tables";
public static final String LEDGER_NAME_WITH_TAGS = "tags";
public static final IonSystem SYSTEM = IonSystemBuilder.standard().build();
public static final IonObjectMapper MAPPER = new IonValueMapper(SYSTEM);
private Constants() { }
static {
MAPPER.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
}
}
```
------
#### [ 1.x ]
**importante**
Para el paquete Amazon Ion, debe usar el espacio de nombres `com.amazon.ion` de su aplicación. 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 QLDB.
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonSystem;
import com.amazon.ion.system.IonSystemBuilder;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.dataformat.ion.IonObjectMapper;
import com.fasterxml.jackson.dataformat.ion.ionvalue.IonValueMapper;
/**
* Constant values used throughout this tutorial.
*/
public final class Constants {
public static final int RETRY_LIMIT = 4;
public static final String LEDGER_NAME = "vehicle-registration";
public static final String STREAM_NAME = "vehicle-registration-stream";
public static final String VEHICLE_REGISTRATION_TABLE_NAME = "VehicleRegistration";
public static final String VEHICLE_TABLE_NAME = "Vehicle";
public static final String PERSON_TABLE_NAME = "Person";
public static final String DRIVERS_LICENSE_TABLE_NAME = "DriversLicense";
public static final String VIN_INDEX_NAME = "VIN";
public static final String PERSON_GOV_ID_INDEX_NAME = "GovId";
public static final String VEHICLE_REGISTRATION_LICENSE_PLATE_NUMBER_INDEX_NAME = "LicensePlateNumber";
public static final String DRIVER_LICENSE_NUMBER_INDEX_NAME = "LicenseNumber";
public static final String DRIVER_LICENSE_PERSONID_INDEX_NAME = "PersonId";
public static final String JOURNAL_EXPORT_S3_BUCKET_NAME_PREFIX = "qldb-tutorial-journal-export";
public static final String USER_TABLES = "information_schema.user_tables";
public static final String LEDGER_NAME_WITH_TAGS = "tags";
public static final IonSystem SYSTEM = IonSystemBuilder.standard().build();
public static final IonObjectMapper MAPPER = new IonValueMapper(SYSTEM);
private Constants() { }
static {
MAPPER.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
}
}
```
------
**nota**
Esta clase `Constants` incluye una instancia de la clase `IonValueMapper` Jackson de código abierto. Puede usar este mapeador para procesar sus datos de [Amazon Ion](ion.md) al realizar transacciones de lectura y escritura.
El archivo `CreateLedger.java` también depende del siguiente programa (`DescribeLedger.java`), que describe el estado actual de su libro mayor.
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.services.qldb.AmazonQLDB;
import com.amazonaws.services.qldb.model.DescribeLedgerRequest;
import com.amazonaws.services.qldb.model.DescribeLedgerResult;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* Describe a QLDB ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class DescribeLedger {
public static AmazonQLDB client = CreateLedger.getClient();
public static final Logger log = LoggerFactory.getLogger(DescribeLedger.class);
private DescribeLedger() { }
public static void main(final String... args) {
try {
describe(Constants.LEDGER_NAME);
} catch (Exception e) {
log.error("Unable to describe a ledger!", e);
}
}
/**
* Describe a ledger.
*
* @param name
* Name of the ledger to describe.
* @return {@link DescribeLedgerResult} from QLDB.
*/
public static DescribeLedgerResult describe(final String name) {
log.info("Let's describe ledger with name: {}...", name);
DescribeLedgerRequest request = new DescribeLedgerRequest().withName(name);
DescribeLedgerResult result = client.describeLedger(request);
log.info("Success. Ledger description: {}", result);
return result;
}
}
```
1. Compile y ejecute el programa `CreateLedger.java` para crear un libro mayor denominado `vehicle-registration`.
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.client.builder.AwsClientBuilder;
import com.amazonaws.services.qldb.AmazonQLDB;
import com.amazonaws.services.qldb.AmazonQLDBClientBuilder;
import com.amazonaws.services.qldb.model.CreateLedgerRequest;
import com.amazonaws.services.qldb.model.CreateLedgerResult;
import com.amazonaws.services.qldb.model.DescribeLedgerResult;
import com.amazonaws.services.qldb.model.LedgerState;
import com.amazonaws.services.qldb.model.PermissionsMode;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* Create a ledger and wait for it to be active.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class CreateLedger {
public static final Logger log = LoggerFactory.getLogger(CreateLedger.class);
public static final Long LEDGER_CREATION_POLL_PERIOD_MS = 10_000L;
public static String endpoint = null;
public static String region = null;
public static AmazonQLDB client = getClient();
private CreateLedger() {
}
/**
* Build a low-level QLDB client.
*
* @return {@link AmazonQLDB} control plane client.
*/
public static AmazonQLDB getClient() {
AmazonQLDBClientBuilder builder = AmazonQLDBClientBuilder.standard();
if (null != endpoint && null != region) {
builder.setEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration(endpoint, region));
}
return builder.build();
}
public static void main(final String... args) throws Exception {
try {
client = getClient();
create(Constants.LEDGER_NAME);
waitForActive(Constants.LEDGER_NAME);
} catch (Exception e) {
log.error("Unable to create the ledger!", e);
throw e;
}
}
/**
* Create a new ledger with the specified ledger name.
*
* @param ledgerName Name of the ledger to be created.
* @return {@link CreateLedgerResult} from QLDB.
*/
public static CreateLedgerResult create(final String ledgerName) {
log.info("Let's create the ledger with name: {}...", ledgerName);
CreateLedgerRequest request = new CreateLedgerRequest()
.withName(ledgerName)
.withPermissionsMode(PermissionsMode.ALLOW_ALL);
CreateLedgerResult result = client.createLedger(request);
log.info("Success. Ledger state: {}.", result.getState());
return result;
}
/**
* Wait for a newly created ledger to become active.
*
* @param ledgerName Name of the ledger to wait on.
* @return {@link DescribeLedgerResult} from QLDB.
* @throws InterruptedException if thread is being interrupted.
*/
public static DescribeLedgerResult waitForActive(final String ledgerName) throws InterruptedException {
log.info("Waiting for ledger to become active...");
while (true) {
DescribeLedgerResult result = DescribeLedger.describe(ledgerName);
if (result.getState().equals(LedgerState.ACTIVE.name())) {
log.info("Success. Ledger is active and ready to use.");
return result;
}
log.info("The ledger is still creating. Please wait...");
Thread.sleep(LEDGER_CREATION_POLL_PERIOD_MS);
}
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.services.qldb.AmazonQLDB;
import com.amazonaws.services.qldb.AmazonQLDBClientBuilder;
import com.amazonaws.services.qldb.model.CreateLedgerRequest;
import com.amazonaws.services.qldb.model.CreateLedgerResult;
import com.amazonaws.services.qldb.model.DescribeLedgerResult;
import com.amazonaws.services.qldb.model.LedgerState;
import com.amazonaws.services.qldb.model.PermissionsMode;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* Create a ledger and wait for it to be active.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class CreateLedger {
public static final Logger log = LoggerFactory.getLogger(CreateLedger.class);
public static final Long LEDGER_CREATION_POLL_PERIOD_MS = 10_000L;
public static AmazonQLDB client = getClient();
private CreateLedger() { }
/**
* Build a low-level QLDB client.
*
* @return {@link AmazonQLDB} control plane client.
*/
public static AmazonQLDB getClient() {
return AmazonQLDBClientBuilder.standard().build();
}
public static void main(final String... args) throws Exception {
try {
create(Constants.LEDGER_NAME);
waitForActive(Constants.LEDGER_NAME);
} catch (Exception e) {
log.error("Unable to create the ledger!", e);
throw e;
}
}
/**
* Create a new ledger with the specified ledger name.
*
* @param ledgerName
* Name of the ledger to be created.
* @return {@link CreateLedgerResult} from QLDB.
*/
public static CreateLedgerResult create(final String ledgerName) {
log.info("Let's create the ledger with name: {}...", ledgerName);
CreateLedgerRequest request = new CreateLedgerRequest()
.withName(ledgerName)
.withPermissionsMode(PermissionsMode.ALLOW_ALL);
CreateLedgerResult result = client.createLedger(request);
log.info("Success. Ledger state: {}.", result.getState());
return result;
}
/**
* Wait for a newly created ledger to become active.
*
* @param ledgerName
* Name of the ledger to wait on.
* @return {@link DescribeLedgerResult} from QLDB.
* @throws InterruptedException if thread is being interrupted.
*/
public static DescribeLedgerResult waitForActive(final String ledgerName) throws InterruptedException {
log.info("Waiting for ledger to become active...");
while (true) {
DescribeLedgerResult result = DescribeLedger.describe(ledgerName);
if (result.getState().equals(LedgerState.ACTIVE.name())) {
log.info("Success. Ledger is active and ready to use.");
return result;
}
log.info("The ledger is still creating. Please wait...");
Thread.sleep(LEDGER_CREATION_POLL_PERIOD_MS);
}
}
}
```
------
**nota**
En la llamada `createLedger`, debe especificar un nombre de libro mayor y un modo de permisos. Recomendamos encarecidamente el modo de permisos `STANDARD` para maximizar la seguridad de los datos del libro mayor.
Al crear un libro mayor, se habilita de forma predeterminada la *protección contra la eliminación*. Se trata de una característica de QLDB que impide que los libros mayores sean eliminados por cualquier usuario. Tiene la opción de deshabilitar la protección contra la eliminación al crear el libro mayor mediante la API QLDB o el (). AWS Command Line Interface AWS CLI
Si lo desea, también puede especificar etiquetas para adjuntar al libro mayor.
Para comprobar la conexión con el nuevo libro mayor, continúe con [Paso 2: probar la conectividad con el libro mayor](getting-started.java.step-2.md).
# Paso 2: probar la conectividad con el libro mayor
**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 paso, verifica que puede conectarse al libro mayor `vehicle-registration` de Amazon QLDB mediante el punto de conexión de la API de datos transaccionales.
**Para probar la conectividad con el libro mayor**
1. Utilice el siguiente programa (`ConnectToLedger.java`) para crear una conexión de sesión de datos con el libro mayor `vehicle-registration`.
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.net.URI;
import java.net.URISyntaxException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
import software.amazon.awssdk.services.qldbsession.QldbSessionClient;
import software.amazon.awssdk.services.qldbsession.QldbSessionClientBuilder;
import software.amazon.qldb.QldbDriver;
import software.amazon.qldb.RetryPolicy;
/**
* Connect to a session for a given ledger using default settings.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class ConnectToLedger {
public static final Logger log = LoggerFactory.getLogger(ConnectToLedger.class);
public static AwsCredentialsProvider credentialsProvider;
public static String endpoint = null;
public static String ledgerName = Constants.LEDGER_NAME;
public static String region = null;
public static QldbDriver driver;
private ConnectToLedger() {
}
/**
* Create a pooled driver for creating sessions.
*
* @param retryAttempts How many times the transaction will be retried in
* case of a retryable issue happens like Optimistic Concurrency Control exception,
* server side failures or network issues.
* @return The pooled driver for creating sessions.
*/
public static QldbDriver createQldbDriver(int retryAttempts) {
QldbSessionClientBuilder builder = getAmazonQldbSessionClientBuilder();
return QldbDriver.builder()
.ledger(ledgerName)
.transactionRetryPolicy(RetryPolicy
.builder()
.maxRetries(retryAttempts)
.build())
.sessionClientBuilder(builder)
.build();
}
/**
* Create a pooled driver for creating sessions.
*
* @return The pooled driver for creating sessions.
*/
public static QldbDriver createQldbDriver() {
QldbSessionClientBuilder builder = getAmazonQldbSessionClientBuilder();
return QldbDriver.builder()
.ledger(ledgerName)
.transactionRetryPolicy(RetryPolicy.builder()
.maxRetries(Constants.RETRY_LIMIT).build())
.sessionClientBuilder(builder)
.build();
}
/**
* Creates a QldbSession builder that is passed to the QldbDriver to connect to the Ledger.
*
* @return An instance of the AmazonQLDBSessionClientBuilder
*/
public static QldbSessionClientBuilder getAmazonQldbSessionClientBuilder() {
QldbSessionClientBuilder builder = QldbSessionClient.builder();
if (null != endpoint && null != region) {
try {
builder.endpointOverride(new URI(endpoint));
} catch (URISyntaxException e) {
throw new IllegalArgumentException(e);
}
}
if (null != credentialsProvider) {
builder.credentialsProvider(credentialsProvider);
}
return builder;
}
/**
* Create a pooled driver for creating sessions.
*
* @return The pooled driver for creating sessions.
*/
public static QldbDriver getDriver() {
if (driver == null) {
driver = createQldbDriver();
}
return driver;
}
public static void main(final String... args) {
Iterable tables = ConnectToLedger.getDriver().getTableNames();
log.info("Existing tables in the ledger:");
for (String table : tables) {
log.info("- {} ", table);
}
}
}
```
**nota**
Para ejecutar operaciones de datos en su libro mayor, debe crear una instancia de la clase `QldbDriver` para conectarse a un libro mayor específico. Se trata de un objeto de cliente diferente al cliente de `AmazonQLDB` que utilizó en el paso anterior para crear el libro mayor. Ese cliente anterior solo se usa para ejecutar las operaciones de la API de administración que se enumeran en [Referencia de la API de Amazon QLDB](api-reference.md).
En primer lugar, debe crear un objeto `QldbDriver`. Debe especificar un nombre de libro mayor al crear este controlador.
A continuación, puede utilizar el método `execute` de este controlador para ejecutar instrucciones PartiQL.
Si lo desea, puede especificar un número máximo de reintentos para las excepciones de transacción. El método `execute` reintenta automáticamente los conflictos de control de concurrencia optimista (OCC) y otras excepciones transitorias frecuentes hasta este límite configurable. El valor predeterminado es `4`.
Si la transacción sigue fallando una vez alcanzado el límite, el controlador lanza la excepción. Para obtener más información, consulte [Descripción de la política de reintentos del controlador en Amazon QLDB](driver-retry-policy.md).
------
#### [ 1.x ]
```
/*
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.auth.AWSCredentialsProvider;
import com.amazonaws.client.builder.AwsClientBuilder;
import com.amazonaws.services.qldbsession.AmazonQLDBSessionClientBuilder;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.PooledQldbDriver;
import software.amazon.qldb.QldbDriver;
import software.amazon.qldb.QldbSession;
import software.amazon.qldb.exceptions.QldbClientException;
/**
* Connect to a session for a given ledger using default settings.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class ConnectToLedger {
public static final Logger log = LoggerFactory.getLogger(ConnectToLedger.class);
public static AWSCredentialsProvider credentialsProvider;
public static String endpoint = null;
public static String ledgerName = Constants.LEDGER_NAME;
public static String region = null;
private static PooledQldbDriver driver;
private ConnectToLedger() {
}
/**
* Create a pooled driver for creating sessions.
*
* @return The pooled driver for creating sessions.
*/
public static PooledQldbDriver createQldbDriver() {
AmazonQLDBSessionClientBuilder builder = AmazonQLDBSessionClientBuilder.standard();
if (null != endpoint && null != region) {
builder.setEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration(endpoint, region));
}
if (null != credentialsProvider) {
builder.setCredentials(credentialsProvider);
}
return PooledQldbDriver.builder()
.withLedger(ledgerName)
.withRetryLimit(Constants.RETRY_LIMIT)
.withSessionClientBuilder(builder)
.build();
}
/**
* Create a pooled driver for creating sessions.
*
* @return The pooled driver for creating sessions.
*/
public static PooledQldbDriver getDriver() {
if (driver == null) {
driver = createQldbDriver();
}
return driver;
}
/**
* Connect to a ledger through a {@link QldbDriver}.
*
* @return {@link QldbSession}.
*/
public static QldbSession createQldbSession() {
return getDriver().getSession();
}
public static void main(final String... args) {
try (QldbSession qldbSession = createQldbSession()) {
log.info("Listing table names ");
for (String tableName : qldbSession.getTableNames()) {
log.info(tableName);
}
} catch (QldbClientException e) {
log.error("Unable to create session.", e);
}
}
}
```
**nota**
Para ejecutar operaciones de datos en su libro mayor, debe crear una instancia de la clase `PooledQldbDriver` o `QldbDriver` para conectarse a un libro mayor específico. Se trata de un objeto de cliente diferente al cliente de `AmazonQLDB` que utilizó en el paso anterior para crear el libro mayor. Ese cliente anterior solo se usa para ejecutar las operaciones de la API de administración que se enumeran en [Referencia de la API de Amazon QLDB](api-reference.md).
Recomendamos usar `PooledQldbDriver` a menos que necesite implementar un grupo de sesiones personalizado con `QldbDriver`. El tamaño predeterminado del grupo para `PooledQldbDriver` es el [número máximo de conexiones HTTP abiertas](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/ClientConfiguration.html#getMaxConnections--) que permite el cliente de sesión.
En primer lugar, debe crear un objeto `PooledQldbDriver`. Debe especificar un nombre de libro mayor al crear este controlador.
A continuación, puede utilizar el método `execute` de este controlador para ejecutar instrucciones PartiQL. O bien, puede crear manualmente una sesión a partir de este objeto controlador agrupado y utilizar el método `execute` de la sesión. Una sesión representa una conexión única con el libro mayor.
Si lo desea, puede especificar un número máximo de reintentos para las excepciones de transacción. El método `execute` reintenta automáticamente los conflictos de control de concurrencia optimista (OCC) y otras excepciones transitorias frecuentes hasta este límite configurable. El valor predeterminado es `4`.
Si la transacción sigue fallando una vez alcanzado el límite, el controlador lanza la excepción. Para obtener más información, consulte [Descripción de la política de reintentos del controlador en Amazon QLDB](driver-retry-policy.md).
------
1. Compila y ejecuta el programa `ConnectToLedger.java` para probar la conectividad de la sesión de datos con el libro mayor `vehicle-registration`.
**Anular el Región de AWS**
La aplicación de ejemplo se conecta a QLDB de Región de AWS forma predeterminada, que puede configurar como se describe en el paso previo. [Configuración de la región y las credenciales de AWS predeterminadas](getting-started.java.md#getting-started.java.credentials) Puede cambiar la región modificando las propiedades del constructor del cliente de sesión QLDB.
------
#### [ 2.x ]
En el siguiente ejemplo de código se crea una instancia de objeto de `QldbSessionClientBuilder` nuevo.
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.qldbsession.QldbSessionClientBuilder;
// This client builder will default to US East (Ohio)
QldbSessionClientBuilder builder = QldbSessionClient.builder()
.region(Region.US_EAST_2);
```
Puede usar el método `region` para ejecutar el código en QLDB en cualquier región donde se encuentre disponible. Para obtener una lista completa, 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*.
------
#### [ 1.x ]
En el siguiente ejemplo de código se crea una instancia de objeto de `AmazonQLDBSessionClientBuilder` nuevo.
```
import com.amazonaws.regions.Regions;
import com.amazonaws.services.qldbsession.AmazonQLDBSessionClientBuilder;
// This client builder will default to US East (Ohio)
AmazonQLDBSessionClientBuilder builder = AmazonQLDBSessionClientBuilder.standard()
.withRegion(Regions.US_EAST_2);
```
Puede usar el método `withRegion` para ejecutar el código en QLDB en cualquier región donde se encuentre disponible. Para obtener una lista completa, 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*.
------
Para crear tablas en el libro mayor `vehicle-registration`, continúe con [Paso 3: cree tablas, índices y datos de muestra](getting-started.java.step-3.md).
# Paso 3: cree tablas, índices y datos de muestra
**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.
Cuando su libro mayor de Amazon QLDB esté activo y acepte conexiones, podrá empezar a crear tablas con datos sobre los vehículos, sus propietarios y su información de registro. Tras crear las tablas y los índices, puede cargarlos con datos.
En este paso, creará cuatro tablas en el libro mayor `vehicle-registration`:
+ `VehicleRegistration`
+ `Vehicle`
+ `Person`
+ `DriversLicense`
También se crean los siguientes índices.
****
| Nombre de la tabla | Campo |
| --- | --- |
| VehicleRegistration | VIN |
| VehicleRegistration | LicensePlateNumber |
| Vehicle | VIN |
| Person | GovId |
| DriversLicense | LicenseNumber |
| DriversLicense | PersonId |
Al insertar datos de ejemplo, primero debe insertar los documentos en la tabla `Person`. A continuación, utilice los `id` asignados por el sistema de cada documento `Person` para rellenar los campos pertinentes en los documentos `VehicleRegistration` y `DriversLicense` correspondientes.
**sugerencia**
Como práctica recomendada, utilice un `id` de documento asignado por el sistema como clave externa. Si bien puede definir campos que pretenden ser identificadores únicos (por ejemplo, el VIN de un vehículo), el verdadero identificador único de un documento es su `id`. Este campo se incluye en los metadatos del documento, que puede consultar en la *vista confirmada* (la vista de una tabla definida por el sistema).
Para obtener más información acerca de las vistas en QLDB, consulte [Conceptos clave](ledger-structure.md). Para obtener más información sobre metadatos, consulte [Consulta de los metadatos del documento](working.metadata.md).
**Para configurar los datos de muestra**
1. Revise los siguientes archivos `.java`. Estas clases de modelos representan los documentos que ha almacenado en las tablas `vehicle-registration`. Se pueden serializar desde y hacia el formato Amazon Ion.
**nota**
Los [Documentos de Amazon QLDB](ql-reference.docs.md) se almacenan en formato Ion, que es un superconjunto de JSON. Por lo tanto, puede usar la biblioteca FasterXML Jackson para modelar los datos en JSON.
1. `DriversLicense.java`
```
/*
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import software.amazon.qldb.tutorial.model.streams.RevisionData;
import java.time.LocalDate;
/**
* Represents a driver's license, serializable to (and from) Ion.
*/
public final class DriversLicense implements RevisionData {
private final String personId;
private final String licenseNumber;
private final String licenseType;
@JsonSerialize(using = IonLocalDateSerializer.class)
@JsonDeserialize(using = IonLocalDateDeserializer.class)
private final LocalDate validFromDate;
@JsonSerialize(using = IonLocalDateSerializer.class)
@JsonDeserialize(using = IonLocalDateDeserializer.class)
private final LocalDate validToDate;
@JsonCreator
public DriversLicense(@JsonProperty("PersonId") final String personId,
@JsonProperty("LicenseNumber") final String licenseNumber,
@JsonProperty("LicenseType") final String licenseType,
@JsonProperty("ValidFromDate") final LocalDate validFromDate,
@JsonProperty("ValidToDate") final LocalDate validToDate) {
this.personId = personId;
this.licenseNumber = licenseNumber;
this.licenseType = licenseType;
this.validFromDate = validFromDate;
this.validToDate = validToDate;
}
@JsonProperty("PersonId")
public String getPersonId() {
return personId;
}
@JsonProperty("LicenseNumber")
public String getLicenseNumber() {
return licenseNumber;
}
@JsonProperty("LicenseType")
public String getLicenseType() {
return licenseType;
}
@JsonProperty("ValidFromDate")
public LocalDate getValidFromDate() {
return validFromDate;
}
@JsonProperty("ValidToDate")
public LocalDate getValidToDate() {
return validToDate;
}
@Override
public String toString() {
return "DriversLicense{" +
"personId='" + personId + '\'' +
", licenseNumber='" + licenseNumber + '\'' +
", licenseType='" + licenseType + '\'' +
", validFromDate=" + validFromDate +
", validToDate=" + validToDate +
'}';
}
}
```
1. `Person.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import java.time.LocalDate;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.Constants;
import software.amazon.qldb.tutorial.model.streams.RevisionData;
/**
* Represents a person, serializable to (and from) Ion.
*/
public final class Person implements RevisionData {
private final String firstName;
private final String lastName;
@JsonSerialize(using = IonLocalDateSerializer.class)
@JsonDeserialize(using = IonLocalDateDeserializer.class)
private final LocalDate dob;
private final String govId;
private final String govIdType;
private final String address;
@JsonCreator
public Person(@JsonProperty("FirstName") final String firstName,
@JsonProperty("LastName") final String lastName,
@JsonProperty("DOB") final LocalDate dob,
@JsonProperty("GovId") final String govId,
@JsonProperty("GovIdType") final String govIdType,
@JsonProperty("Address") final String address) {
this.firstName = firstName;
this.lastName = lastName;
this.dob = dob;
this.govId = govId;
this.govIdType = govIdType;
this.address = address;
}
@JsonProperty("Address")
public String getAddress() {
return address;
}
@JsonProperty("DOB")
public LocalDate getDob() {
return dob;
}
@JsonProperty("FirstName")
public String getFirstName() {
return firstName;
}
@JsonProperty("LastName")
public String getLastName() {
return lastName;
}
@JsonProperty("GovId")
public String getGovId() {
return govId;
}
@JsonProperty("GovIdType")
public String getGovIdType() {
return govIdType;
}
/**
* This returns the unique document ID given a specific government ID.
*
* @param txn
* A transaction executor object.
* @param govId
* The government ID of a driver.
* @return the unique document ID.
*/
public static String getDocumentIdByGovId(final TransactionExecutor txn, final String govId) {
return SampleData.getDocumentId(txn, Constants.PERSON_TABLE_NAME, "GovId", govId);
}
@Override
public String toString() {
return "Person{" +
"firstName='" + firstName + '\'' +
", lastName='" + lastName + '\'' +
", dob=" + dob +
", govId='" + govId + '\'' +
", govIdType='" + govIdType + '\'' +
", address='" + address + '\'' +
'}';
}
}
```
1. `VehicleRegistration.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.Constants;
import software.amazon.qldb.tutorial.model.streams.RevisionData;
import java.math.BigDecimal;
import java.time.LocalDate;
/**
* Represents a vehicle registration, serializable to (and from) Ion.
*/
public final class VehicleRegistration implements RevisionData {
private final String vin;
private final String licensePlateNumber;
private final String state;
private final String city;
private final BigDecimal pendingPenaltyTicketAmount;
private final LocalDate validFromDate;
private final LocalDate validToDate;
private final Owners owners;
@JsonCreator
public VehicleRegistration(@JsonProperty("VIN") final String vin,
@JsonProperty("LicensePlateNumber") final String licensePlateNumber,
@JsonProperty("State") final String state,
@JsonProperty("City") final String city,
@JsonProperty("PendingPenaltyTicketAmount") final BigDecimal pendingPenaltyTicketAmount,
@JsonProperty("ValidFromDate") final LocalDate validFromDate,
@JsonProperty("ValidToDate") final LocalDate validToDate,
@JsonProperty("Owners") final Owners owners) {
this.vin = vin;
this.licensePlateNumber = licensePlateNumber;
this.state = state;
this.city = city;
this.pendingPenaltyTicketAmount = pendingPenaltyTicketAmount;
this.validFromDate = validFromDate;
this.validToDate = validToDate;
this.owners = owners;
}
@JsonProperty("City")
public String getCity() {
return city;
}
@JsonProperty("LicensePlateNumber")
public String getLicensePlateNumber() {
return licensePlateNumber;
}
@JsonProperty("Owners")
public Owners getOwners() {
return owners;
}
@JsonProperty("PendingPenaltyTicketAmount")
public BigDecimal getPendingPenaltyTicketAmount() {
return pendingPenaltyTicketAmount;
}
@JsonProperty("State")
public String getState() {
return state;
}
@JsonProperty("ValidFromDate")
@JsonSerialize(using = IonLocalDateSerializer.class)
@JsonDeserialize(using = IonLocalDateDeserializer.class)
public LocalDate getValidFromDate() {
return validFromDate;
}
@JsonProperty("ValidToDate")
@JsonSerialize(using = IonLocalDateSerializer.class)
@JsonDeserialize(using = IonLocalDateDeserializer.class)
public LocalDate getValidToDate() {
return validToDate;
}
@JsonProperty("VIN")
public String getVin() {
return vin;
}
/**
* Returns the unique document ID of a vehicle given a specific VIN.
*
* @param txn
* A transaction executor object.
* @param vin
* The VIN of a vehicle.
* @return the unique document ID of the specified vehicle.
*/
public static String getDocumentIdByVin(final TransactionExecutor txn, final String vin) {
return SampleData.getDocumentId(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME, "VIN", vin);
}
@Override
public String toString() {
return "VehicleRegistration{" +
"vin='" + vin + '\'' +
", licensePlateNumber='" + licensePlateNumber + '\'' +
", state='" + state + '\'' +
", city='" + city + '\'' +
", pendingPenaltyTicketAmount=" + pendingPenaltyTicketAmount +
", validFromDate=" + validFromDate +
", validToDate=" + validToDate +
", owners=" + owners +
'}';
}
}
```
1. `Vehicle.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import software.amazon.qldb.tutorial.model.streams.RevisionData;
/**
* Represents a vehicle, serializable to (and from) Ion.
*/
public final class Vehicle implements RevisionData {
private final String vin;
private final String type;
private final int year;
private final String make;
private final String model;
private final String color;
@JsonCreator
public Vehicle(@JsonProperty("VIN") final String vin,
@JsonProperty("Type") final String type,
@JsonProperty("Year") final int year,
@JsonProperty("Make") final String make,
@JsonProperty("Model") final String model,
@JsonProperty("Color") final String color) {
this.vin = vin;
this.type = type;
this.year = year;
this.make = make;
this.model = model;
this.color = color;
}
@JsonProperty("Color")
public String getColor() {
return color;
}
@JsonProperty("Make")
public String getMake() {
return make;
}
@JsonProperty("Model")
public String getModel() {
return model;
}
@JsonProperty("Type")
public String getType() {
return type;
}
@JsonProperty("VIN")
public String getVin() {
return vin;
}
@JsonProperty("Year")
public int getYear() {
return year;
}
@Override
public String toString() {
return "Vehicle{" +
"vin='" + vin + '\'' +
", type='" + type + '\'' +
", year=" + year +
", make='" + make + '\'' +
", model='" + model + '\'' +
", color='" + color + '\'' +
'}';
}
}
```
1. `Owner.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* Represents a vehicle owner, serializable to (and from) Ion.
*/
public final class Owner {
private final String personId;
public Owner(@JsonProperty("PersonId") final String personId) {
this.personId = personId;
}
@JsonProperty("PersonId")
public String getPersonId() {
return personId;
}
@Override
public String toString() {
return "Owner{" +
"personId='" + personId + '\'' +
'}';
}
}
```
1. `Owners.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* Represents a set of owners for a given vehicle, serializable to (and from) Ion.
*/
public final class Owners {
private final Owner primaryOwner;
private final List secondaryOwners;
public Owners(@JsonProperty("PrimaryOwner") final Owner primaryOwner,
@JsonProperty("SecondaryOwners") final List secondaryOwners) {
this.primaryOwner = primaryOwner;
this.secondaryOwners = secondaryOwners;
}
@JsonProperty("PrimaryOwner")
public Owner getPrimaryOwner() {
return primaryOwner;
}
@JsonProperty("SecondaryOwners")
public List getSecondaryOwners() {
return secondaryOwners;
}
@Override
public String toString() {
return "Owners{" +
"primaryOwner=" + primaryOwner +
", secondaryOwners=" + secondaryOwners +
'}';
}
}
```
1. `DmlResultDocument.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* Contains information about an individual document inserted or modified
* as a result of DML.
*/
public class DmlResultDocument {
private String documentId;
@JsonCreator
public DmlResultDocument(@JsonProperty("documentId") final String documentId) {
this.documentId = documentId;
}
public String getDocumentId() {
return documentId;
}
@Override
public String toString() {
return "DmlResultDocument{"
+ "documentId='" + documentId + '\''
+ '}';
}
}
```
1. `RevisionData.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model.streams;
/**
* Allows modeling the content of all revisions as a generic revision data. Used
* in the {@link Revision} and extended by domain models in {@link
* software.amazon.qldb.tutorial.model} to make it easier to write the {@link
* Revision.RevisionDataDeserializer} that must deserialize the {@link
* Revision#data} from different domain models.
*/
public interface RevisionData { }
```
1. `RevisionMetadata.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import com.amazon.ion.IonInt;
import com.amazon.ion.IonString;
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonTimestamp;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import com.fasterxml.jackson.dataformat.ion.IonTimestampSerializers;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.util.Date;
import java.util.Objects;
/**
* Represents the metadata field of a QLDB Document
*/
public class RevisionMetadata {
private static final Logger log = LoggerFactory.getLogger(RevisionMetadata.class);
private final String id;
private final long version;
@JsonSerialize(using = IonTimestampSerializers.IonTimestampJavaDateSerializer.class)
private final Date txTime;
private final String txId;
@JsonCreator
public RevisionMetadata(@JsonProperty("id") final String id,
@JsonProperty("version") final long version,
@JsonProperty("txTime") final Date txTime,
@JsonProperty("txId") final String txId) {
this.id = id;
this.version = version;
this.txTime = txTime;
this.txId = txId;
}
/**
* Gets the unique ID of a QLDB document.
*
* @return the document ID.
*/
public String getId() {
return id;
}
/**
* Gets the version number of the document in the document's modification history.
* @return the version number.
*/
public long getVersion() {
return version;
}
/**
* Gets the time during which the document was modified.
*
* @return the transaction time.
*/
public Date getTxTime() {
return txTime;
}
/**
* Gets the transaction ID associated with this document.
*
* @return the transaction ID.
*/
public String getTxId() {
return txId;
}
public static RevisionMetadata fromIon(final IonStruct ionStruct) {
if (ionStruct == null) {
throw new IllegalArgumentException("Metadata cannot be null");
}
try {
IonString id = (IonString) ionStruct.get("id");
IonInt version = (IonInt) ionStruct.get("version");
IonTimestamp txTime = (IonTimestamp) ionStruct.get("txTime");
IonString txId = (IonString) ionStruct.get("txId");
if (id == null || version == null || txTime == null || txId == null) {
throw new IllegalArgumentException("Document is missing required fields");
}
return new RevisionMetadata(id.stringValue(), version.longValue(), new Date(txTime.getMillis()), txId.stringValue());
} catch (ClassCastException e) {
log.error("Failed to parse ion document");
throw new IllegalArgumentException("Document members are not of the correct type", e);
}
}
/**
* Converts a {@link RevisionMetadata} object to a string.
*
* @return the string representation of the {@link QldbRevision} object.
*/
@Override
public String toString() {
return "Metadata{"
+ "id='" + id + '\''
+ ", version=" + version
+ ", txTime=" + txTime
+ ", txId='" + txId
+ '\''
+ '}';
}
/**
* Check whether two {@link RevisionMetadata} objects are equivalent.
*
* @return {@code true} if the two objects are equal, {@code false} otherwise.
*/
@Override
public boolean equals(Object o) {
if (this == o) { return true; }
if (o == null || getClass() != o.getClass()) { return false; }
RevisionMetadata metadata = (RevisionMetadata) o;
return version == metadata.version
&& id.equals(metadata.id)
&& txTime.equals(metadata.txTime)
&& txId.equals(metadata.txId);
}
/**
* Generate a hash code for the {@link RevisionMetadata} object.
*
* @return the hash code.
*/
@Override
public int hashCode() {
// CHECKSTYLE:OFF - Disabling as we are generating a hashCode of multiple properties.
return Objects.hash(id, version, txTime, txId);
// CHECKSTYLE:ON
}
}
```
1. `QldbRevision.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import com.amazon.ion.IonBlob;
import com.amazon.ion.IonStruct;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.tutorial.Constants;
import software.amazon.qldb.tutorial.Verifier;
import java.io.IOException;
import java.util.Arrays;
import java.util.Objects;
/**
* Represents a QldbRevision including both user data and metadata.
*/
public final class QldbRevision {
private static final Logger log = LoggerFactory.getLogger(QldbRevision.class);
private final BlockAddress blockAddress;
private final RevisionMetadata metadata;
private final byte[] hash;
private final byte[] dataHash;
private final IonStruct data;
@JsonCreator
public QldbRevision(@JsonProperty("blockAddress") final BlockAddress blockAddress,
@JsonProperty("metadata") final RevisionMetadata metadata,
@JsonProperty("hash") final byte[] hash,
@JsonProperty("dataHash") final byte[] dataHash,
@JsonProperty("data") final IonStruct data) {
this.blockAddress = blockAddress;
this.metadata = metadata;
this.hash = hash;
this.dataHash = dataHash;
this.data = data;
}
/**
* Gets the unique ID of a QLDB document.
*
* @return the {@link BlockAddress} object.
*/
public BlockAddress getBlockAddress() {
return blockAddress;
}
/**
* Gets the metadata of the revision.
*
* @return the {@link RevisionMetadata} object.
*/
public RevisionMetadata getMetadata() {
return metadata;
}
/**
* Gets the SHA-256 hash value of the revision.
* This is equivalent to the hash of the revision metadata and data.
*
* @return the byte array representing the hash.
*/
public byte[] getHash() {
return hash;
}
/**
* Gets the SHA-256 hash value of the data portion of the revision.
* This is only present if the revision is redacted.
*
* @return the byte array representing the hash.
*/
public byte[] getDataHash() {
return dataHash;
}
/**
* Gets the revision data.
*
* @return the revision data.
*/
public IonStruct getData() {
return data;
}
/**
* Returns true if the revision has been redacted.
* @return a boolean value representing the redaction status
* of this revision.
*/
public Boolean isRedacted() {
return dataHash != null;
}
/**
* Constructs a new {@link QldbRevision} from an {@link IonStruct}.
*
* The specified {@link IonStruct} must include the following fields
*
* - blockAddress -- a {@link BlockAddress},
* - metadata -- a {@link RevisionMetadata},
* - hash -- the revision's hash calculated by QLDB,
* - dataHash -- the user data's hash calculated by QLDB (only present if revision is redacted),
* - data -- an {@link IonStruct} containing user data in the document.
*
* If any of these fields are missing or are malformed, then throws {@link IllegalArgumentException}.
*
* If the document hash calculated from the members of the specified {@link IonStruct} does not match
* the hash member of the {@link IonStruct} then throws {@link IllegalArgumentException}.
*
* @param ionStruct
* The {@link IonStruct} that contains a {@link QldbRevision} object.
* @return the converted {@link QldbRevision} object.
* @throws IOException if failed to parse parameter {@link IonStruct}.
*/
public static QldbRevision fromIon(final IonStruct ionStruct) throws IOException {
try {
BlockAddress blockAddress = Constants.MAPPER.readValue(ionStruct.get("blockAddress"), BlockAddress.class);
IonBlob revisionHash = (IonBlob) ionStruct.get("hash");
IonStruct metadataStruct = (IonStruct) ionStruct.get("metadata");
IonStruct data = ionStruct.get("data") == null || ionStruct.get("data").isNullValue() ?
null : (IonStruct) ionStruct.get("data");
IonBlob dataHash = ionStruct.get("dataHash") == null || ionStruct.get("dataHash").isNullValue() ?
null : (IonBlob) ionStruct.get("dataHash");
if (revisionHash == null || metadataStruct == null) {
throw new IllegalArgumentException("Document is missing required fields");
}
byte[] dataHashBytes = dataHash != null ? dataHash.getBytes() : QldbIonUtils.hashIonValue(data);
verifyRevisionHash(metadataStruct, dataHashBytes, revisionHash.getBytes());
RevisionMetadata metadata = RevisionMetadata.fromIon(metadataStruct);
return new QldbRevision(
blockAddress,
metadata,
revisionHash.getBytes(),
dataHash != null ? dataHash.getBytes() : null,
data
);
} catch (ClassCastException e) {
log.error("Failed to parse ion document");
throw new IllegalArgumentException("Document members are not of the correct type", e);
}
}
/**
* Converts a {@link QldbRevision} object to string.
*
* @return the string representation of the {@link QldbRevision} object.
*/
@Override
public String toString() {
return "QldbRevision{" +
"blockAddress=" + blockAddress +
", metadata=" + metadata +
", hash=" + Arrays.toString(hash) +
", dataHash=" + Arrays.toString(dataHash) +
", data=" + data +
'}';
}
/**
* Check whether two {@link QldbRevision} objects are equivalent.
*
* @return {@code true} if the two objects are equal, {@code false} otherwise.
*/
@Override
public boolean equals(final Object o) {
if (this == o) {
return true;
}
if (!(o instanceof QldbRevision)) {
return false;
}
final QldbRevision that = (QldbRevision) o;
return Objects.equals(getBlockAddress(), that.getBlockAddress())
&& Objects.equals(getMetadata(), that.getMetadata())
&& Arrays.equals(getHash(), that.getHash())
&& Arrays.equals(getDataHash(), that.getDataHash())
&& Objects.equals(getData(), that.getData());
}
/**
* Create a hash code for the {@link QldbRevision} object.
*
* @return the hash code.
*/
@Override
public int hashCode() {
// CHECKSTYLE:OFF - Disabling as we are generating a hashCode of multiple properties.
int result = Objects.hash(blockAddress, metadata, data);
// CHECKSTYLE:ON
result = 31 * result + Arrays.hashCode(hash);
return result;
}
/**
* Throws an IllegalArgumentException if the hash of the revision data and metadata
* does not match the hash provided by QLDB with the revision.
*/
public void verifyRevisionHash() {
// Certain internal-only system revisions only contain a hash which cannot be
// further computed. However, these system hashes still participate to validate
// the journal block. User revisions will always contain values for all fields
// and can therefore have their hash computed.
if (blockAddress == null && metadata == null && data == null && dataHash == null) {
return;
}
try {
IonStruct metadataIon = (IonStruct) Constants.MAPPER.writeValueAsIonValue(metadata);
byte[] dataHashBytes = isRedacted() ? dataHash : QldbIonUtils.hashIonValue(data);
verifyRevisionHash(metadataIon, dataHashBytes, hash);
} catch (IOException e) {
throw new IllegalArgumentException("Could not encode revision metadata to ion.", e);
}
}
private static void verifyRevisionHash(IonStruct metadata, byte[] dataHash, byte[] expectedHash) {
byte[] metadataHash = QldbIonUtils.hashIonValue(metadata);
byte[] candidateHash = Verifier.dot(metadataHash, dataHash);
if (!Arrays.equals(candidateHash, expectedHash)) {
throw new IllegalArgumentException("Hash entry of QLDB revision and computed hash "
+ "of QLDB revision do not match");
}
}
}
```
1. `IonLocalDateDeserializer.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.amazon.ion.Timestamp;
import com.fasterxml.jackson.core.JsonParser;
import com.fasterxml.jackson.databind.DeserializationContext;
import com.fasterxml.jackson.databind.JsonDeserializer;
import java.io.IOException;
import java.time.LocalDate;
/**
* Deserializes [java.time.LocalDate] from Ion.
*/
public class IonLocalDateDeserializer extends JsonDeserializer {
@Override
public LocalDate deserialize(JsonParser jp, DeserializationContext ctxt) throws IOException {
return timestampToLocalDate((Timestamp) jp.getEmbeddedObject());
}
private LocalDate timestampToLocalDate(Timestamp timestamp) {
return LocalDate.of(timestamp.getYear(), timestamp.getMonth(), timestamp.getDay());
}
}
```
1. `IonLocalDateSerializer.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.amazon.ion.Timestamp;
import com.fasterxml.jackson.core.JsonGenerator;
import com.fasterxml.jackson.databind.SerializerProvider;
import com.fasterxml.jackson.databind.ser.std.StdScalarSerializer;
import com.fasterxml.jackson.dataformat.ion.IonGenerator;
import java.io.IOException;
import java.time.LocalDate;
/**
* Serializes [java.time.LocalDate] to Ion.
*/
public class IonLocalDateSerializer extends StdScalarSerializer {
public IonLocalDateSerializer() {
super(LocalDate.class);
}
@Override
public void serialize(LocalDate date, JsonGenerator jsonGenerator, SerializerProvider serializerProvider) throws IOException {
Timestamp timestamp = Timestamp.forDay(date.getYear(), date.getMonthValue(), date.getDayOfMonth());
((IonGenerator) jsonGenerator).writeValue(timestamp);
}
}
```
1. Revise el siguiente archivo (`SampleData.java`), que representa los datos de ejemplo que inserta en las tablas `vehicle-registration`.
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.amazon.ion.IonString;
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonValue;
import java.io.IOException;
import java.math.BigDecimal;
import java.text.ParseException;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.ConnectToLedger;
import software.amazon.qldb.tutorial.Constants;
import software.amazon.qldb.tutorial.qldb.DmlResultDocument;
import software.amazon.qldb.tutorial.qldb.QldbRevision;
/**
* Sample domain objects for use throughout this tutorial.
*/
public final class SampleData {
public static final DateTimeFormatter DATE_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd");
public static final List REGISTRATIONS = Collections.unmodifiableList(Arrays.asList(
new VehicleRegistration("1N4AL11D75C109151", "LEWISR261LL", "WA", "Seattle",
BigDecimal.valueOf(90.25), convertToLocalDate("2017-08-21"), convertToLocalDate("2020-05-11"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("KM8SRDHF6EU074761", "CA762X", "WA", "Kent",
BigDecimal.valueOf(130.75), convertToLocalDate("2017-09-14"), convertToLocalDate("2020-06-25"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("3HGGK5G53FM761765", "CD820Z", "WA", "Everett",
BigDecimal.valueOf(442.30), convertToLocalDate("2011-03-17"), convertToLocalDate("2021-03-24"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("1HVBBAANXWH544237", "LS477D", "WA", "Tacoma",
BigDecimal.valueOf(42.20), convertToLocalDate("2011-10-26"), convertToLocalDate("2023-09-25"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("1C4RJFAG0FC625797", "TH393F", "WA", "Olympia",
BigDecimal.valueOf(30.45), convertToLocalDate("2013-09-02"), convertToLocalDate("2024-03-19"),
new Owners(new Owner(null), Collections.emptyList()))
));
public static final List VEHICLES = Collections.unmodifiableList(Arrays.asList(
new Vehicle("1N4AL11D75C109151", "Sedan", 2011, "Audi", "A5", "Silver"),
new Vehicle("KM8SRDHF6EU074761", "Sedan", 2015, "Tesla", "Model S", "Blue"),
new Vehicle("3HGGK5G53FM761765", "Motorcycle", 2011, "Ducati", "Monster 1200", "Yellow"),
new Vehicle("1HVBBAANXWH544237", "Semi", 2009, "Ford", "F 150", "Black"),
new Vehicle("1C4RJFAG0FC625797", "Sedan", 2019, "Mercedes", "CLK 350", "White")
));
public static final List PEOPLE = Collections.unmodifiableList(Arrays.asList(
new Person("Raul", "Lewis", convertToLocalDate("1963-08-19"),
"LEWISR261LL", "Driver License", "1719 University Street, Seattle, WA, 98109"),
new Person("Brent", "Logan", convertToLocalDate("1967-07-03"),
"LOGANB486CG", "Driver License", "43 Stockert Hollow Road, Everett, WA, 98203"),
new Person("Alexis", "Pena", convertToLocalDate("1974-02-10"),
"744 849 301", "SSN", "4058 Melrose Street, Spokane Valley, WA, 99206"),
new Person("Melvin", "Parker", convertToLocalDate("1976-05-22"),
"P626-168-229-765", "Passport", "4362 Ryder Avenue, Seattle, WA, 98101"),
new Person("Salvatore", "Spencer", convertToLocalDate("1997-11-15"),
"S152-780-97-415-0", "Passport", "4450 Honeysuckle Lane, Seattle, WA, 98101")
));
public static final List LICENSES = Collections.unmodifiableList(Arrays.asList(
new DriversLicense(null, "LEWISR261LL", "Learner",
convertToLocalDate("2016-12-20"), convertToLocalDate("2020-11-15")),
new DriversLicense(null, "LOGANB486CG", "Probationary",
convertToLocalDate("2016-04-06"), convertToLocalDate("2020-11-15")),
new DriversLicense(null, "744 849 301", "Full",
convertToLocalDate("2017-12-06"), convertToLocalDate("2022-10-15")),
new DriversLicense(null, "P626-168-229-765", "Learner",
convertToLocalDate("2017-08-16"), convertToLocalDate("2021-11-15")),
new DriversLicense(null, "S152-780-97-415-0", "Probationary",
convertToLocalDate("2015-08-15"), convertToLocalDate("2021-08-21"))
));
private SampleData() { }
/**
* Converts a date string with the format 'yyyy-MM-dd' into a {@link java.util.Date} object.
*
* @param date
* The date string to convert.
* @return {@link java.time.LocalDate} or null if there is a {@link ParseException}
*/
public static synchronized LocalDate convertToLocalDate(String date) {
return LocalDate.parse(date, DATE_TIME_FORMAT);
}
/**
* Convert the result set into a list of IonValues.
*
* @param result
* The result set to convert.
* @return a list of IonValues.
*/
public static List toIonValues(Result result) {
final List valueList = new ArrayList<>();
result.iterator().forEachRemaining(valueList::add);
return valueList;
}
/**
* Get the document ID of a particular document.
*
* @param txn
* A transaction executor object.
* @param tableName
* Name of the table containing the document.
* @param identifier
* The identifier used to narrow down the search.
* @param value
* Value of the identifier.
* @return the list of document IDs in the result set.
*/
public static String getDocumentId(final TransactionExecutor txn, final String tableName,
final String identifier, final String value) {
try {
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(value));
final String query = String.format("SELECT metadata.id FROM _ql_committed_%s AS p WHERE p.data.%s = ?",
tableName, identifier);
Result result = txn.execute(query, parameters);
if (result.isEmpty()) {
throw new IllegalStateException("Unable to retrieve document ID using " + value);
}
return getStringValueOfStructField((IonStruct) result.iterator().next(), "id");
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Get the document by ID.
*
* @param tableName
* Name of the table to insert documents into.
* @param documentId
* The unique ID of a document in the Person table.
* @return a {@link QldbRevision} object.
* @throws IllegalStateException if failed to convert parameter into {@link IonValue}.
*/
public static QldbRevision getDocumentById(String tableName, String documentId) {
try {
final IonValue ionValue = Constants.MAPPER.writeValueAsIonValue(documentId);
Result result = ConnectToLedger.getDriver().execute(txn -> {
return txn.execute("SELECT c.* FROM _ql_committed_" + tableName + " AS c BY docId "
+ "WHERE docId = ?", ionValue);
});
if (result.isEmpty()) {
throw new IllegalStateException("Unable to retrieve document by id " + documentId + " in table " + tableName);
}
return Constants.MAPPER.readValue(result.iterator().next(), QldbRevision.class);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Return a list of modified document IDs as strings from a DML {@link Result}.
*
* @param result
* The result set from a DML operation.
* @return the list of document IDs modified by the operation.
*/
public static List getDocumentIdsFromDmlResult(final Result result) {
final List strings = new ArrayList<>();
result.iterator().forEachRemaining(row -> strings.add(getDocumentIdFromDmlResultDocument(row)));
return strings;
}
/**
* Convert the given DML result row's document ID to string.
*
* @param dmlResultDocument
* The {@link IonValue} representing the results of a DML operation.
* @return a string of document ID.
*/
public static String getDocumentIdFromDmlResultDocument(final IonValue dmlResultDocument) {
try {
DmlResultDocument result = Constants.MAPPER.readValue(dmlResultDocument, DmlResultDocument.class);
return result.getDocumentId();
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Get the String value of a given {@link IonStruct} field name.
* @param struct the {@link IonStruct} from which to get the value.
* @param fieldName the name of the field from which to get the value.
* @return the String value of the field within the given {@link IonStruct}.
*/
public static String getStringValueOfStructField(final IonStruct struct, final String fieldName) {
return ((IonString) struct.get(fieldName)).stringValue();
}
/**
* Return a copy of the given driver's license with updated person Id.
*
* @param oldLicense
* The old driver's license to update.
* @param personId
* The PersonId of the driver.
* @return the updated {@link DriversLicense}.
*/
public static DriversLicense updatePersonIdDriversLicense(final DriversLicense oldLicense, final String personId) {
return new DriversLicense(personId, oldLicense.getLicenseNumber(), oldLicense.getLicenseType(),
oldLicense.getValidFromDate(), oldLicense.getValidToDate());
}
/**
* Return a copy of the given vehicle registration with updated person Id.
*
* @param oldRegistration
* The old vehicle registration to update.
* @param personId
* The PersonId of the driver.
* @return the updated {@link VehicleRegistration}.
*/
public static VehicleRegistration updateOwnerVehicleRegistration(final VehicleRegistration oldRegistration,
final String personId) {
return new VehicleRegistration(oldRegistration.getVin(), oldRegistration.getLicensePlateNumber(),
oldRegistration.getState(), oldRegistration.getCity(), oldRegistration.getPendingPenaltyTicketAmount(),
oldRegistration.getValidFromDate(), oldRegistration.getValidToDate(),
new Owners(new Owner(personId), Collections.emptyList()));
}
}
```
------
#### [ 1.x ]
**importante**
Para el paquete Amazon Ion, debe usar el espacio de nombres `com.amazon.ion` de su aplicación. 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 QLDB.
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.model;
import com.amazon.ion.IonString;
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonValue;
import software.amazon.qldb.QldbSession;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.Constants;
import software.amazon.qldb.tutorial.qldb.DmlResultDocument;
import software.amazon.qldb.tutorial.qldb.QldbRevision;
import java.io.IOException;
import java.math.BigDecimal;
import java.text.ParseException;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
/**
* Sample domain objects for use throughout this tutorial.
*/
public final class SampleData {
public static final DateTimeFormatter DATE_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd");
public static final List REGISTRATIONS = Collections.unmodifiableList(Arrays.asList(
new VehicleRegistration("1N4AL11D75C109151", "LEWISR261LL", "WA", "Seattle",
BigDecimal.valueOf(90.25), convertToLocalDate("2017-08-21"), convertToLocalDate("2020-05-11"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("KM8SRDHF6EU074761", "CA762X", "WA", "Kent",
BigDecimal.valueOf(130.75), convertToLocalDate("2017-09-14"), convertToLocalDate("2020-06-25"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("3HGGK5G53FM761765", "CD820Z", "WA", "Everett",
BigDecimal.valueOf(442.30), convertToLocalDate("2011-03-17"), convertToLocalDate("2021-03-24"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("1HVBBAANXWH544237", "LS477D", "WA", "Tacoma",
BigDecimal.valueOf(42.20), convertToLocalDate("2011-10-26"), convertToLocalDate("2023-09-25"),
new Owners(new Owner(null), Collections.emptyList())),
new VehicleRegistration("1C4RJFAG0FC625797", "TH393F", "WA", "Olympia",
BigDecimal.valueOf(30.45), convertToLocalDate("2013-09-02"), convertToLocalDate("2024-03-19"),
new Owners(new Owner(null), Collections.emptyList()))
));
public static final List VEHICLES = Collections.unmodifiableList(Arrays.asList(
new Vehicle("1N4AL11D75C109151", "Sedan", 2011, "Audi", "A5", "Silver"),
new Vehicle("KM8SRDHF6EU074761", "Sedan", 2015, "Tesla", "Model S", "Blue"),
new Vehicle("3HGGK5G53FM761765", "Motorcycle", 2011, "Ducati", "Monster 1200", "Yellow"),
new Vehicle("1HVBBAANXWH544237", "Semi", 2009, "Ford", "F 150", "Black"),
new Vehicle("1C4RJFAG0FC625797", "Sedan", 2019, "Mercedes", "CLK 350", "White")
));
public static final List PEOPLE = Collections.unmodifiableList(Arrays.asList(
new Person("Raul", "Lewis", convertToLocalDate("1963-08-19"),
"LEWISR261LL", "Driver License", "1719 University Street, Seattle, WA, 98109"),
new Person("Brent", "Logan", convertToLocalDate("1967-07-03"),
"LOGANB486CG", "Driver License", "43 Stockert Hollow Road, Everett, WA, 98203"),
new Person("Alexis", "Pena", convertToLocalDate("1974-02-10"),
"744 849 301", "SSN", "4058 Melrose Street, Spokane Valley, WA, 99206"),
new Person("Melvin", "Parker", convertToLocalDate("1976-05-22"),
"P626-168-229-765", "Passport", "4362 Ryder Avenue, Seattle, WA, 98101"),
new Person("Salvatore", "Spencer", convertToLocalDate("1997-11-15"),
"S152-780-97-415-0", "Passport", "4450 Honeysuckle Lane, Seattle, WA, 98101")
));
public static final List LICENSES = Collections.unmodifiableList(Arrays.asList(
new DriversLicense(null, "LEWISR261LL", "Learner",
convertToLocalDate("2016-12-20"), convertToLocalDate("2020-11-15")),
new DriversLicense(null, "LOGANB486CG", "Probationary",
convertToLocalDate("2016-04-06"), convertToLocalDate("2020-11-15")),
new DriversLicense(null, "744 849 301", "Full",
convertToLocalDate("2017-12-06"), convertToLocalDate("2022-10-15")),
new DriversLicense(null, "P626-168-229-765", "Learner",
convertToLocalDate("2017-08-16"), convertToLocalDate("2021-11-15")),
new DriversLicense(null, "S152-780-97-415-0", "Probationary",
convertToLocalDate("2015-08-15"), convertToLocalDate("2021-08-21"))
));
private SampleData() { }
/**
* Converts a date string with the format 'yyyy-MM-dd' into a {@link java.util.Date} object.
*
* @param date
* The date string to convert.
* @return {@link LocalDate} or null if there is a {@link ParseException}
*/
public static synchronized LocalDate convertToLocalDate(String date) {
return LocalDate.parse(date, DATE_TIME_FORMAT);
}
/**
* Convert the result set into a list of IonValues.
*
* @param result
* The result set to convert.
* @return a list of IonValues.
*/
public static List toIonValues(Result result) {
final List valueList = new ArrayList<>();
result.iterator().forEachRemaining(valueList::add);
return valueList;
}
/**
* Get the document ID of a particular document.
*
* @param txn
* A transaction executor object.
* @param tableName
* Name of the table containing the document.
* @param identifier
* The identifier used to narrow down the search.
* @param value
* Value of the identifier.
* @return the list of document IDs in the result set.
*/
public static String getDocumentId(final TransactionExecutor txn, final String tableName,
final String identifier, final String value) {
try {
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(value));
final String query = String.format("SELECT metadata.id FROM _ql_committed_%s AS p WHERE p.data.%s = ?",
tableName, identifier);
Result result = txn.execute(query, parameters);
if (result.isEmpty()) {
throw new IllegalStateException("Unable to retrieve document ID using " + value);
}
return getStringValueOfStructField((IonStruct) result.iterator().next(), "id");
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Get the document by ID.
*
* @param qldbSession
* A QLDB session.
* @param tableName
* Name of the table to insert documents into.
* @param documentId
* The unique ID of a document in the Person table.
* @return a {@link QldbRevision} object.
* @throws IllegalStateException if failed to convert parameter into {@link IonValue}.
*/
public static QldbRevision getDocumentById(QldbSession qldbSession, String tableName, String documentId) {
try {
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(documentId));
final String query = String.format("SELECT c.* FROM _ql_committed_%s AS c BY docId WHERE docId = ?", tableName);
Result result = qldbSession.execute(query, parameters);
if (result.isEmpty()) {
throw new IllegalStateException("Unable to retrieve document by id " + documentId + " in table " + tableName);
}
return Constants.MAPPER.readValue(result.iterator().next(), QldbRevision.class);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Return a list of modified document IDs as strings from a DML {@link Result}.
*
* @param result
* The result set from a DML operation.
* @return the list of document IDs modified by the operation.
*/
public static List getDocumentIdsFromDmlResult(final Result result) {
final List strings = new ArrayList<>();
result.iterator().forEachRemaining(row -> strings.add(getDocumentIdFromDmlResultDocument(row)));
return strings;
}
/**
* Convert the given DML result row's document ID to string.
*
* @param dmlResultDocument
* The {@link IonValue} representing the results of a DML operation.
* @return a string of document ID.
*/
public static String getDocumentIdFromDmlResultDocument(final IonValue dmlResultDocument) {
try {
DmlResultDocument result = Constants.MAPPER.readValue(dmlResultDocument, DmlResultDocument.class);
return result.getDocumentId();
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Get the String value of a given {@link IonStruct} field name.
* @param struct the {@link IonStruct} from which to get the value.
* @param fieldName the name of the field from which to get the value.
* @return the String value of the field within the given {@link IonStruct}.
*/
public static String getStringValueOfStructField(final IonStruct struct, final String fieldName) {
return ((IonString) struct.get(fieldName)).stringValue();
}
/**
* Return a copy of the given driver's license with updated person Id.
*
* @param oldLicense
* The old driver's license to update.
* @param personId
* The PersonId of the driver.
* @return the updated {@link DriversLicense}.
*/
public static DriversLicense updatePersonIdDriversLicense(final DriversLicense oldLicense, final String personId) {
return new DriversLicense(personId, oldLicense.getLicenseNumber(), oldLicense.getLicenseType(),
oldLicense.getValidFromDate(), oldLicense.getValidToDate());
}
/**
* Return a copy of the given vehicle registration with updated person Id.
*
* @param oldRegistration
* The old vehicle registration to update.
* @param personId
* The PersonId of the driver.
* @return the updated {@link VehicleRegistration}.
*/
public static VehicleRegistration updateOwnerVehicleRegistration(final VehicleRegistration oldRegistration,
final String personId) {
return new VehicleRegistration(oldRegistration.getVin(), oldRegistration.getLicensePlateNumber(),
oldRegistration.getState(), oldRegistration.getCity(), oldRegistration.getPendingPenaltyTicketAmount(),
oldRegistration.getValidFromDate(), oldRegistration.getValidToDate(),
new Owners(new Owner(personId), Collections.emptyList()));
}
}
```
------
**nota**
Esta clase utiliza las bibliotecas de Ion para proporcionar métodos auxiliares que convierten los datos al formato Ion y desde él.
El método `getDocumentId` ejecuta una consulta en una tabla con el prefijo `_ql_committed_`. Se trata de un prefijo reservado que indica que desea consultar la *vista confirmada* de la tabla. En esta vista, los datos están anidados en el campo `data` y los metadatos están anidados en el campo `metadata`.
1. Compile y ejecute el siguiente programa (`CreateTable.java`) para crear las tablas mencionadas anteriormente.
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Create tables in a QLDB ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class CreateTable {
public static final Logger log = LoggerFactory.getLogger(CreateTable.class);
private CreateTable() { }
/**
* Registrations, vehicles, owners, and licenses tables being created in a single transaction.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param tableName
* Name of the table to be created.
* @return the number of tables created.
*/
public static int createTable(final TransactionExecutor txn, final String tableName) {
log.info("Creating the '{}' table...", tableName);
final String createTable = String.format("CREATE TABLE %s", tableName);
final Result result = txn.execute(createTable);
log.info("{} table created successfully.", tableName);
return SampleData.toIonValues(result).size();
}
public static void main(final String... args) {
ConnectToLedger.getDriver().execute(txn -> {
createTable(txn, Constants.DRIVERS_LICENSE_TABLE_NAME);
createTable(txn, Constants.PERSON_TABLE_NAME);
createTable(txn, Constants.VEHICLE_TABLE_NAME);
createTable(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME);
});
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Create tables in a QLDB ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class CreateTable {
public static final Logger log = LoggerFactory.getLogger(CreateTable.class);
private CreateTable() { }
/**
* Registrations, vehicles, owners, and licenses tables being created in a single transaction.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param tableName
* Name of the table to be created.
* @return the number of tables created.
*/
public static int createTable(final TransactionExecutor txn, final String tableName) {
log.info("Creating the '{}' table...", tableName);
final String createTable = String.format("CREATE TABLE %s", tableName);
final Result result = txn.execute(createTable);
log.info("{} table created successfully.", tableName);
return SampleData.toIonValues(result).size();
}
public static void main(final String... args) {
ConnectToLedger.getDriver().execute(txn -> {
createTable(txn, Constants.DRIVERS_LICENSE_TABLE_NAME);
createTable(txn, Constants.PERSON_TABLE_NAME);
createTable(txn, Constants.VEHICLE_TABLE_NAME);
createTable(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME);
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
}
}
```
------
**nota**
Este programa muestra cómo pasar una lambda `TransactionExecutor` al método `execute`. En este ejemplo, ejecuta varias instrucciones `CREATE TABLE` de PartiQL en una única transacción con una expresión lambda.
El método `execute` inicia implícitamente una transacción, ejecuta todas las instrucciones en lambda y, a continuación, confirma automáticamente la transacción.
1. Compile y ejecute el siguiente programa (`CreateIndex.java`) para crear índices en las tablas, tal y como se describió anteriormente.
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Create indexes on tables in a particular ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class CreateIndex {
public static final Logger log = LoggerFactory.getLogger(CreateIndex.class);
private CreateIndex() { }
/**
* In this example, create indexes for registrations and vehicles tables.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param tableName
* Name of the table to be created.
* @param indexAttribute
* The index attribute to use.
* @return the number of tables created.
*/
public static int createIndex(final TransactionExecutor txn, final String tableName, final String indexAttribute) {
log.info("Creating an index on {}...", indexAttribute);
final String createIndex = String.format("CREATE INDEX ON %s (%s)", tableName, indexAttribute);
final Result r = txn.execute(createIndex);
return SampleData.toIonValues(r).size();
}
public static void main(final String... args) {
ConnectToLedger.getDriver().execute(txn -> {
createIndex(txn, Constants.PERSON_TABLE_NAME, Constants.PERSON_GOV_ID_INDEX_NAME);
createIndex(txn, Constants.VEHICLE_TABLE_NAME, Constants.VIN_INDEX_NAME);
createIndex(txn, Constants.DRIVERS_LICENSE_TABLE_NAME, Constants.DRIVER_LICENSE_NUMBER_INDEX_NAME);
createIndex(txn, Constants.DRIVERS_LICENSE_TABLE_NAME, Constants.DRIVER_LICENSE_PERSONID_INDEX_NAME);
createIndex(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME, Constants.VIN_INDEX_NAME);
createIndex(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME,
Constants.VEHICLE_REGISTRATION_LICENSE_PLATE_NUMBER_INDEX_NAME);
});
log.info("Indexes created successfully!");
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Create indexes on tables in a particular ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class CreateIndex {
public static final Logger log = LoggerFactory.getLogger(CreateIndex.class);
private CreateIndex() { }
/**
* In this example, create indexes for registrations and vehicles tables.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param tableName
* Name of the table to be created.
* @param indexAttribute
* The index attribute to use.
* @return the number of tables created.
*/
public static int createIndex(final TransactionExecutor txn, final String tableName, final String indexAttribute) {
log.info("Creating an index on {}...", indexAttribute);
final String createIndex = String.format("CREATE INDEX ON %s (%s)", tableName, indexAttribute);
final Result r = txn.execute(createIndex);
return SampleData.toIonValues(r).size();
}
public static void main(final String... args) {
ConnectToLedger.getDriver().execute(txn -> {
createIndex(txn, Constants.PERSON_TABLE_NAME, Constants.PERSON_GOV_ID_INDEX_NAME);
createIndex(txn, Constants.VEHICLE_TABLE_NAME, Constants.VIN_INDEX_NAME);
createIndex(txn, Constants.DRIVERS_LICENSE_TABLE_NAME, Constants.DRIVER_LICENSE_NUMBER_INDEX_NAME);
createIndex(txn, Constants.DRIVERS_LICENSE_TABLE_NAME, Constants.DRIVER_LICENSE_PERSONID_INDEX_NAME);
createIndex(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME, Constants.VIN_INDEX_NAME);
createIndex(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME,
Constants.VEHICLE_REGISTRATION_LICENSE_PLATE_NUMBER_INDEX_NAME);
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
log.info("Indexes created successfully!");
}
}
```
------
1. Compile y ejecute el siguiente programa (`InsertDocument.java`) para insertar los datos de ejemplo en las tablas.
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.amazon.ion.IonValue;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.DriversLicense;
import software.amazon.qldb.tutorial.model.SampleData;
import software.amazon.qldb.tutorial.model.VehicleRegistration;
/**
* Insert documents into a table in a QLDB ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class InsertDocument {
public static final Logger log = LoggerFactory.getLogger(InsertDocument.class);
private InsertDocument() { }
/**
* Insert the given list of documents into the specified table and return the document IDs of the inserted documents.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param tableName
* Name of the table to insert documents into.
* @param documents
* List of documents to insert into the specified table.
* @return a list of document IDs.
* @throws IllegalStateException if failed to convert documents into an {@link IonValue}.
*/
public static List insertDocuments(final TransactionExecutor txn, final String tableName,
final List documents) {
log.info("Inserting some documents in the {} table...", tableName);
try {
final String query = String.format("INSERT INTO %s ?", tableName);
final IonValue ionDocuments = Constants.MAPPER.writeValueAsIonValue(documents);
return SampleData.getDocumentIdsFromDmlResult(txn.execute(query, ionDocuments));
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Update PersonIds in driver's licenses and in vehicle registrations using document IDs.
*
* @param documentIds
* List of document IDs representing the PersonIds in DriversLicense and PrimaryOwners in VehicleRegistration.
* @param licenses
* List of driver's licenses to update.
* @param registrations
* List of registrations to update.
*/
public static void updatePersonId(final List documentIds, final List licenses,
final List registrations) {
for (int i = 0; i < documentIds.size(); ++i) {
DriversLicense license = SampleData.LICENSES.get(i);
VehicleRegistration registration = SampleData.REGISTRATIONS.get(i);
licenses.add(SampleData.updatePersonIdDriversLicense(license, documentIds.get(i)));
registrations.add(SampleData.updateOwnerVehicleRegistration(registration, documentIds.get(i)));
}
}
public static void main(final String... args) {
final List newDriversLicenses = new ArrayList<>();
final List newVehicleRegistrations = new ArrayList<>();
ConnectToLedger.getDriver().execute(txn -> {
List documentIds = insertDocuments(txn, Constants.PERSON_TABLE_NAME, SampleData.PEOPLE);
updatePersonId(documentIds, newDriversLicenses, newVehicleRegistrations);
insertDocuments(txn, Constants.VEHICLE_TABLE_NAME, SampleData.VEHICLES);
insertDocuments(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME,
Collections.unmodifiableList(newVehicleRegistrations));
insertDocuments(txn, Constants.DRIVERS_LICENSE_TABLE_NAME,
Collections.unmodifiableList(newDriversLicenses));
});
log.info("Documents inserted successfully!");
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonValue;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.QldbSession;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.DriversLicense;
import software.amazon.qldb.tutorial.model.SampleData;
import software.amazon.qldb.tutorial.model.VehicleRegistration;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* Insert documents into a table in a QLDB ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class InsertDocument {
public static final Logger log = LoggerFactory.getLogger(InsertDocument.class);
private InsertDocument() { }
/**
* Insert the given list of documents into the specified table and return the document IDs of the inserted documents.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param tableName
* Name of the table to insert documents into.
* @param documents
* List of documents to insert into the specified table.
* @return a list of document IDs.
* @throws IllegalStateException if failed to convert documents into an {@link IonValue}.
*/
public static List insertDocuments(final TransactionExecutor txn, final String tableName,
final List documents) {
log.info("Inserting some documents in the {} table...", tableName);
try {
final String statement = String.format("INSERT INTO %s ?", tableName);
final IonValue ionDocuments = Constants.MAPPER.writeValueAsIonValue(documents);
final List parameters = Collections.singletonList(ionDocuments);
return SampleData.getDocumentIdsFromDmlResult(txn.execute(statement, parameters));
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Update PersonIds in driver's licenses and in vehicle registrations using document IDs.
*
* @param documentIds
* List of document IDs representing the PersonIds in DriversLicense and PrimaryOwners in VehicleRegistration.
* @param licenses
* List of driver's licenses to update.
* @param registrations
* List of registrations to update.
*/
public static void updatePersonId(final List documentIds, final List licenses,
final List registrations) {
for (int i = 0; i < documentIds.size(); ++i) {
DriversLicense license = SampleData.LICENSES.get(i);
VehicleRegistration registration = SampleData.REGISTRATIONS.get(i);
licenses.add(SampleData.updatePersonIdDriversLicense(license, documentIds.get(i)));
registrations.add(SampleData.updateOwnerVehicleRegistration(registration, documentIds.get(i)));
}
}
public static void main(final String... args) {
final List newDriversLicenses = new ArrayList<>();
final List newVehicleRegistrations = new ArrayList<>();
ConnectToLedger.getDriver().execute(txn -> {
List documentIds = insertDocuments(txn, Constants.PERSON_TABLE_NAME, SampleData.PEOPLE);
updatePersonId(documentIds, newDriversLicenses, newVehicleRegistrations);
insertDocuments(txn, Constants.VEHICLE_TABLE_NAME, SampleData.VEHICLES);
insertDocuments(txn, Constants.VEHICLE_REGISTRATION_TABLE_NAME,
Collections.unmodifiableList(newVehicleRegistrations));
insertDocuments(txn, Constants.DRIVERS_LICENSE_TABLE_NAME,
Collections.unmodifiableList(newDriversLicenses));
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
log.info("Documents inserted successfully!");
}
}
```
------
**nota**
Este programa muestra cómo llamar al método `execute` con valores parametrizados. Puede pasar parámetros de datos de tipo `IonValue` además de la instrucción PartiQL que desee ejecutar. Utilice un signo de interrogación (`?`) como marcador de posición variable en la cadena de la instrucción.
Si una instrucción `INSERT` tiene éxito, devuelve el `id` de cada documento insertado.
A continuación, puede usar las instrucciones `SELECT` para leer los datos de las tablas del libro mayor `vehicle-registration`. Continúe en [Paso 4: consultar las tablas en un libro mayor](getting-started.java.step-4.md).
# Paso 4: consultar las tablas en un libro mayor
**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.
Tras crear tablas en un libro mayor de Amazon QLDB y cargarlas con datos, puede ejecutar consultas para revisar los datos de registro del vehículo que acaba de insertar. QLDB emplea [PartiQL](ql-reference.md) como lenguaje de consulta y [Amazon Ion](ion.md) como modelo de datos orientado a documentos.
PartiQL es un lenguaje de consulta de código abierto compatible con SQL que se ha ampliado para funcionar con Ion. PartiQL le permite insertar, consultar y administrar sus datos con operadores SQL conocidos. Amazon Ion es un superconjunto de JSON. Ion es un formato de datos de código abierto basado en documentos que le brinda la flexibilidad de almacenar y procesar datos estructurados, semiestructurados y anidados.
En este paso, puede usar las instrucciones `SELECT` para leer los datos de las tablas del libro mayor `vehicle-registration`.
**aviso**
Cuando ejecuta una consulta en QLDB sin una búsqueda indexada, se invoca un escaneo completo de la tabla. PartiQL admite este tipo de consultas porque es compatible con SQL. Sin embargo, *no* ejecute escaneados de tablas para casos de uso de producción en QLDB. Los escaneos de tablas pueden provocar problemas de rendimiento en tablas grandes, como conflictos de concurrencia y tiempos de espera de las transacciones.
Para evitar el escaneado de tablas, debe ejecutar las instrucciones con una cláusula de predicado `WHERE` usando un operador de *igualdad* en un campo indexado o en un ID de documento, por ejemplo `WHERE indexedField = 123` o `WHERE indexedField IN (456, 789)`. Para obtener más información, consulte [Optimización del rendimiento de las consultas](working.optimize.md).
**Para consultar las tablas**
+ Compile y ejecute el siguiente programa (`FindVehicles.java`) para consultar todos los vehículos registrados a nombre de una persona en su libro mayor.
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.io.IOException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.amazon.ion.IonValue;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.Person;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Find all vehicles registered under a person.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class FindVehicles {
public static final Logger log = LoggerFactory.getLogger(FindVehicles.class);
private FindVehicles() { }
/**
* Find vehicles registered under a driver using their government ID.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param govId
* The government ID of the owner.
* @throws IllegalStateException if failed to convert parameters into {@link IonValue}.
*/
public static void findVehiclesForOwner(final TransactionExecutor txn, final String govId) {
try {
final String documentId = Person.getDocumentIdByGovId(txn, govId);
final String query = "SELECT v FROM Vehicle AS v INNER JOIN VehicleRegistration AS r "
+ "ON v.VIN = r.VIN WHERE r.Owners.PrimaryOwner.PersonId = ?";
final Result result = txn.execute(query, Constants.MAPPER.writeValueAsIonValue(documentId));
log.info("List of Vehicles for owner with GovId: {}...", govId);
ScanTable.printDocuments(result);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final Person person = SampleData.PEOPLE.get(0);
ConnectToLedger.getDriver().execute(txn -> {
findVehiclesForOwner(txn, person.getGovId());
});
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.io.IOException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.amazon.ion.IonValue;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.Person;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Find all vehicles registered under a person.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class FindVehicles {
public static final Logger log = LoggerFactory.getLogger(FindVehicles.class);
private FindVehicles() { }
/**
* Find vehicles registered under a driver using their government ID.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param govId
* The government ID of the owner.
* @throws IllegalStateException if failed to convert parameters into {@link IonValue}.
*/
public static void findVehiclesForOwner(final TransactionExecutor txn, final String govId) {
try {
final String documentId = Person.getDocumentIdByGovId(txn, govId);
final String query = "SELECT v FROM Vehicle AS v INNER JOIN VehicleRegistration AS r "
+ "ON v.VIN = r.VIN WHERE r.Owners.PrimaryOwner.PersonId = ?";
final Result result = txn.execute(query, Constants.MAPPER.writeValueAsIonValue(documentId));
log.info("List of Vehicles for owner with GovId: {}...", govId);
ScanTable.printDocuments(result);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final Person person = SampleData.PEOPLE.get(0);
ConnectToLedger.getDriver().execute(txn -> {
findVehiclesForOwner(txn, person.getGovId());
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
}
}
```
------
**nota**
En primer lugar, este programa consulta la tabla `Person` del documento con `GovId LEWISR261LL` para obtener su campo de metadatos `id`.
A continuación, utiliza el `id` de este documento como clave externa para consultar la tabla `VehicleRegistration` mediante `PrimaryOwner.PersonId`. También combina `VehicleRegistration` con la tabla `Vehicle` en el campo `VIN`.
Para obtener información sobre la modificación de los documentos en las tablas del libro mayor `vehicle-registration`, consulte [Paso 5: modificar los documentos de un libro mayor](getting-started.java.step-5.md).
# Paso 5: modificar los documentos de un libro mayor
**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.
Ahora que tiene datos con los que trabajar, puede empezar a realizar cambios en los documentos del libro mayor `vehicle-registration` de Amazon QLDB. En este paso, los siguientes ejemplos de código muestran cómo ejecutar instrucciones de lenguaje de manipulación de datos (DML). Estas instrucciones actualizan al propietario principal de un vehículo y añaden un propietario secundario a otro vehículo.
**Modificación de documentos**
1. Compile y ejecute el siguiente programa (`TransferVehicleOwnership.java`) para actualizar el VIN del propietario principal del vehículo `1N4AL11D75C109151` en su libro mayor.
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonReader;
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonValue;
import com.amazon.ion.system.IonReaderBuilder;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.Owner;
import software.amazon.qldb.tutorial.model.Person;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Find primary owner for a particular vehicle's VIN.
* Transfer to another primary owner for a particular vehicle's VIN.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class TransferVehicleOwnership {
public static final Logger log = LoggerFactory.getLogger(TransferVehicleOwnership.class);
private TransferVehicleOwnership() { }
/**
* Query a driver's information using the given ID.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param documentId
* The unique ID of a document in the Person table.
* @return a {@link Person} object.
* @throws IllegalStateException if failed to convert parameter into {@link IonValue}.
*/
public static Person findPersonFromDocumentId(final TransactionExecutor txn, final String documentId) {
try {
log.info("Finding person for documentId: {}...", documentId);
final String query = "SELECT p.* FROM Person AS p BY pid WHERE pid = ?";
Result result = txn.execute(query, Constants.MAPPER.writeValueAsIonValue(documentId));
if (result.isEmpty()) {
throw new IllegalStateException("Unable to find person with ID: " + documentId);
}
return Constants.MAPPER.readValue(result.iterator().next(), Person.class);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Find the primary owner for the given VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @return a {@link Person} object.
* @throws IllegalStateException if failed to convert parameter into {@link IonValue}.
*/
public static Person findPrimaryOwnerForVehicle(final TransactionExecutor txn, final String vin) {
try {
log.info("Finding primary owner for vehicle with Vin: {}...", vin);
final String query = "SELECT Owners.PrimaryOwner.PersonId FROM VehicleRegistration AS v WHERE v.VIN = ?";
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(vin));
Result result = txn.execute(query, parameters);
final List documents = ScanTable.toIonStructs(result);
ScanTable.printDocuments(documents);
if (documents.isEmpty()) {
throw new IllegalStateException("Unable to find registrations with VIN: " + vin);
}
final IonReader reader = IonReaderBuilder.standard().build(documents.get(0));
final String personId = Constants.MAPPER.readValue(reader, LinkedHashMap.class).get("PersonId").toString();
return findPersonFromDocumentId(txn, personId);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Update the primary owner for a vehicle registration with the given documentId.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @param documentId
* New PersonId for the primary owner.
* @throws IllegalStateException if no vehicle registration was found using the given document ID and VIN, or if failed
* to convert parameters into {@link IonValue}.
*/
public static void updateVehicleRegistration(final TransactionExecutor txn, final String vin, final String documentId) {
try {
log.info("Updating primary owner for vehicle with Vin: {}...", vin);
final String query = "UPDATE VehicleRegistration AS v SET v.Owners.PrimaryOwner = ? WHERE v.VIN = ?";
final List parameters = new ArrayList<>();
parameters.add(Constants.MAPPER.writeValueAsIonValue(new Owner(documentId)));
parameters.add(Constants.MAPPER.writeValueAsIonValue(vin));
Result result = txn.execute(query, parameters);
ScanTable.printDocuments(result);
if (result.isEmpty()) {
throw new IllegalStateException("Unable to transfer vehicle, could not find registration.");
} else {
log.info("Successfully transferred vehicle with VIN '{}' to new owner.", vin);
}
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final String vin = SampleData.VEHICLES.get(0).getVin();
final String primaryOwnerGovId = SampleData.PEOPLE.get(0).getGovId();
final String newPrimaryOwnerGovId = SampleData.PEOPLE.get(1).getGovId();
ConnectToLedger.getDriver().execute(txn -> {
final Person primaryOwner = findPrimaryOwnerForVehicle(txn, vin);
if (!primaryOwner.getGovId().equals(primaryOwnerGovId)) {
// Verify the primary owner.
throw new IllegalStateException("Incorrect primary owner identified for vehicle, unable to transfer.");
}
final String newOwner = Person.getDocumentIdByGovId(txn, newPrimaryOwnerGovId);
updateVehicleRegistration(txn, vin, newOwner);
});
log.info("Successfully transferred vehicle ownership!");
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonReader;
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonValue;
import com.amazon.ion.system.IonReaderBuilder;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.Owner;
import software.amazon.qldb.tutorial.model.Person;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Find primary owner for a particular vehicle's VIN.
* Transfer to another primary owner for a particular vehicle's VIN.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class TransferVehicleOwnership {
public static final Logger log = LoggerFactory.getLogger(TransferVehicleOwnership.class);
private TransferVehicleOwnership() { }
/**
* Query a driver's information using the given ID.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param documentId
* The unique ID of a document in the Person table.
* @return a {@link Person} object.
* @throws IllegalStateException if failed to convert parameter into {@link IonValue}.
*/
public static Person findPersonFromDocumentId(final TransactionExecutor txn, final String documentId) {
try {
log.info("Finding person for documentId: {}...", documentId);
final String query = "SELECT p.* FROM Person AS p BY pid WHERE pid = ?";
Result result = txn.execute(query, Constants.MAPPER.writeValueAsIonValue(documentId));
if (result.isEmpty()) {
throw new IllegalStateException("Unable to find person with ID: " + documentId);
}
return Constants.MAPPER.readValue(result.iterator().next(), Person.class);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Find the primary owner for the given VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @return a {@link Person} object.
* @throws IllegalStateException if failed to convert parameter into {@link IonValue}.
*/
public static Person findPrimaryOwnerForVehicle(final TransactionExecutor txn, final String vin) {
try {
log.info("Finding primary owner for vehicle with Vin: {}...", vin);
final String query = "SELECT Owners.PrimaryOwner.PersonId FROM VehicleRegistration AS v WHERE v.VIN = ?";
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(vin));
Result result = txn.execute(query, parameters);
final List documents = ScanTable.toIonStructs(result);
ScanTable.printDocuments(documents);
if (documents.isEmpty()) {
throw new IllegalStateException("Unable to find registrations with VIN: " + vin);
}
final IonReader reader = IonReaderBuilder.standard().build(documents.get(0));
final String personId = Constants.MAPPER.readValue(reader, LinkedHashMap.class).get("PersonId").toString();
return findPersonFromDocumentId(txn, personId);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Update the primary owner for a vehicle registration with the given documentId.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @param documentId
* New PersonId for the primary owner.
* @throws IllegalStateException if no vehicle registration was found using the given document ID and VIN, or if failed
* to convert parameters into {@link IonValue}.
*/
public static void updateVehicleRegistration(final TransactionExecutor txn, final String vin, final String documentId) {
try {
log.info("Updating primary owner for vehicle with Vin: {}...", vin);
final String query = "UPDATE VehicleRegistration AS v SET v.Owners.PrimaryOwner = ? WHERE v.VIN = ?";
final List parameters = new ArrayList<>();
parameters.add(Constants.MAPPER.writeValueAsIonValue(new Owner(documentId)));
parameters.add(Constants.MAPPER.writeValueAsIonValue(vin));
Result result = txn.execute(query, parameters);
ScanTable.printDocuments(result);
if (result.isEmpty()) {
throw new IllegalStateException("Unable to transfer vehicle, could not find registration.");
} else {
log.info("Successfully transferred vehicle with VIN '{}' to new owner.", vin);
}
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final String vin = SampleData.VEHICLES.get(0).getVin();
final String primaryOwnerGovId = SampleData.PEOPLE.get(0).getGovId();
final String newPrimaryOwnerGovId = SampleData.PEOPLE.get(1).getGovId();
ConnectToLedger.getDriver().execute(txn -> {
final Person primaryOwner = findPrimaryOwnerForVehicle(txn, vin);
if (!primaryOwner.getGovId().equals(primaryOwnerGovId)) {
// Verify the primary owner.
throw new IllegalStateException("Incorrect primary owner identified for vehicle, unable to transfer.");
}
final String newOwner = Person.getDocumentIdByGovId(txn, newPrimaryOwnerGovId);
updateVehicleRegistration(txn, vin, newOwner);
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
log.info("Successfully transferred vehicle ownership!");
}
}
```
------
1. Compile y ejecute el siguiente programa (`AddSecondaryOwner.java`) para añadir un propietario secundario al vehículo con el VIN `KM8SRDHF6EU074761` en su libro mayor.
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.io.IOException;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.amazon.ion.IonValue;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.Owner;
import software.amazon.qldb.tutorial.model.Owners;
import software.amazon.qldb.tutorial.model.Person;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Finds and adds secondary owners for a vehicle.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class AddSecondaryOwner {
public static final Logger log = LoggerFactory.getLogger(AddSecondaryOwner.class);
private AddSecondaryOwner() { }
/**
* Check whether a secondary owner has already been registered for the given VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @param secondaryOwnerId
* The secondary owner to add.
* @return {@code true} if the given secondary owner has already been registered, {@code false} otherwise.
* @throws IllegalStateException if failed to convert VIN to an {@link IonValue}.
*/
public static boolean isSecondaryOwnerForVehicle(final TransactionExecutor txn, final String vin,
final String secondaryOwnerId) {
try {
log.info("Finding secondary owners for vehicle with VIN: {}...", vin);
final String query = "SELECT Owners.SecondaryOwners FROM VehicleRegistration AS v WHERE v.VIN = ?";
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(vin));
final Result result = txn.execute(query, parameters);
final Iterator itr = result.iterator();
if (!itr.hasNext()) {
return false;
}
final Owners owners = Constants.MAPPER.readValue(itr.next(), Owners.class);
if (null != owners.getSecondaryOwners()) {
for (Owner owner : owners.getSecondaryOwners()) {
if (secondaryOwnerId.equalsIgnoreCase(owner.getPersonId())) {
return true;
}
}
}
return false;
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Adds a secondary owner for the specified VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @param secondaryOwner
* The secondary owner to add.
* @throws IllegalStateException if failed to convert parameter into an {@link IonValue}.
*/
public static void addSecondaryOwnerForVin(final TransactionExecutor txn, final String vin,
final String secondaryOwner) {
try {
log.info("Inserting secondary owner for vehicle with VIN: {}...", vin);
final String query = String.format("FROM VehicleRegistration AS v WHERE v.VIN = ?" +
"INSERT INTO v.Owners.SecondaryOwners VALUE ?");
final IonValue newOwner = Constants.MAPPER.writeValueAsIonValue(new Owner(secondaryOwner));
final IonValue vinAsIonValue = Constants.MAPPER.writeValueAsIonValue(vin);
Result result = txn.execute(query, vinAsIonValue, newOwner);
log.info("VehicleRegistration Document IDs which had secondary owners added: ");
ScanTable.printDocuments(result);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final String vin = SampleData.VEHICLES.get(1).getVin();
final String govId = SampleData.PEOPLE.get(0).getGovId();
ConnectToLedger.getDriver().execute(txn -> {
final String documentId = Person.getDocumentIdByGovId(txn, govId);
if (isSecondaryOwnerForVehicle(txn, vin, documentId)) {
log.info("Person with ID {} has already been added as a secondary owner of this vehicle.", govId);
} else {
addSecondaryOwnerForVin(txn, vin, documentId);
}
});
log.info("Secondary owners successfully updated.");
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.io.IOException;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.amazon.ion.IonValue;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.Owner;
import software.amazon.qldb.tutorial.model.Owners;
import software.amazon.qldb.tutorial.model.Person;
import software.amazon.qldb.tutorial.model.SampleData;
/**
* Finds and adds secondary owners for a vehicle.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class AddSecondaryOwner {
public static final Logger log = LoggerFactory.getLogger(AddSecondaryOwner.class);
private AddSecondaryOwner() { }
/**
* Check whether a secondary owner has already been registered for the given VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @param secondaryOwnerId
* The secondary owner to add.
* @return {@code true} if the given secondary owner has already been registered, {@code false} otherwise.
* @throws IllegalStateException if failed to convert VIN to an {@link IonValue}.
*/
public static boolean isSecondaryOwnerForVehicle(final TransactionExecutor txn, final String vin,
final String secondaryOwnerId) {
try {
log.info("Finding secondary owners for vehicle with VIN: {}...", vin);
final String query = "SELECT Owners.SecondaryOwners FROM VehicleRegistration AS v WHERE v.VIN = ?";
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(vin));
final Result result = txn.execute(query, parameters);
final Iterator itr = result.iterator();
if (!itr.hasNext()) {
return false;
}
final Owners owners = Constants.MAPPER.readValue(itr.next(), Owners.class);
if (null != owners.getSecondaryOwners()) {
for (Owner owner : owners.getSecondaryOwners()) {
if (secondaryOwnerId.equalsIgnoreCase(owner.getPersonId())) {
return true;
}
}
}
return false;
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Adds a secondary owner for the specified VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* Unique VIN for a vehicle.
* @param secondaryOwner
* The secondary owner to add.
* @throws IllegalStateException if failed to convert parameter into an {@link IonValue}.
*/
public static void addSecondaryOwnerForVin(final TransactionExecutor txn, final String vin,
final String secondaryOwner) {
try {
log.info("Inserting secondary owner for vehicle with VIN: {}...", vin);
final String query = String.format("FROM VehicleRegistration AS v WHERE v.VIN = '%s' " +
"INSERT INTO v.Owners.SecondaryOwners VALUE ?", vin);
final IonValue newOwner = Constants.MAPPER.writeValueAsIonValue(new Owner(secondaryOwner));
Result result = txn.execute(query, newOwner);
log.info("VehicleRegistration Document IDs which had secondary owners added: ");
ScanTable.printDocuments(result);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final String vin = SampleData.VEHICLES.get(1).getVin();
final String govId = SampleData.PEOPLE.get(0).getGovId();
ConnectToLedger.getDriver().execute(txn -> {
final String documentId = Person.getDocumentIdByGovId(txn, govId);
if (isSecondaryOwnerForVehicle(txn, vin, documentId)) {
log.info("Person with ID {} has already been added as a secondary owner of this vehicle.", govId);
} else {
addSecondaryOwnerForVin(txn, vin, documentId);
}
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
log.info("Secondary owners successfully updated.");
}
}
```
------
Para revisar estos cambios en el libro mayor `vehicle-registration`, consulte [Paso 6: ver el historial de revisiones de un documento](getting-started.java.step-6.md).
# Paso 6: ver el historial de revisiones de un documento
**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.
Tras modificar los datos de registro de un vehículo en el paso anterior, puede consultar el historial de todos sus propietarios registrados y cualquier otro campo actualizado. En este paso, consulta el historial de revisiones de un documento de la tabla `VehicleRegistration` del libro mayor `vehicle-registration`.
**Para ver el historial de revisiones**
1. Revise el siguiente programa (`QueryHistory.java`).
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.io.IOException;
import java.time.Instant;
import java.time.temporal.ChronoUnit;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.amazon.ion.IonValue;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
import software.amazon.qldb.tutorial.model.VehicleRegistration;
/**
* Query a table's history for a particular set of documents.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class QueryHistory {
public static final Logger log = LoggerFactory.getLogger(QueryHistory.class);
private static final int THREE_MONTHS = 90;
private QueryHistory() { }
/**
* In this example, query the 'VehicleRegistration' history table to find all previous primary owners for a VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* VIN to find previous primary owners for.
* @param query
* The query to find previous primary owners.
* @throws IllegalStateException if failed to convert document ID to an {@link IonValue}.
*/
public static void previousPrimaryOwners(final TransactionExecutor txn, final String vin, final String query) {
try {
final String docId = VehicleRegistration.getDocumentIdByVin(txn, vin);
log.info("Querying the 'VehicleRegistration' table's history using VIN: {}...", vin);
final Result result = txn.execute(query, Constants.MAPPER.writeValueAsIonValue(docId));
ScanTable.printDocuments(result);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final String threeMonthsAgo = Instant.now().minus(THREE_MONTHS, ChronoUnit.DAYS).toString();
final String query = String.format("SELECT data.Owners.PrimaryOwner, metadata.version "
+ "FROM history(VehicleRegistration, `%s`) "
+ "AS h WHERE h.metadata.id = ?", threeMonthsAgo);
ConnectToLedger.getDriver().execute(txn -> {
final String vin = SampleData.VEHICLES.get(0).getVin();
previousPrimaryOwners(txn, vin, query);
});
log.info("Successfully queried history.");
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonValue;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.QldbSession;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
import software.amazon.qldb.tutorial.model.VehicleRegistration;
import java.io.IOException;
import java.time.Instant;
import java.time.temporal.ChronoUnit;
import java.util.Collections;
import java.util.List;
/**
* Query a table's history for a particular set of documents.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class QueryHistory {
public static final Logger log = LoggerFactory.getLogger(QueryHistory.class);
private static final int THREE_MONTHS = 90;
private QueryHistory() { }
/**
* In this example, query the 'VehicleRegistration' history table to find all previous primary owners for a VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* VIN to find previous primary owners for.
* @param query
* The query to find previous primary owners.
* @throws IllegalStateException if failed to convert document ID to an {@link IonValue}.
*/
public static void previousPrimaryOwners(final TransactionExecutor txn, final String vin, final String query) {
try {
final String docId = VehicleRegistration.getDocumentIdByVin(txn, vin);
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(docId));
log.info("Querying the 'VehicleRegistration' table's history using VIN: {}...", vin);
final Result result = txn.execute(query, parameters);
ScanTable.printDocuments(result);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
public static void main(final String... args) {
final String threeMonthsAgo = Instant.now().minus(THREE_MONTHS, ChronoUnit.DAYS).toString();
final String query = String.format("SELECT data.Owners.PrimaryOwner, metadata.version "
+ "FROM history(VehicleRegistration, `%s`) "
+ "AS h WHERE h.metadata.id = ?", threeMonthsAgo);
ConnectToLedger.getDriver().execute(txn -> {
final String vin = SampleData.VEHICLES.get(0).getVin();
previousPrimaryOwners(txn, vin, query);
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
log.info("Successfully queried history.");
}
}
```
------
**nota**
Puede ver el historial de revisiones de un documento consultando la [Función de historial](working.history.md#working.history.function) integrada en la siguiente sintaxis.
```
SELECT * FROM history( table_name [, `start-time` [, `end-time` ] ] ) AS h
[ WHERE h.metadata.id = 'id' ]
```
Tanto la *hora de inicio* como la hora de *finalización* son opcionales. Son valores literales de Amazon Ion que se pueden indicar con acentos graves (``...``). Para obtener más información, consulte [Consulta de Ion con PartiQL en Amazon QLDB](ql-reference.query.md).
Como práctica recomendada, califique una consulta de historial con un intervalo de fechas (*hora de inicio* y *hora de finalización*) y un identificador de documento (`metadata.id`). QLDB procesa las consultas `SELECT` en las transacciones, que están sujetas a un [límite de tiempo de espera de las transacciones](limits.md#limits.fixed).
El historial de QLDB se indexa por ID de documento y no se pueden crear índices de historial adicionales en este momento. Las consultas de historial que incluyen una hora de inicio y una hora de finalización se benefician de la calificación por intervalo de fechas.
1. Compile y ejecute el programa `QueryHistory.java` para consultar el historial de revisiones del documento `VehicleRegistration` con el VIN `1N4AL11D75C109151`.
Para verificar criptográficamente la revisión de un documento en el libro mayor `vehicle-registration`, continúe con [Paso 7: verificar un documento en un libro mayor](getting-started.java.step-7.md).
# Paso 7: verificar un documento en un libro mayor
**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.
Con Amazon QLDB, puede verificar de manera eficiente la integridad de un documento del diario de su libro mayor mediante el uso de hash criptográfico con SHA-256. Para obtener más información sobre cómo funcionan la verificación y el hash criptográfico en QLDB, consulte [Verificación de datos en Amazon QLDB](verification.md).
En este paso, verificará la revisión de un documento en la tabla `VehicleRegistration` del libro mayor `vehicle-registration`. En primer lugar, solicite un resumen, que se devuelve como un archivo de salida y actúa como firma de todo el historial de cambios del libro mayor. A continuación, solicita una prueba de la revisión relativa a ese resumen. Con esta prueba, se verifica la integridad de la revisión si se aprueban todas las comprobaciones de validación.
**Verificación de la revisión de un documento**
1. Revise los siguientes archivos `.java`, que representan los objetos de QLDB necesarios para las clases de verificación y de utilidad, con métodos auxiliares para los valores Ion y de cadenas.
1. `BlockAddress.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import java.util.Objects;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* Represents the BlockAddress field of a QLDB document.
*/
public final class BlockAddress {
private static final Logger log = LoggerFactory.getLogger(BlockAddress.class);
private final String strandId;
private final long sequenceNo;
@JsonCreator
public BlockAddress(@JsonProperty("strandId") final String strandId,
@JsonProperty("sequenceNo") final long sequenceNo) {
this.strandId = strandId;
this.sequenceNo = sequenceNo;
}
public long getSequenceNo() {
return sequenceNo;
}
public String getStrandId() {
return strandId;
}
@Override
public String toString() {
return "BlockAddress{"
+ "strandId='" + strandId + '\''
+ ", sequenceNo=" + sequenceNo
+ '}';
}
@Override
public boolean equals(final Object o) {
if (this == o) {
return true;
}
if (o == null || getClass() != o.getClass()) {
return false;
}
BlockAddress that = (BlockAddress) o;
return sequenceNo == that.sequenceNo
&& strandId.equals(that.strandId);
}
@Override
public int hashCode() {
// CHECKSTYLE:OFF - Disabling as we are generating a hashCode of multiple properties.
return Objects.hash(strandId, sequenceNo);
// CHECKSTYLE:ON
}
}
```
1. `Proof.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import com.amazon.ion.IonReader;
import com.amazon.ion.IonSystem;
import com.amazon.ion.system.IonSystemBuilder;
import com.amazonaws.services.qldb.model.GetRevisionRequest;
import com.amazonaws.services.qldb.model.GetRevisionResult;
import java.util.ArrayList;
import java.util.List;
/**
* A Java representation of the {@link Proof} object.
* Returned from the {@link com.amazonaws.services.qldb.AmazonQLDB#getRevision(GetRevisionRequest)} api.
*/
public final class Proof {
private static final IonSystem SYSTEM = IonSystemBuilder.standard().build();
private List internalHashes;
public Proof(final List internalHashes) {
this.internalHashes = internalHashes;
}
public List getInternalHashes() {
return internalHashes;
}
/**
* Decodes a {@link Proof} from an ion text String. This ion text is returned in
* a {@link GetRevisionResult#getProof()}
*
* @param ionText
* The ion text representing a {@link Proof} object.
* @return {@link JournalBlock} parsed from the ion text.
* @throws IllegalStateException if failed to parse the {@link Proof} object from the given ion text.
*/
public static Proof fromBlob(final String ionText) {
try {
IonReader reader = SYSTEM.newReader(ionText);
List list = new ArrayList<>();
reader.next();
reader.stepIn();
while (reader.next() != null) {
list.add(reader.newBytes());
}
return new Proof(list);
} catch (Exception e) {
throw new IllegalStateException("Failed to parse a Proof from byte array");
}
}
}
```
1. `QldbIonUtils.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import com.amazon.ion.IonReader;
import com.amazon.ion.IonValue;
import com.amazon.ionhash.IonHashReader;
import com.amazon.ionhash.IonHashReaderBuilder;
import com.amazon.ionhash.MessageDigestIonHasherProvider;
import software.amazon.qldb.tutorial.Constants;
public class QldbIonUtils {
private static MessageDigestIonHasherProvider ionHasherProvider = new MessageDigestIonHasherProvider("SHA-256");
private QldbIonUtils() {}
/**
* Builds a hash value from the given {@link IonValue}.
*
* @param ionValue
* The {@link IonValue} to hash.
* @return a byte array representing the hash value.
*/
public static byte[] hashIonValue(final IonValue ionValue) {
IonReader reader = Constants.SYSTEM.newReader(ionValue);
IonHashReader hashReader = IonHashReaderBuilder.standard()
.withHasherProvider(ionHasherProvider)
.withReader(reader)
.build();
while (hashReader.next() != null) { }
return hashReader.digest();
}
}
```
1. `QldbStringUtils.java`
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import com.amazon.ion.IonWriter;
import com.amazon.ion.system.IonReaderBuilder;
import com.amazon.ion.system.IonTextWriterBuilder;
import com.amazonaws.services.qldb.model.GetBlockResult;
import com.amazonaws.services.qldb.model.GetDigestResult;
import com.amazonaws.services.qldb.model.ValueHolder;
import java.io.IOException;
/**
* Helper methods to pretty-print certain QLDB response types.
*/
public class QldbStringUtils {
private QldbStringUtils() {}
/**
* Returns the string representation of a given {@link ValueHolder}.
* Adapted from the AWS SDK autogenerated {@code toString()} method, with sensitive values un-redacted.
* Additionally, this method pretty-prints any IonText included in the {@link ValueHolder}.
*
* @param valueHolder the {@link ValueHolder} to convert to a String.
* @return the String representation of the supplied {@link ValueHolder}.
*/
public static String toUnredactedString(ValueHolder valueHolder) {
StringBuilder sb = new StringBuilder();
sb.append("{");
if (valueHolder.getIonText() != null) {
sb.append("IonText: ");
IonWriter prettyWriter = IonTextWriterBuilder.pretty().build(sb);
try {
prettyWriter.writeValues(IonReaderBuilder.standard().build(valueHolder.getIonText()));
} catch (IOException ioe) {
sb.append("**Exception while printing this IonText**");
}
}
sb.append("}");
return sb.toString();
}
/**
* Returns the string representation of a given {@link GetBlockResult}.
* Adapted from the AWS SDK autogenerated {@code toString()} method, with sensitive values un-redacted.
*
* @param getBlockResult the {@link GetBlockResult} to convert to a String.
* @return the String representation of the supplied {@link GetBlockResult}.
*/
public static String toUnredactedString(GetBlockResult getBlockResult) {
StringBuilder sb = new StringBuilder();
sb.append("{");
if (getBlockResult.getBlock() != null) {
sb.append("Block: ").append(toUnredactedString(getBlockResult.getBlock())).append(",");
}
if (getBlockResult.getProof() != null) {
sb.append("Proof: ").append(toUnredactedString(getBlockResult.getProof()));
}
sb.append("}");
return sb.toString();
}
/**
* Returns the string representation of a given {@link GetDigestResult}.
* Adapted from the AWS SDK autogenerated {@code toString()} method, with sensitive values un-redacted.
*
* @param getDigestResult the {@link GetDigestResult} to convert to a String.
* @return the String representation of the supplied {@link GetDigestResult}.
*/
public static String toUnredactedString(GetDigestResult getDigestResult) {
StringBuilder sb = new StringBuilder();
sb.append("{");
if (getDigestResult.getDigest() != null) {
sb.append("Digest: ").append(getDigestResult.getDigest()).append(",");
}
if (getDigestResult.getDigestTipAddress() != null) {
sb.append("DigestTipAddress: ").append(toUnredactedString(getDigestResult.getDigestTipAddress()));
}
sb.append("}");
return sb.toString();
}
}
```
1. `Verifier.java`
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import java.nio.ByteBuffer;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Comparator;
import java.util.Iterator;
import java.util.List;
import java.util.concurrent.ThreadLocalRandom;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.amazonaws.util.Base64;
import software.amazon.qldb.tutorial.qldb.Proof;
/**
* Encapsulates the logic to verify the integrity of revisions or blocks in a QLDB ledger.
*
* The main entry point is {@link #verify(byte[], byte[], String)}.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class Verifier {
public static final Logger log = LoggerFactory.getLogger(Verifier.class);
private static final int HASH_LENGTH = 32;
private static final int UPPER_BOUND = 8;
/**
* Compares two hashes by their signed byte values in little-endian order.
*/
private static Comparator hashComparator = (h1, h2) -> {
if (h1.length != HASH_LENGTH || h2.length != HASH_LENGTH) {
throw new IllegalArgumentException("Invalid hash.");
}
for (int i = h1.length - 1; i >= 0; i--) {
int byteEqual = Byte.compare(h1[i], h2[i]);
if (byteEqual != 0) {
return byteEqual;
}
}
return 0;
};
private Verifier() { }
/**
* Verify the integrity of a document with respect to a QLDB ledger digest.
*
* The verification algorithm includes the following steps:
*
* 1. {@link #buildCandidateDigest(Proof, byte[])} build the candidate digest from the internal hashes
* in the {@link Proof}.
* 2. Check that the {@code candidateLedgerDigest} is equal to the {@code ledgerDigest}.
*
* @param documentHash
* The hash of the document to be verified.
* @param digest
* The QLDB ledger digest. This digest should have been retrieved using
* {@link com.amazonaws.services.qldb.AmazonQLDB#getDigest}
* @param proofBlob
* The ion encoded bytes representing the {@link Proof} associated with the supplied
* {@code digestTipAddress} and {@code address} retrieved using
* {@link com.amazonaws.services.qldb.AmazonQLDB#getRevision}.
* @return {@code true} if the record is verified or {@code false} if it is not verified.
*/
public static boolean verify(
final byte[] documentHash,
final byte[] digest,
final String proofBlob
) {
Proof proof = Proof.fromBlob(proofBlob);
byte[] candidateDigest = buildCandidateDigest(proof, documentHash);
return Arrays.equals(digest, candidateDigest);
}
/**
* Build the candidate digest representing the entire ledger from the internal hashes of the {@link Proof}.
*
* @param proof
* A Java representation of {@link Proof}
* returned from {@link com.amazonaws.services.qldb.AmazonQLDB#getRevision}.
* @param leafHash
* Leaf hash to build the candidate digest with.
* @return a byte array of the candidate digest.
*/
private static byte[] buildCandidateDigest(final Proof proof, final byte[] leafHash) {
return calculateRootHashFromInternalHashes(proof.getInternalHashes(), leafHash);
}
/**
* Get a new instance of {@link MessageDigest} using the SHA-256 algorithm.
*
* @return an instance of {@link MessageDigest}.
* @throws IllegalStateException if the algorithm is not available on the current JVM.
*/
static MessageDigest newMessageDigest() {
try {
return MessageDigest.getInstance("SHA-256");
} catch (NoSuchAlgorithmException e) {
log.error("Failed to create SHA-256 MessageDigest", e);
throw new IllegalStateException("SHA-256 message digest is unavailable", e);
}
}
/**
* Takes two hashes, sorts them, concatenates them, and then returns the
* hash of the concatenated array.
*
* @param h1
* Byte array containing one of the hashes to compare.
* @param h2
* Byte array containing one of the hashes to compare.
* @return the concatenated array of hashes.
*/
public static byte[] dot(final byte[] h1, final byte[] h2) {
if (h1.length == 0) {
return h2;
}
if (h2.length == 0) {
return h1;
}
byte[] concatenated = new byte[h1.length + h2.length];
if (hashComparator.compare(h1, h2) < 0) {
System.arraycopy(h1, 0, concatenated, 0, h1.length);
System.arraycopy(h2, 0, concatenated, h1.length, h2.length);
} else {
System.arraycopy(h2, 0, concatenated, 0, h2.length);
System.arraycopy(h1, 0, concatenated, h2.length, h1.length);
}
MessageDigest messageDigest = newMessageDigest();
messageDigest.update(concatenated);
return messageDigest.digest();
}
/**
* Starting with the provided {@code leafHash} combined with the provided {@code internalHashes}
* pairwise until only the root hash remains.
*
* @param internalHashes
* Internal hashes of Merkle tree.
* @param leafHash
* Leaf hashes of Merkle tree.
* @return the root hash.
*/
private static byte[] calculateRootHashFromInternalHashes(final List internalHashes, final byte[] leafHash) {
return internalHashes.stream().reduce(leafHash, Verifier::dot);
}
/**
* Flip a single random bit in the given byte array. This method is used to demonstrate
* QLDB's verification features.
*
* @param original
* The original byte array.
* @return the altered byte array with a single random bit changed.
*/
public static byte[] flipRandomBit(final byte[] original) {
if (original.length == 0) {
throw new IllegalArgumentException("Array cannot be empty!");
}
int alteredPosition = ThreadLocalRandom.current().nextInt(original.length);
int b = ThreadLocalRandom.current().nextInt(UPPER_BOUND);
byte[] altered = new byte[original.length];
System.arraycopy(original, 0, altered, 0, original.length);
altered[alteredPosition] = (byte) (altered[alteredPosition] ^ (1 << b));
return altered;
}
public static String toBase64(byte[] arr) {
return new String(Base64.encode(arr), StandardCharsets.UTF_8);
}
/**
* Convert a {@link ByteBuffer} into byte array.
*
* @param buffer
* The {@link ByteBuffer} to convert.
* @return the converted byte array.
*/
public static byte[] convertByteBufferToByteArray(final ByteBuffer buffer) {
byte[] arr = new byte[buffer.remaining()];
buffer.get(arr);
return arr;
}
/**
* Calculates the root hash from a list of hashes that represent the base of a Merkle tree.
*
* @param hashes
* The list of byte arrays representing hashes making up base of a Merkle tree.
* @return a byte array that is the root hash of the given list of hashes.
*/
public static byte[] calculateMerkleTreeRootHash(List hashes) {
if (hashes.isEmpty()) {
return new byte[0];
}
List remaining = combineLeafHashes(hashes);
while (remaining.size() > 1) {
remaining = combineLeafHashes(remaining);
}
return remaining.get(0);
}
private static List combineLeafHashes(List hashes) {
List combinedHashes = new ArrayList<>();
Iterator it = hashes.stream().iterator();
while (it.hasNext()) {
byte[] left = it.next();
if (it.hasNext()) {
byte[] right = it.next();
byte[] combined = dot(left, right);
combinedHashes.add(combined);
} else {
combinedHashes.add(left);
}
}
return combinedHashes;
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.util.Base64;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.tutorial.qldb.Proof;
import java.nio.ByteBuffer;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.*;
import java.util.concurrent.ThreadLocalRandom;
/**
* Encapsulates the logic to verify the integrity of revisions or blocks in a QLDB ledger.
*
* The main entry point is {@link #verify(byte[], byte[], String)}.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class Verifier {
public static final Logger log = LoggerFactory.getLogger(Verifier.class);
private static final int HASH_LENGTH = 32;
private static final int UPPER_BOUND = 8;
/**
* Compares two hashes by their signed byte values in little-endian order.
*/
private static Comparator hashComparator = (h1, h2) -> {
if (h1.length != HASH_LENGTH || h2.length != HASH_LENGTH) {
throw new IllegalArgumentException("Invalid hash.");
}
for (int i = h1.length - 1; i >= 0; i--) {
int byteEqual = Byte.compare(h1[i], h2[i]);
if (byteEqual != 0) {
return byteEqual;
}
}
return 0;
};
private Verifier() { }
/**
* Verify the integrity of a document with respect to a QLDB ledger digest.
*
* The verification algorithm includes the following steps:
*
* 1. {@link #buildCandidateDigest(Proof, byte[])} build the candidate digest from the internal hashes
* in the {@link Proof}.
* 2. Check that the {@code candidateLedgerDigest} is equal to the {@code ledgerDigest}.
*
* @param documentHash
* The hash of the document to be verified.
* @param digest
* The QLDB ledger digest. This digest should have been retrieved using
* {@link com.amazonaws.services.qldb.AmazonQLDB#getDigest}
* @param proofBlob
* The ion encoded bytes representing the {@link Proof} associated with the supplied
* {@code digestTipAddress} and {@code address} retrieved using
* {@link com.amazonaws.services.qldb.AmazonQLDB#getRevision}.
* @return {@code true} if the record is verified or {@code false} if it is not verified.
*/
public static boolean verify(
final byte[] documentHash,
final byte[] digest,
final String proofBlob
) {
Proof proof = Proof.fromBlob(proofBlob);
byte[] candidateDigest = buildCandidateDigest(proof, documentHash);
return Arrays.equals(digest, candidateDigest);
}
/**
* Build the candidate digest representing the entire ledger from the internal hashes of the {@link Proof}.
*
* @param proof
* A Java representation of {@link Proof}
* returned from {@link com.amazonaws.services.qldb.AmazonQLDB#getRevision}.
* @param leafHash
* Leaf hash to build the candidate digest with.
* @return a byte array of the candidate digest.
*/
private static byte[] buildCandidateDigest(final Proof proof, final byte[] leafHash) {
return calculateRootHashFromInternalHashes(proof.getInternalHashes(), leafHash);
}
/**
* Get a new instance of {@link MessageDigest} using the SHA-256 algorithm.
*
* @return an instance of {@link MessageDigest}.
* @throws IllegalStateException if the algorithm is not available on the current JVM.
*/
static MessageDigest newMessageDigest() {
try {
return MessageDigest.getInstance("SHA-256");
} catch (NoSuchAlgorithmException e) {
log.error("Failed to create SHA-256 MessageDigest", e);
throw new IllegalStateException("SHA-256 message digest is unavailable", e);
}
}
/**
* Takes two hashes, sorts them, concatenates them, and then returns the
* hash of the concatenated array.
*
* @param h1
* Byte array containing one of the hashes to compare.
* @param h2
* Byte array containing one of the hashes to compare.
* @return the concatenated array of hashes.
*/
public static byte[] dot(final byte[] h1, final byte[] h2) {
if (h1.length == 0) {
return h2;
}
if (h2.length == 0) {
return h1;
}
byte[] concatenated = new byte[h1.length + h2.length];
if (hashComparator.compare(h1, h2) < 0) {
System.arraycopy(h1, 0, concatenated, 0, h1.length);
System.arraycopy(h2, 0, concatenated, h1.length, h2.length);
} else {
System.arraycopy(h2, 0, concatenated, 0, h2.length);
System.arraycopy(h1, 0, concatenated, h2.length, h1.length);
}
MessageDigest messageDigest = newMessageDigest();
messageDigest.update(concatenated);
return messageDigest.digest();
}
/**
* Starting with the provided {@code leafHash} combined with the provided {@code internalHashes}
* pairwise until only the root hash remains.
*
* @param internalHashes
* Internal hashes of Merkle tree.
* @param leafHash
* Leaf hashes of Merkle tree.
* @return the root hash.
*/
private static byte[] calculateRootHashFromInternalHashes(final List internalHashes, final byte[] leafHash) {
return internalHashes.stream().reduce(leafHash, Verifier::dot);
}
/**
* Flip a single random bit in the given byte array. This method is used to demonstrate
* QLDB's verification features.
*
* @param original
* The original byte array.
* @return the altered byte array with a single random bit changed.
*/
public static byte[] flipRandomBit(final byte[] original) {
if (original.length == 0) {
throw new IllegalArgumentException("Array cannot be empty!");
}
int alteredPosition = ThreadLocalRandom.current().nextInt(original.length);
int b = ThreadLocalRandom.current().nextInt(UPPER_BOUND);
byte[] altered = new byte[original.length];
System.arraycopy(original, 0, altered, 0, original.length);
altered[alteredPosition] = (byte) (altered[alteredPosition] ^ (1 << b));
return altered;
}
public static String toBase64(byte[] arr) {
return new String(Base64.encode(arr), StandardCharsets.UTF_8);
}
/**
* Convert a {@link ByteBuffer} into byte array.
*
* @param buffer
* The {@link ByteBuffer} to convert.
* @return the converted byte array.
*/
public static byte[] convertByteBufferToByteArray(final ByteBuffer buffer) {
byte[] arr = new byte[buffer.remaining()];
buffer.get(arr);
return arr;
}
/**
* Calculates the root hash from a list of hashes that represent the base of a Merkle tree.
*
* @param hashes
* The list of byte arrays representing hashes making up base of a Merkle tree.
* @return a byte array that is the root hash of the given list of hashes.
*/
public static byte[] calculateMerkleTreeRootHash(List hashes) {
if (hashes.isEmpty()) {
return new byte[0];
}
List remaining = combineLeafHashes(hashes);
while (remaining.size() > 1) {
remaining = combineLeafHashes(remaining);
}
return remaining.get(0);
}
private static List combineLeafHashes(List hashes) {
List combinedHashes = new ArrayList<>();
Iterator it = hashes.stream().iterator();
while (it.hasNext()) {
byte[] left = it.next();
if (it.hasNext()) {
byte[] right = it.next();
byte[] combined = dot(left, right);
combinedHashes.add(combined);
} else {
combinedHashes.add(left);
}
}
return combinedHashes;
}
}
```
------
1. Utilice dos archivos `.java` (`GetDigest.java` y `GetRevision.java`) para completar los siguientes pasos:
+ Solicite un nuevo resumen del libro mayor `vehicle-registration`.
+ Solicitar una prueba de cada revisión del documento de la tabla `VehicleRegistration`.
+ Verifique las revisiones utilizando el resumen devuelto y compruébelo recalculando el resumen.
El programa `GetDigest.java` contiene el siguiente código.
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.services.qldb.AmazonQLDB;
import com.amazonaws.services.qldb.model.GetDigestRequest;
import com.amazonaws.services.qldb.model.GetDigestResult;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.tutorial.qldb.QldbStringUtils;
/**
* This is an example for retrieving the digest of a particular ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class GetDigest {
public static final Logger log = LoggerFactory.getLogger(GetDigest.class);
public static AmazonQLDB client = CreateLedger.getClient();
private GetDigest() { }
/**
* Calls {@link #getDigest(String)} for a ledger.
*
* @param args
* Arbitrary command-line arguments.
* @throws Exception if failed to get a ledger digest.
*/
public static void main(final String... args) throws Exception {
try {
getDigest(Constants.LEDGER_NAME);
} catch (Exception e) {
log.error("Unable to get a ledger digest!", e);
throw e;
}
}
/**
* Get the digest for the specified ledger.
*
* @param ledgerName
* The ledger to get digest from.
* @return {@link GetDigestResult}.
*/
public static GetDigestResult getDigest(final String ledgerName) {
log.info("Let's get the current digest of the ledger named {}.", ledgerName);
GetDigestRequest request = new GetDigestRequest()
.withName(ledgerName);
GetDigestResult result = client.getDigest(request);
log.info("Success. LedgerDigest: {}.", QldbStringUtils.toUnredactedString(result));
return result;
}
}
```
**nota**
Utilice el método `getDigest` para solicitar un resumen que incluya la *sugerencia* actual del diario del libro mayor. La sugerencia del diario hace referencia al último bloque confirmado en el momento en que QLDB recibe su solicitud.
El programa `GetRevision.java` contiene el siguiente código.
------
#### [ 2.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonReader;
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonSystem;
import com.amazon.ion.IonValue;
import com.amazon.ion.IonWriter;
import com.amazon.ion.system.IonReaderBuilder;
import com.amazon.ion.system.IonSystemBuilder;
import com.amazonaws.services.qldb.AmazonQLDB;
import com.amazonaws.services.qldb.model.GetDigestResult;
import com.amazonaws.services.qldb.model.GetRevisionRequest;
import com.amazonaws.services.qldb.model.GetRevisionResult;
import com.amazonaws.services.qldb.model.ValueHolder;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.QldbDriver;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
import software.amazon.qldb.tutorial.qldb.BlockAddress;
import software.amazon.qldb.tutorial.qldb.QldbRevision;
import software.amazon.qldb.tutorial.qldb.QldbStringUtils;
/**
* Verify the integrity of a document revision in a QLDB ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class GetRevision {
public static final Logger log = LoggerFactory.getLogger(GetRevision.class);
public static AmazonQLDB client = CreateLedger.getClient();
private static final IonSystem SYSTEM = IonSystemBuilder.standard().build();
private GetRevision() { }
public static void main(String... args) throws Exception {
final String vin = SampleData.REGISTRATIONS.get(0).getVin();
verifyRegistration(ConnectToLedger.getDriver(), Constants.LEDGER_NAME, vin);
}
/**
* Verify each version of the registration for the given VIN.
*
* @param driver
* A QLDB driver.
* @param ledgerName
* The ledger to get digest from.
* @param vin
* VIN to query the revision history of a specific registration with.
* @throws Exception if failed to verify digests.
* @throws AssertionError if document revision verification failed.
*/
public static void verifyRegistration(final QldbDriver driver, final String ledgerName, final String vin)
throws Exception {
log.info(String.format("Let's verify the registration with VIN=%s, in ledger=%s.", vin, ledgerName));
try {
log.info("First, let's get a digest.");
GetDigestResult digestResult = GetDigest.getDigest(ledgerName);
ValueHolder digestTipAddress = digestResult.getDigestTipAddress();
byte[] digestBytes = Verifier.convertByteBufferToByteArray(digestResult.getDigest());
log.info("Got a ledger digest. Digest end address={}, digest={}.",
QldbStringUtils.toUnredactedString(digestTipAddress),
Verifier.toBase64(digestBytes));
log.info(String.format("Next, let's query the registration with VIN=%s. "
+ "Then we can verify each version of the registration.", vin));
List documentsWithMetadataList = new ArrayList<>();
driver.execute(txn -> {
documentsWithMetadataList.addAll(queryRegistrationsByVin(txn, vin));
});
log.info("Registrations queried successfully!");
log.info(String.format("Found %s revisions of the registration with VIN=%s.",
documentsWithMetadataList.size(), vin));
for (IonStruct ionStruct : documentsWithMetadataList) {
QldbRevision document = QldbRevision.fromIon(ionStruct);
log.info(String.format("Let's verify the document: %s", document));
log.info("Let's get a proof for the document.");
GetRevisionResult proofResult = getRevision(
ledgerName,
document.getMetadata().getId(),
digestTipAddress,
document.getBlockAddress()
);
final IonValue proof = Constants.MAPPER.writeValueAsIonValue(proofResult.getProof());
final IonReader reader = IonReaderBuilder.standard().build(proof);
reader.next();
ByteArrayOutputStream baos = new ByteArrayOutputStream();
IonWriter writer = SYSTEM.newBinaryWriter(baos);
writer.writeValue(reader);
writer.close();
baos.flush();
baos.close();
byte[] byteProof = baos.toByteArray();
log.info(String.format("Got back a proof: %s", Verifier.toBase64(byteProof)));
boolean verified = Verifier.verify(
document.getHash(),
digestBytes,
proofResult.getProof().getIonText()
);
if (!verified) {
throw new AssertionError("Document revision is not verified!");
} else {
log.info("Success! The document is verified");
}
byte[] alteredDigest = Verifier.flipRandomBit(digestBytes);
log.info(String.format("Flipping one bit in the digest and assert that the document is NOT verified. "
+ "The altered digest is: %s", Verifier.toBase64(alteredDigest)));
verified = Verifier.verify(
document.getHash(),
alteredDigest,
proofResult.getProof().getIonText()
);
if (verified) {
throw new AssertionError("Expected document to not be verified against altered digest.");
} else {
log.info("Success! As expected flipping a bit in the digest causes verification to fail.");
}
byte[] alteredDocumentHash = Verifier.flipRandomBit(document.getHash());
log.info(String.format("Flipping one bit in the document's hash and assert that it is NOT verified. "
+ "The altered document hash is: %s.", Verifier.toBase64(alteredDocumentHash)));
verified = Verifier.verify(
alteredDocumentHash,
digestBytes,
proofResult.getProof().getIonText()
);
if (verified) {
throw new AssertionError("Expected altered document hash to not be verified against digest.");
} else {
log.info("Success! As expected flipping a bit in the document hash causes verification to fail.");
}
}
} catch (Exception e) {
log.error("Failed to verify digests.", e);
throw e;
}
log.info(String.format("Finished verifying the registration with VIN=%s in ledger=%s.", vin, ledgerName));
}
/**
* Get the revision of a particular document specified by the given document ID and block address.
*
* @param ledgerName
* Name of the ledger containing the document.
* @param documentId
* Unique ID for the document to be verified, contained in the committed view of the document.
* @param digestTipAddress
* The latest block location covered by the digest.
* @param blockAddress
* The location of the block to request.
* @return the requested revision.
*/
public static GetRevisionResult getRevision(final String ledgerName, final String documentId,
final ValueHolder digestTipAddress, final BlockAddress blockAddress) {
try {
GetRevisionRequest request = new GetRevisionRequest()
.withName(ledgerName)
.withDigestTipAddress(digestTipAddress)
.withBlockAddress(new ValueHolder().withIonText(Constants.MAPPER.writeValueAsIonValue(blockAddress)
.toString()))
.withDocumentId(documentId);
return client.getRevision(request);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Query the registration history for the given VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* The unique VIN to query.
* @return a list of {@link IonStruct} representing the registration history.
* @throws IllegalStateException if failed to convert parameters into {@link IonValue}
*/
public static List queryRegistrationsByVin(final TransactionExecutor txn, final String vin) {
log.info(String.format("Let's query the 'VehicleRegistration' table for VIN: %s...", vin));
log.info("Let's query the 'VehicleRegistration' table for VIN: {}...", vin);
final String query = String.format("SELECT * FROM _ql_committed_%s WHERE data.VIN = ?",
Constants.VEHICLE_REGISTRATION_TABLE_NAME);
try {
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(vin));
final Result result = txn.execute(query, parameters);
List list = ScanTable.toIonStructs(result);
log.info(String.format("Found %d document(s)!", list.size()));
return list;
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
}
```
------
#### [ 1.x ]
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazon.ion.IonReader;
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonValue;
import com.amazon.ion.IonWriter;
import com.amazon.ion.system.IonReaderBuilder;
import com.amazonaws.services.qldb.AmazonQLDB;
import com.amazonaws.services.qldb.model.GetDigestResult;
import com.amazonaws.services.qldb.model.GetRevisionRequest;
import com.amazonaws.services.qldb.model.GetRevisionResult;
import com.amazonaws.services.qldb.model.ValueHolder;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.QldbSession;
import software.amazon.qldb.Result;
import software.amazon.qldb.TransactionExecutor;
import software.amazon.qldb.tutorial.model.SampleData;
import software.amazon.qldb.tutorial.qldb.BlockAddress;
import software.amazon.qldb.tutorial.qldb.QldbRevision;
import software.amazon.qldb.tutorial.qldb.QldbStringUtils;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* Verify the integrity of a document revision in a QLDB ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class GetRevision {
public static final Logger log = LoggerFactory.getLogger(GetRevision.class);
public static AmazonQLDB client = CreateLedger.getClient();
private GetRevision() { }
public static void main(String... args) throws Exception {
final String vin = SampleData.REGISTRATIONS.get(0).getVin();
try (QldbSession qldbSession = ConnectToLedger.createQldbSession()) {
verifyRegistration(qldbSession, Constants.LEDGER_NAME, vin);
}
}
/**
* Verify each version of the registration for the given VIN.
*
* @param qldbSession
* A QLDB session.
* @param ledgerName
* The ledger to get digest from.
* @param vin
* VIN to query the revision history of a specific registration with.
* @throws Exception if failed to verify digests.
* @throws AssertionError if document revision verification failed.
*/
public static void verifyRegistration(final QldbSession qldbSession, final String ledgerName, final String vin)
throws Exception {
log.info(String.format("Let's verify the registration with VIN=%s, in ledger=%s.", vin, ledgerName));
try {
log.info("First, let's get a digest.");
GetDigestResult digestResult = GetDigest.getDigest(ledgerName);
ValueHolder digestTipAddress = digestResult.getDigestTipAddress();
byte[] digestBytes = Verifier.convertByteBufferToByteArray(digestResult.getDigest());
log.info("Got a ledger digest. Digest end address={}, digest={}.",
QldbStringUtils.toUnredactedString(digestTipAddress),
Verifier.toBase64(digestBytes));
log.info(String.format("Next, let's query the registration with VIN=%s. "
+ "Then we can verify each version of the registration.", vin));
List documentsWithMetadataList = new ArrayList<>();
qldbSession.execute(txn -> {
documentsWithMetadataList.addAll(queryRegistrationsByVin(txn, vin));
}, (retryAttempt) -> log.info("Retrying due to OCC conflict..."));
log.info("Registrations queried successfully!");
log.info(String.format("Found %s revisions of the registration with VIN=%s.",
documentsWithMetadataList.size(), vin));
for (IonStruct ionStruct : documentsWithMetadataList) {
QldbRevision document = QldbRevision.fromIon(ionStruct);
log.info(String.format("Let's verify the document: %s", document));
log.info("Let's get a proof for the document.");
GetRevisionResult proofResult = getRevision(
ledgerName,
document.getMetadata().getId(),
digestTipAddress,
document.getBlockAddress()
);
final IonValue proof = Constants.MAPPER.writeValueAsIonValue(proofResult.getProof());
final IonReader reader = IonReaderBuilder.standard().build(proof);
reader.next();
ByteArrayOutputStream baos = new ByteArrayOutputStream();
IonWriter writer = Constants.SYSTEM.newBinaryWriter(baos);
writer.writeValue(reader);
writer.close();
baos.flush();
baos.close();
byte[] byteProof = baos.toByteArray();
log.info(String.format("Got back a proof: %s", Verifier.toBase64(byteProof)));
boolean verified = Verifier.verify(
document.getHash(),
digestBytes,
proofResult.getProof().getIonText()
);
if (!verified) {
throw new AssertionError("Document revision is not verified!");
} else {
log.info("Success! The document is verified");
}
byte[] alteredDigest = Verifier.flipRandomBit(digestBytes);
log.info(String.format("Flipping one bit in the digest and assert that the document is NOT verified. "
+ "The altered digest is: %s", Verifier.toBase64(alteredDigest)));
verified = Verifier.verify(
document.getHash(),
alteredDigest,
proofResult.getProof().getIonText()
);
if (verified) {
throw new AssertionError("Expected document to not be verified against altered digest.");
} else {
log.info("Success! As expected flipping a bit in the digest causes verification to fail.");
}
byte[] alteredDocumentHash = Verifier.flipRandomBit(document.getHash());
log.info(String.format("Flipping one bit in the document's hash and assert that it is NOT verified. "
+ "The altered document hash is: %s.", Verifier.toBase64(alteredDocumentHash)));
verified = Verifier.verify(
alteredDocumentHash,
digestBytes,
proofResult.getProof().getIonText()
);
if (verified) {
throw new AssertionError("Expected altered document hash to not be verified against digest.");
} else {
log.info("Success! As expected flipping a bit in the document hash causes verification to fail.");
}
}
} catch (Exception e) {
log.error("Failed to verify digests.", e);
throw e;
}
log.info(String.format("Finished verifying the registration with VIN=%s in ledger=%s.", vin, ledgerName));
}
/**
* Get the revision of a particular document specified by the given document ID and block address.
*
* @param ledgerName
* Name of the ledger containing the document.
* @param documentId
* Unique ID for the document to be verified, contained in the committed view of the document.
* @param digestTipAddress
* The latest block location covered by the digest.
* @param blockAddress
* The location of the block to request.
* @return the requested revision.
*/
public static GetRevisionResult getRevision(final String ledgerName, final String documentId,
final ValueHolder digestTipAddress, final BlockAddress blockAddress) {
try {
GetRevisionRequest request = new GetRevisionRequest()
.withName(ledgerName)
.withDigestTipAddress(digestTipAddress)
.withBlockAddress(new ValueHolder().withIonText(Constants.MAPPER.writeValueAsIonValue(blockAddress)
.toString()))
.withDocumentId(documentId);
return client.getRevision(request);
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
/**
* Query the registration history for the given VIN.
*
* @param txn
* The {@link TransactionExecutor} for lambda execute.
* @param vin
* The unique VIN to query.
* @return a list of {@link IonStruct} representing the registration history.
* @throws IllegalStateException if failed to convert parameters into {@link IonValue}
*/
public static List queryRegistrationsByVin(final TransactionExecutor txn, final String vin) {
log.info(String.format("Let's query the 'VehicleRegistration' table for VIN: %s...", vin));
log.info("Let's query the 'VehicleRegistration' table for VIN: {}...", vin);
final String query = String.format("SELECT * FROM _ql_committed_%s WHERE data.VIN = ?",
Constants.VEHICLE_REGISTRATION_TABLE_NAME);
try {
final List parameters = Collections.singletonList(Constants.MAPPER.writeValueAsIonValue(vin));
final Result result = txn.execute(query, parameters);
List list = ScanTable.toIonStructs(result);
log.info(String.format("Found %d document(s)!", list.size()));
return list;
} catch (IOException ioe) {
throw new IllegalStateException(ioe);
}
}
}
```
------
**nota**
Una vez que el método `getRevision` devuelve una prueba de la revisión del documento especificada, este programa utiliza una API del cliente para verificar esa revisión. Para obtener una descripción general del algoritmo utilizado por esta API, consulte [Uso de una prueba para volver a calcular el resumen](verification.results.md#verification.results.recalc).
1. Compile y ejecute el programa `GetRevision.java` para verificar criptográficamente el documento `VehicleRegistration` con el VIN `1N4AL11D75C109151`.
Para exportar y validar los datos del diario en el libro mayor `vehicle-registration`, continúe con [Paso 8: exportar y validar los datos del diario en un libro mayor](getting-started.java.step-8.md).
# Paso 8: exportar y validar los datos del diario en un libro mayor
**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 Amazon QLDB, puede acceder al contenido del diario de su libro mayor para diversos fines, como la retención de datos, el análisis y la auditoría. Para obtener más información, consulte [Exportación de datos de diarios desde Amazon QLDB](export-journal.md).
En este paso, exporta [bloques de diario](journal-contents.md) del libro mayor `vehicle-registration` a un bucket de Amazon S3. A continuación, utiliza los datos exportados para validar la cadena de hash entre los bloques de diario y los componentes de hash individuales de cada bloque.
La entidad principal AWS Identity and Access Management (IAM) que utilice debe tener permisos de IAM suficientes para crear un bucket de Amazon S3 en su. Cuenta de AWS Para obtener información, consulte [políticas y permisos en Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-policy-language-overview.html) en la *Guía del usuario de Amazon S3*. También debe tener permisos para crear un rol de IAM con una política de permisos adjunta que permita a QLDB escribir objetos en su bucket de Amazon S3. Para obtener más información, consulte [permisos necesarios para acceder a los recursos de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_permissions-required.html) en la *Guía del usuario de IAM*.
**Exportar y validar los datos del diario**
1. Revise el siguiente archivo (`JournalBlock.java`), que representa un bloque de diario y su contenido de datos. Incluye un método denominado `verifyBlockHash()` que muestra cómo calcular cada componente individual de un hash de bloque.
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial.qldb;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import com.fasterxml.jackson.dataformat.ion.IonTimestampSerializers;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.tutorial.Constants;
import software.amazon.qldb.tutorial.Verifier;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.util.Arrays;
import java.util.Date;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
import java.util.stream.Collectors;
import static java.nio.ByteBuffer.wrap;
/**
* Represents a JournalBlock that was recorded after executing a transaction
* in the ledger.
*/
public final class JournalBlock {
private static final Logger log = LoggerFactory.getLogger(JournalBlock.class);
private BlockAddress blockAddress;
private String transactionId;
@JsonSerialize(using = IonTimestampSerializers.IonTimestampJavaDateSerializer.class)
private Date blockTimestamp;
private byte[] blockHash;
private byte[] entriesHash;
private byte[] previousBlockHash;
private byte[][] entriesHashList;
private TransactionInfo transactionInfo;
private RedactionInfo redactionInfo;
private List revisions;
@JsonCreator
public JournalBlock(@JsonProperty("blockAddress") final BlockAddress blockAddress,
@JsonProperty("transactionId") final String transactionId,
@JsonProperty("blockTimestamp") final Date blockTimestamp,
@JsonProperty("blockHash") final byte[] blockHash,
@JsonProperty("entriesHash") final byte[] entriesHash,
@JsonProperty("previousBlockHash") final byte[] previousBlockHash,
@JsonProperty("entriesHashList") final byte[][] entriesHashList,
@JsonProperty("transactionInfo") final TransactionInfo transactionInfo,
@JsonProperty("redactionInfo") final RedactionInfo redactionInfo,
@JsonProperty("revisions") final List revisions) {
this.blockAddress = blockAddress;
this.transactionId = transactionId;
this.blockTimestamp = blockTimestamp;
this.blockHash = blockHash;
this.entriesHash = entriesHash;
this.previousBlockHash = previousBlockHash;
this.entriesHashList = entriesHashList;
this.transactionInfo = transactionInfo;
this.redactionInfo = redactionInfo;
this.revisions = revisions;
}
public BlockAddress getBlockAddress() {
return blockAddress;
}
public String getTransactionId() {
return transactionId;
}
public Date getBlockTimestamp() {
return blockTimestamp;
}
public byte[][] getEntriesHashList() {
return entriesHashList;
}
public TransactionInfo getTransactionInfo() {
return transactionInfo;
}
public RedactionInfo getRedactionInfo() {
return redactionInfo;
}
public List getRevisions() {
return revisions;
}
public byte[] getEntriesHash() {
return entriesHash;
}
public byte[] getBlockHash() {
return blockHash;
}
public byte[] getPreviousBlockHash() {
return previousBlockHash;
}
@Override
public String toString() {
return "JournalBlock{"
+ "blockAddress=" + blockAddress
+ ", transactionId='" + transactionId + '\''
+ ", blockTimestamp=" + blockTimestamp
+ ", blockHash=" + Arrays.toString(blockHash)
+ ", entriesHash=" + Arrays.toString(entriesHash)
+ ", previousBlockHash=" + Arrays.toString(previousBlockHash)
+ ", entriesHashList=" + Arrays.toString(entriesHashList)
+ ", transactionInfo=" + transactionInfo
+ ", redactionInfo=" + redactionInfo
+ ", revisions=" + revisions
+ '}';
}
@Override
public boolean equals(final Object o) {
if (this == o) {
return true;
}
if (!(o instanceof JournalBlock)) {
return false;
}
final JournalBlock that = (JournalBlock) o;
if (!getBlockAddress().equals(that.getBlockAddress())) {
return false;
}
if (!getTransactionId().equals(that.getTransactionId())) {
return false;
}
if (!getBlockTimestamp().equals(that.getBlockTimestamp())) {
return false;
}
if (!Arrays.equals(getBlockHash(), that.getBlockHash())) {
return false;
}
if (!Arrays.equals(getEntriesHash(), that.getEntriesHash())) {
return false;
}
if (!Arrays.equals(getPreviousBlockHash(), that.getPreviousBlockHash())) {
return false;
}
if (!Arrays.deepEquals(getEntriesHashList(), that.getEntriesHashList())) {
return false;
}
if (!getTransactionInfo().equals(that.getTransactionInfo())) {
return false;
}
if (getRedactionInfo() != null ? !getRedactionInfo().equals(that.getRedactionInfo()) : that.getRedactionInfo() != null) {
return false;
}
return getRevisions() != null ? getRevisions().equals(that.getRevisions()) : that.getRevisions() == null;
}
@Override
public int hashCode() {
int result = getBlockAddress().hashCode();
result = 31 * result + getTransactionId().hashCode();
result = 31 * result + getBlockTimestamp().hashCode();
result = 31 * result + Arrays.hashCode(getBlockHash());
result = 31 * result + Arrays.hashCode(getEntriesHash());
result = 31 * result + Arrays.hashCode(getPreviousBlockHash());
result = 31 * result + Arrays.deepHashCode(getEntriesHashList());
result = 31 * result + getTransactionInfo().hashCode();
result = 31 * result + (getRedactionInfo() != null ? getRedactionInfo().hashCode() : 0);
result = 31 * result + (getRevisions() != null ? getRevisions().hashCode() : 0);
return result;
}
/**
* This method validates that the hashes of the components of a journal block make up the block
* hash that is provided with the block itself.
*
* The components that contribute to the hash of the journal block consist of the following:
* - user transaction information (contained in [transactionInfo])
* - user redaction information (contained in [redactionInfo])
* - user revisions (contained in [revisions])
* - hashes of internal-only system metadata (contained in [revisions] and in [entriesHashList])
* - the previous block hash
*
* If any of the computed hashes of user information cannot be validated or any of the system
* hashes do not result in the correct computed values, this method will throw an IllegalArgumentException.
*
* Internal-only system metadata is represented by its hash, and can be present in the form of certain
* items in the [revisions] list that only contain a hash and no user data, as well as some hashes
* in [entriesHashList].
*
* To validate that the hashes of the user data are valid components of the [blockHash], this method
* performs the following steps:
*
* 1. Compute the hash of the [transactionInfo] and validate that it is included in the [entriesHashList].
* 2. Compute the hash of the [redactionInfo], if present, and validate that it is included in the [entriesHashList].
* 3. Validate the hash of each user revision was correctly computed and matches the hash published
* with that revision.
* 4. Compute the hash of the [revisions] by treating the revision hashes as the leaf nodes of a Merkle tree
* and calculating the root hash of that tree. Then validate that hash is included in the [entriesHashList].
* 5. Compute the hash of the [entriesHashList] by treating the hashes as the leaf nodes of a Merkle tree
* and calculating the root hash of that tree. Then validate that hash matches [entriesHash].
* 6. Finally, compute the block hash by computing the hash resulting from concatenating the [entriesHash]
* and previous block hash, and validate that the result matches the [blockHash] provided by QLDB with the block.
*
* This method is called by ValidateQldbHashChain::verify for each journal block to validate its
* contents before verifying that the hash chain between consecutive blocks is correct.
*/
public void verifyBlockHash() {
Set entriesHashSet = new HashSet<>();
Arrays.stream(entriesHashList).forEach(hash -> entriesHashSet.add(wrap(hash).asReadOnlyBuffer()));
byte[] computedTransactionInfoHash = computeTransactionInfoHash();
if (!entriesHashSet.contains(wrap(computedTransactionInfoHash).asReadOnlyBuffer())) {
throw new IllegalArgumentException(
"Block transactionInfo hash is not contained in the QLDB block entries hash list.");
}
if (redactionInfo != null) {
byte[] computedRedactionInfoHash = computeRedactionInfoHash();
if (!entriesHashSet.contains(wrap(computedRedactionInfoHash).asReadOnlyBuffer())) {
throw new IllegalArgumentException(
"Block redactionInfo hash is not contained in the QLDB block entries hash list.");
}
}
if (revisions != null) {
revisions.forEach(QldbRevision::verifyRevisionHash);
byte[] computedRevisionsHash = computeRevisionsHash();
if (!entriesHashSet.contains(wrap(computedRevisionsHash).asReadOnlyBuffer())) {
throw new IllegalArgumentException(
"Block revisions list hash is not contained in the QLDB block entries hash list.");
}
}
byte[] computedEntriesHash = computeEntriesHash();
if (!Arrays.equals(computedEntriesHash, entriesHash)) {
throw new IllegalArgumentException("Computed entries hash does not match entries hash provided in the block.");
}
byte[] computedBlockHash = Verifier.dot(computedEntriesHash, previousBlockHash);
if (!Arrays.equals(computedBlockHash, blockHash)) {
throw new IllegalArgumentException("Computed block hash does not match block hash provided in the block.");
}
}
private byte[] computeTransactionInfoHash() {
try {
return QldbIonUtils.hashIonValue(Constants.MAPPER.writeValueAsIonValue(transactionInfo));
} catch (IOException e) {
throw new IllegalArgumentException("Could not compute transactionInfo hash to verify block hash.", e);
}
}
private byte[] computeRedactionInfoHash() {
try {
return QldbIonUtils.hashIonValue(Constants.MAPPER.writeValueAsIonValue(redactionInfo));
} catch (IOException e) {
throw new IllegalArgumentException("Could not compute redactionInfo hash to verify block hash.", e);
}
}
private byte[] computeRevisionsHash() {
return Verifier.calculateMerkleTreeRootHash(revisions.stream().map(QldbRevision::getHash).collect(Collectors.toList()));
}
private byte[] computeEntriesHash() {
return Verifier.calculateMerkleTreeRootHash(Arrays.asList(entriesHashList));
}
}
```
1. Compile y ejecute el siguiente programa (`ValidateQldbHashChain.java`) para completar los siguientes pasos:
1. Exporte los bloques del diario del `vehicle-registration` libro mayor a un depósito de Amazon S3 con el nombre **qldb-tutorial-journal-export-*111122223333*** (sustitúyalos por su Cuenta de AWS número).
1. Valide los componentes de hash individuales de cada bloque llamando a `verifyBlockHash()`.
1. Valide la cadena de hash entre los bloques de diario.
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.services.qldb.model.ExportJournalToS3Result;
import com.amazonaws.services.qldb.model.S3EncryptionConfiguration;
import com.amazonaws.services.qldb.model.S3ObjectEncryptionType;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import java.time.Instant;
import java.util.Arrays;
import java.util.List;
import com.amazonaws.services.securitytoken.AWSSecurityTokenServiceClientBuilder;
import com.amazonaws.services.securitytoken.model.GetCallerIdentityRequest;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.qldb.tutorial.qldb.JournalBlock;
/**
* Validate the hash chain of a QLDB ledger by stepping through its S3 export.
*
* This code accepts an exportId as an argument, if exportId is passed the code
* will use that or request QLDB to generate a new export to perform QLDB hash
* chain validation.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class ValidateQldbHashChain {
public static final Logger log = LoggerFactory.getLogger(ValidateQldbHashChain.class);
private static final int TIME_SKEW = 20;
private ValidateQldbHashChain() { }
/**
* Export journal contents to a S3 bucket.
*
* @return the ExportId of the journal export.
* @throws InterruptedException if the thread is interrupted while waiting for export to complete.
*/
private static String createExport() throws InterruptedException {
String accountId = AWSSecurityTokenServiceClientBuilder.defaultClient()
.getCallerIdentity(new GetCallerIdentityRequest()).getAccount();
String bucketName = Constants.JOURNAL_EXPORT_S3_BUCKET_NAME_PREFIX + "-" + accountId;
String prefix = Constants.LEDGER_NAME + "-" + Instant.now().getEpochSecond() + "/";
S3EncryptionConfiguration encryptionConfiguration = new S3EncryptionConfiguration()
.withObjectEncryptionType(S3ObjectEncryptionType.SSE_S3);
ExportJournalToS3Result exportJournalToS3Result =
ExportJournal.createJournalExportAndAwaitCompletion(Constants.LEDGER_NAME,
bucketName, prefix, null, encryptionConfiguration, ExportJournal.DEFAULT_EXPORT_TIMEOUT_MS);
return exportJournalToS3Result.getExportId();
}
/**
* Validates that the chain hash on the {@link JournalBlock} is valid.
*
* @param journalBlocks
* {@link JournalBlock} containing hashes to validate.
* @throws IllegalStateException if previous block hash does not match.
*/
public static void verify(final List journalBlocks) {
if (journalBlocks.size() == 0) {
return;
}
journalBlocks.stream().reduce(null, (previousJournalBlock, journalBlock) -> {
journalBlock.verifyBlockHash();
if (previousJournalBlock == null) { return journalBlock; }
if (!Arrays.equals(previousJournalBlock.getBlockHash(), journalBlock.getPreviousBlockHash())) {
throw new IllegalStateException("Previous block hash doesn't match.");
}
byte[] blockHash = Verifier.dot(journalBlock.getEntriesHash(), previousJournalBlock.getBlockHash());
if (!Arrays.equals(blockHash, journalBlock.getBlockHash())) {
throw new IllegalStateException("Block hash doesn't match entriesHash dot previousBlockHash, the chain is "
+ "broken.");
}
return journalBlock;
});
}
public static void main(final String... args) throws InterruptedException {
try {
String exportId;
if (args.length == 1) {
exportId = args[0];
log.info("Validating QLDB hash chain for exportId: " + exportId);
} else {
log.info("Requesting QLDB to create an export.");
exportId = createExport();
}
List journalBlocks =
JournalS3ExportReader.readExport(DescribeJournalExport.describeExport(Constants.LEDGER_NAME,
exportId), AmazonS3ClientBuilder.defaultClient());
verify(journalBlocks);
} catch (Exception e) {
log.error("Unable to perform hash chain verification.", e);
throw e;
}
}
}
```
Si ya no necesita usar el libro mayor `vehicle-registration`, continúe con [Paso 9 (opcional): limpiar recursos](getting-started.java.step-9.md).
# Paso 9 (opcional): limpiar recursos
**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.
Puede seguir utilizando el libro mayor `vehicle-registration`. Sin embargo, si ya no lo necesita, debe eliminarlo.
**Para eliminar el libro mayor**
1. Compile y ejecute el siguiente programa (`DeleteLedger.java`) para eliminar el libro mayor `vehicle-registration` y todo su contenido.
```
/*
* Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* SPDX-License-Identifier: MIT-0
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package software.amazon.qldb.tutorial;
import com.amazonaws.services.qldb.AmazonQLDB;
import com.amazonaws.services.qldb.model.DeleteLedgerRequest;
import com.amazonaws.services.qldb.model.DeleteLedgerResult;
import com.amazonaws.services.qldb.model.ResourceNotFoundException;
import com.amazonaws.services.qldb.model.UpdateLedgerRequest;
import com.amazonaws.services.qldb.model.UpdateLedgerResult;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* Delete a ledger.
*
* This code expects that you have AWS credentials setup per:
* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html
*/
public final class DeleteLedger {
public static final Logger log = LoggerFactory.getLogger(DeleteLedger.class);
public static final Long LEDGER_DELETION_POLL_PERIOD_MS = 20_000L;
public static AmazonQLDB client = CreateLedger.getClient();
private DeleteLedger() { }
public static void main(String... args) throws Exception {
try {
setDeletionProtection(Constants.LEDGER_NAME, false);
delete(Constants.LEDGER_NAME);
waitForDeleted(Constants.LEDGER_NAME);
} catch (Exception e) {
log.error("Unable to delete the ledger.", e);
throw e;
}
}
/**
* Send a request to the QLDB database to delete the specified ledger.
*
* @param ledgerName
* Name of the ledger to be deleted.
* @return DeleteLedgerResult.
*/
public static DeleteLedgerResult delete(final String ledgerName) {
log.info("Attempting to delete the ledger with name: {}...", ledgerName);
DeleteLedgerRequest request = new DeleteLedgerRequest().withName(ledgerName);
DeleteLedgerResult result = client.deleteLedger(request);
log.info("Success.");
return result;
}
/**
* Wait for the ledger to be deleted.
*
* @param ledgerName
* Name of the ledger being deleted.
* @throws InterruptedException if thread is being interrupted.
*/
public static void waitForDeleted(final String ledgerName) throws InterruptedException {
log.info("Waiting for the ledger to be deleted...");
while (true) {
try {
DescribeLedger.describe(ledgerName);
log.info("The ledger is still being deleted. Please wait...");
Thread.sleep(LEDGER_DELETION_POLL_PERIOD_MS);
} catch (ResourceNotFoundException ex) {
log.info("Success. The ledger is deleted.");
break;
}
}
}
public static UpdateLedgerResult setDeletionProtection(String ledgerName, boolean deletionProtection) {
log.info("Let's set deletionProtection to {} for the ledger with name {}", deletionProtection, ledgerName);
UpdateLedgerRequest request = new UpdateLedgerRequest()
.withName(ledgerName)
.withDeletionProtection(deletionProtection);
UpdateLedgerResult result = client.updateLedger(request);
log.info("Success. Ledger updated: {}", result);
return result;
}
}
```
**nota**
Si la protección contra eliminación está habilitada para su libro mayor, primero debe desactivarla para poder eliminar el libro mayor utilizando la API de QLDB.
1. Si exportó los datos del diario en el [paso anterior](getting-started.java.step-8.md) y ya no los necesita, utilice la consola de Amazon S3 para eliminar el bucket de S3.
Abra la consola de Amazon S3 en [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).