{
return await driver.executeLambda(async (txn: TransactionExecutor) => {
const results: dom.Value[] = (await txn.execute(
"SELECT insured FROM Vehicles WHERE vin = ? AND insured = FALSE", vin)).getResultList();
if (results.length > 0) {
await txn.execute(
"UPDATE Vehicles SET insured = TRUE WHERE vin = ?", vin);
return true;
}
return false;
});
};
```
------
#### [ Python ]
```
# This code snippet is intentionally trivial. In reality you wouldn't do this because you'd
# set your UPDATE to filter on vin and insured, and check if you updated something or not.
def do_insure_car(transaction_executor, vin):
cursor = transaction_executor.execute_statement(
"SELECT insured FROM Vehicles WHERE vin = ? AND insured = FALSE", vin)
first_record = next(cursor, None)
if first_record:
transaction_executor.execute_statement(
"UPDATE Vehicles SET insured = TRUE WHERE vin = ?", vin)
return True
else:
return False
def insure_car(qldb_driver, vin_to_insure):
return qldb_driver.execute_lambda(
lambda executor: do_insure_car(executor, vin_to_insure))
```
------
驱动程序的 `execute` 操作会隐式启动会话和该会话中的事务。您在 lambda 表达式中运行的每条语句都包含在此事务中。所有语句运行后，驱动程序将自动提交事务。如果在自动重试限制用尽后任何语句失败，则事务将会中止。
**在事务中传播异常**
当每个事务运行多个语句时，我们通常不建议您捕获并吞掉事务内的异常。
例如，在 Java 中，以下程序会捕获的任何`RuntimeException`实例，记录错误并继续。此代码示例被认为是错误做法，因为即使`UPDATE`语句失败，事务也会成功。因此，客户端可能会假定更新成功，而更新却没有成功。
**警告**
切勿使用此代码示例。提供它是为了展示被认为是不良做法的反模式示例。
```
// DO NOT USE this code example because it is considered bad practice
public static void main(final String... args) {
ConnectToLedger.getDriver().execute(txn -> {
final Result selectTableResult = txn.execute("SELECT * FROM Vehicle WHERE VIN ='123456789'");
// Catching an error inside the transaction is an anti-pattern because the operation might
// not succeed.
// In this example, the transaction succeeds even when the update statement fails.
// So, the client might assume that the update succeeded when it didn't.
try {
processResults(selectTableResult);
String model = // some code that extracts the model
final Result updateResult = txn.execute("UPDATE Vehicle SET model = ? WHERE VIN = '123456789'",
Constants.MAPPER.writeValueAsIonValue(model));
} catch (RuntimeException e) {
log.error("Exception when updating the Vehicle table {}", e.getMessage());
}
});
log.info("Vehicle table updated successfully.");
}
```
改为传播（冒泡）异常。如果事务的任何部分失败，则让`execute`操作中止事务，以便客户端可以相应地处理异常。
# 使用 Amazon QLDB 中的驱动程序了解重试策略
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
Amazon QLDB 驱动程序使用重试策略，通过透明重试失败的事务来处理暂时异常。这些异常（例如`CapacityExceededException`和`RateExceededException`）通常会在一段时间后自行纠正。如果在适当延迟之后重试因异常而失败的事务，则很可能会成功。这有助于提高使用 QLDB 应用程序的稳定性。
**Topics**
+ [
## 可重试错误类型
](#driver-retry-policy.retryable-errors)
+ [
## 默认重试策略
](#driver-retry-policy.default)
## 可重试错误类型
当且仅当该事务的操作期间出现以下任何异常时，驱动程序才会自动重试此事务：
+ [CapacityExceededException](driver-errors.md)— 当请求超出账本的处理能力时返回。
+ [InvalidSessionException](driver-errors.md)— 当会话不再有效或会话不存在时返回。
+ [LimitExceededException](driver-errors.md)— 如果超过资源限制（例如活动会话数），则返回。
+ [OccConflictException](concurrency.md)— 当由于*乐观并发控制* (OCC) 的验证阶段失败而导致交易无法写入日志时返回。
+ [RateExceededException](driver-errors.md)— 当请求速率超过允许的吞吐量时返回。
## 默认重试策略
重试策略由重试条件与退避策略组成。重试条件定义何时应重试事务，而退避策略定义在重试事务之前的等待时间。
创建驱动程序实例时，默认重试策略指定最多重试四次，并使用指数退避策略。指数退避策略使用最小延迟 10 毫秒，最大延迟 5000 毫秒，抖动相等。如果无法在重试策略内成功提交此事务，我们建议您改时尝试该事务。
指数回退的原理是对于连续错误响应，重试等待间隔越来越长。有关更多信息，请参阅 AWS 博客文章[指数退缩和抖动。](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)
# Amazon QLDB 驱动程序中的常见错误
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
本节描述了 Amazon QLDB 驱动程序在与[ QLDB 会话 API](https://docs.aws.amazon.com/qldb/latest/developerguide/API_Types_Amazon_QLDB_Session.html) 交互时可能引发的运行时错误。
下面是驱动程序返回的常见异常列表。每个异常都包括特定的错误消息，然后是简短的描述和可能的解决方案建议。
**CapacityExceededException**
消息：容量已超出
Amazon QLDB 拒绝了该请求，因为它超出了分类账的处理能力。QLDB 对每个分类账强制执行内部扩展限制，以维护服务的运行状况和性能。此限制因每个请求的工作负载大小而异。例如，如果请求执行效率低下的数据事务，例如由非索引限定查询产生的表扫描，则该请求的工作负载可能会增加。
我们建议您在重试请求之前等待。如果您的应用程序一直遇到此异常，请优化您的语句并降低发送到分类账的请求的速率和数量。语句优化的示例包括每个事务运行更少的语句和调优表索引。要了解如何优化语句和避免表扫描，请参阅 [优化查询性能](working.optimize.md)。
建议使用最新版本的 QLDB 驱动程序。驱动程序具有默认的重试策略，该策略使用[指数回退和抖动](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)来自动重试此类异常。指数回退的原理是对于连续错误响应，重试等待间隔越来越长。
**InvalidSessionException**
消息：交易*transactionId*已过期
事务已超过其最长生命周期。在提交之前，事务最多可运行 30 秒。超过此时间限制后，QLDB 会拒绝在事务完成的任何工作，并丢弃运行该事务会话。此限制通过启动事务（而不提交或取消事务）以保护客户端免遭泄漏会话。
如果这是应用程序中常见的异常，那么很可能是事务运行时间过长。如果事务运行时间超过 30 秒，请优化您的语句以加快事务速度。语句优化的示例包括每个事务运行更少的语句和调优表索引。有关更多信息，请参阅 [优化查询性能](working.optimize.md)。
**InvalidSessionException**
消息：会话*sessionId*已过期
QLDB 放弃了会话，因为它已超过其最大总生命周期。无论事务是否处于活动状态，QLDB 都会在 13-17 分钟后丢弃会话。会话丢失或受损的原因有很多，如硬件故障、网络故障或应用程序重启。因此，QLDB 对会话强制使用最长生命周期，以确保客户端软件能应对会话故障。
如果您遇到此异常，我们建议您获取一个新的会话并重试该事务。我们还建议使用最新版本的 QLDB 驱动程序，该驱动程序代表应用程序管理会话池及其运行状况。
**InvalidSessionException**
消息：没有这样的会话
客户试图使用不存在的会话与 QLDB 进行事务处理。假设客户端正在使用先前存在的会话，则由于以下原因之一，该会话可能不再存在：
+ 如果会话涉及内部服务器故障（即 HTTP 响应代码 500 错误），那么 QLDB 可能会选择完全放弃该会话，而不是允许客户使用状态不确定的会话进行事务。然后，对该会话的任何重试尝试都会失败，并出现此错误。
+ 过期的会话最终会被 QLDB 遗忘。然后，任何继续使用会话的尝试都会导致此错误，而不是初始 `InvalidSessionException`。
如果您遇到此异常，我们建议您获取一个新的会话并重试该事务。我们还建议使用最新版本的 QLDB 驱动程序，该驱动程序代表应用程序管理会话池及其运行状况。
**RateExceededException**
消息：已超出速率
QLDB 根据调用者的标识对客户端进行节流。QLDB 使用[令牌桶](https://en.wikipedia.org/wiki/Token_bucket)节流算法在每个区域、每个账户的基础上强制执行节流。QLDB 这样做是为了帮助提高服务的性能，并确保所有 QLDB 客户的公平使用。例如，尝试使用 `StartSessionRequest` 操作获取大量并发会话可能会导致节流。
为了保持应用程序的运行状况并缓解进一步的节流，您可以使用[指数回退](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)和抖动来重试此异常。指数回退的原理是对于连续错误响应，重试等待间隔越来越长。建议使用最新版本的 QLDB 驱动程序。驱动程序具有默认的重试策略，该策略使用指数回退和抖动来自动重试此类异常。
如果您的应用程序持续受到 QLDB 的 `StartSessionRequest` 调用节流，那么最新版本的 QLDB 驱动程序也可以提供帮助。驱动程序维护着一个跨事务重复使用的会话池，这有助于减少应用程序发出的 `StartSessionRequest` 调用次数。要请求提高 API 节流限额，请联系 [AWS 支持 中心](https://console.aws.amazon.com/support/home#/)。
**LimitExceededException**
消息：已超出会话限制
分类账的活跃会话数量超过了其配额（也称为*限制*）。此配额在 [Amazon QLDB 资源中的限额和限制](limits.md) 中定义。分类账的活动会话计数最终是一致的，并且始终在配额附近运行的分类账可能会定期看到此异常。
为了保持应用程序的运行状况，我们建议重试此异常。为避免出现这种异常，请确保在所有客户端上为单个分类账配置的并发会话不超过 1,500 个。例如，您可以使用适用于 Java 的 [Amazon QLDB 驱动程序的[maxConcurrentTransactions](https://github.com/awslabs/amazon-qldb-driver-java/blob/master/src/main/java/software/amazon/qldb/QldbDriverBuilder.java#L125)](https://github.com/awslabs/amazon-qldb-driver-java/)方法来配置驱动程序实例中的最大可用会话数。
**QldbClientException**
消息：流结果仅在父事务打开时有效
事务已关闭，无法用于从 QLDB 检索结果。事务在提交或取消时关闭。
当客户端直接处理 `Transaction` 对象，并且在提交或取消事务后尝试从 QLDB 检索结果时，就会发生此异常。为了缓解此问题，客户端必须在关闭事务之前读取数据。
# 使用示例应用程序教程，开始使用 Amazon QLDB
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在本教程中，您将使用 Amazon QLDB 驱动程序和软件开发工具包来创建 QLDB 账本，并在其中 AWS 填充示例数据。该驱动程序允许您的应用程序通过事务数据 API 与 QLDB 交互。该 AWS 软件开发工具包支持与 QLDB 资源管理 API 的交互。
您在此场景中创建的示例分类账是一个机动车辆部门（DMV）数据库，用于追踪有关车辆登记的完整历史信息。以下主题说明了如何添加车辆登记、修改车辆登记，以及如何查看这些登记的更改历史记录。本指南还向您展示了如何以加密方式验证注册文档，最后还会清理资源并删除示例分类账。
示例应用程序可提供以下编程语言版本。
**Topics**
+ [Java 教程](getting-started.java.tutorial.md)
+ [Node.js 教程](getting-started.nodejs.tutorial.md)
+ [Python 教程](getting-started.python.tutorial.md)
# Amazon QLDB Java 教程
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在本教程示例应用程序的本实现中，您将使用带有 Amazon QLDB 驱动程序来创建 QLDB 账本并使用示例数据填充 适用于 Java 的 AWS SDK 该账本。
在学习本教程时，您可以参考 [适用于 Java 的 AWS SDK API 参考](https://docs.aws.amazon.com/sdk-for-java/latest/reference/) 以了解管理 API 操作。有关事务数据操作，您可参见[适用于 Java 的 QLDB 驱动程序 API 参考](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/index.html)。
**注意**
在适用的情况下，某些用例对于 Java 的 QLDB 驱动程序的每个支持主要版本都配备不同的命令或代码示例。
**Topics**
+ [
# 安装 Amazon QLDB Java 示例应用程序
](sample-app.java.md)
+ [
# 步骤 1：创建新分类账
](getting-started.java.step-1.md)
+ [
# 第 2 步：测试与分类账的连接
](getting-started.java.step-2.md)
+ [
# 步骤 3：创建表、索引与示例数据
](getting-started.java.step-3.md)
+ [
# 步骤 4：查询分类账中的表
](getting-started.java.step-4.md)
+ [
# 第 5 步：修改分类账中的文档
](getting-started.java.step-5.md)
+ [
# 步骤 6：查看文档修订历史记录
](getting-started.java.step-6.md)
+ [
# 第 7 步：验证分类账中的文档
](getting-started.java.step-7.md)
+ [
# 步骤 8：导出并验证分类账中的日记账数据
](getting-started.java.step-8.md)
+ [
# 步骤 9：（可选）清除资源
](getting-started.java.step-9.md)
# 安装 Amazon QLDB Java 示例应用程序
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
本节介绍如何为 Java 教程安装和运行所提供的 Amazon QLDB 示例应用程序。 step-by-step此示例应用程序的用例是机动车辆部门（DMV）数据库，用于追踪有关车辆登记的完整历史信息。
适用于 Java 的 DMV 示例应用程序在 GitHub 存储库 a [ws-samples/-amazon-qldb-dmv-sample](https://github.com/aws-samples/amazon-qldb-dmv-sample-java) java 中是开源的。
## 先决条件
在开始之前，请确保您已完成适用于 Java[先决条件](getting-started.java.md#getting-started.java.prereqs) 的 QLDB 驱动程序。这包括以下这些：
1. 注册 AWS.
1. 创建具有适当 QLDB 权限的用户。要完成本教程中的所有步骤，您需要通过 QLDB API 对分类账资源拥有完全管理权限。
1. 如果您使用的是以外的 IDE AWS Cloud9，请安装 Java 并授予开发所需的编程访问权限。
## 安装
以下步骤介绍如何在本地开发环境中下载与设置示例应用程序。或者，您可以使用 AWS Cloud9 作为 IDE 自动设置示例应用程序，并使用 CloudFormation 模板来配置开发资源。
### 本地开发环境
这些说明描述了如何利用自有资源和开发环境下载和安装 QLDB Java 示例应用程序。
**下载并运行示例应用程序**
1. 输入以下命令以从中克隆示例应用程序 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
```
------
此软件包包含来自[Java 教程](getting-started.java.tutorial.md)的 Gradle 配置和完整代码。
1. 下载并运行提供的应用程序。
+ 如果您使用的是 Eclipse：
1. 启动 Eclipse，然后在**Eclipse**菜单选择**文件**、**导入**，然后选择 **现有 Gradle 项目**。
1. 在项目根目录中，浏览并选择包含 `build.gradle` 文件的应用程序目录。然后，选择 **完成** 以使用默认 Gradle 设置进行导入。
1. 你可以尝试运行 `ListLedgers` 程序作为示例。打开 `ListLedgers.java` 文件的上下文菜单（右键单击），选择 **作为 Java 应用程序运行**。
+ 如果您使用的是 IntelliJ：
1. 启动 IntelliJ，在 **IntelliJ** 菜单选择 **文件**，然后选择 **打开**。
1. 在项目根目录中，浏览并选择包含 `build.gradle`文件的应用程序目录。然后选择 **OK**（确定）。保留默认设置，然后再次选择 **确定**。
1. 你可以尝试运行 `ListLedgers` 程序作为示例。打开`ListLedgers.java`文件的上下文（右键单击）菜单，然后选择 **“运行ListLedgers”**。
1. 继续 [步骤 1：创建新分类账](getting-started.java.step-1.md) 开始教程并创建分类账。
### AWS Cloud9
这些说明描述了如何使用[AWS Cloud9](https://aws.amazon.com/cloud9)作为 IDE 自动设置适用于 Java 的 Amazon QLDB 车辆登记示例应用程序。在本指南中，您将使 用[CloudFormation](https://aws.amazon.com/cloudformation) 模板配置您的开发资源。
有关的更多信息 AWS Cloud9，请参阅《[AWS Cloud9 用户指南》](https://docs.aws.amazon.com/cloud9/latest/user-guide/)。要了解有关 CloudFormation的更多信息，请参阅 [AWS CloudFormation 用户指南](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/)。
**Topics**
+ [
#### 第 1 部分：配置资源
](#sample-app.java.cfn-ac9.step-1)
+ [
#### 部分 2：设置 IDE
](#sample-app.java.cfn-ac9.step-2)
+ [
#### 第 3 部分：运行 QLDB DMV 示例应用程序
](#sample-app.java.cfn-ac9.step-3)
#### 第 1 部分：配置资源
在第一步中，您将使用 CloudFormation Amazon QLDB 示例应用程序预配置设置开发环境所需的资源。
**打开 CloudFormation 控制台并加载 QLDB 示例应用程序模板**
1. 登录 AWS 管理控制台 并在 [https://console.aws.amazon.com/cloudformat](https://console.aws.amazon.com/cloudformation/) ion 上打开 CloudFormation 控制台。
切换至支持 QLDB 的区域。有关完整列表，请参阅 *AWS 一般参考* 中的 [Amazon QLDB 端点和限额](https://docs.aws.amazon.com/general/latest/gr/qldb.html)。以下屏幕截图 AWS 管理控制台 显示美国东部（弗吉尼亚北部）为选定区域 AWS 区域。
![\[AWS 管理控制台 将美国东部（弗吉尼亚北部）显示为选中 AWS 区域。\]](http://docs.aws.amazon.com/zh_cn/qldb/latest/developerguide/images/cfn-ac9/aws-region-us-east-1.png)
1. 在 CloudFormation 控制台上，选择**创建堆栈**，然后选择**使用新资源（标准）**。
1. 在 **创建堆栈**页面上，选择 **指定模板**，选择 **Amazon S3 URL**。
1. 输入以下 URL，然后选择 **下一步**。
```
https://amazon-qldb-assets.s3.amazonaws.com/templates/QLDB-DMV-SampleApp.yml
```
1. 输入**堆栈名称**（例如**qldb-sample-app**），然后选择**下一步**。
1. 您可以根据需要添加任何标签，并保留默认选项。然后选择**下一步**。
1. 检查您的堆栈设置，然后选择**创建堆栈**。 CloudFormation 脚本可能需要几分钟才能完成。
此脚本为您的 AWS Cloud9 环境预置一个关联的亚马逊弹性计算云 (Amazon EC2) 实例，用于运行本教程中的 QLDB 示例应用程序。它还会将 [aws-samples/ amazon-qldb-dmv-sample-java](https://github.com/aws-samples/amazon-qldb-dmv-sample-java/) 存储库从您的开发环境中克隆到您的开发环境中。 GitHub AWS Cloud9
#### 部分 2：设置 IDE
在此步骤中，您已完成云开发环境设置。您可以下载并运行提供的 shell 脚本，使用示例应用程序的依赖项来设置 AWS Cloud9 IDE。
**设置您的 AWS Cloud9 环境**
1. 打开 AWS Cloud9 控制台，网址为[https://console.aws.amazon.com/cloud9/](https://console.aws.amazon.com/cloud9/)。
1. 在 **您的环境**，定位名为 **QLDB DMV Sample Application**的环境牌，然后选择 **打开 IDE**。底层 EC2 实例启动时，您的环境可能需要一分钟才能加载。
您的 AWS Cloud9 环境已预先配置了运行本教程所需的系统依赖项。在控制台的 **环境** 导航窗格中，确认您看到一个名为`QLDB DMV Sample Application`的文件夹。 AWS Cloud9 控制台的以下屏幕截图显示了 QLDB DMV 示例应用程序环境文件夹窗格。
![\[AWS Cloud9 控制台显示 QLDB DMV 示例应用程序环境文件夹窗格。\]](http://docs.aws.amazon.com/zh_cn/qldb/latest/developerguide/images/cfn-ac9/cloud9-folders.png)
如果您没有看到导航窗格，请切换主机左侧的 **环境** 选项卡。如果您在窗格中看不到任何文件夹，请使用设置图标（![\[Settings icon\]](http://docs.aws.amazon.com/zh_cn/qldb/latest/developerguide/images/settings.png)）启用**显示环境根目录**。
1. 在控制台底部窗格中，您应该会看到一个打开的`bash`终端窗口。如果您没有看到这个，请从主机顶部的 **窗口 菜单中**选择**新建终端**。
1. 接下来，下载并运行安装脚本以安装 OpenJDK 8，如果适用，请从 Git 存储库中查看相应的分支。在上一步中创建的 AWS Cloud9 终端中，按顺序运行以下两个命令：
------
#### [ 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
```
------
完成后，您可看到终端中打印了以下消息：
```
** DMV Sample App setup completed , enjoy!! **
```
1. 花点时间浏览中的示例应用程序代码 AWS Cloud9，尤其是在以下目录路径中：`src/main/java/software/amazon/qldb/tutorial`。
#### 第 3 部分：运行 QLDB DMV 示例应用程序
在本步骤中，您将学习如何使用运行 Amazon QLDB DMV 示例应用程序任务。 AWS Cloud9要运行示例代码，请返回 AWS Cloud9 终端或按照*第 2 部分：设置 IDE* 中所做的那样创建一个新的终端窗口。
**运行示例应用程序**
1. 在终端中运行以下命令，以切换至项目根目录：
```
cd ~/environment/amazon-qldb-dmv-sample-java
```
确保您在以下目录路径运行示例。
```
/home/ec2-user/environment/amazon-qldb-dmv-sample-java/
```
1. 以下命令显示了运行每项任务的 Gradle 语法。
```
./gradlew run -Dtutorial=Task
```
例如，运行以下命令列出您 AWS 账户 和当前区域中的所有账本。
```
./gradlew run -Dtutorial=ListLedgers
```
1. 继续 [步骤 1：创建新分类账](getting-started.java.step-1.md) 开始教程并创建分类账。
1. （可选）完成教程后，如果您不再需要 CloudFormation 资源，就可以清理它们了。
1. 在 [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/) 上打开 CloudFormation 控制台，然后删除您在*第 1 部分：配置*资源中创建的堆栈。
1. 同时删除 CloudFormation 模板为您创建的 AWS Cloud9 堆栈。
# 步骤 1：创建新分类账
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在此步骤中，您将创建一个名为 `vehicle-registration` 的新 Amazon QLDB 分类账。
**创建新分类账**
1. 查看以下文件（`Constants.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 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 ]
**重要**
对于 Amazon Ion 软件包，您必须在应用程序中使用命名空间`com.amazon.ion`。 适用于 Java 的 AWS SDK 依赖于命名空间下的另一个 Ion 包`software.amazon.ion`，但这是一个与 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);
}
}
```
------
**注意**
该 `Constants` 类包括开源 Jackson `IonValueMapper`类实例。在执行读写事务时，您可以使用此映射器处理您的 [Amazon Ion](ion.md) 数据。
该 `CreateLedger.java` 文件还依赖于以下程序（`DescribeLedger.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;
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. 编译并运行 `CreateLedger.java` 程序以创建名为`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);
}
}
}
```
------
**注意**
在 `createLedger` 调用中，您必须指定分类账名称和权限模式。我们强烈建议使用 `STANDARD` 权限模式来最大限度地提高分类账数据的安全性。
创建分类账时，将默认启用 *删除保护*。QLDB 中有一项功能，可防止分类账被任何用户删除。您可以选择使用 QLDB API 或 AWS Command Line Interface () 在创建账本时禁用删除保护。AWS CLI
您还可选择指定要附加到分类账的标签。
要验证您与新分类账的连接，请继续 [第 2 步：测试与分类账的连接](getting-started.java.step-2.md)。
# 第 2 步：测试与分类账的连接
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在此步骤中，您将验证是否可以使用事务数据 API 端点连接至 Amazon QLDB 中的`vehicle-registration`分类账。
**测试分类账的连接性**
1. 查看以下程序（`ConnectToLedger.java`），该程序创建了与`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);
}
}
}
```
**注意**
若对分类账运行数据操作，您必须创建`QldbDriver`类实例以连接至特定分类账。这与您在上一步中创建分类账时使用的`AmazonQLDB` 客户端对象不同。此前客户端仅适用于运行[Amazon QLDB API 参考](api-reference.md)中列出的管理 API 操作。
首先，创建一个 `QldbDriver` 对象。创建此驱动程序时，您必须指定分类账名称。
然后，您可以使用此驱动程序的 `execute` 方法运行 PartiQL 语句。
或者，您可指定事务异常的最大重试次数。该 `execute` 方法会自动重试乐观并发控制（OCC）冲突和其他常见的瞬态异常，但不超过此可配置限制。默认值为 `4`。
如果在达到限制后事务仍失败，则驱动程序会抛出异常。要了解更多信息，请参阅 [使用 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);
}
}
}
```
**注意**
要对分类账运行数据操作，您必须创建`PooledQldbDriver` 或 `QldbDriver` 类的实例以连接到特定分类账。这与您在上一步中创建分类账时使用的 `AmazonQLDB` 客户端对象不同。之前的客户端仅用于[Amazon QLDB API 参考](api-reference.md)中列出的管理 API 操作。
除非您需要使用`QldbDriver`实现自定义会话池，否则我们建议使用`PooledQldbDriver`。默认`PooledQldbDriver`池大小是会话客户端允许[的最大打开 HTTP 连接数](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/ClientConfiguration.html#getMaxConnections--)。
首先，创建一个 `PooledQldbDriver` 对象。创建此驱动程序时，您必须指定分类账名称。
然后，您可以使用此驱动程序的 `execute` 方法运行 PartiQL 语句。或者，您可通过此池驱动程序对象手动创建会话并使用该会话`execute`方法。会话代表与分类账的单个连接。
或者，您可指定事务异常的最大重试次数。该 `execute` 方法会自动重试乐观并发控制（OCC）冲突和其他常见的瞬态异常，但不超过此可配置限制。默认值为 `4`。
如果在达到限制后事务仍失败，则驱动程序会抛出异常。要了解更多信息，请参阅 [使用 Amazon QLDB 中的驱动程序了解重试策略](driver-retry-policy.md)。
------
1. 编译并运行该 `ConnectToLedger.java` 程序，以测试您的数据会话与`vehicle-registration` 分类账的连接。
**覆盖 AWS 区域**
示例应用程序以 AWS 区域默认方式连接到 QLDB，您可以按照先决条件步骤中的说明进行设置。[设置您的默认 AWS 凭证和区域](getting-started.java.md#getting-started.java.credentials)可以修改 QLDB 会话客户构建程序的属性来更改区域。
------
#### [ 2.x ]
下面的代码示例实例化一个新的 `QldbSessionClientBuilder` 对象。
```
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);
```
您可以使用 `region` 方法对任何可用区域中的 QLDB 运行您的代码。有关完整列表，请参阅 *AWS 一般参考* 中的 [Amazon QLDB 端点和限额](https://docs.aws.amazon.com/general/latest/gr/qldb.html)。
------
#### [ 1.x ]
下面的代码示例实例化一个新的 `AmazonQLDBSessionClientBuilder` 对象。
```
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);
```
您可以使用 `withRegion` 方法对任何可用区域中的 QLDB 运行您的代码。有关完整列表，请参阅 *AWS 一般参考* 中的 [Amazon QLDB 端点和限额](https://docs.aws.amazon.com/general/latest/gr/qldb.html)。
------
要在 `vehicle-registration` 分类账中创建表，请继续 [步骤 3：创建表、索引与示例数据](getting-started.java.step-3.md)。
# 步骤 3：创建表、索引与示例数据
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
当您的 Amazon QLDB 分类账处于活动状态且接受连接时，您可开始创建有关车辆、车主和注册信息的数据表。创建表和索引后，可以向其中加载数据。
在此步骤中，您将在`vehicle-registration`分类账中创建四个表格：
+ `VehicleRegistration`
+ `Vehicle`
+ `Person`
+ `DriversLicense`
您还可创建以下索引。
****
| 表名称 | 字段 |
| --- | --- |
| VehicleRegistration | VIN |
| VehicleRegistration | LicensePlateNumber |
| Vehicle | VIN |
| Person | GovId |
| DriversLicense | LicenseNumber |
| DriversLicense | PersonId |
插入示例数据时，首先要在 `Person` 表格中插入文档。然后使用系统分配的、来自每个`Person`文档的`id`填充适当`VehicleRegistration` 和 `DriversLicense`文档中的相应文档。
**提示**
最佳做法是使用系统分配的 `id` 文档作为外键。虽然您可以定义作为唯一标识符的字段（例如车辆的 VIN），但文档的真正唯一标识符是`id`。字段都包含在文档元数据中，您可以在*提交视图*（系统定义的表格视图）中对其进行查询。
有关 QLDB 中的视图的更多信息，请参阅[核心概念](ledger-structure.md)。了解有关元数据的更多信息，请参阅 [查询文档元数据](working.metadata.md)。
**设置示例数据**
1. 审查以下 `.java` 文件。这些模型类代表您存储在 `vehicle-registration` 表格中的文档。它们可在 Amazon Ion 格式之间进行序列化。
**注意**
[Amazon QLDB 文档](ql-reference.docs.md)以 Ion 格式（JSON 父集）存储。因此，您可使用 FasterXML Jackson 库对 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. 查看以下文件（`SampleData.java`），该文件代表您插入 `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 ]
**重要**
对于 Amazon Ion 软件包，您必须在应用程序中使用命名空间`com.amazon.ion`。 适用于 Java 的 AWS SDK 依赖于命名空间下的另一个 Ion 包`software.amazon.ion`，但这是一个与 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()));
}
}
```
------
**注意**
该类使用 Ion 库提供辅助方法，用于将您的数据与 Ion 格式进行相互转换。
该 `getDocumentId`方法对带有前缀`_ql_committed_`的表运行查询。这是保留的前缀，表示您要查询表的*已提交视图*。在此视图中，您的数据嵌套至`data`字段中，元数据嵌套至`metadata`字段中。
1. 编译并运行以下程序（`CreateTable.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 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..."));
}
}
```
------
**注意**
该程序演示了如何将 `TransactionExecutor` lambda 传递至`execute`方法。在此示例中，您使用 lambda 表达式在单个事务中运行多个`CREATE TABLE` PartiQL 语句。
该 `execute` 方法采用隐式启动事务，运行 lambda 中的所有语句，然后自动提交事务。
1. 如前所述，编译并运行以下程序（`CreateIndex.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 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. 编译并运行以下程序（`InsertDocument.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.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!");
}
}
```
------
**注意**
该程序演示如何使用参数化值调用`execute`方法。除了要运行的 PartiQL 语句之外，您还可以传递`IonValue`类数据参数。在语句字符串中将问号（`?`）作为变量占位符。
如果 `INSERT` 语句成功，则返回每个插入文档的`id`。
接下来，您可以使用 `SELECT` 语句从 `vehicle-registration` 分类账中的表中读取数据。继续执行[步骤 4：查询分类账中的表](getting-started.java.step-4.md)。
# 步骤 4：查询分类账中的表
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在 Amazon QLDB 分类账中创建表格和加载数据后，您可运行查询以查看刚刚插入的车辆登记数据。QLDB 使用 [PartiQL](ql-reference.md)作为其查询语言，使用 [Amazon Ion](ion.md)作为其面向文档的数据模型。
PartiQL 是开源、与 SQL 兼容的查询语言，现已扩展为可与 Ion 配合使用。使用 PartiQL，您可使用熟悉的 SQL 运算符插入、查询和管理数据。Amazon Ion 是 JSON 的超集。Ion 是基于文档的开源数据格式，可让您灵活地存储和处理结构化、半结构化和嵌套数据。
在此步骤中，您将使用 `SELECT` 语句从 `vehicle-registration`分类账中的表中读取数据。
**警告**
当您在没有索引查找的情况下运行查询时，它会调用全表扫描。PartiQL 之所以支持此类查询，是因为其与 SQL 兼容。但是，*切勿*在 QLDB 中对生产用例运行表扫描。表扫描可能会导致大型表出现性能问题，包括并发冲突与事务超时。
为避免表扫描，必须在索引字段或文档 ID 上使用*相等*运算符（`WHERE indexedField = 123`或`WHERE indexedField IN (456, 789)`）运行带有`WHERE`谓词子句的语句。有关更多信息，请参阅 [优化查询性能](working.optimize.md)。
**查询表格**
+ 编译并运行以下程序（`FindVehicles.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 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..."));
}
}
```
------
**注意**
首先，该程序在 `Person` 表格中查询文档`GovId LEWISR261LL`，以获取其`id`元数据字段。
然后，它使用文档`id`，通过`PrimaryOwner.PersonId`作为外键查询`VehicleRegistration`表。它还结合`VIN`字段上的`Vehicle`表`VehicleRegistration`。
要了解如何修改 `vehicle-registration` 分类账表格中的文档，请参阅 [第 5 步：修改分类账中的文档](getting-started.java.step-5.md)。
# 第 5 步：修改分类账中的文档
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
现在您有了要处理的数据，可以开始在 Amazon QLDB 中对 `vehicle-registration` 分类账文档进行更改。在此步骤中，以下代码示例介绍了如何运行数据操作语言（DML）语句。这些声明更新一辆车的主要车主，并为另一辆车添加了次要车主。
**修改文档**
1. 编译并运行以下程序（`TransferVehicleOwnership.java`），使用分类账中的 VIN`1N4AL11D75C109151` 更新车辆的主要车主。
------
#### [ 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. 编译并运行以下程序（`AddSecondaryOwner.java`），将二级车主添加至分类账中带有 VIN `KM8SRDHF6EU074761` 的车辆中。
------
#### [ 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.");
}
}
```
------
若要 查看 `vehicle-registration` 分类账中的这些更改，请参阅[步骤 6：查看文档修订历史记录](getting-started.java.step-6.md)。
# 步骤 6：查看文档修订历史记录
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在上一步中修改车辆注册数据后，您可查询其所有注册车主的历史记录以及任何其他更新的字段。在此步骤中，您将在 `vehicle-registration` 分类账的 `VehicleRegistration` 表格中查询文档的修订历史记录。
**若要查看修订历史记录**
1. 查看以下程序（`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.");
}
}
```
------
**注意**
您可以通过以下语法查询内置版本，以查看文档[历史记录函数](working.history.md#working.history.function)的修订历史记录。
```
SELECT * FROM history( table_name [, `start-time` [, `end-time` ] ] ) AS h
[ WHERE h.metadata.id = 'id' ]
```
*开始时间*和*结束时间*均为可选。它们是 Amazon Ion 的字面值，可以用反引号（``...``）表示。要了解更多信息，请参阅 [在 Amazon QLDB 中使用 PartiQL 查询 Ion](ql-reference.query.md)。
最佳做法是，使用日期范围（*开始时间* 和 *结束时间*）和文档 ID（`metadata.id`）来限定历史记录查询。QLDB 处理事务中的`SELECT`查询，这些查询受[事务超时限制](limits.md#limits.fixed)的约束。
QLDB 历史记录按文档 ID 编制索引，目前无法创建其他历史索引。包含开始时间和结束时间的历史记录查询将从日期范围限定中获得便利。
1. 编译并运行 `QueryHistory.java` 程序，以使用 VIN `1N4AL11D75C109151`查询`VehicleRegistration`文档的修订历史记录。
要以加密方式验证 `vehicle-registration` 分类账中的文档修订版，请继续[第 7 步：验证分类账中的文档](getting-started.java.step-7.md)。
# 第 7 步：验证分类账中的文档
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
借助 Amazon QLDB，您可在 SHA-256 中使用加密哈希，从而有效地验证分类账日记账中文档的完整性。要详细了解验证和加密哈希在 QLDB 中的工作原理，请参阅 [Amazon QLDB 中的数据验证](verification.md)。
在此步骤中，您将验证 `vehicle-registration` 分类账 `VehicleRegistration` 表格中的单据修订版本。首先，您请求一份摘要，该摘要作为输出文件返回，并作为分类账整个变更历史记录的签名。然后，您要求提供与此摘要相关的修订证明。使用此证明，如果所有验证检查都可通过，可以验证修订版的完整性。
**验证文档的修订版**
1. 查看以下 `.java` 文件，这些文件代表了验证所需 QLDB 对象，以及带有 Ion 和字符串值的辅助方法的实用程序类。
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. 使用两个`.java`文件（`GetDigest.java`和`GetRevision.java`）执行以下步骤：
+ 从`vehicle-registration`分类账中请求新摘要。
+ 请索取 `VehicleRegistration` 表格中每份文件修订版的证明。
+ 通过重新计算摘要，使用返回的摘要和证明验证修订版。
`GetDigest.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;
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;
}
}
```
**注意**
使用该 `getDigest` 方法请求一份涵盖分类账中日记账当前*提示*的摘要。日记账提示指的是 QLDB 收到您的请求时的最近提交的数据块。
`GetRevision.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 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);
}
}
}
```
------
**注意**
在`getRevision`方法返回指定文档修订版本的证明后，此程序使用客户端 API 验证该修订版。有关此 API 使用的算法的概述，请参阅 [使用证明重新计算您的摘要](verification.results.md#verification.results.recalc)。
1. 编译并运行`GetRevision.java`程序，使用 VIN `1N4AL11D75C109151` 对 `VehicleRegistration` 文档进行加密验证。
要导出和验证 `vehicle-registration` 分类账中的日记账数据，请继续 [步骤 8：导出并验证分类账中的日记账数据](getting-started.java.step-8.md)。
# 步骤 8：导出并验证分类账中的日记账数据
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在 Amazon QLDB 中，您可出于各种目的访问分类账中的日记账内容，例如数据保留、分析和审计。有关更多信息，请参阅 [从Amazon QLDB 导出日记账数据](export-journal.md)。
在此步骤中，您将`vehicle-registration`分类账中的[日记账数据块](journal-contents.md)导出至 Amazon S3 存储桶中。然后，您可使用导出的数据验证日记账数据块和每个区块中各个哈希组件之间的哈希链。
您使用的 AWS Identity and Access Management (IAM) 委托人实体必须具有足够的 IAM 权限才能在您的中创建 Amazon S3 存储桶 AWS 账户。有关更多信息，请参阅 *Amazon S3 用户指南* 中的 [Policies and Permissions in Amazon S3 中的策略和权限](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-policy-language-overview.html)。您还必须有权创建附带权限策略的 IAM 角色，该策略允许 QLDB 将对象写入至您的 Amazon S3 存储桶。有关更多信息，请参阅 *IAM 用户指南*中的[访问 IAM 资源所需的权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_permissions-required.html)。
**导出和验证日记账数据**
1. 查看以下文件（`JournalBlock.java`），该文件代表日记账数据块及其数据内容。它包括一个名为`verifyBlockHash()`的方法，该方法演示了如何计算区块哈希的每个组成部分。
```
/*
* 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. 编译并运行以下程序（`ValidateQldbHashChain.java`），以执行以下步骤：
1. 将账本中的日记`vehicle-registration`账块导出到名为**qldb-tutorial-journal-export-*111122223333***（用您的 AWS 账户 数字替换）的 Amazon S3 存储桶中。
1. 通过调用`verifyBlockHash()`来验证每个区块中的各个哈希组件。
1. 验证日记账数据块之间的哈希链。
```
/*
* 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;
}
}
}
```
如果您不再需要使用`vehicle-registration`分类账，请继续[步骤 9：（可选）清除资源](getting-started.java.step-9.md)。
# 步骤 9：（可选）清除资源
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
您可以继续使用 `vehicle-registration` 分类账。但是，如果您不再需要，请将其删除。
**删除分类账**
1. 编译并运行以下程序（`DeleteLedger.java`）以删除您的 `vehicle-registration` 分类账及其所有内容。
```
/*
* 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;
}
}
```
**注意**
如果您的分类账启用了删除保护，您必须先禁用它，然后才能使用 QLDB API 删除分类账。
1. 如果您在[上一步](getting-started.java.step-8.md)中导出了日记账数据，但不再需要这些数据，请使用 Amazon S3 控制台删除 S3 存储桶。
打开 Amazon S3 控制台，网址为 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
# Amazon QLDB Node.js 教程
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在本教程示例应用程序的本实现中，您将使用 Amazon QLDB 驱动程序和 Node.js 中的软件开发工具包来创建 QLD JavaScript B 账本并使用示例数据填充 AWS 该账本。
在学习本教程时，您可以参考 [适用于 JavaScript 的 AWS SDK API 参考](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/) 以了解管理 API 操作。有关事务数据操作，您可参见[适用于 Node.js API 参考的 QLDB 驱动程序](https://amazon-qldb-docs.s3.amazonaws.com/drivers/nodejs/3.1.0/index.html)。
**注意**
在适用的情况下，某些用例对于 Node.js 的 QLDB 驱动程序的每个支持主要版本都配备不同的命令或代码示例。
**Topics**
+ [
# 安装 Amazon QLDB Node.js 示例应用程序
](sample-app.nodejs.md)
+ [
# 第 1 步：创建新的分类账
](getting-started.nodejs.step-1.md)
+ [
# 第 2 步：测试与分类账的连接
](getting-started.nodejs.step-2.md)
+ [
# 步骤 3：创建表、索引与示例数据
](getting-started.nodejs.step-3.md)
+ [
# 步骤 4：查询分类账中的表
](getting-started.nodejs.step-4.md)
+ [
# 第 5 步：修改分类账中的文档
](getting-started.nodejs.step-5.md)
+ [
# 步骤 6：查看文档修订历史记录
](getting-started.nodejs.step-6.md)
+ [
# 第 7 步：验证分类账中的文档
](getting-started.nodejs.step-7.md)
+ [
# 第 8 步（可选）：清除资源
](getting-started.nodejs.step-8.md)
# 安装 Amazon QLDB Node.js 示例应用程序
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
本节介绍如何安装和运行为 Node.js 教程提供的亚马逊 QLDB 示例应用程序。 step-by-step此示例应用程序的用例是机动车辆部门（DMV）数据库，用于追踪有关车辆登记的完整历史信息。
Node.js 的 DMV 示例应用程序在 GitHub 存储库 [aws-samples/-amazon-qldb-dmv-sample](https://github.com/aws-samples/amazon-qldb-dmv-sample-nodejs) nodejs 中是开源的。
## 先决条件
在开始之前，请确保您已完成适用于 Node.js [先决条件](getting-started.nodejs.md#getting-started.nodejs.prereqs) 的 QLDB 驱动程序。这包括安装 Node.js 并执行以下操作：
1. 报名参加 AWS.
1. 创建具有适当 QLDB 权限的用户。
1. 授权以编程方式访问开发。
要完成本教程中的所有步骤，您需要通过 QLDB API 对分类账资源拥有完全管理权限。
## 安装
**要安装示例应用程序**
1. 输入以下命令以从中克隆示例应用程序 GitHub。
------
#### [ 2.x ]
```
git clone https://github.com/aws-samples/amazon-qldb-dmv-sample-nodejs.git
```
------
#### [ 1.x ]
```
git clone -b v1.0.0 https://github.com/aws-samples/amazon-qldb-dmv-sample-nodejs.git
```
------
该示例应用程序打包了本教程中的完整源代码及其依赖项，包括 Node.js 驱动程序和 [Node.js JavaScript 中的 S AWS DK](https://aws.amazon.com/sdk-for-node-js)。此应用程序是用编写的 TypeScript。
1. 切换到克隆 `amazon-qldb-dmv-sample-nodejs` 包的目录。
```
cd amazon-qldb-dmv-sample-nodejs
```
1. 对依赖项进行全新安装。
```
npm ci
```
1. 转换包。
```
npm run build
```
转译后的 JavaScript 文件写入`./dist`目录中。
1. 继续 [第 1 步：创建新的分类账](getting-started.nodejs.step-1.md) 开始教程并创建分类账。
# 第 1 步：创建新的分类账
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在此步骤中，您将创建一个名为 `vehicle-registration` 的新 Amazon QLDB 分类账。
**创建新分类账**
1. 查看以下文件（`Constants.ts`），其包含本教程中所有其他程序使用的常量值。
```
/*
* 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.
*/
/**
* Constant values used throughout this tutorial.
*/
export const LEDGER_NAME = "vehicle-registration";
export const LEDGER_NAME_WITH_TAGS = "tags";
export const DRIVERS_LICENSE_TABLE_NAME = "DriversLicense";
export const PERSON_TABLE_NAME = "Person";
export const VEHICLE_REGISTRATION_TABLE_NAME = "VehicleRegistration";
export const VEHICLE_TABLE_NAME = "Vehicle";
export const GOV_ID_INDEX_NAME = "GovId";
export const LICENSE_NUMBER_INDEX_NAME = "LicenseNumber";
export const LICENSE_PLATE_NUMBER_INDEX_NAME = "LicensePlateNumber";
export const PERSON_ID_INDEX_NAME = "PersonId";
export const VIN_INDEX_NAME = "VIN";
export const RETRY_LIMIT = 4;
export const JOURNAL_EXPORT_S3_BUCKET_NAME_PREFIX = "qldb-tutorial-journal-export";
export const USER_TABLES = "information_schema.user_tables";
```
1. 使用以下程序（`CreateLedger.ts`）创建名为 `vehicle-registration` 的分类账。
```
/*
* 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.
*/
import { QLDB } from "aws-sdk";
import {
CreateLedgerRequest,
CreateLedgerResponse,
DescribeLedgerRequest,
DescribeLedgerResponse
} from "aws-sdk/clients/qldb";
import { LEDGER_NAME } from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
import { sleep } from "./qldb/Util";
const LEDGER_CREATION_POLL_PERIOD_MS = 10000;
const ACTIVE_STATE = "ACTIVE";
/**
* Create a new ledger with the specified name.
* @param ledgerName Name of the ledger to be created.
* @param qldbClient The QLDB control plane client to use.
* @returns Promise which fulfills with a CreateLedgerResponse.
*/
export async function createLedger(ledgerName: string, qldbClient: QLDB): Promise {
log(`Creating a ledger named: ${ledgerName}...`);
const request: CreateLedgerRequest = {
Name: ledgerName,
PermissionsMode: "ALLOW_ALL"
}
const result: CreateLedgerResponse = await qldbClient.createLedger(request).promise();
log(`Success. Ledger state: ${result.State}.`);
return result;
}
/**
* Wait for the newly created ledger to become active.
* @param ledgerName Name of the ledger to be checked on.
* @param qldbClient The QLDB control plane client to use.
* @returns Promise which fulfills with a DescribeLedgerResponse.
*/
export async function waitForActive(ledgerName: string, qldbClient: QLDB): Promise {
log(`Waiting for ledger ${ledgerName} to become active...`);
const request: DescribeLedgerRequest = {
Name: ledgerName
}
while (true) {
const result: DescribeLedgerResponse = await qldbClient.describeLedger(request).promise();
if (result.State === ACTIVE_STATE) {
log("Success. Ledger is active and ready to be used.");
return result;
}
log("The ledger is still creating. Please wait...");
await sleep(LEDGER_CREATION_POLL_PERIOD_MS);
}
}
/**
* Create a ledger and wait for it to be active.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbClient: QLDB = new QLDB();
await createLedger(LEDGER_NAME, qldbClient);
await waitForActive(LEDGER_NAME, qldbClient);
} catch (e) {
error(`Unable to create the ledger: ${e}`);
}
}
if (require.main === module) {
main();
}
```
**注意**
在 `createLedger` 调用中，您必须指定分类账名称和权限模式。我们强烈建议使用 `STANDARD` 权限模式来最大限度地提高分类账数据的安全性。
创建分类账时，将默认启用 *删除保护*。QLDB 中有一项功能，可防止分类账被任何用户删除。您可以选择使用 QLDB API 或 AWS Command Line Interface () 在创建账本时禁用删除保护。AWS CLI
您还可选择指定要附加到分类账的标签。
1. 要运行编译后的程序，请输入以下命令。
```
node dist/CreateLedger.js
```
要验证您与新分类账的连接，请继续 [第 2 步：测试与分类账的连接](getting-started.nodejs.step-2.md)。
# 第 2 步：测试与分类账的连接
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在此步骤中，您将验证是否可以使用事务数据 API 端点连接至 Amazon QLDB 中的`vehicle-registration`分类账。
**测试与分类账的连接**
1. 使用以下程序（`ConnectToLedger.ts`），该程序创建了与`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.
*/
import { QldbDriver, RetryConfig } from "amazon-qldb-driver-nodejs";
import { ClientConfiguration } from "aws-sdk/clients/qldbsession";
import { LEDGER_NAME } from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
const qldbDriver: QldbDriver = createQldbDriver();
/**
* Create a driver for creating sessions.
* @param ledgerName The name of the ledger to create the driver on.
* @param serviceConfigurationOptions The configurations for the AWS SDK client that the driver uses.
* @returns The driver for creating sessions.
*/
export function createQldbDriver(
ledgerName: string = LEDGER_NAME,
serviceConfigurationOptions: ClientConfiguration = {}
): QldbDriver {
const retryLimit = 4;
const maxConcurrentTransactions = 10;
//Use driver's default backoff function (and hence, no second parameter provided to RetryConfig)
const retryConfig: RetryConfig = new RetryConfig(retryLimit);
const qldbDriver: QldbDriver = new QldbDriver(ledgerName, serviceConfigurationOptions, maxConcurrentTransactions, retryConfig);
return qldbDriver;
}
export function getQldbDriver(): QldbDriver {
return qldbDriver;
}
/**
* Connect to a session for a given ledger using default settings.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
log("Listing table names...");
const tableNames: string[] = await qldbDriver.getTableNames();
tableNames.forEach((tableName: string): void => {
log(tableName);
});
} catch (e) {
error(`Unable to create session: ${e}`);
}
}
if (require.main === module) {
main();
}
```
------
#### [ 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.
*/
import { QldbDriver } from "amazon-qldb-driver-nodejs";
import { ClientConfiguration } from "aws-sdk/clients/qldbsession";
import { LEDGER_NAME } from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
const qldbDriver: QldbDriver = createQldbDriver();
/**
* Create a driver for creating sessions.
* @param ledgerName The name of the ledger to create the driver on.
* @param serviceConfigurationOptions The configurations for the AWS SDK client that the driver uses.
* @returns The driver for creating sessions.
*/
export function createQldbDriver(
ledgerName: string = LEDGER_NAME,
serviceConfigurationOptions: ClientConfiguration = {}
): QldbDriver {
const qldbDriver: QldbDriver = new QldbDriver(ledgerName, serviceConfigurationOptions);
return qldbDriver;
}
export function getQldbDriver(): QldbDriver {
return qldbDriver;
}
/**
* Connect to a session for a given ledger using default settings.
* @returns Promise which fulfills with void.
*/
var main = async function(): Promise {
try {
log("Listing table names...");
const tableNames: string[] = await qldbDriver.getTableNames();
tableNames.forEach((tableName: string): void => {
log(tableName);
});
} catch (e) {
error(`Unable to create session: ${e}`);
}
}
if (require.main === module) {
main();
}
```
------
**注意**
要在分类账上运行数据事务，必须创建一个 QLDB 驱动对象以连接到指定的分类账。这与您在 [上一步](getting-started.nodejs.step-1.md) 中创建分类账时使用的 `qldbClient` 客户端对象不同。之前的客户端仅用于运行[Amazon QLDB API 参考](api-reference.md)中列出的管理 API 操作。
1. 要运行编译后的程序，请输入以下命令。
```
node dist/ConnectToLedger.js
```
要在 `vehicle-registration` 分类账中创建表，请继续 [步骤 3：创建表、索引与示例数据](getting-started.nodejs.step-3.md)。
# 步骤 3：创建表、索引与示例数据
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
当您的 Amazon QLDB 分类账处于活动状态且接受连接时，您可开始创建有关车辆、车主和注册信息的数据表。创建表和索引后，可以向其中加载数据。
在此步骤中，您将在`vehicle-registration`分类账中创建四个表格：
+ `VehicleRegistration`
+ `Vehicle`
+ `Person`
+ `DriversLicense`
您还可创建以下索引。
****
| 表名称 | 字段 |
| --- | --- |
| VehicleRegistration | VIN |
| VehicleRegistration | LicensePlateNumber |
| Vehicle | VIN |
| Person | GovId |
| DriversLicense | LicenseNumber |
| DriversLicense | PersonId |
插入示例数据时，首先要在 `Person` 表格中插入文档。然后使用系统分配的、来自每个`Person`文档的`id`填充适当`VehicleRegistration` 和 `DriversLicense`文档中的相应文档。
**提示**
最佳做法是使用系统分配的 `id` 文档作为外键。虽然您可以定义作为唯一标识符的字段（例如车辆的 VIN），但文档的真正唯一标识符是`id`。字段都包含在文档元数据中，您可以在*提交视图*（系统定义的表格视图）中对其进行查询。
有关 QLDB 中的视图的更多信息，请参阅[核心概念](ledger-structure.md)。了解有关元数据的更多信息，请参阅 [查询文档元数据](working.metadata.md)。
**创建表和索引**
1. 使用以下程序（`CreateTable.ts`）以创建前面提到的表。
```
/*
* 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.
*/
import { QldbDriver, Result, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { getQldbDriver } from "./ConnectToLedger";
import {
DRIVERS_LICENSE_TABLE_NAME,
PERSON_TABLE_NAME,
VEHICLE_REGISTRATION_TABLE_NAME,
VEHICLE_TABLE_NAME
} from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
/**
* Create multiple tables in a single transaction.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param tableName Name of the table to create.
* @returns Promise which fulfills with the number of changes to the database.
*/
export async function createTable(txn: TransactionExecutor, tableName: string): Promise {
const statement: string = `CREATE TABLE ${tableName}`;
return await txn.execute(statement).then((result: Result) => {
log(`Successfully created table ${tableName}.`);
return result.getResultList().length;
});
}
/**
* Create tables in a QLDB ledger.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbDriver: QldbDriver = getQldbDriver();
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
Promise.all([
createTable(txn, VEHICLE_REGISTRATION_TABLE_NAME),
createTable(txn, VEHICLE_TABLE_NAME),
createTable(txn, PERSON_TABLE_NAME),
createTable(txn, DRIVERS_LICENSE_TABLE_NAME)
]);
});
} catch (e) {
error(`Unable to create tables: ${e}`);
}
}
if (require.main === module) {
main();
}
```
**注意**
该程序演示如何在 QLDB 驱动程序实例中使用 `executeLambda` 函数。在此示例中，您使用单个 lambda 表达式运行多个`CREATE TABLE` PartiQL 语句。
该执行函数采用隐式启动事务，运行 lambda 中的所有语句，然后自动提交事务。
1. 要运行编译后的程序，请输入以下命令。
```
node dist/CreateTable.js
```
1. 如前所述，使用以下程序（`CreateIndex.ts`），以在表上创建索引。
```
/*
* 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.
*/
import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { getQldbDriver } from "./ConnectToLedger";
import {
DRIVERS_LICENSE_TABLE_NAME,
GOV_ID_INDEX_NAME,
LICENSE_NUMBER_INDEX_NAME,
LICENSE_PLATE_NUMBER_INDEX_NAME,
PERSON_ID_INDEX_NAME,
PERSON_TABLE_NAME,
VEHICLE_REGISTRATION_TABLE_NAME,
VEHICLE_TABLE_NAME,
VIN_INDEX_NAME
} from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
/**
* Create an index for a particular table.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param tableName Name of the table to add indexes for.
* @param indexAttribute Index to create on a single attribute.
* @returns Promise which fulfills with the number of changes to the database.
*/
export async function createIndex(
txn: TransactionExecutor,
tableName: string,
indexAttribute: string
): Promise {
const statement: string = `CREATE INDEX on ${tableName} (${indexAttribute})`;
return await txn.execute(statement).then((result) => {
log(`Successfully created index ${indexAttribute} on table ${tableName}.`);
return result.getResultList().length;
});
}
/**
* Create indexes on tables in a particular ledger.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbDriver: QldbDriver = getQldbDriver();
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
Promise.all([
createIndex(txn, PERSON_TABLE_NAME, GOV_ID_INDEX_NAME),
createIndex(txn, VEHICLE_TABLE_NAME, VIN_INDEX_NAME),
createIndex(txn, VEHICLE_REGISTRATION_TABLE_NAME, VIN_INDEX_NAME),
createIndex(txn, VEHICLE_REGISTRATION_TABLE_NAME, LICENSE_PLATE_NUMBER_INDEX_NAME),
createIndex(txn, DRIVERS_LICENSE_TABLE_NAME, PERSON_ID_INDEX_NAME),
createIndex(txn, DRIVERS_LICENSE_TABLE_NAME, LICENSE_NUMBER_INDEX_NAME)
]);
});
} catch (e) {
error(`Unable to create indexes: ${e}`);
}
}
if (require.main === module) {
main();
}
```
1. 要运行编译后的程序，请输入以下命令。
```
node dist/CreateIndex.js
```
**将样本数据加载到表中**
1. 审查以下 `.ts` 文件。
1. `SampleData.ts` - 包含您插入到 `vehicle-registration` 表中的示例数据。
```
/*
* 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.
*/
import { Decimal } from "ion-js";
const EMPTY_SECONDARY_OWNERS: object[] = [];
export const DRIVERS_LICENSE = [
{
PersonId: "",
LicenseNumber: "LEWISR261LL",
LicenseType: "Learner",
ValidFromDate: new Date("2016-12-20"),
ValidToDate: new Date("2020-11-15")
},
{
PersonId: "",
LicenseNumber : "LOGANB486CG",
LicenseType: "Probationary",
ValidFromDate : new Date("2016-04-06"),
ValidToDate : new Date("2020-11-15")
},
{
PersonId: "",
LicenseNumber : "744 849 301",
LicenseType: "Full",
ValidFromDate : new Date("2017-12-06"),
ValidToDate : new Date("2022-10-15")
},
{
PersonId: "",
LicenseNumber : "P626-168-229-765",
LicenseType: "Learner",
ValidFromDate : new Date("2017-08-16"),
ValidToDate : new Date("2021-11-15")
},
{
PersonId: "",
LicenseNumber : "S152-780-97-415-0",
LicenseType: "Probationary",
ValidFromDate : new Date("2015-08-15"),
ValidToDate : new Date("2021-08-21")
}
];
export const PERSON = [
{
FirstName : "Raul",
LastName : "Lewis",
DOB : new Date("1963-08-19"),
Address : "1719 University Street, Seattle, WA, 98109",
GovId : "LEWISR261LL",
GovIdType : "Driver License"
},
{
FirstName : "Brent",
LastName : "Logan",
DOB : new Date("1967-07-03"),
Address : "43 Stockert Hollow Road, Everett, WA, 98203",
GovId : "LOGANB486CG",
GovIdType : "Driver License"
},
{
FirstName : "Alexis",
LastName : "Pena",
DOB : new Date("1974-02-10"),
Address : "4058 Melrose Street, Spokane Valley, WA, 99206",
GovId : "744 849 301",
GovIdType : "SSN"
},
{
FirstName : "Melvin",
LastName : "Parker",
DOB : new Date("1976-05-22"),
Address : "4362 Ryder Avenue, Seattle, WA, 98101",
GovId : "P626-168-229-765",
GovIdType : "Passport"
},
{
FirstName : "Salvatore",
LastName : "Spencer",
DOB : new Date("1997-11-15"),
Address : "4450 Honeysuckle Lane, Seattle, WA, 98101",
GovId : "S152-780-97-415-0",
GovIdType : "Passport"
}
];
export const VEHICLE = [
{
VIN : "1N4AL11D75C109151",
Type : "Sedan",
Year : 2011,
Make : "Audi",
Model : "A5",
Color : "Silver"
},
{
VIN : "KM8SRDHF6EU074761",
Type : "Sedan",
Year : 2015,
Make : "Tesla",
Model : "Model S",
Color : "Blue"
},
{
VIN : "3HGGK5G53FM761765",
Type : "Motorcycle",
Year : 2011,
Make : "Ducati",
Model : "Monster 1200",
Color : "Yellow"
},
{
VIN : "1HVBBAANXWH544237",
Type : "Semi",
Year : 2009,
Make : "Ford",
Model : "F 150",
Color : "Black"
},
{
VIN : "1C4RJFAG0FC625797",
Type : "Sedan",
Year : 2019,
Make : "Mercedes",
Model : "CLK 350",
Color : "White"
}
];
export const VEHICLE_REGISTRATION = [
{
VIN : "1N4AL11D75C109151",
LicensePlateNumber : "LEWISR261LL",
State : "WA",
City : "Seattle",
ValidFromDate : new Date("2017-08-21"),
ValidToDate : new Date("2020-05-11"),
PendingPenaltyTicketAmount : new Decimal(9025, -2),
Owners : {
PrimaryOwner : { PersonId : "" },
SecondaryOwners : EMPTY_SECONDARY_OWNERS
}
},
{
VIN : "KM8SRDHF6EU074761",
LicensePlateNumber : "CA762X",
State : "WA",
City : "Kent",
PendingPenaltyTicketAmount : new Decimal(13075, -2),
ValidFromDate : new Date("2017-09-14"),
ValidToDate : new Date("2020-06-25"),
Owners : {
PrimaryOwner : { PersonId : "" },
SecondaryOwners : EMPTY_SECONDARY_OWNERS
}
},
{
VIN : "3HGGK5G53FM761765",
LicensePlateNumber : "CD820Z",
State : "WA",
City : "Everett",
PendingPenaltyTicketAmount : new Decimal(44230, -2),
ValidFromDate : new Date("2011-03-17"),
ValidToDate : new Date("2021-03-24"),
Owners : {
PrimaryOwner : { PersonId : "" },
SecondaryOwners : EMPTY_SECONDARY_OWNERS
}
},
{
VIN : "1HVBBAANXWH544237",
LicensePlateNumber : "LS477D",
State : "WA",
City : "Tacoma",
PendingPenaltyTicketAmount : new Decimal(4220, -2),
ValidFromDate : new Date("2011-10-26"),
ValidToDate : new Date("2023-09-25"),
Owners : {
PrimaryOwner : { PersonId : "" },
SecondaryOwners : EMPTY_SECONDARY_OWNERS
}
},
{
VIN : "1C4RJFAG0FC625797",
LicensePlateNumber : "TH393F",
State : "WA",
City : "Olympia",
PendingPenaltyTicketAmount : new Decimal(3045, -2),
ValidFromDate : new Date("2013-09-02"),
ValidToDate : new Date("2024-03-19"),
Owners : {
PrimaryOwner : { PersonId : "" },
SecondaryOwners : EMPTY_SECONDARY_OWNERS
}
}
];
```
1. `Util.ts` - 从 `ion-js` 包导入的实用程序模块，提供用于转换、解析和打印 [Amazon Ion](ion.md) 数据的辅助函数。
```
/*
* 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.
*/
import { Result, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { GetBlockResponse, GetDigestResponse, ValueHolder } from "aws-sdk/clients/qldb";
import {
Decimal,
decodeUtf8,
dom,
IonTypes,
makePrettyWriter,
makeReader,
Reader,
Timestamp,
toBase64,
Writer
} from "ion-js";
import { error } from "./LogUtil";
/**
* TODO: Replace this with json.stringify
* Returns the string representation of a given BlockResponse.
* @param blockResponse The BlockResponse to convert to string.
* @returns The string representation of the supplied BlockResponse.
*/
export function blockResponseToString(blockResponse: GetBlockResponse): string {
let stringBuilder: string = "";
if (blockResponse.Block.IonText) {
stringBuilder = stringBuilder + "Block: " + blockResponse.Block.IonText + ", ";
}
if (blockResponse.Proof.IonText) {
stringBuilder = stringBuilder + "Proof: " + blockResponse.Proof.IonText;
}
stringBuilder = "{" + stringBuilder + "}";
const writer: Writer = makePrettyWriter();
const reader: Reader = makeReader(stringBuilder);
writer.writeValues(reader);
return decodeUtf8(writer.getBytes());
}
/**
* TODO: Replace this with json.stringify
* Returns the string representation of a given GetDigestResponse.
* @param digestResponse The GetDigestResponse to convert to string.
* @returns The string representation of the supplied GetDigestResponse.
*/
export function digestResponseToString(digestResponse: GetDigestResponse): string {
let stringBuilder: string = "";
if (digestResponse.Digest) {
stringBuilder += "Digest: " + JSON.stringify(toBase64( digestResponse.Digest)) + ", ";
}
if (digestResponse.DigestTipAddress.IonText) {
stringBuilder += "DigestTipAddress: " + digestResponse.DigestTipAddress.IonText;
}
stringBuilder = "{" + stringBuilder + "}";
const writer: Writer = makePrettyWriter();
const reader: Reader = makeReader(stringBuilder);
writer.writeValues(reader);
return decodeUtf8(writer.getBytes());
}
/**
* Get the document IDs from the given table.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param tableName The table name to query.
* @param field A field to query.
* @param value The key of the given field.
* @returns Promise which fulfills with the document ID as a string.
*/
export async function getDocumentId(
txn: TransactionExecutor,
tableName: string,
field: string,
value: string
): Promise {
const query: string = `SELECT id FROM ${tableName} AS t BY id WHERE t.${field} = ?`;
let documentId: string = undefined;
await txn.execute(query, value).then((result: Result) => {
const resultList: dom.Value[] = result.getResultList();
if (resultList.length === 0) {
throw new Error(`Unable to retrieve document ID using ${value}.`);
}
documentId = resultList[0].get("id").stringValue();
}).catch((err: any) => {
error(`Error getting documentId: ${err}`);
});
return documentId;
}
/**
* Sleep for the specified amount of time.
* @param ms The amount of time to sleep in milliseconds.
* @returns Promise which fulfills with void.
*/
export function sleep(ms: number): Promise {
return new Promise(resolve => setTimeout(resolve, ms));
}
/**
* Find the value of a given path in an Ion value. The path should contain a blob value.
* @param value The Ion value that contains the journal block attributes.
* @param path The path to a certain attribute.
* @returns Uint8Array value of the blob, or null if the attribute cannot be found in the Ion value
* or is not of type Blob
*/
export function getBlobValue(value: dom.Value, path: string): Uint8Array | null {
const attribute: dom.Value = value.get(path);
if (attribute !== null && attribute.getType() === IonTypes.BLOB) {
return attribute.uInt8ArrayValue();
}
return null;
}
/**
* TODO: Replace this with json.stringify
* Returns the string representation of a given ValueHolder.
* @param valueHolder The ValueHolder to convert to string.
* @returns The string representation of the supplied ValueHolder.
*/
export function valueHolderToString(valueHolder: ValueHolder): string {
const stringBuilder: string = `{ IonText: ${valueHolder.IonText}}`;
const writer: Writer = makePrettyWriter();
const reader: Reader = makeReader(stringBuilder);
writer.writeValues(reader);
return decodeUtf8(writer.getBytes());
}
/**
* Converts a given value to Ion using the provided writer.
* @param value The value to convert to Ion.
* @param ionWriter The Writer to pass the value into.
* @throws Error: If the given value cannot be converted to Ion.
*/
export function writeValueAsIon(value: any, ionWriter: Writer): void {
switch (typeof value) {
case "string":
ionWriter.writeString(value);
break;
case "boolean":
ionWriter.writeBoolean(value);
break;
case "number":
ionWriter.writeInt(value);
break;
case "object":
if (Array.isArray(value)) {
// Object is an array.
ionWriter.stepIn(IonTypes.LIST);
for (const element of value) {
writeValueAsIon(element, ionWriter);
}
ionWriter.stepOut();
} else if (value instanceof Date) {
// Object is a Date.
ionWriter.writeTimestamp(Timestamp.parse(value.toISOString()));
} else if (value instanceof Decimal) {
// Object is a Decimal.
ionWriter.writeDecimal(value);
} else if (value === null) {
ionWriter.writeNull(IonTypes.NULL);
} else {
// Object is a struct.
ionWriter.stepIn(IonTypes.STRUCT);
for (const key of Object.keys(value)) {
ionWriter.writeFieldName(key);
writeValueAsIon(value[key], ionWriter);
}
ionWriter.stepOut();
}
break;
default:
throw new Error(`Cannot convert to Ion for type: ${(typeof value)}.`);
}
}
```
**注意**
该`getDocumentId`函数运行一个查询， IDs 从表中返回系统分配的文档。要了解更多信息，请参阅 [通过 BY 子句查询文档 ID](working.metadata.by-clause.md)。
1. 使用以下程序（`InsertDocument.ts`），将示例数据插入表内。
```
/*
* 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.
*/
import { QldbDriver, Result, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";
import { getQldbDriver } from "./ConnectToLedger";
import { DRIVERS_LICENSE, PERSON, VEHICLE, VEHICLE_REGISTRATION } from "./model/SampleData";
import {
DRIVERS_LICENSE_TABLE_NAME,
PERSON_TABLE_NAME,
VEHICLE_REGISTRATION_TABLE_NAME,
VEHICLE_TABLE_NAME
} from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
/**
* Insert the given list of documents into a table in a single transaction.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param tableName Name of the table to insert documents into.
* @param documents List of documents to insert.
* @returns Promise which fulfills with a {@linkcode Result} object.
*/
export async function insertDocument(
txn: TransactionExecutor,
tableName: string,
documents: object[]
): Promise {
const statement: string = `INSERT INTO ${tableName} ?`;
const result: Result = await txn.execute(statement, documents);
return result;
}
/**
* Handle the insertion of documents and updating PersonIds all in a single transaction.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @returns Promise which fulfills with void.
*/
async function updateAndInsertDocuments(txn: TransactionExecutor): Promise {
log("Inserting multiple documents into the 'Person' table...");
const documentIds: Result = await insertDocument(txn, PERSON_TABLE_NAME, PERSON);
const listOfDocumentIds: dom.Value[] = documentIds.getResultList();
log("Updating PersonIds for 'DriversLicense' and PrimaryOwner for 'VehicleRegistration'...");
updatePersonId(listOfDocumentIds);
log("Inserting multiple documents into the remaining tables...");
await Promise.all([
insertDocument(txn, DRIVERS_LICENSE_TABLE_NAME, DRIVERS_LICENSE),
insertDocument(txn, VEHICLE_REGISTRATION_TABLE_NAME, VEHICLE_REGISTRATION),
insertDocument(txn, VEHICLE_TABLE_NAME, VEHICLE)
]);
}
/**
* Update the PersonId value for DriversLicense records and the PrimaryOwner value for VehicleRegistration records.
* @param documentIds List of document IDs.
*/
export function updatePersonId(documentIds: dom.Value[]): void {
documentIds.forEach((value: dom.Value, i: number) => {
const documentId: string = value.get("documentId").stringValue();
DRIVERS_LICENSE[i].PersonId = documentId;
VEHICLE_REGISTRATION[i].Owners.PrimaryOwner.PersonId = documentId;
});
}
/**
* Insert documents into a table in a QLDB ledger.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbDriver: QldbDriver = getQldbDriver();
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
await updateAndInsertDocuments(txn);
});
} catch (e) {
error(`Unable to insert documents: ${e}`);
}
}
if (require.main === module) {
main();
}
```
**注意**
该程序演示如何使用参数化值调用`execute`方法。除了要运行的 PartiQL 语句之外，您还可以传递数据参数。在语句字符串中将问号（`?`）作为变量占位符。
如果 `INSERT` 语句成功，则返回每个插入文档的`id`。
1. 要运行编译后的程序，请输入以下命令。
```
node dist/InsertDocument.js
```
接下来，您可以使用 `SELECT` 语句从 `vehicle-registration` 分类账中的表中读取数据。继续执行[步骤 4：查询分类账中的表](getting-started.nodejs.step-4.md)。
# 步骤 4：查询分类账中的表
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在 Amazon QLDB 分类账中创建表格和加载数据后，您可运行查询以查看刚刚插入的车辆登记数据。QLDB 使用 [PartiQL](ql-reference.md)作为其查询语言，使用 [Amazon Ion](ion.md)作为其面向文档的数据模型。
PartiQL 是开源、与 SQL 兼容的查询语言，现已扩展为可与 Ion 配合使用。使用 PartiQL，您可使用熟悉的 SQL 运算符插入、查询和管理数据。Amazon Ion 是 JSON 的超集。Ion 是基于文档的开源数据格式，可让您灵活地存储和处理结构化、半结构化和嵌套数据。
在此步骤中，您将使用 `SELECT` 语句从 `vehicle-registration`分类账中的表中读取数据。
**警告**
当您在没有索引查找的情况下运行查询时，它会调用全表扫描。PartiQL 之所以支持此类查询，是因为其与 SQL 兼容。但是，*切勿*在 QLDB 中对生产用例运行表扫描。表扫描可能会导致大型表出现性能问题，包括并发冲突与事务超时。
为避免表扫描，必须在索引字段或文档 ID 上使用*相等*运算符（`WHERE indexedField = 123`或`WHERE indexedField IN (456, 789)`）运行带有`WHERE`谓词子句的语句。有关更多信息，请参阅 [优化查询性能](working.optimize.md)。
**查询表格**
1. 使用以下程序（`FindVehicles.ts`），以查询分类账中某人名下注册的所有车辆。
```
/*
* 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.
*/
import { QldbDriver, Result, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";
import { getQldbDriver } from "./ConnectToLedger";
import { PERSON } from "./model/SampleData";
import { PERSON_TABLE_NAME } from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
import { getDocumentId } from "./qldb/Util";
import { prettyPrintResultList } from "./ScanTable";
/**
* Query 'Vehicle' and 'VehicleRegistration' tables using a unique document ID in one transaction.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param govId The owner's government ID.
* @returns Promise which fulfills with void.
*/
async function findVehiclesForOwner(txn: TransactionExecutor, govId: string): Promise {
const documentId: string = await getDocumentId(txn, PERSON_TABLE_NAME, "GovId", govId);
const query: string = "SELECT Vehicle FROM Vehicle INNER JOIN VehicleRegistration AS r " +
"ON Vehicle.VIN = r.VIN WHERE r.Owners.PrimaryOwner.PersonId = ?";
await txn.execute(query, documentId).then((result: Result) => {
const resultList: dom.Value[] = result.getResultList();
log(`List of vehicles for owner with GovId: ${govId}`);
prettyPrintResultList(resultList);
});
}
/**
* Find all vehicles registered under a person.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbDriver: QldbDriver = getQldbDriver();
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
await findVehiclesForOwner(txn, PERSON[0].GovId);
});
} catch (e) {
error(`Error getting vehicles for owner: ${e}`);
}
}
if (require.main === module) {
main();
}
```
**注意**
首先，该程序在 `Person` 表格中查询文档`GovId LEWISR261LL`，以获取其`id`元数据字段。
然后，它使用文档`id`，通过`PrimaryOwner.PersonId`作为外键查询`VehicleRegistration`表。它还结合`VIN`字段上的`Vehicle`表的`VehicleRegistration`。
1. 要运行编译后的程序，请输入以下命令。
```
node dist/FindVehicles.js
```
要了解如何修改 `vehicle-registration` 分类账表格中的文档，请参阅 [第 5 步：修改分类账中的文档](getting-started.nodejs.step-5.md)。
# 第 5 步：修改分类账中的文档
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
现在您有了要处理的数据，可以开始在 Amazon QLDB 中对 `vehicle-registration` 分类账文档进行更改。在此步骤中，以下代码示例介绍了如何运行数据操作语言（DML）语句。这些声明更新一辆车的主要车主，并为另一辆车添加了次要车主。
**修改文档**
1. 使用以下程序（`TransferVehicleOwnership.ts`），更新分类账中带有 VIN `1N4AL11D75C109151` 的车辆的主要车主。
```
/*
* 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.
*/
import { QldbDriver, Result, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";
import { getQldbDriver } from "./ConnectToLedger";
import { PERSON, VEHICLE } from "./model/SampleData";
import { PERSON_TABLE_NAME } from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
import { getDocumentId } from "./qldb/Util";
/**
* Query a driver's information using the given ID.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param documentId The unique ID of a document in the Person table.
* @returns Promise which fulfills with an Ion value containing the person.
*/
export async function findPersonFromDocumentId(txn: TransactionExecutor, documentId: string): Promise {
const query: string = "SELECT p.* FROM Person AS p BY pid WHERE pid = ?";
let personId: dom.Value;
await txn.execute(query, documentId).then((result: Result) => {
const resultList: dom.Value[] = result.getResultList();
if (resultList.length === 0) {
throw new Error(`Unable to find person with ID: ${documentId}.`);
}
personId = resultList[0];
});
return personId;
}
/**
* Find the primary owner for the given VIN.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param vin The VIN to find primary owner for.
* @returns Promise which fulfills with an Ion value containing the primary owner.
*/
export async function findPrimaryOwnerForVehicle(txn: TransactionExecutor, vin: string): Promise {
log(`Finding primary owner for vehicle with VIN: ${vin}`);
const query: string = "SELECT Owners.PrimaryOwner.PersonId FROM VehicleRegistration AS v WHERE v.VIN = ?";
let documentId: string = undefined;
await txn.execute(query, vin).then((result: Result) => {
const resultList: dom.Value[] = result.getResultList();
if (resultList.length === 0) {
throw new Error(`Unable to retrieve document ID using ${vin}.`);
}
const PersonIdValue: dom.Value = resultList[0].get("PersonId");
if (PersonIdValue === null) {
throw new Error(`Expected field name PersonId not found.`);
}
documentId = PersonIdValue.stringValue();
});
return findPersonFromDocumentId(txn, documentId);
}
/**
* Update the primary owner for a vehicle using the given VIN.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param vin The VIN for the vehicle to operate on.
* @param documentId New PersonId for the primary owner.
* @returns Promise which fulfills with void.
*/
async function updateVehicleRegistration(txn: TransactionExecutor, vin: string, documentId: string): Promise {
const statement: string = "UPDATE VehicleRegistration AS r SET r.Owners.PrimaryOwner.PersonId = ? WHERE r.VIN = ?";
log(`Updating the primary owner for vehicle with VIN: ${vin}...`);
await txn.execute(statement, documentId, vin).then((result: Result) => {
const resultList: dom.Value[] = result.getResultList();
if (resultList.length === 0) {
throw new Error("Unable to transfer vehicle, could not find registration.");
}
log(`Successfully transferred vehicle with VIN ${vin} to new owner.`);
});
}
/**
* Validate the current owner of the given vehicle and transfer its ownership to a new owner in a single transaction.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param vin The VIN of the vehicle to transfer ownership of.
* @param currentOwner The GovId of the current owner of the vehicle.
* @param newOwner The GovId of the new owner of the vehicle.
*/
export async function validateAndUpdateRegistration(
txn: TransactionExecutor,
vin: string,
currentOwner: string,
newOwner: string
): Promise {
const primaryOwner: dom.Value = await findPrimaryOwnerForVehicle(txn, vin);
const govIdValue: dom.Value = primaryOwner.get("GovId");
if (govIdValue !== null && govIdValue.stringValue() !== currentOwner) {
log("Incorrect primary owner identified for vehicle, unable to transfer.");
}
else {
const documentId: string = await getDocumentId(txn, PERSON_TABLE_NAME, "GovId", newOwner);
await updateVehicleRegistration(txn, vin, documentId);
log("Successfully transferred vehicle ownership!");
}
}
/**
* Find primary owner for a particular vehicle's VIN.
* Transfer to another primary owner for a particular vehicle's VIN.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbDriver: QldbDriver = getQldbDriver();
const vin: string = VEHICLE[0].VIN;
const previousOwnerGovId: string = PERSON[0].GovId;
const newPrimaryOwnerGovId: string = PERSON[1].GovId;
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
await validateAndUpdateRegistration(txn, vin, previousOwnerGovId, newPrimaryOwnerGovId);
});
} catch (e) {
error(`Unable to connect and run queries: ${e}`);
}
}
if (require.main === module) {
main();
}
```
1. 要运行编译后的程序，请输入以下命令。
```
node dist/TransferVehicleOwnership.js
```
1. 使用以下程序（`AddSecondaryOwner.ts`），将二级车主添加至分类账中带有 VIN `KM8SRDHF6EU074761` 的车辆中。
```
/*
* 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.
*/
import { QldbDriver, Result, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";
import { getQldbDriver } from "./ConnectToLedger";
import { PERSON, VEHICLE_REGISTRATION } from "./model/SampleData";
import { PERSON_TABLE_NAME } from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
import { getDocumentId } from "./qldb/Util";
import { prettyPrintResultList } from "./ScanTable";
/**
* Add a secondary owner into 'VehicleRegistration' table for a particular VIN.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param vin VIN of the vehicle to query.
* @param secondaryOwnerId The secondary owner's person ID.
* @returns Promise which fulfills with void.
*/
export async function addSecondaryOwner(
txn: TransactionExecutor,
vin: string,
secondaryOwnerId: string
): Promise {
log(`Inserting secondary owner for vehicle with VIN: ${vin}`);
const query: string =
`FROM VehicleRegistration AS v WHERE v.VIN = ? INSERT INTO v.Owners.SecondaryOwners VALUE ?`;
const personToInsert = {PersonId: secondaryOwnerId};
await txn.execute(query, vin, personToInsert).then(async (result: Result) => {
const resultList: dom.Value[] = result.getResultList();
log("VehicleRegistration Document IDs which had secondary owners added: ");
prettyPrintResultList(resultList);
});
}
/**
* Query for a document ID with a government ID.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param governmentId The government ID to query with.
* @returns Promise which fulfills with the document ID as a string.
*/
export async function getDocumentIdByGovId(txn: TransactionExecutor, governmentId: string): Promise {
const documentId: string = await getDocumentId(txn, PERSON_TABLE_NAME, "GovId", governmentId);
return documentId;
}
/**
* Check whether a driver has already been registered for the given VIN.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param vin VIN of the vehicle to query.
* @param secondaryOwnerId The secondary owner's person ID.
* @returns Promise which fulfills with a boolean.
*/
export async function isSecondaryOwnerForVehicle(
txn: TransactionExecutor,
vin: string,
secondaryOwnerId: string
): Promise {
log(`Finding secondary owners for vehicle with VIN: ${vin}`);
const query: string = "SELECT Owners.SecondaryOwners FROM VehicleRegistration AS v WHERE v.VIN = ?";
let doesExist: boolean = false;
await txn.execute(query, vin).then((result: Result) => {
const resultList: dom.Value[] = result.getResultList();
resultList.forEach((value: dom.Value) => {
const secondaryOwnersList: dom.Value[] = value.get("SecondaryOwners").elements();
secondaryOwnersList.forEach((secondaryOwner) => {
const personId: dom.Value = secondaryOwner.get("PersonId");
if (personId !== null && personId.stringValue() === secondaryOwnerId) {
doesExist = true;
}
});
});
});
return doesExist;
}
/**
* Finds and adds secondary owners for a vehicle.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbDriver: QldbDriver = getQldbDriver();
const vin: string = VEHICLE_REGISTRATION[1].VIN;
const govId: string = PERSON[0].GovId;
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
const documentId: string = await getDocumentIdByGovId(txn, govId);
if (await isSecondaryOwnerForVehicle(txn, vin, documentId)) {
log(`Person with ID ${documentId} has already been added as a secondary owner of this vehicle.`);
} else {
await addSecondaryOwner(txn, vin, documentId);
}
});
log("Secondary owners successfully updated.");
} catch (e) {
error(`Unable to add secondary owner: ${e}`);
}
}
if (require.main === module) {
main();
}
```
1. 要运行编译后的程序，请输入以下命令。
```
node dist/AddSecondaryOwner.js
```
若要查看 `vehicle-registration` 分类账中的这些更改，请参阅[步骤 6：查看文档修订历史记录](getting-started.nodejs.step-6.md)。
# 步骤 6：查看文档修订历史记录
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在[上一步](getting-started.nodejs.step-5.md)中修改车辆注册数据后，您可查询其所有注册车主的历史记录以及任何其他更新的字段。在此步骤中，您将在 `vehicle-registration` 分类账的 `VehicleRegistration` 表格中查询文档的修订历史记录。
**若要查看修订历史记录**
1. 编译并运行 `QueryHistory.ts` 程序，以使用 VIN `1N4AL11D75C109151`查询`VehicleRegistration`文档的修订历史记录。
```
/*
* 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.
*/
import { QldbDriver, Result, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";
import { getQldbDriver } from "./ConnectToLedger";
import { VEHICLE_REGISTRATION } from "./model/SampleData";
import { VEHICLE_REGISTRATION_TABLE_NAME } from "./qldb/Constants";
import { prettyPrintResultList } from "./ScanTable";
import { error, log } from "./qldb/LogUtil";
import { getDocumentId } from "./qldb/Util";
/**
* Find previous primary owners for the given VIN in a single transaction.
* @param txn The {@linkcode TransactionExecutor} for lambda execute.
* @param vin The VIN to find previous primary owners for.
* @returns Promise which fulfills with void.
*/
async function previousPrimaryOwners(txn: TransactionExecutor, vin: string): Promise {
const documentId: string = await getDocumentId(txn, VEHICLE_REGISTRATION_TABLE_NAME, "VIN", vin);
const todaysDate: Date = new Date();
// set todaysDate back one minute to ensure end time is in the past
// by the time the request reaches our backend
todaysDate.setMinutes(todaysDate.getMinutes() - 1);
const threeMonthsAgo: Date = new Date(todaysDate);
threeMonthsAgo.setMonth(todaysDate.getMonth() - 3);
const query: string =
`SELECT data.Owners.PrimaryOwner, metadata.version FROM history ` +
`(${VEHICLE_REGISTRATION_TABLE_NAME}, \`${threeMonthsAgo.toISOString()}\`, \`${todaysDate.toISOString()}\`) ` +
`AS h WHERE h.metadata.id = ?`;
await txn.execute(query, documentId).then((result: Result) => {
log(`Querying the 'VehicleRegistration' table's history using VIN: ${vin}.`);
const resultList: dom.Value[] = result.getResultList();
prettyPrintResultList(resultList);
});
}
/**
* Query a table's history for a particular set of documents.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbDriver: QldbDriver = getQldbDriver();
const vin: string = VEHICLE_REGISTRATION[0].VIN;
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
await previousPrimaryOwners(txn, vin);
});
} catch (e) {
error(`Unable to query history to find previous owners: ${e}`);
}
}
if (require.main === module) {
main();
}
```
**注意**
您可以通过以下语法查询内置版本[历史记录函数](working.history.md#working.history.function)，以查看文档的修订历史记录。
```
SELECT * FROM history( table_name [, `start-time` [, `end-time` ] ] ) AS h
[ WHERE h.metadata.id = 'id' ]
```
*开始时间*和*结束时间*均为可选。它们是 Amazon Ion 的字面值，可以用反引号（``...``）表示。有关更多信息，请参阅 [在 Amazon QLDB 中使用 PartiQL 查询 Ion](ql-reference.query.md)。
最佳做法是，使用日期范围（*开始时间* 和 *结束时间*）和文档 ID（`metadata.id`）来限定历史记录查询。QLDB 处理事务中的`SELECT`查询，这些查询受[事务超时限制](limits.md#limits.fixed)的约束。
QLDB 历史记录按文档 ID 编制索引，目前无法创建其他历史索引。包含开始时间和结束时间的历史记录查询将从日期范围限定中获得便利。
1. 要运行编译后的程序，请输入以下命令。
```
node dist/QueryHistory.js
```
要以加密方式验证 `vehicle-registration` 分类账中的文档修订版，请继续 [第 7 步：验证分类账中的文档](getting-started.nodejs.step-7.md)。
# 第 7 步：验证分类账中的文档
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
借助 Amazon QLDB，您可在 SHA-256 中使用加密哈希，从而有效地验证分类账日记账中文档的完整性。要详细了解验证和加密哈希在 QLDB 中的工作原理，请参阅 [Amazon QLDB 中的数据验证](verification.md)。
在此步骤中，您将验证 `vehicle-registration` 分类账 `VehicleRegistration` 表格中的单据修订版本。首先，您请求一份摘要，该摘要作为输出文件返回，并作为分类账整个变更历史记录的签名。然后，您要求提供与此摘要相关的修订证明。使用此证明，如果所有验证检查都可通过，可以验证修订版的完整性。
**验证文档的修订版**
1. 查看以下 `.ts` 文件，其中包含验证所需的 QLDB 对象。
1. `BlockAddress.ts`
```
/*
* 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.
*/
import { ValueHolder } from "aws-sdk/clients/qldb";
import { dom, IonTypes } from "ion-js";
export class BlockAddress {
_strandId: string;
_sequenceNo: number;
constructor(strandId: string, sequenceNo: number) {
this._strandId = strandId;
this._sequenceNo = sequenceNo;
}
}
/**
* Convert a block address from an Ion value into a ValueHolder.
* Shape of the ValueHolder must be: {'IonText': "{strandId: <"strandId">, sequenceNo: }"}
* @param value The Ion value that contains the block address values to convert.
* @returns The ValueHolder that contains the strandId and sequenceNo.
*/
export function blockAddressToValueHolder(value: dom.Value): ValueHolder {
const blockAddressValue : dom.Value = getBlockAddressValue(value);
const strandId: string = getStrandId(blockAddressValue);
const sequenceNo: number = getSequenceNo(blockAddressValue);
const valueHolder: string = `{strandId: "${strandId}", sequenceNo: ${sequenceNo}}`;
const blockAddress: ValueHolder = {IonText: valueHolder};
return blockAddress;
}
/**
* Helper method that to get the Metadata ID.
* @param value The Ion value.
* @returns The Metadata ID.
*/
export function getMetadataId(value: dom.Value): string {
const metaDataId: dom.Value = value.get("id");
if (metaDataId === null) {
throw new Error(`Expected field name id, but not found.`);
}
return metaDataId.stringValue();
}
/**
* Helper method to get the Sequence No.
* @param value The Ion value.
* @returns The Sequence No.
*/
export function getSequenceNo(value : dom.Value): number {
const sequenceNo: dom.Value = value.get("sequenceNo");
if (sequenceNo === null) {
throw new Error(`Expected field name sequenceNo, but not found.`);
}
return sequenceNo.numberValue();
}
/**
* Helper method to get the Strand ID.
* @param value The Ion value.
* @returns The Strand ID.
*/
export function getStrandId(value: dom.Value): string {
const strandId: dom.Value = value.get("strandId");
if (strandId === null) {
throw new Error(`Expected field name strandId, but not found.`);
}
return strandId.stringValue();
}
export function getBlockAddressValue(value: dom.Value) : dom.Value {
const type = value.getType();
if (type !== IonTypes.STRUCT) {
throw new Error(`Unexpected format: expected struct, but got IonType: ${type.name}`);
}
const blockAddress: dom.Value = value.get("blockAddress");
if (blockAddress == null) {
throw new Error(`Expected field name blockAddress, but not found.`);
}
return blockAddress;
}
```
1. `Verifier.ts`
```
/*
* 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.
*/
import { Digest, ValueHolder } from "aws-sdk/clients/qldb";
import { createHash } from "crypto";
import { dom, toBase64 } from "ion-js";
import { getBlobValue } from "./Util";
const HASH_LENGTH: number = 32;
const UPPER_BOUND: number = 8;
/**
* Build the candidate digest representing the entire ledger from the Proof hashes.
* @param proof The Proof object.
* @param leafHash The revision hash to pair with the first hash in the Proof hashes list.
* @returns The calculated root hash.
*/
function buildCandidateDigest(proof: ValueHolder, leafHash: Uint8Array): Uint8Array {
const parsedProof: Uint8Array[] = parseProof(proof);
const rootHash: Uint8Array = calculateRootHashFromInternalHash(parsedProof, leafHash);
return rootHash;
}
/**
* Combine the internal hashes and the leaf hash until only one root hash remains.
* @param internalHashes An array of hash values.
* @param leafHash The revision hash to pair with the first hash in the Proof hashes list.
* @returns The root hash constructed by combining internal hashes.
*/
function calculateRootHashFromInternalHash(internalHashes: Uint8Array[], leafHash: Uint8Array): Uint8Array {
const rootHash: Uint8Array = internalHashes.reduce(joinHashesPairwise, leafHash);
return rootHash;
}
/**
* Compare two hash values by converting each Uint8Array byte, which is unsigned by default,
* into a signed byte, assuming they are little endian.
* @param hash1 The hash value to compare.
* @param hash2 The hash value to compare.
* @returns Zero if the hash values are equal, otherwise return the difference of the first pair of non-matching bytes.
*/
function compareHashValues(hash1: Uint8Array, hash2: Uint8Array): number {
if (hash1.length !== HASH_LENGTH || hash2.length !== HASH_LENGTH) {
throw new Error("Invalid hash.");
}
for (let i = hash1.length-1; i >= 0; i--) {
const difference: number = (hash1[i]<<24 >>24) - (hash2[i]<<24 >>24);
if (difference !== 0) {
return difference;
}
}
return 0;
}
/**
* Helper method that concatenates two Uint8Array.
* @param arrays List of array to concatenate, in the order provided.
* @returns The concatenated array.
*/
function concatenate(...arrays: Uint8Array[]): Uint8Array {
let totalLength = 0;
for (const arr of arrays) {
totalLength += arr.length;
}
const result = new Uint8Array(totalLength);
let offset = 0;
for (const arr of arrays) {
result.set(arr, offset);
offset += arr.length;
}
return result;
}
/**
* Flip a single random bit in the given hash value.
* This method is intended to be used for purpose of demonstrating the QLDB verification features only.
* @param original The hash value to alter.
* @returns The altered hash with a single random bit changed.
*/
export function flipRandomBit(original: any): Uint8Array {
if (original.length === 0) {
throw new Error("Array cannot be empty!");
}
const bytePos: number = Math.floor(Math.random() * original.length);
const bitShift: number = Math.floor(Math.random() * UPPER_BOUND);
const alteredHash: Uint8Array = original;
alteredHash[bytePos] = alteredHash[bytePos] ^ (1 << bitShift);
return alteredHash;
}
/**
* Take two hash values, sort them, concatenate them, and generate a new hash value from the concatenated values.
* @param h1 Byte array containing one of the hashes to compare.
* @param h2 Byte array containing one of the hashes to compare.
* @returns The concatenated array of hashes.
*/
export function joinHashesPairwise(h1: Uint8Array, h2: Uint8Array): Uint8Array {
if (h1.length === 0) {
return h2;
}
if (h2.length === 0) {
return h1;
}
let concat: Uint8Array;
if (compareHashValues(h1, h2) < 0) {
concat = concatenate(h1, h2);
} else {
concat = concatenate(h2, h1);
}
const hash = createHash('sha256');
hash.update(concat);
const newDigest: Uint8Array = hash.digest();
return newDigest;
}
/**
* Parse the Block object returned by QLDB and retrieve block hash.
* @param valueHolder A structure containing an Ion string value.
* @returns The block hash.
*/
export function parseBlock(valueHolder: ValueHolder): Uint8Array {
const block: dom.Value = dom.load(valueHolder.IonText);
const blockHash: Uint8Array = getBlobValue(block, "blockHash");
return blockHash;
}
/**
* Parse the Proof object returned by QLDB into an iterator.
* The Proof object returned by QLDB is a dictionary like the following:
* {'IonText': '[{{}},{{}}]'}
* @param valueHolder A structure containing an Ion string value.
* @returns A list of hash values.
*/
function parseProof(valueHolder: ValueHolder): Uint8Array[] {
const proofs : dom.Value = dom.load(valueHolder.IonText);
return proofs.elements().map(proof => proof.uInt8ArrayValue());
}
/**
* Verify document revision against the provided digest.
* @param documentHash The SHA-256 value representing the document revision to be verified.
* @param digest The SHA-256 hash value representing the ledger digest.
* @param proof The Proof object retrieved from GetRevision.getRevision.
* @returns If the document revision verifies against the ledger digest.
*/
export function verifyDocument(documentHash: Uint8Array, digest: Digest, proof: ValueHolder): boolean {
const candidateDigest = buildCandidateDigest(proof, documentHash);
return (toBase64( digest) === toBase64(candidateDigest));
}
```
1. 使用两个`.ts`程序（`GetDigest.ts`和`GetRevision.ts`）执行以下步骤：
+ 从 `vehicle-registration` 分类账中请求新摘要。
+ 通过 `VehicleRegistration` 表的 VIN `1N4AL11D75C109151`，索取每份文件修订版的证明。
+ 通过重新计算摘要，使用返回的摘要来验证修订版。
`GetDigest.ts` 文件包含以下代码。
```
/*
* 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.
*/
import { QLDB } from "aws-sdk";
import { GetDigestRequest, GetDigestResponse } from "aws-sdk/clients/qldb";
import { LEDGER_NAME } from "./qldb/Constants";
import { error, log } from "./qldb/LogUtil";
import { digestResponseToString } from "./qldb/Util";
/**
* Get the digest of a ledger's journal.
* @param ledgerName Name of the ledger to operate on.
* @param qldbClient The QLDB control plane client to use.
* @returns Promise which fulfills with a GetDigestResponse.
*/
export async function getDigestResult(ledgerName: string, qldbClient: QLDB): Promise {
const request: GetDigestRequest = {
Name: ledgerName
};
const result: GetDigestResponse = await qldbClient.getDigest(request).promise();
return result;
}
/**
* This is an example for retrieving the digest of a particular ledger.
* @returns Promise which fulfills with void.
*/
const main = async function(): Promise {
try {
const qldbClient: QLDB = new QLDB();
log(`Retrieving the current digest for ledger: ${LEDGER_NAME}.`);
const digest: GetDigestResponse = await getDigestResult(LEDGER_NAME, qldbClient);
log(`Success. Ledger digest: \n${digestResponseToString(digest)}.`);
} catch (e) {
error(`Unable to get a ledger digest: ${e}`);
}
}
if (require.main === module) {
main();
}
```
**注意**
使用该 `getDigest` 方法请求一份涵盖分类账中日记账当前*提示*的摘要。日记账的提示指的是 QLDB 收到您的请求时的最近提交的数据块。
`GetRevision.ts` 文件包含以下代码。
```
/*
* 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.
*/
import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { QLDB } from "aws-sdk";
import { Digest, GetDigestResponse, GetRevisionRequest, GetRevisionResponse, ValueHolder } from "aws-sdk/clients/qldb";
import { dom, toBase64 } from "ion-js";
import { getQldbDriver } from "./ConnectToLedger";
import { getDigestResult } from './GetDigest';
import { VEHICLE_REGISTRATION } from "./model/SampleData"
import { blockAddressToValueHolder, getMetadataId } from './qldb/BlockAddress';
import { LEDGER_NAME } from './qldb/Constants';
import { error, log } from "./qldb/LogUtil";
import { getBlobValue, valueHolderToString } from "./qldb/Util";
import { flipRandomBit, verifyDocument } from "./qldb/Verifier";
/**
* Get the revision data object for a specified document ID and block address.
* Also returns a proof of the specified revision for verification.
* @param ledgerName Name of the ledger containing the document to query.
* @param documentId Unique ID for the document to be verified, contained in the committed view of the document.
* @param blockAddress The location of the block to request.
* @param digestTipAddress The latest block location covered by the digest.
* @param qldbClient The QLDB control plane client to use.
* @returns Promise which fulfills with a GetRevisionResponse.
*/
async function getRevision(
ledgerName: string,
documentId: string,
blockAddress: ValueHolder,
digestTipAddress: ValueHolder,
qldbClient: QLDB
): Promise