As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Driver Amazon QLDB para Java **Importante** Aviso de fim do suporte: os clientes existentes poderão usar o Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte [Migrar um Amazon QLDB Ledger para o Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL. Para trabalhar com dados em seu livro contábil, você pode se conectar ao Amazon QLDB a partir do seu aplicativo Java usando um driver fornecido. AWS Os tópicos a seguir descrevem como começar a usar o driver QLDB para Java. **Topics** + [Recursos para driver](#getting-started.java.resources) + [Pré-requisitos](#getting-started.java.prereqs) + [Como credenciar suas credenciais AWS e região padrão](#getting-started.java.credentials) + [Instalação](#getting-started.java.install) + [Tutorial de início rápido](driver-quickstart-java.md) + [Referência de Cookbook](driver-cookbook-java.md) ## Recursos para driver Para obter mais informações sobre a funcionalidade suportada pelo driver Java, consulte os recursos a seguir: + Referência de API: [2.x](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/), [1.x](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/1.1.0/index.html) + [Código-fonte do driver (GitHub)](https://github.com/awslabs/amazon-qldb-driver-java) + [Exemplo de código-fonte do aplicativo (GitHub)](https://github.com/aws-samples/amazon-qldb-dmv-sample-java) + [Estrutura do carregador de livros contábeis () GitHub](https://github.com/awslabs/amazon-qldb-ledger-load-java) + [Exemplos de código do Amazon Ion](ion.code-examples.md) ## Pré-requisitos Antes de começar a usar o driver QLDB para Java, você deverá fazer o seguinte: 1. Siga as instruções AWS de configuração em[Acessar o Amazon QLDB](accessing.md). Essa transmissão inclui o seguinte: 1. Inscreva-se em AWS. 1. Crie um usuário com as permissões adequadas para QLDB. 1. Conceda acesso programático para desenvolvimento. 1. Configure um ambiente de desenvolvimento Java baixando e instalando o seguinte: 1. Java SE Development Kit 8, como o [Amazon Corretto 8](https://docs.aws.amazon.com/corretto/latest/corretto-8-ug/downloads-list.html). 1. (Opcional) Ambiente de desenvolvimento integrado (IDE) Java de sua escolha, como [Eclipse](http://www.eclipse.org) ou [IntelliJ](https://www.jetbrains.com/idea/). 1. Configure seu ambiente de desenvolvimento para AWS SDK para Java sempre[Como credenciar suas credenciais AWS e região padrão](#getting-started.java.credentials). Em seguida, você pode baixar o aplicativo completo de amostra do tutorial ou instalar somente o driver em um projeto Java e executar exemplos de códigos curtos. + Para instalar o driver QLDB e AWS SDK para Java o em um projeto existente, vá para. [Instalação](#getting-started.java.install) + Para configurar um projeto e executar exemplos de códigos curtos que demonstram transações básicas de dados em um ledger, consulte o [Tutorial de início rápido](driver-quickstart-java.md). + Para executar exemplos mais detalhados das operações da API de dados e gerenciamento no aplicativo de amostra completo do tutorial, consulte [Tutorial de Java](getting-started.java.tutorial.md). ## Como credenciar suas credenciais AWS e região padrão O driver QLDB e o [AWS SDK para Java](https://aws.amazon.com/sdk-for-java)subjacente exigem que você AWS forneça credenciais para seu aplicativo em tempo de execução. Os exemplos de código neste guia pressupõem que você esteja usando um arquivo de credenciais AWS , conforme descrito em [Configurar credenciais e região padrão](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html#setup-credentials) no *Guia do desenvolvedor do AWS SDK for Java 2.x *. Como parte dessas etapas, você também deve definir seu padrão Região da AWS para determinar seu endpoint QLDB padrão. Os exemplos de código se conectam ao QLDB em sua Região da AWS padrão. Para obter uma lista completa das regiões nas quais o QLDB está disponível, consulte [endpoints e cotas Amazon QLDB](https://docs.aws.amazon.com/general/latest/gr/qldb.html) em *Referência geral da AWS*. Veja a seguir um exemplo de um arquivo de AWS credenciais chamado`~/.aws/credentials`, em que o caractere tilde (`~`) representa seu diretório inicial. ``` [default] aws_access_key_id = your_access_key_id aws_secret_access_key = your_secret_access_key ``` Substitua seus próprios valores de AWS credenciais pelos valores *your\$1access\$1key\$1id* e. *your\$1secret\$1access\$1key* ## Instalação O QLDB é compatível com as seguintes versões do driver Java e AWS suas dependências do SDK. **** | Versão do driver | AWS SDK | Status | Data da versão mais recente | | --- | --- | --- | --- | | [1.x](https://search.maven.org/artifact/software.amazon.qldb/amazon-qldb-driver-java/1.1.0/jar) | AWS SDK para Java 1.x | Lançamento de produção | 20 de março de 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 | Lançamento de produção | 04 de junho de 2021 | Para instalar o driver QLDB, recomendamos usar um sistema de gerenciamento de dependências, como o Gradle ou o Maven. Por exemplo, adicione o artefato a seguir como uma dependência no seu projeto Java. ------ #### [ 2.x ] **Gradle** Adicione essa dependência ao seu arquivo `build.gradle` de configuração. ``` dependencies { compile group: 'software.amazon.qldb', name: 'amazon-qldb-driver-java', version: '2.3.1' } ``` **Maven** Adicione essa dependência ao seu arquivo `pom.xml` de configuração. ``` software.amazon.qldb amazon-qldb-driver-java 2.3.1 ``` Esse artefato inclui automaticamente o módulo AWS SDK for Java 2.x principal, as bibliotecas [Amazon Ion](ion.md) e outras dependências necessárias. ------ #### [ 1.x ] **Gradle** Adicione essa dependência ao seu arquivo `build.gradle` de configuração. ``` dependencies { compile group: 'software.amazon.qldb', name: 'amazon-qldb-driver-java', version: '1.1.0' } ``` **Maven** Adicione essa dependência ao seu arquivo `pom.xml` de configuração. ``` software.amazon.qldb amazon-qldb-driver-java 1.1.0 ``` Esse artefato inclui automaticamente o módulo AWS SDK para Java principal, as bibliotecas [Amazon Ion](ion.md) e outras dependências necessárias. **Importante** **Namespace Amazon Ion**: ao importar classes Amazon Ion em seu aplicativo, você deve usar o pacote que está sob o namespace`com.amazon.ion`. O AWS SDK para Java depende de outro pacote Ion no namespace `software.amazon.ion`, mas esse é um pacote legado que não é compatível com o driver QLDB. ------ Para exemplos de código curto de como executar transações básicas de dados em um ledger, consulte o [Referência de Cookbook](driver-cookbook-java.md). ### Outras bibliotecas opcionais Como opção, adicione também as seguintes bibliotecas úteis ao seu projeto. Esses artefatos são dependências obrigatórias no aplicativo [Tutorial de Java](getting-started.java.tutorial.md) de amostra. 1. [aws-java-sdk-qldb](https://search.maven.org/artifact/com.amazonaws/aws-java-sdk-qldb/1.11.785/jar)— O módulo QLDB do. AWS SDK para Java A versão mínima compatível do QLDB é `1.11.785`. Use esse módulo em seu aplicativo para interagir diretamente com as operações da API de gerenciamento listadas no [Referência da API do Amazon QLDB](api-reference.md). 1. [jackson-dataformat-ion](https://search.maven.org/artifact/com.fasterxml.jackson.dataformat/jackson-dataformat-ion/2.10.0/bundle)— Módulo de formato de dados Jackson do FasterXML para Ion. O aplicativo de amostra requer uma versão `2.10.0` ou posterior. ------ #### [ Gradle ] Adicione essas dependências ao seu arquivo de configuração `build.gradle`. ``` 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 ] Adicione essas dependências ao seu arquivo de configuração `pom.xml`. ``` com.amazonaws aws-java-sdk-qldb 1.11.785 com.fasterxml.jackson.dataformat jackson-dataformat-ion 2.10.0 ``` ------ # Driver Amazon QLDB para Python: tutorial de início rápido **Importante** Aviso de fim do suporte: os clientes existentes poderão usar o Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte [Migrar um Amazon QLDB Ledger para o Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL. Neste tutorial, você aprenderá como configurar um aplicativo simples usando a versão mais recente do driver QLDB da Amazon para Java. Este guia inclui etapas para instalação do driver e exemplos de códigos curtos de 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](getting-started.java.tutorial.md). **Topics** + [Pré-requisitos](#driver-quickstart-java.prereqs) + [Etapa 1: configurar o projeto do](#driver-quickstart-java.step-1) + [Etapa 2: Inicializar o driver](#driver-quickstart-java.step-2) + [Etapa 3: Crie uma tabela e um índice](#driver-quickstart-java.step-3) + [Etapa 4: Inserir um documento](#driver-quickstart-java.step-4) + [Etapa 5: consultar o documento](#driver-quickstart-java.step-5) + [Etapa 6: Atualize o documento](#driver-quickstart-java.step-6) + [Executar o aplicativo completo](#driver-quickstart-java.complete) ## Pré-requisitos Antes de iniciar, certifique-se de fazer o seguinte: 1. Complete a [Pré-requisitos](getting-started.java.md#getting-started.java.prereqs) 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 (IDE) Java. 1. Crie um ledger chamado `quick-start`. Para saber como criar um ledger, consulte [Operações básicas para ledgers do Amazon QLDB](ledger-management.basics.md) ou [Etapa 1: criar um novo ledger](getting-started-step-1.md) 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](https://maven.apache.org/index.html) para este tutorial. **nota** Se você usa um IDE que tenha atributos para automatizar essas etapas de configuração, pode pular para [Etapa 2: Inicializar o driver](#driver-quickstart-java.step-2). 1. Crie uma pasta para o seu aplicativo. ``` $ mkdir myproject $ cd myproject ``` 1. Digite o comando a seguir para Inicializar o projeto a partir de um modelo Maven. Substitua *project-package**project-name*, e *maven-template* por seus próprios valores, conforme apropriado. ``` $ mvn archetype:generate -DgroupId=project-package \ -DartifactId=project-name \ -DarchetypeArtifactId=maven-template \ -DinteractiveMode=false ``` Para isso*maven-template*, você pode usar o modelo básico do Maven: `maven-archetype-quickstart` 1. Para adicionar o [driver QLDB para Java](https://search.maven.org/artifact/software.amazon.qldb/amazon-qldb-driver-java/2.3.1/jar) como uma dependência do projeto, navegue até o arquivo `pom.xml` recém-criado e adicione o artefato a seguir. ``` software.amazon.qldb amazon-qldb-driver-java 2.3.1 ``` Esse artefato inclui automaticamente o módulo [AWS SDK for Java 2.x](https://aws.amazon.com/sdk-for-java) principal, as bibliotecas [Amazon Ion](ion.md) e outras dependências necessárias. Seu arquivo `pom.xml` deverá ser semelhante ao seguinte: ``` 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. Abra o arquivo `App.java`. Em seguida, adicione incrementalmente os exemplos de código nas etapas a seguir para experimentar algumas operações básicas de CRUD. Ou você pode pular o step-by-step tutorial e, em vez disso, executar o [aplicativo completo](#driver-quickstart-java.complete). ## 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](ql-reference.create-index.md) são necessários para otimizar o desempenho da consulta e ajudar a limitar as exceções de conflitos de [controle de simultaneidade otimista (OCC)](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)"); }); ``` ## Etapa 4: Inserir um documento O exemplo de código a seguir mostra como executar uma instrução `INSERT`. O QLDB suporta a linguagem de consulta [partiQL](ql-reference.md) (compatível com SQL) e o formato de dados [Amazon Ion ](ion.md) (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](ql-reference.insert.md) instrução, você pode passar um parâmetro do tipo [IonList](driver-working-with-ion.md#driver-ion-list)(convertido explicitamente como um`IonValue`) 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 parameters = new ArrayList<>(); parameters.add(ionSys.newInt(42)); parameters.add(ionSys.newString("Doe")); txn.execute("UPDATE People SET age = ? WHERE lastName = ?", parameters); }); ``` 1. 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 }); ``` 1. Use o Maven ou seu IDE para compilar e executar o arquivo `App.java`. ## 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 operações básicas do CRUD no ledger denominado `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, *project-package* substitua pelo `groupId` valor que você usou para o comando Maven em[Etapa 1: configurar o projeto do](#driver-quickstart-java.step-1). ``` 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 }); } } ``` Use o Maven ou seu IDE para compilar e executar o arquivo `App.java`. # Driver Amazon QLDB para Java — Referência do livro de receitas **Importante** Aviso de fim do suporte: os clientes existentes poderão usar o Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte [Migrar um Amazon QLDB Ledger para o Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL. Este guia de referência mostra casos de uso comuns do driver Amazon QLDB para Java. Ele fornece exemplos de código Java que demonstram como usar o driver para executar operações básicas CRUD (*create, read, update, delete*). Também inclui exemplos de código para processamento de dados do Amazon Ion. Além disso, este guia destaca as práticas recomendadas para tornar as transações idempotentes e implantar restrições de exclusividade. **nota** Quando aplicável, alguns casos de uso têm exemplos de código diferentes para cada versão principal com suporte do driver QLDB para Java. **Contents** + [Importação do driver](#cookbook-java.importing) + [Instanciação do driver](#cookbook-java.instantiating) + [Operações de CRUD](#cookbook-java.crud) + [Criar tabelas](#cookbook-java.crud.creating-tables) + [Criar índices](#cookbook-java.crud.creating-indexes) + [Ler documentos](#cookbook-java.crud.reading) + [Inserir documentos](#cookbook-java.crud.inserting) + [Como inserir vários documentos em uma instrução](#cookbook-java.crud.inserting.multiple) + [Como atualizar documentos](#cookbook-java.crud.updating) + [Como excluir documentos](#cookbook-java.crud.deleting) + [Como executar várias instruções em uma transação](#cookbook-java.crud.multi-statement) + [Lógica de novas tentativas](#cookbook-java.crud.retry-logic) + [Implementação de restrições de exclusividade](#cookbook-java.crud.uniqueness-constraints) + [Como trabalhar com o Amazon Ion](#cookbook-java.ion) + [Importando os pacotes Ion](#cookbook-java.ion.importing) + [Inicializando Ion](#cookbook-java.ion.initializing) + [Criação de objetos do Ion](#cookbook-java.ion.creating) + [Leitura de objetos do Ion](#cookbook-java.ion.reading) ## Importação do driver O exemplo de código a seguir importa o driver, o cliente de sessão do QLDB, os pacotes Amazon Ion, e outras dependências relacionadas. ------ #### [ 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; ``` ------ ## Instanciação do driver O exemplo de código a seguir cria uma instância de driver que se conecta a um nome do ledger especificado e usa a [lógica de repetição](#cookbook-java.crud.retry-logic) especificada com um limite de repetição personalizado. **nota** Este exemplo também instancia um objeto do sistema Amazon Ion (`IonSystem`). Você precisa desse objeto para processar dados Ion ao executar algumas operações de dados nesta referência. Para saber mais, consulte [Como trabalhar com o 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(); ``` ------ ## Operações de CRUD O QLDB *executa operações de criação, leitura, atualização e exclusão* (CRUD) como parte de uma transação. **Atenção** Como prática recomendada, torne suas transações de gravação estritamente idempotentes. **Tornar as transações idempotentes** Recomendamos que você torne as transações de gravação idempotentes para evitar efeitos colaterais inesperados no caso de novas tentativas. Uma transação é *idempotente* se puder ser executada várias vezes e produzir resultados idênticos a cada vez. Por exemplo, considere uma transação que insere um documento em uma tabela chamada `Person`. A transação deve primeiro verificar se o documento já existe ou não na tabela. Sem essa verificação, a tabela pode acabar com documentos duplicados. Suponha que o QLDB confirme com sucesso a transação no lado do servidor, mas o tempo do cliente expire enquanto espera por uma resposta. Se a transação não for idempotente, o mesmo documento poderá ser inserido mais de uma vez no caso de uma nova tentativa. **Usar índices para evitar varreduras completas da tabela** Também recomendamos executar instruções com uma cláusula de predicado `WHERE` usando um operador de *igualdade* em um campo indexado ou em um ID de documento, por exemplo, `WHERE indexedField = 123` ou `WHERE indexedField IN (456, 789)`. Sem essa pesquisa indexada, o QLDB precisa fazer uma varredura de tabela, o que pode levar a tempos limite de transação ou conflitos *otimistas de controle de simultaneidade* (OCC). Para obter mais informações sobre OCC, consulte [Modelo de simultaneidade do Amazon QLDB](concurrency.md). **Transações criadas implicitamente** O método [QldbDriver.execute](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/software/amazon/qldb/QldbDriver.html) aceita uma função lambda que recebe uma instância do [Executor](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/software/amazon/qldb/Executor.html), que você pode usar para executar instruções. A instância `Executor` envolve uma transação criada implicitamente. Você pode executar instruções na função do Lambda usando o método `Executor.execute`. O driver confirma implicitamente a transação quando a função do Lambda retorna. As seções a seguir mostram como executar operações CRUD básicas, especificar a lógica de repetição personalizada e implementar restrições de exclusividade. **nota** Quando aplicável, essas seções fornecem exemplos de código de processamento de dados do Amazon Ion usando a biblioteca Ion integrada e a biblioteca Jackson Ion mapper. Para saber mais, consulte [Como trabalhar com o Amazon Ion](#cookbook-java.ion). **Contents** + [Criar tabelas](#cookbook-java.crud.creating-tables) + [Criar índices](#cookbook-java.crud.creating-indexes) + [Ler documentos](#cookbook-java.crud.reading) + [Inserir documentos](#cookbook-java.crud.inserting) + [Como inserir vários documentos em uma instrução](#cookbook-java.crud.inserting.multiple) + [Como atualizar documentos](#cookbook-java.crud.updating) + [Como excluir documentos](#cookbook-java.crud.deleting) + [Como executar várias instruções em uma transação](#cookbook-java.crud.multi-statement) + [Lógica de novas tentativas](#cookbook-java.crud.retry-logic) + [Implementação de restrições de exclusividade](#cookbook-java.crud.uniqueness-constraints) ### Criar tabelas ``` qldbDriver.execute(txn -> { txn.execute("CREATE TABLE Person"); }); ``` ### Criar índices ``` qldbDriver.execute(txn -> { txn.execute("CREATE INDEX ON Person(GovId)"); }); ``` ### Ler documentos ``` // 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 }); ``` **Como usar parâmetros de consulta** O exemplo de código a seguir usa um parâmetro de consulta do tipo 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 }); ``` O exemplo de código a seguir usa múltiplos parâmetros de consulta. ``` 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 }); ``` O exemplo de código a seguir usa uma lista de parâmetros de consulta. ``` 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 }); ``` #### Usar o mapeador Jackson ``` // 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(); } }); ``` **Como usar parâmetros de consulta** O exemplo de código a seguir usa um parâmetro de consulta do tipo 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(); } }); ``` O exemplo de código a seguir usa múltiplos parâmetros de consulta. ``` 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(); } }); ``` O exemplo de código a seguir usa uma lista de parâmetros de consulta. ``` 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(); } }); ``` **nota** Quando você executa uma consulta sem uma pesquisa indexada, ela invoca uma verificação completa da tabela. Neste exemplo, recomendamos ter um [índice](ql-reference.create-index.md) no campo `GovId` para otimizar o desempenho. Sem um índice em `GovId`, as consultas podem ter mais latência e também podem levar a exceções de conflitos de OCC ou a tempos limite de transação. ### Inserir documentos Os exemplos de código a seguir inserem os tipos de dados Ion. ``` 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); } }); ``` #### Usar o mapeador Jackson Os exemplos de código a seguir inserem os tipos de dados Ion. ``` 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(); } }); ``` Essa transação insere um documento na tabela `Person`. Antes de inserir, ele primeiro verifica se o documento já existe na tabela. **Essa verificação torna a transação idempotente por natureza.** Mesmo que você execute essa transação várias vezes, ela não causará efeitos colaterais indesejados. **nota** Neste exemplo, recomendamos ter um índice no campo `GovId` para otimizar o desempenho. Sem um índice em `GovId`, as instruções podem ter mais latência e também podem levar a exceções de conflitos de OCC ou a tempos limite de transação. #### Como inserir vários documentos em uma instrução Para inserir vários documentos usando uma única [INSERT](ql-reference.insert.md) instrução, você pode passar um parâmetro do tipo [IonList](driver-working-with-ion.md#driver-ion-list)(convertido explicitamente como um`IonValue`) 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*. ##### Por que o elenco explícito é necessário? O [TransactionExecutormétodo.execute](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/software/amazon/qldb/TransactionExecutor.html) está sobrecarregado. Ele aceita um número variável de `IonValue` argumentos (*varargs*) ou um único argumento `List`. Em [ion-java](https://www.javadoc.io/doc/com.amazon.ion/ion-java/latest/index.html), `IonList` é implementado como um `List`. O Java usa como padrão a implantação do método mais específico quando você chama um método sobrecarregado. Nesse caso, quando você passa um parâmetro `IonList`, o padrão é o método que usa a `List`. Quando invocada, essa implementação de método passa os elementos `IonValue` da lista como valores distintos. Portanto, para invocar o método varargs em vez disso, você deve converter explicitamente um parâmetro `IonList` em `IonValue`. ### Como atualizar documentos ``` 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); }); ``` #### Usar o mapeador Jackson ``` 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(); } }); ``` **nota** Neste exemplo, recomendamos ter um índice no campo `GovId` para otimizar o desempenho. Sem um índice em `GovId`, as instruções podem ter mais latência e também podem levar a exceções de conflitos de OCC ou a tempos limite de transação. ### Como excluir documentos ``` qldbDriver.execute(txn -> { txn.execute("DELETE FROM Person WHERE GovId = ?", SYSTEM.newString("TOYENC486FH")); }); ``` #### Usar o mapeador Jackson ``` qldbDriver.execute(txn -> { try { txn.execute("DELETE FROM Person WHERE GovId = ?", MAPPER.writeValueAsIonValue("TOYENC486FH")); } catch (IOException e) { e.printStackTrace(); } }); ``` **nota** Neste exemplo, recomendamos ter um índice no campo `GovId` para otimizar o desempenho. Sem um índice em `GovId`, as instruções podem ter mais latência e também podem levar a exceções de conflitos de OCC ou a tempos limite de transação. ### Como executar várias instruções em uma transação ``` // 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; }); } ``` ### Lógica de novas tentativas O método `execute` do driver tem um mecanismo de repetição integrado que repete a transação se ocorrer uma exceção que pode ser repetida (como tempos limite ou conflitos de OCC). ------ #### [ 2.x ] O número máximo de tentativas de repetição e a estratégia de recuo são configuráveis. O limite padrão de repetição é`4`, e a estratégia de recuo padrão é. [DefaultQldbTransactionBackoffStrategy](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/software/amazon/qldb/DefaultQldbTransactionBackoffStrategy.html) Você pode definir a configuração de repetição por instância de driver e também por transação usando uma instância de [RetryPolicy](https://javadoc.io/doc/software.amazon.qldb/amazon-qldb-driver-java/latest/software/amazon/qldb/RetryPolicy.html). O exemplo de código a seguir especifica a lógica de repetição com um limite de repetição personalizado e uma estratégia de recuo personalizada para uma instância do driver. ``` 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()); } } ``` O exemplo de código a seguir especifica a lógica de repetição com um limite de repetição personalizado e uma estratégia de recuo personalizada para uma instância particular. Essa configuração para `execute` substitui a lógica de repetição definida para a instância do driver. ``` 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 ] O número máximo de tentativas de repetição pode ser configurado. Você pode configurar o limite de novas tentativas definindo a propriedade `retryLimit` ao inicializar `PooledQldbDriver`. O limite padrão de novas tentativas é `4`. ------ ### Implementação de restrições de exclusividade O QLDB não oferece suporte a índices exclusivos, mas você pode implementar esse comportamento em seu aplicativo. Suponha que você queira implementar uma restrição de exclusividade no campo `GovId` da tabela `Person`. Para fazer isso, você pode escrever uma transação que faça o seguinte: 1. Afirme que a tabela não tem documentos existentes com um `GovId` especificado. 1. Insira o documento se a afirmação for aprovada. Se uma transação concorrente passar simultaneamente pela declaração, somente uma das transações será confirmada com sucesso. A outra transação falhará com uma exceção de conflito de OCC. O exemplo de código a seguir mostra como implementar essa lógica de restrição de exclusividade. ``` 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); } }); ``` **nota** Neste exemplo, recomendamos ter um índice no campo `GovId` para otimizar o desempenho. Sem um índice em `GovId`, as instruções podem ter mais latência e também podem levar a exceções de conflitos de OCC ou a tempos limite de transação. ## Como trabalhar com o Amazon Ion Há várias maneiras de processar dados do Amazon Ion no QLDB. Você pode usar métodos integrados da [biblioteca Ion](https://github.com/amzn/ion-java) para criar e modificar documentos com flexibilidade, conforme necessário. Ou você pode usar o [módulo de formato de dados Jackson do FasterXML para Ion para](https://github.com/FasterXML/jackson-dataformats-binary/tree/master/ion) mapear documentos Ion para modelos *simples de objetos Java antigos* (POJO). As seções a seguir fornecem exemplos de código de processamento de dados Ion usando ambas as técnicas. **Contents** + [Importando os pacotes Ion](#cookbook-java.ion.importing) + [Inicializando Ion](#cookbook-java.ion.initializing) + [Criação de objetos do Ion](#cookbook-java.ion.creating) + [Leitura de objetos do Ion](#cookbook-java.ion.reading) ### Importando os pacotes Ion Adicione o artefato [ion-java](https://search.maven.org/artifact/com.amazon.ion/ion-java/1.6.1/bundle) como uma dependência em seu projeto Java. ------ #### [ Gradle ] ``` dependencies { compile group: 'com.amazon.ion', name: 'ion-java', version: '1.6.1' } ``` ------ #### [ Maven ] ``` com.amazon.ion ion-java 1.6.1 ``` ------ Importe os seguintes pacotes de Ion. ``` import com.amazon.ion.IonStruct; import com.amazon.ion.IonSystem; import com.amazon.ion.system.IonSystemBuilder; ``` #### Usar o mapeador Jackson Adicione o artefato [jackson-dataformat-ion](https://search.maven.org/artifact/com.fasterxml.jackson.dataformat/jackson-dataformat-ion/2.10.0/bundle)como uma dependência em seu projeto Java. O QLDB requer uma versão `2.10.0` ou posterior. ------ #### [ 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 ``` ------ Importe os seguintes pacotes de Ion. ``` 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; ``` ### Inicializando Ion ``` IonSystem SYSTEM = IonSystemBuilder.standard().build(); ``` #### Usar o mapeador Jackson ``` IonObjectMapper MAPPER = new IonValueMapper(IonSystemBuilder.standard().build()); ``` ### Criação de objetos do Ion O exemplo de código a seguir cria um objeto Ion usando a interface `IonStruct` e seus métodos integrados. ``` 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 ``` #### Usar o mapeador Jackson Suponha que você tenha uma classe de modelo mapeada em JSON com o nome `Person` a seguir. ``` 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; } } ``` O exemplo de código a seguir cria um objeto `IonStruct` a partir de uma instância de `Person`. ``` IonStruct ionStruct = (IonStruct) MAPPER.writeValueAsIonValue(new Person("Brent", "TOYENC486FH")); ``` ### Leitura de objetos do Ion O exemplo de código a seguir imprime cada campo da instância `ionStruct`. ``` // ionStruct is an instance of IonStruct System.out.println(ionStruct.get("GovId")); // prints TOYENC486FH System.out.println(ionStruct.get("FirstName")); // prints Brent ``` #### Usar o mapeador Jackson O exemplo de código a seguir lê o objeto e mapas de `IonStruct` a partir de uma instância de `Person`. ``` // 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 ``` Para obter mais informações sobre como trabalhar com o Ion, consulte a [documentação do Amazon Ion](http://amzn.github.io/ion-docs/) em GitHub. Para obter mais exemplos de código sobre como trabalhar com o Ion no QLDB, consulte [Como trabalhar com tipos de dados do Amazon Ion no Amazon QLDB](driver-working-with-ion.md).