Pilote Amazon QLDB pour Java — Tutoriel de démarrage rapide - Amazon Quantum Ledger Database (Amazon QLDB)
PrérequisÉtape 1 : Configurer votre projet Étape 2 : Initialiser le piloteÉtape 3 : création d'une table et d'un indexÉtape 4 : Insertion d'un documentÉtape 5 : interroger le documentÉtape 6 : Mettre à jour le documentExécution de l'application complète

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Pilote Amazon QLDB pour Java — Tutoriel de démarrage rapide

Dans ce tutoriel, vous apprendrez comment configurer une application simple à l'aide de la dernière version du pilote Amazon QLDB pour Java. Ce guide inclut les étapes d'installation du pilote et des exemples de base de création, mise à jour et suppression (CRUD). Pour des exemples plus détaillés illustrant ces opérations dans un exemple d'application complet, consultez leTutoriel Java.

Prérequis

Avant de commencer, veillez à exécuter les actions suivantes :

  1. Complétez lePrérequis pour le pilote Java, si vous ne l'avez pas déjà fait. Cela inclut l'inscriptionAWS, l'octroi d'un accès programmatique pour le développement et l'installation d'un environnement de développement intégré (IDE) Java.

  2. Créez un registre nomméquick-start.

    Pour savoir comment créer un registre, consultezOpérations de base pour les registres Amazon QLDB ouÉtape 1 : Créer un nouveau registre dans Prise en main de la console.

Étape 1 : Configurer votre projet

Tout d'abord, configurez votre projet Java. Nous vous recommandons d'utiliser le système de gestion des dépendances Maven pour ce didacticiel.

Note

Si vous utilisez un IDE doté de fonctionnalités permettant d'automatiser ces étapes de configuration, vous pouvez passer directement àÉtape 2 : Initialiser le pilote.

  1. Créez un dossier pour votre application.

    $ mkdir myproject
$ cd myproject

  2. Saisissez la commande suivante pour initialiser votre projet à partir d'un modèle Maven. Remplacez le package du projet, le nom du projet et le modèle maven par vos propres valeurs, le cas échéant.

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

    Pour maven-template, vous pouvez utiliser le modèle Maven de base :maven-archetype-quickstart

  3. Pour ajouter le pilote QLDB pour Java en tant que dépendance de projet, accédez aupom.xml fichier que vous venez de créer et ajoutez l'artefact suivant.

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

    Cet artefact inclut automatiquement le module AWS SDK for Java 2.xprincipal, les bibliothèques Amazon Ion et les autres dépendances requises. Votrepom.xml fichier doit maintenant se présenter comme suit :

    <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. Ouvrez le fichier App.java.

    Ajoutez ensuite progressivement les exemples de code dans les étapes suivantes pour essayer certaines opérations CRUD de base. Vous pouvez également ignorer le step-by-step didacticiel et exécuter l'application complète.

Étape 2 : Initialiser le pilote

Initialisez une instance du pilote qui se connecte au registre nomméquick-start. Ajoutez le code suivant à votreApp.java fichier.

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

Étape 3 : création d'une table et d'un index

L'exemple de code suivant montre comment exécuterCREATE TABLE lesCREATE INDEX instructions and.

Dans lamain méthode, ajoutez le code suivant qui crée une table nomméePeople et un index pour lelastName champ de cette table. Les index sont nécessaires pour optimiser les performances des requêtes et contribuer à limiter les exceptions de conflit liées au contrôle optimiste de la concurrence (OCC).

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

Étape 4 : Insertion d'un document

L'exemple de code suivant montre comment exécuter uneINSERT instruction. QLDB prend en charge le langage de requête PartiQL (compatible SQL) et le format de données Amazon Ion (surensemble de JSON).

Ajoutez le code suivant pour insérer un document dans lePeople tableau.

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

Cet exemple utilise un point d'interrogation (?) comme espace réservé variable pour transmettre les informations du document à l'instruction. Lorsque vous utilisez des espaces réservés, vous devez transmettre une valeur de typeIonValue.

Astuce

Pour insérer plusieurs documents à l'aide d'une seuleINSERT instruction, vous pouvez transmettre un paramètre de type IonList(explicitement converti en tant queIonValue) à l'instruction comme suit.

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

Vous ne placez pas l'espace réservé à la variable (?) entre crochets (<<...>>) lorsque vous transmettez unIonList. Dans les instructions manuelles de PartiQL, les crochets doubles indiquent une collection non ordonnée appelée sac.

Étape 5 : interroger le document

L'exemple de code suivant montre comment exécuter uneSELECT instruction.

Ajoutez le code suivant qui interroge un document à partir duPeople tableau.

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

Étape 6 : Mettre à jour le document

L'exemple de code suivant montre comment exécuter uneUPDATE instruction.

  1. Ajoutez le code suivant pour mettre à jour un document dans lePeople tableau en le mettant à jourage vers42.

    // 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. Interrogez à nouveau le document pour voir la valeur mise à jour.

    // 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. Utilisez Maven ou votre IDE pour compiler et exécuter leApp.java fichier.

Exécution de l'application complète

L'exemple de code suivant représente la version complète de l'App.javaapplication. Au lieu de suivre les étapes précédentes individuellement, vous pouvez également copier et exécuter cet exemple de code du début à la fin. Cette application montre certaines opérations CRUD de base sur le registre nomméquick-start.

Note

Avant d'exécuter ce code, assurez-vous qu'aucune table active n'est déjà nomméePeople dans lequick-start registre.

Sur la première ligne, remplacez project-package par lagroupId valeur que vous avez utilisée pour la commande Maven dansÉtape 1 : Configurer votre projet .

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

Utilisez Maven ou votre IDE pour compiler et exécuter leApp.java fichier.