Importieren des Treibers Instanziieren des Treibers CRUD-Operationen Arbeiten mit Amazon Ion-Technologie

Amazon QLDB-Treiber für Java — Kochbuch-Referenz

Dieses Referenzhandbuch zeigt häufige Anwendungsfälle des Amazon QLDB-Treibers für Java. Es enthält Java-Codebeispiele, die zeigen, wie CRUD-Vorgänge (Erstellen, Lesen, Aktualisieren, Löschen) verwendet werden müssen. Es enthält auch Codebeispiele für die Verarbeitung von Amazon Ion-Daten. Darüber hinaus werden in diesem Leitfaden bewährte Verfahren vorgestellt, um Transaktionen idempotent zu machen und Eindeutigkeitsbeschränkungen zu implementieren.

Anmerkung

Gegebenenfalls haben einige Anwendungsfälle unterschiedliche Codebeispiele für jede unterstützte Hauptversion des QLDB-Treibers für Java.

Inhalt

Importieren des Treibers

Das folgende Codebeispiel importiert den Treiber, den QLDB-Sitzungsclient, Amazon Ion-Pakete und andere verwandte Abhängigkeiten.

Instanziieren des Treibers

Im folgenden Codebeispiel wird eine Treiberinstanz erstellt, die eine Verbindung zu einem angegebenen Ledger-Namen herstellt und die angegebene Wiederholungslogik mit einem benutzerdefinierten Wiederholungslimit verwendet.

Anmerkung

In diesem Beispiel wird auch ein Amazon Ion-Systemobjekt (IonSystem) instanziiert. Sie benötigen dieses Objekt, um Ionen-Daten zu verarbeiten, wenn Sie einige Datenoperationen in dieser Referenz ausführen. Weitere Informationen hierzu finden Sie unter Arbeiten mit Amazon Ion-Technologie.

CRUD-Operationen

QLDB führt CRUD-Operationen (Erstellen, Lesen, Aktualisieren, Löschen) als Teil einer Transaktion durch.

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 zu identischen Ergebnissen führt.

Stellen Sie sich zum Beispiel eine Transaktion vor, bei der ein Dokument in eine Tabelle mit dem Namen eingefügt wirdPerson. Die Transaktion sollte zunächst prüfen, ob das Dokument bereits in der Tabelle vorhanden ist. Ohne diese Überprüfung enthält die Tabelle möglicherweise doppelte Dokumente.

Nehmen wir an, QLDB führt die Transaktion auf der Serverseite erfolgreich durch, aber der Client läuft beim Warten auf eine Antwort ein Timeout. Wenn die Transaktion nicht idempotent ist, kann dasselbe Dokument im Falle eines erneuten Versuchs mehrmals eingefügt werden.

Verwendung von Indizes zur Vermeidung vollständiger Tabellenscans

Wir empfehlen außerdem, Anweisungen mit einerWHERE Prädikatklausel auszuführen, indem Sie einen Gleichheitsoperator für ein indiziertes Feld oder eine Dokument-ID verwenden, z. B.WHERE indexedField = 123 oderWHERE indexedField IN (456, 789). Ohne diese indizierte Suche muss QLDB einen Tabellenscan durchführen, was zu Transaktions-Timeouts oder OCC-Konflikten (Optimist Concurrency Control) führen kann.

Weitere Informationen zu OCC finden Sie unter Amazon QLDB-Nebenläufigkeit von Amazon QLDB-Nebenläufigkeit.

Implizit erstellte Transaktionen

Die Methode QldbDriver.execute akzeptiert eine Lambda-Funktion, die eine Instanz von Executor empfängt, mit der Sie Anweisungen ausführen können. DieExecutor Instanz umschließt eine implizit erstellte Transaktion.

Sie können Anweisungen innerhalb der Lambda-Funktion ausführen, indem Sie dieExecutor.execute Methode verwenden. 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

