Amazon Quantum Ledger Database (Amazon QLDB)
Developer Guide

Java and Amazon QLDB

In this tutorial, you use the QLDB driver for Java to create an Amazon QLDB ledger and populate it with tables and sample data. The sample ledger that you create in this scenario is a vehicle tracking database that has complete historical information about car registrations.

As you work through this tutorial, the following sections explain how to add vehicle registrations, modify them, and view the history of changes to those registrations. This guide also shows you how to cryptographically verify a registration document, and concludes by cleaning up resources and deleting the sample ledger.

Note

This tutorial has step-by-step instructions on setting up and running the Java sample application. To quickly get started instead, we recommend downloading the sample application that packages the necessary QLDB dependencies and the source code from the tutorial. For instructions on downloading and running the complete sample application, see Running the Java Sample Application in Amazon QLDB.

Tutorial Prerequisites

Before you start this tutorial, you must do the following:

  1. Follow the AWS setup instructions in Accessing Amazon QLDB.

  2. Install a Java development environment.

  3. Set up your AWS credentials and Region for development:

  4. Add the Amazon QLDB Driver for Java. The driver enables your application to interact with QLDB using the transactional data API.

Add the Amazon QLDB Driver for Java

To work with data in your ledger, you can connect to Amazon QLDB from your Java application using an AWS-provided driver. Then you can code your application to use transactional data APIs.

Add the following artifacts as dependencies in your Java project:

The Amazon QLDB driver for Java and other project dependencies

  1. The QLDB driver for Java is available in the Maven Central Repository under artifact name amazon-qldb-driver-java. This artifact automatically includes the AWS SDK for Java core module, Amazon Ion libraries, and other required dependencies.

  2. The QLDB module of the AWS SDK for Java enables your application to interact with the ledger management API operations listed in the Amazon QLDB API Reference.

  3. To run the sample application in the Getting Started with the Driver tutorial for Java, you also need the open source Jackson data format module for Ion. The vehicle registration application requires version 2.10.0.pr1 of this module. This module is available in Maven Central under artifact name jackson-dataformat-ion.

    If you are using your own application to interact with QLDB, you don't need to add this Jackson dependency to your project.

For example, if you use Maven or Gradle as your build tool, add the following dependencies in your pom.xml (Maven) or build.gradle (Gradle) configuration file.

MavenGradle
Maven
<dependencies> <dependency> <groupId>software.amazon.qldb</groupId> <artifactId>amazon-qldb-driver-java</artifactId> <version>1.0.1</version> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-java-sdk-qldb</artifactId> <version>1.11.628</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.dataformat</groupId> <artifactId>jackson-dataformat-ion</artifactId> <version>2.10.0.pr1</version> </dependency> </dependencies>
Gradle
dependencies { compile group: 'software.amazon.qldb', name: 'amazon-qldb-driver-java', version: '1.0.1' compile group: 'com.amazonaws', name: 'aws-java-sdk-qldb', version: '1.11.628' compile group: 'com.fasterxml.jackson.dataformat', name: 'jackson-dataformat-ion', version: '2.10.0.pr1' }

The Java driver source code is available in the amazon-qldb-driver-java repository on the AWS Labs GitHub site.

After you add the driver to your Java project, proceed to Step 1: Create a New Ledger in Getting Started with the Driver for example code that demonstrates how to create a new ledger and create a session that connects your application to the ledger.

Executing Transactions with the Driver

With the QLDB driver for Java, you can create a session with connectivity to a specific ledger in QLDB. This session enables you to execute PartiQL statements and retrieve the results of those statements. You can also take control over transactions to group multiple executions within a transaction.

To learn how to use the driver to control transactions and handle possible exceptions, see Handling Transaction Exceptions in the Concurrency Model section.

Driver API Javadoc

For information about the functionality supported by this driver, see the QLDB Driver API Javadoc.