先决条件步骤 1：设置您的项目第 2 步：初始化驱动程序第 3 步：创建表和索引第 4 步：插入文档第 5 步：查询文档第 6 步：更新文档运行完整的应用程序

适用于 Java 的 Amazon QLDB 驱动程序 — 快速入门教程

重要

终止支持通知：现有客户将能够使用亚马逊，QLDB直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅将亚马逊QLDB账本迁移到亚马逊 Aurora Postgr SQL e。

在本教程中，您将学习如何使用最新版本的 Amazon Java QLDB 驱动程序设置简单的应用程序。本指南包括安装驱动程序的步骤以及基本创建、读取、更新和删除 (CRUD) 操作的简短代码示例。有关在完整示例应用程序中演示这些操作的更深入的示例，请参阅 Java 教程。

先决条件

在开始之前，请务必执行以下操作：

请为 Java 驱动程序完成（先决条件如果尚未执行此操作）。这包括注册 AWS、授予开发所需的编程访问权限以及安装 Java 集成开发环境 (IDE)。
创建一个名为 quick-start 分类账。

要了解如何创建分类账，请参阅控制台入门中的 Amazon QLDB 账本的基本操作或第 1 步：创建新的分类账。

步骤 1：设置您的项目

首先，您需要设置您的 Java 项目。我们建议在本教程中使用 Maven 依赖项管理系统。

注意

如果您使用IDE具有自动执行这些设置步骤的功能，则可以直接跳到第 2 步：初始化驱动程序。

为应用程序创建一个文件夹。
```
$ mkdir myproject
$ cd myproject
```
输入以下命令从 Maven 模板初始化项目。Replace（替换） project-package, project-name，以及 maven-template 酌情使用你自己的价值观。
```
$ mvn archetype:generate
  -DgroupId=project-package \
  -DartifactId=project-name \
  -DarchetypeArtifactId=maven-template \
  -DinteractiveMode=false
```
对于 maven-template，你可以使用基本的 Maven 模板：maven-archetype-quickstart

要将 Java 的QLDB驱动程序添加为项目依赖项，请导航到新创建pom.xml的文件并添加以下构件。


<dependency>
    <groupId>software.amazon.qldb</groupId>
    <artifactId>amazon-qldb-driver-java</artifactId>
    <version>2.3.1</version>
</dependency>

此构件自动包含 AWS SDK for Java 2.x 核心模块、Amazon Ion 库和其他必需的依赖项。您的 pom.xml 文件应类似于如下所示：


<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>software.amazon.qldb</groupId>
  <artifactId>qldb-quickstart</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>qldb-quickstart</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>software.amazon.qldb</groupId>
        <artifactId>amazon-qldb-driver-java</artifactId>
        <version>2.3.1</version>
    </dependency>
  </dependencies>
</project>

打开 App.java文件。

然后，按以下步骤逐步添加代码示例，尝试一些基本CRUD操作。或者，您可以跳过本 step-by-step 教程，改为运行完整的应用程序。

第 2 步：初始化驱动程序

初始化连接到名为 quick-start 的分类账的驱动程序实例。将以下代码添加到您的 App.java文件。


import java.util.*;
import com.amazon.ion.*;
import com.amazon.ion.system.*;
import software.amazon.awssdk.services.qldbsession.QldbSessionClient;
import software.amazon.qldb.*;

public final class App {
    public static IonSystem ionSys = IonSystemBuilder.standard().build();
    public static QldbDriver qldbDriver;

    public static void main(final String... args) {
        System.out.println("Initializing the driver");
        qldbDriver = QldbDriver.builder()
            .ledger("quick-start")
            .transactionRetryPolicy(RetryPolicy
                .builder()
                .maxRetries(3)
                .build())
            .sessionClientBuilder(QldbSessionClient.builder())
            .build();
    }
}

第 3 步：创建表和索引

以下代码示例显示如何运行 CREATE TABLE 和 CREATE INDEX。

在 main 方法中，添加以下代码，创建名为 People 的表以及该表上的 lastName 字段的索引。索引是优化查询性能和帮助限制乐观并发控制 (OCC) 冲突异常所必需的。


// Create a table and an index in the same transaction
qldbDriver.execute(txn -> {
    System.out.println("Creating a table and an index");
    txn.execute("CREATE TABLE People");
    txn.execute("CREATE INDEX ON People(lastName)");
});

第 4 步：插入文档

以下代码示例显示如何运行 INSERT 语句。QLDB支持 P artiQL 查询语言（SQL兼容）和 A mazon Ion 数据格式（的超集）。JSON

添加以下代码，在 People 表格中插入文档。


// Insert a document
qldbDriver.execute(txn -> {
    System.out.println("Inserting a document");
    IonStruct person = ionSys.newEmptyStruct();
    person.put("firstName").newString("John");
    person.put("lastName").newString("Doe");
    person.put("age").newInt(32);
    txn.execute("INSERT INTO People ?", person);
});

此示例使用问号（?）作为变量占位符，将文档信息传递给语句。使用占位符时，必须传递一个 IonValue 类型的值。

提示