Gegebenenfalls enthalten diese Abschnitte Codebeispiele für die Verarbeitung von Amazon Ion-Daten mit der integrierten Ion-Bibliothek und der Jackson Ion Mapper-Bibliothek. Weitere Informationen hierzu finden Sie unter Arbeiten mit Amazon Ion-Technologie.

Inhalt

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

Verwendung von Abfrageparametern

Das folgende Codebeispiel verwendet einen Abfrageparameter vom Typ Ion.


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


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

Verwendung von Abfrageparametern

Das folgende Codebeispiel verwendet einen Abfrageparameter vom Typ Ion.


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<IonValue> 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 eine indizierte Suche ausführen, wird ein vollständiger Tabellenscan aufgerufen. In diesem Beispiel empfehlen wir, einen Index für dasGovId Feld zu haben, um die Leistung zu optimieren. Ohne aktiviertenGovId Index können Abfragen mehr Latenz haben und auch zu OCC-Konfliktausnahmen oder Transaktions-Timeouts führen.

Einfügen von Dokumenten

Das folgende Codebeispiel fügt Ion-Datentypen ein.


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

Das folgende Codebeispiel fügt Ion-Datentypen ein.


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 diePerson 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 idempotenter Natur. Selbst wenn Sie diese Transaktion mehrmals ausführen, verursacht sie keine unbeabsichtigten Nebenwirkungen.

Anmerkung

In diesem Beispiel empfehlen wir, einen Index für dasGovId Feld zu haben, um die Leistung zu optimieren. Ohne aktiviertenGovId Index können Anweisungen mehr Latenz haben und auch zu OCC-Konfliktausnahmen oder Transaktions-Timeouts führen.

Einfügen mehrerer Dokumente in eine Anweisung

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.

Die Methode TransactionExecutor.execute ist überlastet. Es akzeptiert eine variable Anzahl vonIonValue Argumenten (varargs) oder ein einzelnesList<IonValue> Argument. In Ion-JavaIonList ist es implementiert alsList<IonValue>.

Java verwendet standardmäßig die spezifischste Methodenimplementierung, wenn Sie eine überladene Methode aufrufen. In diesem Fall wird, wenn Sie einenIonList Parameter übergeben, standardmäßig die Methode verwendet, die a verwendetList<IonValue>. Beim Aufruf übergibt diese Methodenimplementierung dieIonValue Elemente der Liste als unterschiedliche Werte. Um stattdessen die Methode varargs aufzurufen, müssen Sie einenIonList Parameter explizit in einen umwandelnIonValue.

Dokumente aktualisieren


qldbDriver.execute(txn -> {
    final List<IonValue> parameters = new ArrayList<>();
    parameters.add(SYSTEM.newString("John"));
    parameters.add(SYSTEM.newString("TOYENC486FH"));
    txn.execute("UPDATE Person SET FirstName = ? WHERE GovId = ?", parameters);
});


qldbDriver.execute(txn -> {
    try {
        final List<IonValue> 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

Dokumente löschen


qldbDriver.execute(txn -> {
    txn.execute("DELETE FROM Person WHERE GovId = ?",
            SYSTEM.newString("TOYENC486FH"));
});


qldbDriver.execute(txn -> {
    try {
        txn.execute("DELETE FROM Person WHERE GovId = ?",
                MAPPER.writeValueAsIonValue("TOYENC486FH"));
    } catch (IOException e) {
        e.printStackTrace();
    }
});

Anmerkung

Ausführen mehrerer Kontoauszüge 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;
    });
}

Wiederholungslogik

Dieexecute Methode des Treibers verfügt über einen integrierten Wiederholungsmechanismus, der die Transaktion erneut versucht, wenn eine wiederholbare Ausnahme auftritt (z. B. Timeouts oder OCC-Konflikte).

2.x

Die maximale Anzahl der Wiederholungsversuche und die Backoff-Strategie sind konfigurierbar.

