Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# Amazon QLDB-Treiber für Java
**Wichtig**
Hinweis zum Ende des Supports: Bestandskunden können Amazon QLDB bis zum Ende des Supports am 31.07.2025 nutzen. Weitere Informationen finden Sie unter [Migrieren eines Amazon QLDB-Ledgers zu Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL.
Um mit Daten in Ihrem Ledger zu arbeiten, können Sie von Ihrer Java-Anwendung aus mithilfe eines bereitgestellten Treibers eine AWS Verbindung zu Amazon QLDB herstellen. In den folgenden Themen werden die ersten Schritte mit dem QLDB-Treiber für Java beschrieben.
**Topics**
+ [Ressourcen für Treiber](#getting-started.java.resources)
+ [Voraussetzungen](#getting-started.java.prereqs)
+ [Einstellung Ihrer AWS Standardanmeldedaten und Region](#getting-started.java.credentials)
+ [Installation](#getting-started.java.install)
+ [Schnellstart-Tutorial](driver-quickstart-java.md)
+ [Referenz zum Kochbuch](driver-cookbook-java.md)
## Ressourcen für Treiber
Weitere Informationen zu den vom Java-Treiber unterstützten Funktionen finden Sie in den folgenden Ressourcen:
+ [API-Referenz: [2.x, 1.x](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/)](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/1.1.0/index.html)
+ [Treiber-Quellcode () GitHub](https://github.com/awslabs/amazon-qldb-driver-java)
+ [Quellcode einer Beispielanwendung (GitHub)](https://github.com/aws-samples/amazon-qldb-dmv-sample-java)
+ [Ledger Loader-Framework () GitHub](https://github.com/awslabs/amazon-qldb-ledger-load-java)
+ [Beispiele für Amazon Ion-Code](ion.code-examples.md)
## Voraussetzungen
Bevor Sie mit dem QLDB-Treiber für Java beginnen, müssen Sie Folgendes tun:
1. Folgen Sie den Anweisungen zur AWS Einrichtung unter. [Zugreifen auf Amazon QLDB](accessing.md) Diese umfasst die folgenden Funktionen:
1. Melde dich an für AWS.
1. Erstellen Sie einen Benutzer mit den entsprechenden QLDB-Berechtigungen.
1. Gewähren Sie programmatischen Zugriff für die Entwicklung.
1. Richten Sie eine Java-Entwicklungsumgebung ein, indem Sie Folgendes herunterladen und installieren:
1. Java SE Development Kit 8, z. B. [Amazon Corretto](https://docs.aws.amazon.com/corretto/latest/corretto-8-ug/downloads-list.html) 8.
1. (Optional) Integrierte Java-Entwicklungsumgebung (IDE) Ihrer Wahl, wie [Eclipse](http://www.eclipse.org) oder [IntelliJ](https://www.jetbrains.com/idea/).
1. Konfigurieren Sie nebenbei Ihre Entwicklungsumgebung. AWS SDK für Java [Einstellung Ihrer AWS Standardanmeldedaten und Region](#getting-started.java.credentials)
Als Nächstes können Sie die vollständige Beispielanwendung für das Tutorial herunterladen — oder Sie können nur den Treiber in einem Java-Projekt installieren und kurze Codebeispiele ausführen.
+ Um den QLDB-Treiber und den AWS SDK für Java in einem vorhandenen Projekt zu installieren, fahren Sie mit fort. [Installation](#getting-started.java.install)
+ Informationen zum Einrichten eines Projekts und zur Ausführung von kurzen Codebeispielen, die grundlegende Datentransaktionen in einem Ledger demonstrieren, finden Sie unter. [Schnellstart-Tutorial](driver-quickstart-java.md)
+ Ausführlichere Beispiele für Daten- und Verwaltungs-API-Operationen in der vollständigen Beispielanwendung des Tutorials finden Sie unter. [Java-Lernprogramm](getting-started.java.tutorial.md)
## Einstellung Ihrer AWS Standardanmeldedaten und Region
Der QLDB-Treiber und der zugrunde liegende Treiber [AWS SDK für Java](https://aws.amazon.com/sdk-for-java)erfordern, dass Sie zur Laufzeit AWS Anmeldeinformationen für Ihre Anwendung angeben. Bei den Codebeispielen in diesem Handbuch wird davon ausgegangen, dass Sie eine Datei mit AWS Anmeldeinformationen verwenden, wie unter [Standardanmeldedaten und Region festlegen](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html#setup-credentials) im *AWS SDK for Java 2.x Entwicklerhandbuch* beschrieben.
Im Rahmen dieser Schritte sollten Sie auch Ihren Standard festlegen, AWS-Region um Ihren Standard-QLDB-Endpunkt zu bestimmen. Die Codebeispiele stellen in Ihrer Standardeinstellung eine Verbindung zu QLDB her. AWS-Region Eine vollständige Liste der Regionen, in denen QLDB verfügbar ist, finden Sie unter [Amazon QLDB-Endpunkte](https://docs.aws.amazon.com/general/latest/gr/qldb.html) und Kontingente in der. *Allgemeine AWS-Referenz*
Im Folgenden finden Sie ein Beispiel für eine AWS Anmeldeinformationsdatei mit dem Namen`~/.aws/credentials`, wobei das Tilde-Zeichen () `~` für Ihr Home-Verzeichnis steht.
```
[default]
aws_access_key_id = your_access_key_id
aws_secret_access_key = your_secret_access_key
```
Ersetzen Sie die Werte *your\$1access\$1key\$1id* und *your\$1secret\$1access\$1key* durch Ihre eigenen AWS Anmeldeinformationen.
## Installation
QLDB unterstützt die folgenden Java-Treiberversionen und ihre AWS SDK-Abhängigkeiten.
****
| Treiberversion | AWS SDK | Status | Datum der letzten Veröffentlichung |
| --- | --- | --- | --- |
| [1.x](https://search.maven.org/artifact/software.amazon.qldb/amazon-qldb-driver-java/1.1.0/jar) | AWS SDK für Java 1.x | Produktionsfreigabe | 20. März 2020 |
| [2.x](https://search.maven.org/artifact/software.amazon.qldb/amazon-qldb-driver-java/2.3.1/jar) | AWS SDK for Java 2.x | Produktionsfreigabe | 4. Juni 2021 |
Um den QLDB-Treiber zu installieren, empfehlen wir die Verwendung eines Abhängigkeitsverwaltungssystems wie Gradle oder Maven. Fügen Sie beispielsweise das folgende Artefakt als Abhängigkeit in Ihr Java-Projekt ein.
------
#### [ 2.x ]
**Gradle**
Fügen Sie diese Abhängigkeit in Ihre `build.gradle` Konfigurationsdatei ein.
```
dependencies {
compile group: 'software.amazon.qldb', name: 'amazon-qldb-driver-java', version: '2.3.1'
}
```
**Maven**
Fügen Sie diese Abhängigkeit in Ihre `pom.xml` Konfigurationsdatei ein.
```
software.amazon.qldb
amazon-qldb-driver-java
2.3.1
```
Dieses Artefakt beinhaltet automatisch das AWS SDK for Java 2.x Kernmodul, [Amazon Ion-Bibliotheken](ion.md) und andere erforderliche Abhängigkeiten.
------
#### [ 1.x ]
**Gradle**
Fügen Sie diese Abhängigkeit in Ihre `build.gradle` Konfigurationsdatei ein.
```
dependencies {
compile group: 'software.amazon.qldb', name: 'amazon-qldb-driver-java', version: '1.1.0'
}
```
**Maven**
Fügen Sie diese Abhängigkeit in Ihre `pom.xml` Konfigurationsdatei ein.
```
software.amazon.qldb
amazon-qldb-driver-java
1.1.0
```
Dieses Artefakt beinhaltet automatisch das AWS SDK für Java Kernmodul, [Amazon Ion-Bibliotheken](ion.md) und andere erforderliche Abhängigkeiten.
**Wichtig**
**Amazon Ion-Namespace** — Wenn Sie Amazon Ion-Klassen in Ihre Anwendung importieren, müssen Sie das Paket verwenden, das sich unter dem `com.amazon.ion` Namespace befindet. Das AWS SDK für Java hängt von einem anderen Ion-Paket unter dem Namespace ab`software.amazon.ion`, aber das ist ein Legacy-Paket, das nicht mit dem QLDB-Treiber kompatibel ist.
------
Kurze Codebeispiele für die Ausführung grundlegender Datentransaktionen in einem Ledger finden Sie unter. [Referenz zum Kochbuch](driver-cookbook-java.md)
### Andere optionale Bibliotheken
Optional können Sie Ihrem Projekt auch die folgenden nützlichen Bibliotheken hinzufügen. Bei diesen Artefakten handelt es sich um erforderliche Abhängigkeiten in der [Java-Lernprogramm](getting-started.java.tutorial.md) Beispielanwendung.
1. [aws-java-sdk-qldb](https://search.maven.org/artifact/com.amazonaws/aws-java-sdk-qldb/1.11.785/jar)— Das QLDB-Modul des. AWS SDK für Java Die von QLDB unterstützte Mindestversion ist. `1.11.785`
Verwenden Sie dieses Modul in Ihrer Anwendung, um direkt mit den Verwaltungs-API-Vorgängen zu interagieren, die in der aufgeführt sind. [Amazon QLDB API-Referenz](api-reference.md)
1. [jackson-dataformat-ion](https://search.maven.org/artifact/com.fasterxml.jackson.dataformat/jackson-dataformat-ion/2.10.0/bundle)— Das Jackson-Datenformatmodul von FasterXML für Ion. Die Beispielanwendung erfordert Version `2.10.0` oder höher.
------
#### [ Gradle ]
Fügen Sie diese Abhängigkeiten zu Ihrer `build.gradle` Konfigurationsdatei hinzu.
```
dependencies {
compile group: 'com.amazonaws', name: 'aws-java-sdk-qldb', version: '1.11.785'
compile group: 'com.fasterxml.jackson.dataformat', name: 'jackson-dataformat-ion', version: '2.10.0'
}
```
------
#### [ Maven ]
Fügen Sie diese Abhängigkeiten zu Ihrer `pom.xml` Konfigurationsdatei hinzu.
```
com.amazonaws
aws-java-sdk-qldb
1.11.785
com.fasterxml.jackson.dataformat
jackson-dataformat-ion
2.10.0
```
------
# Amazon QLDB-Treiber für Java — Schnellstartanleitung
**Wichtig**
Hinweis zum Ende des Supports: Bestandskunden können Amazon QLDB bis zum Ende des Supports am 31.07.2025 nutzen. Weitere Informationen finden Sie unter [Migrieren eines Amazon QLDB-Ledgers zu Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL.
In diesem Tutorial erfahren Sie, wie Sie eine einfache Anwendung mit der neuesten Version des Amazon QLDB-Treibers für Java einrichten. Dieses Handbuch enthält Schritte zum Installieren des Treibers und kurze Codebeispiele für grundlegende CRUD-Vorgänge (*Create, Read, Update und Delete*). Ausführlichere Beispiele, die diese Vorgänge in einer vollständigen Beispielanwendung veranschaulichen, finden Sie im [Java-Lernprogramm](getting-started.java.tutorial.md).
**Topics**
+ [Voraussetzungen](#driver-quickstart-java.prereqs)
+ [Schritt 1: Einrichten des Projekts](#driver-quickstart-java.step-1)
+ [Schritt 2: Initialisieren des Treibers](#driver-quickstart-java.step-2)
+ [Schritt 3: Erstellen einer Tabelle und eines Index](#driver-quickstart-java.step-3)
+ [Schritt 4: Einfügen eines Dokuments](#driver-quickstart-java.step-4)
+ [Schritt 5: Abfragen des Dokuments](#driver-quickstart-java.step-5)
+ [Schritt 6: Aktualisieren des Dokuments](#driver-quickstart-java.step-6)
+ [Ausführen der vollständigen Anwendung](#driver-quickstart-java.complete)
## Voraussetzungen
Bevor Sie beginnen, stellen Sie sicher, dass die folgende Voraussetzung erfüllt ist:
1. Füllen Sie den [Voraussetzungen](getting-started.java.md#getting-started.java.prereqs) für den Java-Treiber aus, falls Sie dies noch nicht getan haben. Dazu gehören die Registrierung für AWS, die Gewährung des programmatischen Zugriffs für die Entwicklung und die Installation einer integrierten Java-Entwicklungsumgebung (IDE).
1. Ledger mit dem Namen `quick-start` erstellen.
Informationen zum Erstellen eines Ledgers finden Sie unter [Grundlegende Operationen für Amazon QLDB-Ledger](ledger-management.basics.md) oder [Schritt 1: Erstellen Sie ein neues Hauptbuch](getting-started-step-1.md) in *Erste Schritte mit der Konsole*.
## Schritt 1: Einrichten des Projekts
Richten Sie zunächst Ihr Java-Projekt ein. Wir empfehlen, für dieses Tutorial das [Maven-Abhängigkeitsverwaltungssystem](https://maven.apache.org/index.html) zu verwenden.
**Anmerkung**
Wenn Sie eine IDE verwenden, die über Funktionen zur Automatisierung dieser Einrichtungsschritte verfügt, können Sie mit folgenden Schritten fortfahren[Schritt 2: Initialisieren des Treibers](#driver-quickstart-java.step-2).
1. Erstellen Sie einen Ordner für Ihre Anwendung.
```
$ mkdir myproject
$ cd myproject
```
1. Geben Sie den folgenden Befehl ein, um Ihr Projekt anhand einer Maven-Vorlage zu initialisieren. Ersetzen Sie *project-package**project-name*, und gegebenenfalls *maven-template* durch Ihre eigenen Werte.
```
$ mvn archetype:generate
-DgroupId=project-package \
-DartifactId=project-name \
-DarchetypeArtifactId=maven-template \
-DinteractiveMode=false
```
Für *maven-template* können Sie die grundlegende Maven-Vorlage verwenden: `maven-archetype-quickstart`
1. Um den [QLDB-Treiber für Java](https://search.maven.org/artifact/software.amazon.qldb/amazon-qldb-driver-java/2.3.1/jar) als Projektabhängigkeit hinzuzufügen, navigieren Sie zu Ihrer neu erstellten `pom.xml` Datei und fügen Sie das folgende Artefakt hinzu.
```
software.amazon.qldb
amazon-qldb-driver-java
2.3.1
```
Dieses Artefakt enthält automatisch das [AWS SDK for Java 2.x](https://aws.amazon.com/sdk-for-java)-Core-Modul, [Amazon Ion](ion.md)-Bibliotheken und andere erforderliche Abhängigkeiten. Ihre `pom.xml` Datei sollte jetzt in etwa wie folgt aussehen.
```
4.0.0
software.amazon.qldb
qldb-quickstart
jar
1.0-SNAPSHOT
qldb-quickstart
http://maven.apache.org
junit
junit
3.8.1
test
software.amazon.qldb
amazon-qldb-driver-java
2.3.1
```
1. Öffnen Sie die `App.java` Datei.
Fügen Sie dann schrittweise die Codebeispiele in den folgenden Schritten hinzu, um einige grundlegende CRUD-Operationen auszuprobieren. Sie können das step-by-step Tutorial auch überspringen und stattdessen die [gesamte](#driver-quickstart-java.complete) Anwendung ausführen.
## Schritt 2: Initialisieren des Treibers
Initialisieren Sie eine Instance des Treibers, der eine Verbindung mit dem Ledger `quick-start` herstellt. Fügen Sie nun folgenden Code in die Datei `App.java` ein:
```
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();
}
}
```
## Schritt 3: Erstellen einer Tabelle und eines Index
Im folgenden Codebeispiel wird veranschaulicht, wie `CREATE TABLE`- und `CREATE INDEX`-Anweisungen ausgeführt werden.
Fügen Sie der `main` Methode den folgenden Code hinzu, der eine Tabelle mit dem Namen `People` und einen Index für das `lastName` Feld in dieser Tabelle erstellt. [Indizes](ql-reference.create-index.md) sind erforderlich, um die Abfrageleistung zu optimieren und zur Begrenzung von Konfliktausnahmen bei der [optimistischen Parallelitätssteuerung (OCC) beizutragen](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)");
});
```
## Schritt 4: Einfügen eines Dokuments
Im folgenden Codebeispiel wird veranschaulicht, wie eine `INSERT`-Anweisung ausgeführt wird. QLDB unterstützt die [PartiQL-Abfragesprache](ql-reference.md) (SQL-kompatibel) und das [Amazon Ion-Datenformat](ion.md) (Superset von JSON).
Fügen Sie den folgenden Code hinzu, der ein Dokument in die Tabelle `People` einfügt.
```
// 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);
});
```
In diesem Beispiel wird ein Fragezeichen (`?`) als Variablenplatzhalter verwendet, um die Dokumentinformationen an die Anweisung zu übergeben. Wenn Sie Platzhalter verwenden, müssen Sie einen Wert vom Typ `IonValue` übergeben.
**Tipp**
Um mehrere Dokumente mithilfe einer einzigen [INSERT](ql-reference.insert.md) Anweisung einzufügen, können Sie der Anweisung wie folgt einen Typparameter [IonList](driver-working-with-ion.md#driver-ion-list)(explizit als ein umgewandelt`IonValue`) übergeben.
```
// people is an IonList explicitly cast as an IonValue
txn.execute("INSERT INTO People ?", (IonValue) people);
```
Sie schließen den variablen Platzhalter (`?`) nicht in doppelte spitze Klammern (`<<...>>`) ein, wenn Sie eine übergeben. `IonList` *In manuellen PartiQL-Anweisungen bezeichnen doppelte spitze Klammern eine ungeordnete Sammlung, die als Tasche bezeichnet wird.*
## Schritt 5: Abfragen des Dokuments
Im folgenden Codebeispiel wird veranschaulicht, wie eine `SELECT`-Anweisung ausgeführt wird.
Fügen Sie den folgenden Code hinzu, der ein Dokument aus der Tabelle `People` abfragt.
```
// 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
});
```
## Schritt 6: Aktualisieren des Dokuments
Im folgenden Codebeispiel wird veranschaulicht, wie eine `UPDATE`-Anweisung ausgeführt wird.
1. Fügen Sie den folgenden Code hinzu, der ein Dokument in der `People` Tabelle aktualisiert, indem Sie auf aktualisieren. `age` `42`
```
// Update the document
qldbDriver.execute(txn -> {
System.out.println("Updating the document");
final List parameters = new ArrayList<>();
parameters.add(ionSys.newInt(42));
parameters.add(ionSys.newString("Doe"));
txn.execute("UPDATE People SET age = ? WHERE lastName = ?", parameters);
});
```
1. Fragen Sie das Dokument erneut ab, um den aktualisierten Wert zu sehen.
```
// 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. Verwenden Sie Maven oder Ihre IDE, um die `App.java` Datei zu kompilieren und auszuführen.
## Ausführen der vollständigen Anwendung
Das folgende Codebeispiel ist die vollständige Version der `App.java` Anwendung. Anstatt die vorherigen Schritte einzeln auszuführen, können Sie dieses Codebeispiel auch kopieren und von Anfang bis Ende ausführen. Diese Anwendung demonstriert einige grundlegende CRUD-Operationen für den Ledger namens `quick-start`.
**Anmerkung**
Bevor Sie diesen Code ausführen, stellen Sie sicher, dass Sie noch keine aktive Tabelle mit dem Namen `People` im `quick-start`-Ledger besitzen.
Ersetzen Sie in der ersten Zeile *project-package* durch den `groupId` Wert, den Sie für den Maven-Befehl in [Schritt 1: Einrichten des Projekts](#driver-quickstart-java.step-1) verwendet haben.
```
package project-package;
import java.util.*;
import com.amazon.ion.*;
import com.amazon.ion.system.*;
import software.amazon.awssdk.services.qldbsession.QldbSessionClient;
import software.amazon.qldb.*;
public class App {
public static IonSystem ionSys = IonSystemBuilder.standard().build();
public static QldbDriver qldbDriver;
public static void main(final String... args) {
System.out.println("Initializing the driver");
qldbDriver = QldbDriver.builder()
.ledger("quick-start")
.transactionRetryPolicy(RetryPolicy
.builder()
.maxRetries(3)
.build())
.sessionClientBuilder(QldbSessionClient.builder())
.build();
// Create a table and an index in the same transaction
qldbDriver.execute(txn -> {
System.out.println("Creating a table and an index");
txn.execute("CREATE TABLE People");
txn.execute("CREATE INDEX ON People(lastName)");
});
// Insert a document
qldbDriver.execute(txn -> {
System.out.println("Inserting a document");
IonStruct person = ionSys.newEmptyStruct();
person.put("firstName").newString("John");
person.put("lastName").newString("Doe");
person.put("age").newInt(32);
txn.execute("INSERT INTO People ?", person);
});
// Query the document
qldbDriver.execute(txn -> {
System.out.println("Querying the table");
Result result = txn.execute("SELECT * FROM People WHERE lastName = ?",
ionSys.newString("Doe"));
IonStruct person = (IonStruct) result.iterator().next();
System.out.println(person.get("firstName")); // prints John
System.out.println(person.get("lastName")); // prints Doe
System.out.println(person.get("age")); // prints 32
});
// Update the document
qldbDriver.execute(txn -> {
System.out.println("Updating the document");
final List parameters = new ArrayList<>();
parameters.add(ionSys.newInt(42));
parameters.add(ionSys.newString("Doe"));
txn.execute("UPDATE People SET age = ? WHERE lastName = ?", parameters);
});
// Query the updated document
qldbDriver.execute(txn -> {
System.out.println("Querying the table for the updated document");
Result result = txn.execute("SELECT * FROM People WHERE lastName = ?",
ionSys.newString("Doe"));
IonStruct person = (IonStruct) result.iterator().next();
System.out.println(person.get("firstName")); // prints John
System.out.println(person.get("lastName")); // prints Doe
System.out.println(person.get("age")); // prints 42
});
}
}
```
Verwenden Sie Maven oder Ihre IDE, um die Datei zu kompilieren und auszuführen. `App.java`
# Amazon QLDB-Treiber für Java — Kochbuch-Referenz
**Wichtig**
Hinweis zum Ende des Supports: Bestandskunden können Amazon QLDB bis zum Ende des Supports am 31.07.2025 nutzen. Weitere Informationen finden Sie unter [Migrieren eines Amazon QLDB-Ledgers zu Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL.
Dieses Referenzhandbuch zeigt allgemeine Anwendungsfälle des Amazon QLDB-Treibers für Java. Es enthält Java-Codebeispiele, die zeigen, wie der Treiber verwendet wird, um grundlegende *Erstellungs-, Lese-, Aktualisierungs- und Löschvorgänge* (CRUD) auszuführen. Es enthält auch Codebeispiele für die Verarbeitung von Amazon Ion-Daten. Darüber hinaus werden in diesem Leitfaden bewährte Verfahren zur idempotenten Gestaltung von Transaktionen und zur Implementierung von Eindeutigkeitsbeschränkungen beschrieben.
**Anmerkung**
Gegebenenfalls haben einige Anwendungsfälle unterschiedliche Codebeispiele für jede unterstützte Hauptversion des QLDB-Treibers für Java.
**Contents**
+ [Der Treiber wird importiert](#cookbook-java.importing)
+ [Der Treiber wird instanziiert](#cookbook-java.instantiating)
+ [CRUD-Operationen](#cookbook-java.crud)
+ [Erstellen von Tabellen](#cookbook-java.crud.creating-tables)
+ [Erstellen von Indizes](#cookbook-java.crud.creating-indexes)
+ [Dokumente lesen](#cookbook-java.crud.reading)
+ [Dokumente werden eingefügt](#cookbook-java.crud.inserting)
+ [Einfügen mehrerer Dokumente in eine Anweisung](#cookbook-java.crud.inserting.multiple)
+ [Dokumente werden aktualisiert](#cookbook-java.crud.updating)
+ [Dokumente löschen](#cookbook-java.crud.deleting)
+ [Ausführung mehrerer Anweisungen in einer Transaktion](#cookbook-java.crud.multi-statement)
+ [Logik für Wiederholversuche](#cookbook-java.crud.retry-logic)
+ [Implementierung von Eindeutigkeitsbeschränkungen](#cookbook-java.crud.uniqueness-constraints)
+ [Arbeiten mit Amazon Ion](#cookbook-java.ion)
+ [Die Ion-Pakete importieren](#cookbook-java.ion.importing)
+ [Ion wird initialisiert](#cookbook-java.ion.initializing)
+ [Ion-Objekte erstellen](#cookbook-java.ion.creating)
+ [Ion-Objekte lesen](#cookbook-java.ion.reading)
## Der Treiber wird importiert
Das folgende Codebeispiel importiert den Treiber, den QLDB-Sitzungsclient, Amazon Ion-Pakete und andere verwandte Abhängigkeiten.
------
#### [ 2.x ]
```
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonSystem;
import com.amazon.ion.IonValue;
import com.amazon.ion.system.IonSystemBuilder;
import software.amazon.awssdk.services.qldbsession.QldbSessionClient;
import software.amazon.qldb.QldbDriver;
import software.amazon.qldb.Result;
```
------
#### [ 1.x ]
```
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonSystem;
import com.amazon.ion.IonValue;
import com.amazon.ion.system.IonSystemBuilder;
import com.amazonaws.services.qldbsession.AmazonQLDBSessionClientBuilder;
import software.amazon.qldb.PooledQldbDriver;
import software.amazon.qldb.Result;
```
------
## Der Treiber wird instanziiert
Im folgenden Codebeispiel wird eine Treiberinstanz erstellt, die eine Verbindung zu einem angegebenen Ledger-Namen herstellt und die angegebene [Wiederholungslogik mit einem benutzerdefinierten Wiederholungslimit](#cookbook-java.crud.retry-logic) verwendet.
**Anmerkung**
In diesem Beispiel wird auch ein Amazon Ion-Systemobjekt () `IonSystem` instanziiert. Sie benötigen dieses Objekt, um Ion-Daten zu verarbeiten, wenn Sie einige Datenoperationen in dieser Referenz ausführen. Weitere Informationen hierzu finden Sie unter [Arbeiten mit Amazon Ion](#cookbook-java.ion).
------
#### [ 2.x ]
```
QldbDriver qldbDriver = QldbDriver.builder()
.ledger("vehicle-registration")
.transactionRetryPolicy(RetryPolicy
.builder()
.maxRetries(3)
.build())
.sessionClientBuilder(QldbSessionClient.builder())
.build();
IonSystem SYSTEM = IonSystemBuilder.standard().build();
```
------
#### [ 1.x ]
```
PooledQldbDriver qldbDriver = PooledQldbDriver.builder()
.withLedger("vehicle-registration")
.withRetryLimit(3)
.withSessionClientBuilder(AmazonQLDBSessionClientBuilder.standard())
.build();
IonSystem SYSTEM = IonSystemBuilder.standard().build();
```
------
## CRUD-Operationen
QLDB führt *Erstellungs-, Lese-, Aktualisierungs- und Löschvorgänge* (CRUD) als Teil einer Transaktion aus.
**Warnung**
Als bewährte Methode sollten Sie Ihre Schreibtransaktionen strikt idempotent gestalten.
**Transaktionen idempotent machen**
Wir empfehlen, Schreibtransaktionen idempotent zu machen, um unerwartete Nebenwirkungen bei Wiederholungsversuchen zu vermeiden. Eine Transaktion ist *idempotent*, wenn sie mehrfach ausgeführt werden kann und jedes Mal identische Ergebnisse liefert.
Stellen Sie sich zum Beispiel eine Transaktion vor, die ein Dokument in eine Tabelle mit dem Namen einfügt. `Person` Bei der Transaktion sollte zunächst geprüft werden, ob das Dokument bereits in der Tabelle vorhanden ist. Ohne diese Prüfung könnte die Tabelle doppelte Dokumente enthalten.
Nehmen wir an, dass QLDB die Transaktion auf der Serverseite erfolgreich festschreibt, der Client jedoch während des Wartens auf eine Antwort eine Zeitüberschreitung ausführt. Wenn die Transaktion nicht idempotent ist, könnte dasselbe Dokument bei einem erneuten Versuch mehrmals eingefügt werden.
**Verwendung von Indizes zur Vermeidung vollständiger Tabellenscans**
Es wird außerdem empfohlen, Anweisungen mit einer `WHERE` Prädikatklausel unter Verwendung eines *Gleichheitsoperators* für ein indiziertes Feld oder eine Dokument-ID auszuführen, z. B. oder. `WHERE indexedField = 123` `WHERE indexedField IN (456, 789)` Ohne diese indizierte Suche muss QLDB einen Tabellenscan durchführen, was zu Transaktions-Timeouts oder Konflikten mit *optimistischer Parallelitätskontrolle* (OCC) führen kann.
Weitere Informationen zu OCC finden Sie unter [Amazon QLDB-Parallelitätsmodell](concurrency.md).
**Implizit erstellte Transaktionen**
Die Methode [QldbDriver.execute](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/software/amazon/qldb/QldbDriver.html) akzeptiert eine Lambda-Funktion, die eine Instanz von [Executor](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/software/amazon/qldb/Executor.html) empfängt, mit der Sie Anweisungen ausführen können. Die `Executor` Instanz umschließt eine implizit erstellte Transaktion.
Mithilfe der Methode können Sie Anweisungen innerhalb der Lambda-Funktion ausführen. `Executor.execute` Der Treiber schreibt die Transaktion implizit fest, wenn die Lambda-Funktion zurückkehrt.
In den folgenden Abschnitten wird gezeigt, wie grundlegende CRUD-Operationen ausgeführt, eine benutzerdefinierte Wiederholungslogik angegeben und Eindeutigkeitsbeschränkungen implementiert werden.
**Anmerkung**
Sofern zutreffend, enthalten diese Abschnitte Codebeispiele für die Verarbeitung von Amazon Ion-Daten sowohl mit der integrierten Ion-Bibliothek als auch mit der Jackson Ion-Mapper-Bibliothek. Weitere Informationen hierzu finden Sie unter [Arbeiten mit Amazon Ion](#cookbook-java.ion).
**Contents**
+ [Erstellen von Tabellen](#cookbook-java.crud.creating-tables)
+ [Erstellen von Indizes](#cookbook-java.crud.creating-indexes)
+ [Dokumente lesen](#cookbook-java.crud.reading)
+ [Dokumente werden eingefügt](#cookbook-java.crud.inserting)
+ [Einfügen mehrerer Dokumente in eine Anweisung](#cookbook-java.crud.inserting.multiple)
+ [Dokumente werden aktualisiert](#cookbook-java.crud.updating)
+ [Dokumente löschen](#cookbook-java.crud.deleting)
+ [Ausführung mehrerer Anweisungen in einer Transaktion](#cookbook-java.crud.multi-statement)
+ [Logik für Wiederholversuche](#cookbook-java.crud.retry-logic)
+ [Implementierung von Eindeutigkeitsbeschränkungen](#cookbook-java.crud.uniqueness-constraints)
### Erstellen von Tabellen
```
qldbDriver.execute(txn -> {
txn.execute("CREATE TABLE Person");
});
```
### Erstellen von Indizes
```
qldbDriver.execute(txn -> {
txn.execute("CREATE INDEX ON Person(GovId)");
});
```
### Dokumente lesen
```
// Assumes that Person table has documents as follows:
// { GovId: "TOYENC486FH", FirstName: "Brent" }
qldbDriver.execute(txn -> {
Result result = txn.execute("SELECT * FROM Person WHERE GovId = 'TOYENC486FH'");
IonStruct person = (IonStruct) result.iterator().next();
System.out.println(person.get("GovId")); // prints TOYENC486FH
System.out.println(person.get("FirstName")); // prints Brent
});
```
**Verwenden von Abfrageparametern**
Im folgenden Codebeispiel wird ein Abfrageparameter vom Typ Ion verwendet.
```
qldbDriver.execute(txn -> {
Result result = txn.execute("SELECT * FROM Person WHERE GovId = ?",
SYSTEM.newString("TOYENC486FH"));
IonStruct person = (IonStruct) result.iterator().next();
System.out.println(person.get("GovId")); // prints TOYENC486FH
System.out.println(person.get("FirstName")); // prints Brent
});
```
Das folgende Codebeispiel verwendet mehrere Abfrageparameter.
```
qldbDriver.execute(txn -> {
Result result = txn.execute("SELECT * FROM Person WHERE GovId = ? AND FirstName = ?",
SYSTEM.newString("TOYENC486FH"),
SYSTEM.newString("Brent"));
IonStruct person = (IonStruct) result.iterator().next();
System.out.println(person.get("GovId")); // prints TOYENC486FH
System.out.println(person.get("FirstName")); // prints Brent
});
```
Das folgende Codebeispiel verwendet eine Liste von Abfrageparametern.
```
qldbDriver.execute(txn -> {
final List parameters = new ArrayList<>();
parameters.add(SYSTEM.newString("TOYENC486FH"));
parameters.add(SYSTEM.newString("ROEE1"));
parameters.add(SYSTEM.newString("YH844"));
Result result = txn.execute("SELECT * FROM Person WHERE GovId IN (?,?,?)", parameters);
IonStruct person = (IonStruct) result.iterator().next();
System.out.println(person.get("GovId")); // prints TOYENC486FH
System.out.println(person.get("FirstName")); // prints Brent
});
```
#### Verwenden des Jackson-Mappers
```
// Assumes that Person table has documents as follows:
// {GovId: "TOYENC486FH", FirstName: "Brent" }
qldbDriver.execute(txn -> {
try {
Result result = txn.execute("SELECT * FROM Person WHERE GovId = 'TOYENC486FH'");
Person person = MAPPER.readValue(result.iterator().next(), Person.class);
System.out.println(person.getFirstName()); // prints Brent
System.out.println(person.getGovId()); // prints TOYENC486FH
} catch (IOException e) {
e.printStackTrace();
}
});
```
**Verwenden von Abfrageparametern**
Im folgenden Codebeispiel wird ein Abfrageparameter vom Typ Ion verwendet.
```
qldbDriver.execute(txn -> {
try {
Result result = txn.execute("SELECT * FROM Person WHERE GovId = ?",
MAPPER.writeValueAsIonValue("TOYENC486FH"));
Person person = MAPPER.readValue(result.iterator().next(), Person.class);
System.out.println(person.getFirstName()); // prints Brent
System.out.println(person.getGovId()); // prints TOYENC486FH
} catch (IOException e) {
e.printStackTrace();
}
});
```
Das folgende Codebeispiel verwendet mehrere Abfrageparameter.
```
qldbDriver.execute(txn -> {
try {
Result result = txn.execute("SELECT * FROM Person WHERE GovId = ? AND FirstName = ?",
MAPPER.writeValueAsIonValue("TOYENC486FH"),
MAPPER.writeValueAsIonValue("Brent"));
Person person = MAPPER.readValue(result.iterator().next(), Person.class);
System.out.println(person.getFirstName()); // prints Brent
System.out.println(person.getGovId()); // prints TOYENC486FH
} catch (IOException e) {
e.printStackTrace();
}
});
```
Das folgende Codebeispiel verwendet eine Liste von Abfrageparametern.
```
qldbDriver.execute(txn -> {
try {
final List parameters = new ArrayList<>();
parameters.add(MAPPER.writeValueAsIonValue("TOYENC486FH"));
parameters.add(MAPPER.writeValueAsIonValue("ROEE1"));
parameters.add(MAPPER.writeValueAsIonValue("YH844"));
Result result = txn.execute("SELECT * FROM Person WHERE GovId IN (?,?,?)", parameters);
Person person = MAPPER.readValue(result.iterator().next(), Person.class);
System.out.println(person.getFirstName()); // prints Brent
System.out.println(person.getGovId()); // prints TOYENC486FH
} catch (IOException e) {
e.printStackTrace();
}
});
```
**Anmerkung**
Wenn Sie eine Abfrage ohne indizierte Suche ausführen, wird ein vollständiger Tabellenscan aufgerufen. In diesem Beispiel empfehlen wir, einen [Index](ql-reference.create-index.md) für das `GovId` Feld zu verwenden, um die Leistung zu optimieren. Ohne aktivierten `GovId` Index können Abfragen eine höhere Latenz haben und auch zu OCC-Konfliktausnahmen oder Transaktions-Timeouts führen.
### Dokumente werden eingefügt
Im folgenden Codebeispiel werden Ion-Datentypen eingefügt.
```
qldbDriver.execute(txn -> {
// Check if a document with GovId:TOYENC486FH exists
// This is critical to make this transaction idempotent
Result result = txn.execute("SELECT * FROM Person WHERE GovId = ?",
SYSTEM.newString("TOYENC486FH"));
// Check if there is a result
if (!result.iterator().hasNext()) {
IonStruct person = SYSTEM.newEmptyStruct();
person.put("GovId").newString("TOYENC486FH");
person.put("FirstName").newString("Brent");
// Insert the document
txn.execute("INSERT INTO Person ?", person);
}
});
```
#### Verwenden des Jackson-Mappers
Im folgenden Codebeispiel werden Ion-Datentypen eingefügt.
```
qldbDriver.execute(txn -> {
try {
// Check if a document with GovId:TOYENC486FH exists
// This is critical to make this transaction idempotent
Result result = txn.execute("SELECT * FROM Person WHERE GovId = ?",
MAPPER.writeValueAsIonValue("TOYENC486FH"));
// Check if there is a result
if (!result.iterator().hasNext()) {
// Insert the document
txn.execute("INSERT INTO Person ?",
MAPPER.writeValueAsIonValue(new Person("Brent", "TOYENC486FH")));
}
} catch (IOException e) {
e.printStackTrace();
}
});
```
Diese Transaktion fügt ein Dokument in die `Person` Tabelle ein. Vor dem Einfügen wird zunächst geprüft, ob das Dokument bereits in der Tabelle vorhanden ist. **Diese Prüfung macht die Transaktion ihrem Wesen nach idempotent.** Selbst wenn Sie diese Transaktion mehrmals ausführen, hat sie keine unbeabsichtigten Nebenwirkungen.
**Anmerkung**
In diesem Beispiel empfehlen wir, einen Index für das `GovId` Feld zu verwenden, um die Leistung zu optimieren. Ohne aktivierten `GovId` Index können Anweisungen eine längere Latenz haben und auch zu OCC-Konfliktausnahmen oder Transaktions-Timeouts führen.
#### Einfügen mehrerer Dokumente in eine Anweisung
Um mehrere Dokumente mithilfe einer einzigen [INSERT](ql-reference.insert.md) Anweisung einzufügen, können Sie der Anweisung wie folgt einen Typparameter [IonList](driver-working-with-ion.md#driver-ion-list)(explizit als ein`IonValue`) übergeben.
```
// people is an IonList explicitly cast as an IonValue
txn.execute("INSERT INTO People ?", (IonValue) people);
```
Sie schließen den variablen Platzhalter (`?`) nicht in doppelte spitze Klammern (`<<...>>`) ein, wenn Sie eine übergeben. `IonList` *In manuellen PartiQL-Anweisungen bezeichnen doppelte spitze Klammern eine ungeordnete Sammlung, die als Tasche bezeichnet wird.*
##### Warum ist die explizite Besetzung erforderlich?
Die Methode [TransactionExecutor.execute](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/software/amazon/qldb/TransactionExecutor.html) ist überlastet. Sie akzeptiert eine variable Anzahl von `IonValue` Argumenten (*Varargs*) oder ein einzelnes Argument. `List` In [Ion-Java](https://www.javadoc.io/doc/com.amazon.ion/ion-java/latest/index.html) `IonList` ist implementiert als. `List`
Java verwendet standardmäßig die spezifischste Methodenimplementierung, wenn Sie eine überladene Methode aufrufen. Wenn Sie in diesem Fall einen `IonList` Parameter übergeben, wird standardmäßig die Methode verwendet, die eine benötigt. `List` Wenn diese Methodenimplementierung aufgerufen wird, übergibt sie die `IonValue` Elemente der Liste als unterschiedliche Werte. Um also stattdessen die Varargs-Methode aufzurufen, müssen Sie einen Parameter explizit in einen `IonList` umwandeln. `IonValue`
### Dokumente werden aktualisiert
```
qldbDriver.execute(txn -> {
final List parameters = new ArrayList<>();
parameters.add(SYSTEM.newString("John"));
parameters.add(SYSTEM.newString("TOYENC486FH"));
txn.execute("UPDATE Person SET FirstName = ? WHERE GovId = ?", parameters);
});
```
#### Den Jackson-Mapper verwenden
```
qldbDriver.execute(txn -> {
try {
final List parameters = new ArrayList<>();
parameters.add(MAPPER.writeValueAsIonValue("John"));
parameters.add(MAPPER.writeValueAsIonValue("TOYENC486FH"));
txn.execute("UPDATE Person SET FirstName = ? WHERE GovId = ?", parameters);
} catch (IOException e) {
e.printStackTrace();
}
});
```
**Anmerkung**
In diesem Beispiel empfehlen wir, einen Index für das `GovId` Feld zu verwenden, um die Leistung zu optimieren. Ohne aktivierten `GovId` Index können Anweisungen eine längere Latenz haben und auch zu OCC-Konfliktausnahmen oder Transaktions-Timeouts führen.
### Dokumente löschen
```
qldbDriver.execute(txn -> {
txn.execute("DELETE FROM Person WHERE GovId = ?",
SYSTEM.newString("TOYENC486FH"));
});
```
#### Den Jackson-Mapper verwenden
```
qldbDriver.execute(txn -> {
try {
txn.execute("DELETE FROM Person WHERE GovId = ?",
MAPPER.writeValueAsIonValue("TOYENC486FH"));
} catch (IOException e) {
e.printStackTrace();
}
});
```
**Anmerkung**
In diesem Beispiel empfehlen wir, einen Index für das `GovId` Feld zu verwenden, um die Leistung zu optimieren. Ohne aktivierten `GovId` Index können Anweisungen eine längere Latenz haben und auch zu OCC-Konfliktausnahmen oder Transaktions-Timeouts führen.
### Ausführung mehrerer Anweisungen in einer Transaktion
```
// This code snippet is intentionally trivial. In reality you wouldn't do this because you'd
// set your UPDATE to filter on vin and insured, and check if you updated something or not.
public static boolean InsureCar(QldbDriver qldbDriver, final String vin) {
final IonSystem ionSystem = IonSystemBuilder.standard().build();
final IonString ionVin = ionSystem.newString(vin);
return qldbDriver.execute(txn -> {
Result result = txn.execute(
"SELECT insured FROM Vehicles WHERE vin = ? AND insured = FALSE",
ionVin);
if (!result.isEmpty()) {
txn.execute("UPDATE Vehicles SET insured = TRUE WHERE vin = ?", ionVin);
return true;
}
return false;
});
}
```
### Logik für Wiederholversuche
Die `execute` Treibermethode verfügt über einen integrierten Wiederholungsmechanismus, der die Transaktion wiederholt, wenn eine Ausnahme auftritt, die wiederholt werden kann (z. B. Timeouts oder OCC-Konflikte).
------
#### [ 2.x ]
Die maximale Anzahl von Wiederholungsversuchen und die Backoff-Strategie sind konfigurierbar.
Das Standardlimit für Wiederholungsversuche ist`4`, und die Standard-Backoff-Strategie ist. [DefaultQldbTransactionBackoffStrategy](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/software/amazon/qldb/DefaultQldbTransactionBackoffStrategy.html) Sie können die Wiederholungskonfiguration pro Treiberinstanz und auch pro Transaktion festlegen, indem Sie eine Instanz von verwenden. [RetryPolicy](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/software/amazon/qldb/RetryPolicy.html)
Das folgende Codebeispiel spezifiziert die Wiederholungslogik mit einem benutzerdefinierten Wiederholungslimit und einer benutzerdefinierten Backoff-Strategie für eine Instanz des Treibers.
```
public void retry() {
QldbDriver qldbDriver = QldbDriver.builder()
.ledger("vehicle-registration")
.transactionRetryPolicy(RetryPolicy.builder()
.maxRetries(2)
.backoffStrategy(new CustomBackOffStrategy()).build())
.sessionClientBuilder(QldbSessionClient.builder())
.build();
}
private class CustomBackOffStrategy implements BackoffStrategy {
@Override
public Duration calculateDelay(RetryPolicyContext retryPolicyContext) {
return Duration.ofMillis(1000 * retryPolicyContext.retriesAttempted());
}
}
```
Das folgende Codebeispiel spezifiziert die Wiederholungslogik mit einem benutzerdefinierten Wiederholungslimit und einer benutzerdefinierten Backoff-Strategie für eine bestimmte Transaktion. Diese Konfiguration für `execute` überschreibt die Wiederholungslogik, die für die Treiberinstanz festgelegt ist.
```
public void retry() {
Result result = qldbDriver.execute(txn -> { txn.execute("SELECT * FROM Person WHERE GovId = ?",
SYSTEM.newString("TOYENC486FH")); },
RetryPolicy.builder()
.maxRetries(2)
.backoffStrategy(new CustomBackOffStrategy())
.build());
}
private class CustomBackOffStrategy implements BackoffStrategy {
// Configuring a custom backoff which increases delay by 1s for each attempt.
@Override
public Duration calculateDelay(RetryPolicyContext retryPolicyContext) {
return Duration.ofMillis(1000 * retryPolicyContext.retriesAttempted());
}
}
```
------
#### [ 1.x ]
Die maximale Anzahl von Wiederholungsversuchen ist konfigurierbar. Sie können das Wiederholungslimit konfigurieren, indem Sie die `retryLimit` Eigenschaft bei der Initialisierung festlegen. `PooledQldbDriver`
Das Standardlimit für Wiederholungsversuche ist. `4`
------
### Implementierung von Eindeutigkeitsbeschränkungen
QLDB unterstützt keine eindeutigen Indizes, aber Sie können dieses Verhalten in Ihrer Anwendung implementieren.
Angenommen, Sie möchten eine Eindeutigkeitsbeschränkung für das `GovId` Feld in der Tabelle implementieren. `Person` Zu diesem Zweck können Sie eine Transaktion schreiben, die Folgendes tut:
1. Bestätigen Sie, dass die Tabelle keine vorhandenen Dokumente mit einem angegebenen Wert enthält`GovId`.
1. Fügt das Dokument ein, wenn die Assertion erfolgreich ist.
Wenn eine konkurrierende Transaktion gleichzeitig die Assertion besteht, wird nur eine der Transaktionen erfolgreich festgeschrieben. Die andere Transaktion schlägt mit einer OCC-Konfliktausnahme fehl.
Das folgende Codebeispiel zeigt, wie diese Eindeutigkeitsbeschränkungslogik implementiert wird.
```
qldbDriver.execute(txn -> {
Result result = txn.execute("SELECT * FROM Person WHERE GovId = ?",
SYSTEM.newString("TOYENC486FH"));
// Check if there is a result
if (!result.iterator().hasNext()) {
IonStruct person = SYSTEM.newEmptyStruct();
person.put("GovId").newString("TOYENC486FH");
person.put("FirstName").newString("Brent");
// Insert the document
txn.execute("INSERT INTO Person ?", person);
}
});
```
**Anmerkung**
In diesem Beispiel empfehlen wir, einen Index für das `GovId` Feld zu verwenden, um die Leistung zu optimieren. Ohne aktivierten `GovId` Index können Anweisungen eine längere Latenz haben und auch zu OCC-Konfliktausnahmen oder Transaktions-Timeouts führen.
## Arbeiten mit Amazon Ion
Es gibt mehrere Möglichkeiten, Amazon Ion-Daten in QLDB zu verarbeiten. Sie können die integrierten Methoden der [Ion-Bibliothek](https://github.com/amzn/ion-java) verwenden, um Dokumente nach Bedarf flexibel zu erstellen und zu ändern. Oder Sie können das [Jackson-Datenformatmodul von FasterXML für Ion verwenden, um Ion-Dokumente](https://github.com/FasterXML/jackson-dataformats-binary/tree/master/ion) *einfachen alten Java-Objektmodellen* (POJO) zuzuordnen.
Die folgenden Abschnitte enthalten Codebeispiele für die Verarbeitung von Ion-Daten mit beiden Techniken.
**Contents**
+ [Die Ion-Pakete importieren](#cookbook-java.ion.importing)
+ [Ion wird initialisiert](#cookbook-java.ion.initializing)
+ [Ion-Objekte erstellen](#cookbook-java.ion.creating)
+ [Ion-Objekte lesen](#cookbook-java.ion.reading)
### Die Ion-Pakete importieren
Fügen Sie das Artefakt [ion-java](https://search.maven.org/artifact/com.amazon.ion/ion-java/1.6.1/bundle) als Abhängigkeit in Ihr Java-Projekt ein.
------
#### [ Gradle ]
```
dependencies {
compile group: 'com.amazon.ion', name: 'ion-java', version: '1.6.1'
}
```
------
#### [ Maven ]
```
com.amazon.ion
ion-java
1.6.1
```
------
Importieren Sie die folgenden Ion-Pakete.
```
import com.amazon.ion.IonStruct;
import com.amazon.ion.IonSystem;
import com.amazon.ion.system.IonSystemBuilder;
```
#### Verwenden Sie den Jackson-Mapper
Fügen Sie das Artefakt [jackson-dataformat-ion](https://search.maven.org/artifact/com.fasterxml.jackson.dataformat/jackson-dataformat-ion/2.10.0/bundle)als Abhängigkeit in Ihr Java-Projekt ein. QLDB erfordert Version `2.10.0` oder höher.
------
#### [ Gradle ]
```
dependencies {
compile group: 'com.fasterxml.jackson.dataformat', name: 'jackson-dataformat-ion', version: '2.10.0'
}
```
------
#### [ Maven ]
```
com.fasterxml.jackson.dataformat
jackson-dataformat-ion
2.10.0
```
------
Importieren Sie die folgenden Ion-Pakete.
```
import com.amazon.ion.IonReader;
import com.amazon.ion.IonStruct;
import com.amazon.ion.system.IonReaderBuilder;
import com.amazon.ion.system.IonSystemBuilder;
import com.fasterxml.jackson.dataformat.ion.IonObjectMapper;
import com.fasterxml.jackson.dataformat.ion.ionvalue.IonValueMapper;
```
### Ion wird initialisiert
```
IonSystem SYSTEM = IonSystemBuilder.standard().build();
```
#### Den Jackson-Mapper verwenden
```
IonObjectMapper MAPPER = new IonValueMapper(IonSystemBuilder.standard().build());
```
### Ion-Objekte erstellen
Im folgenden Codebeispiel wird mithilfe der `IonStruct` Schnittstelle und der integrierten Methoden ein Ion-Objekt erstellt.
```
IonStruct ionStruct = SYSTEM.newEmptyStruct();
ionStruct.put("GovId").newString("TOYENC486FH");
ionStruct.put("FirstName").newString("Brent");
System.out.println(ionStruct.toPrettyString()); // prints a nicely formatted copy of ionStruct
```
#### Mit dem Jackson-Mapper
Angenommen, Sie haben eine JSON-zugeordnete Modellklasse mit dem folgenden Namen`Person`.
```
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
public static class Person {
private final String firstName;
private final String govId;
@JsonCreator
public Person(@JsonProperty("FirstName") final String firstName,
@JsonProperty("GovId") final String govId) {
this.firstName = firstName;
this.govId = govId;
}
@JsonProperty("FirstName")
public String getFirstName() {
return firstName;
}
@JsonProperty("GovId")
public String getGovId() {
return govId;
}
}
```
Das folgende Codebeispiel erstellt ein `IonStruct` Objekt aus einer Instanz von. `Person`
```
IonStruct ionStruct = (IonStruct) MAPPER.writeValueAsIonValue(new Person("Brent", "TOYENC486FH"));
```
### Ion-Objekte lesen
Das folgende Codebeispiel druckt jedes Feld der `ionStruct` Instanz.
```
// ionStruct is an instance of IonStruct
System.out.println(ionStruct.get("GovId")); // prints TOYENC486FH
System.out.println(ionStruct.get("FirstName")); // prints Brent
```
#### Verwenden des Jackson-Mappers
Das folgende Codebeispiel liest ein `IonStruct` Objekt und ordnet es einer Instanz von `Person` zu.
```
// ionStruct is an instance of IonStruct
IonReader reader = IonReaderBuilder.standard().build(ionStruct);
Person person = MAPPER.readValue(reader, Person.class);
System.out.println(person.getFirstName()); // prints Brent
System.out.println(person.getGovId()); // prints TOYENC486FH
```
Weitere Informationen zur Arbeit mit Ion finden Sie in der [Amazon Ion-Dokumentation](http://amzn.github.io/ion-docs/) unter GitHub. Weitere Codebeispiele für die Arbeit mit Ion in QLDB finden Sie unter. [Arbeiten mit Amazon Ion-Datentypen in Amazon QLDB](driver-working-with-ion.md)