要使用单个INSERT语句插入多个文档，可以向该语句传递一个类型的参数 IonList（显式转换为IonValue），如下所示。


// people is an IonList explicitly cast as an IonValue
txn.execute("INSERT INTO People ?", (IonValue) people);

传递 IonList 列表时，不要将变量占位符（?）包括在双尖括号（ <<...>> ）内。在手动 PartiQL 语句中，双尖括号表示名为bag的无序集合。

第 5 步：查询文档

以下代码示例显示如何运行 SELECT 语句。

添加以下代码，用于从 People 表格中查询文档。


// Query the document
qldbDriver.execute(txn -> {
    System.out.println("Querying the table");
    Result result = txn.execute("SELECT * FROM People WHERE lastName = ?",
            ionSys.newString("Doe"));
    IonStruct person = (IonStruct) result.iterator().next();
    System.out.println(person.get("firstName")); // prints John
    System.out.println(person.get("lastName")); // prints Doe
    System.out.println(person.get("age")); // prints 32
});

第 6 步：更新文档

以下代码示例显示如何运行 UPDATE 语句。

添加以下代码，通过更新 age 到 42 来更新 People 表中的文档。


// Update the document
qldbDriver.execute(txn -> {
    System.out.println("Updating the document");
    final List<IonValue> parameters = new ArrayList<>();
    parameters.add(ionSys.newInt(42));
    parameters.add(ionSys.newString("Doe"));
    txn.execute("UPDATE People SET age = ? WHERE lastName = ?", parameters);
});

再次查询文档以查看更新的值。


// Query the updated document
qldbDriver.execute(txn -> {
    System.out.println("Querying the table for the updated document");
    Result result = txn.execute("SELECT * FROM People WHERE lastName = ?",
            ionSys.newString("Doe"));
    IonStruct person = (IonStruct) result.iterator().next();
    System.out.println(person.get("firstName")); // prints John
    System.out.println(person.get("lastName")); // prints Doe
    System.out.println(person.get("age")); // prints 32
});

使用 Maven 或你的IDE来编译并运行该App.java文件。

运行完整的应用程序

以下代码示例是 App.java 应用程序的完整版本。您还可以从头到尾复制并运行此代码示例，而不必单独执行前面的步骤。此应用程序演示了对名为的账本的一些基本CRUD操作quick-start。

注意

在运行此代码之前，请确保 quick-start 分类账中还没有名为 People 的活动表。

在第一行，替换 project-package 其中包含你在 Maven 命令中步骤 1：设置您的项目使用的groupId值。


package project-package;

import java.util.*;
import com.amazon.ion.*;
import com.amazon.ion.system.*;
import software.amazon.awssdk.services.qldbsession.QldbSessionClient;
import software.amazon.qldb.*;

public class App {
    public static IonSystem ionSys = IonSystemBuilder.standard().build();
    public static QldbDriver qldbDriver;

    public static void main(final String... args) {
        System.out.println("Initializing the driver");
        qldbDriver = QldbDriver.builder()
            .ledger("quick-start")
            .transactionRetryPolicy(RetryPolicy
                .builder()
                .maxRetries(3)
                .build())
            .sessionClientBuilder(QldbSessionClient.builder())
            .build();

        // Create a table and an index in the same transaction
        qldbDriver.execute(txn -> {
            System.out.println("Creating a table and an index");
            txn.execute("CREATE TABLE People");
            txn.execute("CREATE INDEX ON People(lastName)");
        });
        
        // Insert a document
        qldbDriver.execute(txn -> {
            System.out.println("Inserting a document");
            IonStruct person = ionSys.newEmptyStruct();
            person.put("firstName").newString("John");
            person.put("lastName").newString("Doe");
            person.put("age").newInt(32);
            txn.execute("INSERT INTO People ?", person);
        });
        
        // Query the document
        qldbDriver.execute(txn -> {
            System.out.println("Querying the table");
            Result result = txn.execute("SELECT * FROM People WHERE lastName = ?",
                    ionSys.newString("Doe"));
            IonStruct person = (IonStruct) result.iterator().next();
            System.out.println(person.get("firstName")); // prints John
            System.out.println(person.get("lastName")); // prints Doe
            System.out.println(person.get("age")); // prints 32
        });
        
        // Update the document
        qldbDriver.execute(txn -> {
            System.out.println("Updating the document");
            final List<IonValue> parameters = new ArrayList<>();
            parameters.add(ionSys.newInt(42));
            parameters.add(ionSys.newString("Doe"));
            txn.execute("UPDATE People SET age = ? WHERE lastName = ?", parameters);
        });
        
        // Query the updated document
        qldbDriver.execute(txn -> {
            System.out.println("Querying the table for the updated document");
            Result result = txn.execute("SELECT * FROM People WHERE lastName = ?",
                    ionSys.newString("Doe"));
            IonStruct person = (IonStruct) result.iterator().next();
            System.out.println(person.get("firstName")); // prints John
            System.out.println(person.get("lastName")); // prints Doe
            System.out.println(person.get("age")); // prints 42
        });
    }
}

使用 Maven 或你的IDE来编译并运行该App.java文件。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

Java 驱动程序

说明书参考