Das Standardlimit für Wiederholungsversuche ist4 und die Standard-Backoff-Strategie ist DefaultQldbTransactionBackoffStrategy. Sie können die Wiederholungskonfiguration pro Treiberinstanz und auch pro Transaktion festlegen, indem Sie eine Instanz von verwenden RetryPolicy.

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ürexecute ü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 der Wiederholungsversuche ist konfigurierbar. Sie können das Wiederholungslimit konfigurieren, indem Sie dieretryLimit Eigenschaft bei der Initialisierung festlegenPooledQldbDriver.

Das Standardlimit für Wiederholungsversuche ist4.

Implementieren von Eindeutigkeitseinschrä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 dasGovId Feld in derPerson Tabelle implementieren. Dazu können Sie eine Transaktion schreiben, die Folgendes bewirkt:

Stellen Sie sicher, dass die Tabelle keine vorhandenen Dokumente mit einem bestimmten Wert enthältGovId.
Fügen Sie das Dokument ein, wenn die Assertion erfolgreich ist.

Besteht eine konkurrierende Transaktion gleichzeitig die Assertion, wird nur eine der Transaktionen erfolgreich abgeschlossen. Die andere Transaktion schlägt mit einer OCC-Konfliktexception fehl.

Das folgende Codebeispiel veranschaulicht, wie diese Einheitseinschränungslogik implementiert werden muss.


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

Arbeiten mit Amazon Ion-Technologie

Es gibt mehrere Möglichkeiten, Amazon-Ion-Daten in QLDB zu verarbeiten. Sie können integrierte Methoden aus der Ion-Bibliothek verwenden, um Dokumente nach Bedarf flexibel zu erstellen und zu ändern. Oder Sie können das Jackson-Datenformatmodul für Ion von FasterXML verwenden, um Ion-Dokumente einfachen alten Java-Objektmodellen (POJO) zuzuordnen.

Die folgenden Abschnitte enthalten Codebeispiele für die Verarbeitung von Ion-Daten mit beiden Techniken.

Inhalt

Import der Ion-Pakete

Fügen Sie das Artefakt ion-java als Abhängigkeit zu Ihrem Java-Projekt hinzu.

Importieren Sie die folgenden Ion-Pakete.


import com.amazon.ion.IonStruct;
import com.amazon.ion.IonSystem;
import com.amazon.ion.system.IonSystemBuilder;

Fügen Sie das Artefakt jackson-dataformat-ionals Abhängigkeit zu Ihrem Java-Projekt hinzu. QLDB erfordert Version2.10.0 oder höher.

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;

Initialisieren/Ion-Elemente


IonSystem SYSTEM = IonSystemBuilder.standard().build();


IonObjectMapper MAPPER = new IonValueMapper(IonSystemBuilder.standard().build());

Erstellen von Ion-Objekten

Das folgende Codebeispiel erstellt ein Ion-Objekt mithilfe derIonStruct Schnittstelle und ihrer integrierten Methoden.


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

Angenommen, Sie haben eine JSON-zugeordnete Modellklasse wie folgt benanntPerson.


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 einIonStruct Objekt aus einer Instanz vonPerson.


IonStruct ionStruct = (IonStruct) MAPPER.writeValueAsIonValue(new Person("Brent", "TOYENC486FH"));

Lesen von Ion-Objekten

Das folgende Codebeispiel druckt jedes Feld derionStruct Instanz.


// ionStruct is an instance of IonStruct
System.out.println(ionStruct.get("GovId")); // prints TOYENC486FH
System.out.println(ionStruct.get("FirstName")); // prints Brent

Das folgende Codebeispiel liest einIonStruct Objekt und ordnet es einer Instanz von zuPerson.


// 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 unter GitHub. Weitere Codebeispiele für die Arbeit mit Ion in QLDB finden Sie unterArbeiten mit Amazon Ion-Datentypen in Amazon QLDB.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

ErstErstErstErstErste-Erst

.NET-Treiber