QLDBDriver Amazon para Java — Tutorial de início rápido

Importante

Aviso de fim do suporte: os clientes existentes poderão usar a Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte Migrar um Amazon QLDB Ledger para o Amazon Aurora Postgre. SQL

Neste tutorial, você aprende a configurar um aplicativo simples usando a versão mais recente do QLDB driver da Amazon para Java. Este guia inclui etapas para instalar o driver e exemplos de códigos curtos das operações básicas de criação, leitura, atualização e exclusão (CRUD). Para obter exemplos mais detalhados que demonstram essas operações em um aplicativo de amostra completo, consulte o Tutorial de Java.

Pré-requisitos

Antes de iniciar, certifique-se de fazer o seguinte:

1. Complete a Pré-requisitos para o driver Java, caso ainda não o tenha feito. Isso inclui se inscrever AWS, conceder acesso programático para desenvolvimento e instalar um ambiente de desenvolvimento integrado Java ()IDE.

2. Crie um ledger chamado quick-start.

   Para saber como criar um ledger, consulte Operações básicas para livros contábeis da Amazon QLDB ou Etapa 1: criar um novo ledger em Conceitos básicos do console.

Etapa 1: configurar o projeto do

Primeiro, configure seu projeto Java. Recomendamos usar o sistema de gerenciamento de dependências Maven para este tutorial.

nota

Se você usa um IDE que tenha recursos para automatizar essas etapas de configuração, você pode pular para. Etapa 2: Inicializar o driver

1. Crie uma pasta para o seu aplicativo.

   $ mkdir myproject
   $ cd myproject

2. Digite o comando a seguir para Inicializar o projeto a partir de um modelo Maven. Substituir project-package, project-name e maven-template com seus próprios valores, conforme apropriado.

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

   Para maven-template, você pode usar o modelo básico do Maven: maven-archetype-quickstart

3. Para adicionar o QLDBdriver para Java como uma dependência do projeto, navegue até o pom.xml arquivo recém-criado e adicione o seguinte artefato.

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

   Esse artefato inclui automaticamente o módulo AWS SDK for Java 2.x principal, as bibliotecas Amazon Ion e outras dependências necessárias. Seu arquivo pom.xml deverá ser semelhante ao seguinte:

   <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. Abra o arquivo App.java.

   Em seguida, adicione incrementalmente os exemplos de código nas etapas a seguir para experimentar algumas CRUD operações básicas. Ou você pode pular o step-by-step tutorial e, em vez disso, executar o aplicativo completo.

Etapa 2: Inicializar o driver

Inicialize uma instância do driver que se conecta ao ledger chamado quick-start. Adicione o seguinte código ao arquivo App.java.

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

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

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

Etapa 3: Crie uma tabela e um índice

O exemplo de código a seguir mostra como executar as instruções CREATE TABLE e CREATE INDEX.

No método main, adicione o código a seguir que cria uma tabela chamada People e um índice para o campo lastName nessa tabela. Os índices são necessários para otimizar o desempenho da consulta e ajudar a limitar as exceções otimistas de conflitos do controle de simultaneidade (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)");
});

Etapa 4: Inserir um documento

O exemplo de código a seguir mostra como executar uma instrução INSERT. QLDBsuporta a linguagem de consulta partiQL (SQLcompatível) e o formato de dados Amazon Ion (superconjunto de). JSON

Adicione o código a seguir que insere um documento na tabela People.

// Insert a document
qldbDriver.execute(txn -> {
    System.out.println("Inserting a document");
    IonStruct person = ionSys.newEmptyStruct();
    person.put("firstName").newString("John");
    person.put("lastName").newString("Doe");
    person.put("age").newInt(32);
    txn.execute("INSERT INTO People ?", person);
});

Este exemplo usa um ponto de interrogação (?) como um marcador variável para passar as informações do documento para a instrução. Ao usar espaços reservados, você deve passar um valor do tipo IonValue.

dica

Para inserir vários documentos usando uma única INSERT instrução, você pode passar um parâmetro do tipo IonList(convertido explicitamente como umIonValue) para a instrução da seguinte maneira.

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

Você não coloca o marcador variável (?) entre colchetes angulares duplos ( <<...>> ) ao passar uma IonList. Nas instruções manuais do PartiQL, colchetes angulares duplos denotam uma coleção não ordenada conhecida como bolsa.

Etapa 5: consultar o documento

O exemplo de código a seguir mostra como executar uma instrução SELECT.

Adicione o código a seguir que insere um documento da tabela People.

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

Etapa 6: Atualize o documento

O exemplo de código a seguir mostra como executar uma instrução UPDATE.

1. Adicione o código a seguir que insere um documento na tabela People, atualizando age para 42.

   // Update the document
   qldbDriver.execute(txn -> {
       System.out.println("Updating the document");
       final List<IonValue> parameters = new ArrayList<>();
       parameters.add(ionSys.newInt(42));
       parameters.add(ionSys.newString("Doe"));
       txn.execute("UPDATE People SET age = ? WHERE lastName = ?", parameters);
   });

2. Consulte a tabela novamente para ver o valor atualizado.

   // 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. Use o Maven ou o seu IDE para compilar e executar o App.java arquivo.

Executar o aplicativo completo

O exemplo de código a seguir é a versão completa do aplicativo App.java. Em vez de executar as etapas anteriores individualmente, você também pode copiar e executar esse exemplo de código do início ao fim. Este aplicativo demonstra algumas CRUD operações básicas no livro contábil chamado. quick-start

nota

Antes de executar esse código, verifique se você ainda não tem uma tabela ativa chamada People no ledger quick-start.

Na primeira linha, substitua project-package com o groupId valor que você usou para o comando Maven emEtapa 1: configurar o projeto do .

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

Use o Maven ou o seu IDE para compilar e executar o App.java arquivo.