Amazon QLDB-Treiber für Java — Schnellstart-Tutorial

In diesem -Tutortetetetetetetete-Tutortetetetetetetetetete-Tutortetetetetetetetetete-Tutortetetetetetetetete-Tutortetetetetete 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-Anleitung.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass die folgende Voraussetzung erfüllt ist:

1. Vervollständigen Sie dasVoraussetzungen für den Java-Treiber, falls noch nicht geschehen, für den Java-Treiber, falls noch nicht geschehen. Dazu gehören die RegistrierungAWS, die Gewährung von programmatischem Zugriff für die Entwicklung und die Installation einer integrierten Java-Entwicklungsumgebung (IDE).

2. Ledger mit dem Namen quick-start erstellen.

   Informationen zum Erstellen eines Ledgers finden Sie unterGrundfunktionen für Amazon QLDB-Ledgers oderSchritt 1: Erstellen eines neuen Ledgers unter Erste Schritte mit der Konsole.

Schritt 1: Einrichten des Projekts

Zuerst richten Sie Ihr Java-Projekt ein. Wir empfehlen, für dieses Tutorial das Maven-Abhängigkeitsverwaltungssystem zu verwenden.

Anmerkung

Wenn Sie eine IDE verwenden, die Funktionen zur Automatisierung dieser Einrichtungsschritte enthält, können Sie mit dem Vorgang fortfahrenSchritt 2: Initialisieren des Treibers.

1. Erstellen Sie einen Ordner für Ihre Anwendung.

   $ mkdir myproject
   $ cd myproject

2. Geben Sie Sie Sie den folgenden Befehl in Ihrem Terminal, um Ihr Projekt von einer Maven-Vorlage aus zu initialisieren. Ersetzen Sie das Projektpaket, den Projektnamen und die Maven-Vorlage gegebenenfalls durch Ihre eigenen Werte.

   $ mvn archetype:generate
     -DgroupId=project-package \
     -DartifactId=project-name \
     -DarchetypeArtifactId=maven-template \
     -DinteractiveMode=false

   Für das Maven-Template können Sie das grundlegende Maven-Template verwenden:maven-archetype-quickstart

3. Um den QLDB-Treiber für Java als Projektabhängigkeit hinzuzufügen, navigieren Sie zu Ihrer neu erstelltenpom.xml Datei und fügen Sie das folgende Artefakt hinzu.

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

   Dieses Artefakt enthält automatisch das AWS SDK for Java 2.x-Core-Modul, Amazon Ion-Bibliotheken und andere erforderliche Abhängigkeiten. Ihrepom.xml Datei sollte jetzt in etwa folgendermaßen aussehen:

   <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>

4. Öffnen Sie die App.java Datei.

   Fügen Sie dann schrittweise die Codebeispiele in den folgenden Schritten hinzu, um einige grundlegende CRUD-Operationen auszuprobieren. Oder Sie können das step-by-step Tutorial überspringen und stattdessen die komplette 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 in dermain Methode den folgenden Code hinzu, der einen TabellennamenPeople und einen Index für daslastName Feld in dieser Tabelle erstellt. Indizes sind erforderlich, um die Abfrageleistung zu optimieren und dabei zu helfen, Konfliktausnahmen für Optimist Concurrency Control (OCC) zu begrenzen.

// 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 (SQL-kompatibel) und das Amazon Ion-Datenformat (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 einzigenINSERT Anweisung einzufügen, können Sie der Anweisung wie folgt einen Parameter vom Typ IonList(explizit alsIonValue) ü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 eckige Klammern (<<...>>) ein, wenn Sie eine übergebenIonList. In manuellen PartiQL-Anweisungen bezeichnen doppelte spitze Klammern eine ungeordnete Sammlung, die als Bag 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 derPeople Tabelle aktualisiert, indemage es auf aktualisiert wird42.

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

2. 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
   });

3. Verwenden Sie Maven oder Ihre IDE, um dieApp.java Datei zu kompilieren und auszuführen.

Ausführen der vollständigen Anwendung

Das folgende Codebeispiel ist die vollständige Version derApp.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 dengroupId Wert, den Sie für den Maven-Befehl verwendet habenSchritt 1: Einrichten des Projekts .

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

Verwenden Sie Maven oder Ihre IDE, um dieApp.java Datei zu kompilieren und auszuführen.