本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 適用於 Java 的 Amazon QLDB 驅動程式 – 快速入門教學課程
<a name="driver-quickstart-java"></a>

**重要**  
支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。

在本教學課程中，您將了解如何使用適用於 Java 的最新版本 Amazon QLDB 驅動程式來設定簡單的應用程式。本指南包含安裝驅動程式的步驟，以及基本*建立、讀取、更新和刪除* (CRUD) 操作的簡短程式碼範例。如需在完整範例應用程式中示範這些操作的更深入範例，請參閱 [Java 教學課程](getting-started.java.tutorial.md)。

**Topics**
+ [先決條件](#driver-quickstart-java.prereqs)
+ [步驟 1：設定您的 專案](#driver-quickstart-java.step-1)
+ [步驟 2：初始化驅動程式](#driver-quickstart-java.step-2)
+ [步驟 3：建立資料表和索引](#driver-quickstart-java.step-3)
+ [步驟 4：插入文件](#driver-quickstart-java.step-4)
+ [步驟 5：查詢文件](#driver-quickstart-java.step-5)
+ [步驟 6：更新文件](#driver-quickstart-java.step-6)
+ [執行完整的應用程式](#driver-quickstart-java.complete)

## 先決條件
<a name="driver-quickstart-java.prereqs"></a>

開始之前，請務必執行下列動作：

1. 如果您尚未執行此操作，請完成 Java 驅動程式[先決條件](getting-started.java.md#getting-started.java.prereqs)的 。這包括註冊 AWS、授予開發的程式設計存取權，以及安裝 Java 整合開發環境 (IDE)。

1. 建立名為 的分類帳`quick-start`。

   若要了解如何建立分類帳，請參閱 主控台入門[步驟 1：建立新的分類帳](getting-started-step-1.md)中的 [Amazon QLDB 分類帳的基本操作](ledger-management.basics.md)或 。 **

## 步驟 1：設定您的 專案
<a name="driver-quickstart-java.step-1"></a>

首先，設定您的 Java 專案。建議您在本教學課程中使用 [Maven](https://maven.apache.org/index.html) 相依性管理系統。

**注意**  
如果您使用具有自動化這些設定步驟功能的 IDE，您可以直接跳到 [步驟 2：初始化驅動程式](#driver-quickstart-java.step-2)。

1. 為您的應用程式建立資料夾。

   ```
   $ mkdir myproject
   $ cd myproject
   ```

1. 輸入下列命令，從 Maven 範本初始化您的專案。視需要將 *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`

1. 若要將適用於 [Java 的 QLDB 驅動程式](https://search.maven.org/artifact/software.amazon.qldb/amazon-qldb-driver-java/2.3.1/jar)新增為專案相依性，請導覽至新建立`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](https://aws.amazon.com/sdk-for-java)核心模組、[Amazon Ion](ion.md) 程式庫和其他必要的相依性。您的`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>
   ```

1. 開啟 `App.java` 檔案。

   然後，在下列步驟中逐步新增程式碼範例，以嘗試一些基本的 CRUD 操作。或者，您可以略過step-by-step教學課程，改為執行[完整的應用程式](#driver-quickstart-java.complete)。

## 步驟 2：初始化驅動程式
<a name="driver-quickstart-java.step-2"></a>

初始化連接至名為 之分類帳的驅動程式執行個體`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：建立資料表和索引
<a name="driver-quickstart-java.step-3"></a>

下列程式碼範例示範如何執行 `CREATE TABLE`和 `CREATE INDEX`陳述式。

在 `main`方法中，新增下列程式碼，為該資料表上的 `lastName` 欄位建立名為 的資料表`People`和索引。需要[索引](ql-reference.create-index.md)才能最佳化查詢效能，並協助限制[樂觀並行控制 (OCC)](concurrency.md) 衝突例外狀況。

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

## 步驟 4：插入文件
<a name="driver-quickstart-java.step-4"></a>

下列程式碼範例示範如何執行 `INSERT`陳述式。QLDB 支援 [PartiQL](ql-reference.md) 查詢語言 (SQL 相容） 和 [Amazon Ion](ion.md) 資料格式 (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](ql-reference.insert.md)陳述式插入多個文件，您可以將 [IonList](driver-working-with-ion.md#driver-ion-list) 類型的參數 （明確轉換為 `IonValue`) 傳遞至陳述式，如下所示。  

```
// people is an IonList explicitly cast as an IonValue
txn.execute("INSERT INTO People ?", (IonValue) people);
```
傳遞 時，您不會將變數預留位置 (`?`) 括在雙角度括號 `<<...>>` ( ) 中`IonList`。在手動 PartiQL 陳述式中，雙角括號表示稱為*包*的未排序集合。

## 步驟 5：查詢文件
<a name="driver-quickstart-java.step-5"></a>

下列程式碼範例示範如何執行 `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：更新文件
<a name="driver-quickstart-java.step-6"></a>

下列程式碼範例示範如何執行 `UPDATE`陳述式。

1. 新增下列程式碼，透過更新`age`至 來更新`People`資料表中的文件`42`。

   ```
   // 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);
   });
   ```

1. 再次查詢文件以查看更新的值。

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

1. 使用 Maven 或您的 IDE 來編譯和執行 `App.java` 檔案。

## 執行完整的應用程式
<a name="driver-quickstart-java.complete"></a>

下列程式碼範例是`App.java`應用程式的完整版本。您也可以從頭到尾複製並執行此程式碼範例，而不是個別執行上述步驟。此應用程式會在名為 的分類帳上示範一些基本 CRUD 操作`quick-start`。

**注意**  
在您執行此程式碼之前，請確定您尚未在分類帳`People`中擁有名為 `quick-start` 的作用中資料表。  
在第一行，將 *project-package* 取代為您在 中用於 Maven 命令`groupId`的值[步驟 1：設定您的 專案](#driver-quickstart-java.step-1)。

```
package project-package;

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

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

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

        // Create a table and an index in the same transaction
        qldbDriver.execute(txn -> {
            System.out.println("Creating a table and an index");
            txn.execute("CREATE TABLE People");
            txn.execute("CREATE INDEX ON People(lastName)");
        });
        
        // Insert a document
        qldbDriver.execute(txn -> {
            System.out.println("Inserting a document");
            IonStruct person = ionSys.newEmptyStruct();
            person.put("firstName").newString("John");
            person.put("lastName").newString("Doe");
            person.put("age").newInt(32);
            txn.execute("INSERT INTO People ?", person);
        });
        
        // Query the document
        qldbDriver.execute(txn -> {
            System.out.println("Querying the table");
            Result result = txn.execute("SELECT * FROM People WHERE lastName = ?",
                    ionSys.newString("Doe"));
            IonStruct person = (IonStruct) result.iterator().next();
            System.out.println(person.get("firstName")); // prints John
            System.out.println(person.get("lastName")); // prints Doe
            System.out.println(person.get("age")); // prints 32
        });
        
        // Update the document
        qldbDriver.execute(txn -> {
            System.out.println("Updating the document");
            final List<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` 檔案。