Amazon QLDB Driver for Java - Amazon Quantum Ledger Database (Amazon QLDB)

Amazon QLDB Driver for Java

To work with data in your ledger, you can connect to Amazon QLDB from your Java application by using an AWS-provided driver. The following sections describe how to get started with the QLDB Driver for Java.

Driver Resources

For more information about the functionality supported by the Java driver, see the following resources:

Prerequisites

Before you get started with the QLDB Driver for Java, you must do the following:

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

  2. Choose a Java integrated development environment (IDE):

    • AWS Cloud9 (recommended) – Use AWS Cloud9 as your Java IDE and automate setup of the QLDB sample application with a provided AWS CloudFormation template. This option requires the least amount of manual installation and configuration work.

      For this option, skip the rest of this section and proceed to the Java Tutorial. Then, follow the AWS Cloud9 steps in Installing the Sample Application.

    • Other IDE – Use your own development resources to manually install your preferred IDE.

      For this option, continue the following setup steps.

  3. Set up a Java development environment by downloading and installing the following:

  4. Configure your AWS credentials and Region for development:

Next, you can download the complete tutorial sample application—or you can install only the driver in an existing Java project.

  • To run the complete tutorial with the QLDB sample application, see the Java Tutorial.

  • To install only the QLDB Driver and the AWS SDK for Java in an existing project, proceed to Installation (Driver Only).

Setting Your AWS Credentials

The QLDB Driver and the underlying AWS SDK for Java 2.x require that you provide AWS credentials to your application at runtime. The code examples in this guide assume that you are using an AWS credentials file, as described in Set up AWS Credentials and Region for Development in the AWS SDK for Java 2.x Developer Guide.

The following is an example of an AWS credentials file named ~/.aws/credentials, where the tilde character (~) represents your home directory.

[default] aws_access_key_id = AWS access key ID goes here aws_secret_access_key = Secret key goes here

Setting the AWS Region and Endpoint

As part of the previous step to set up your AWS credentials, you should also set your default AWS Region. The sample application connects to QLDB in your default AWS Region. You can also change the Region in your code by modifying the AmazonQLDB client object (control plane) or the QldbSessionClientBuilder object (transactional data plane).

The following code example instantiates a new AmazonQLDB client object.

import com.amazonaws.regions.Regions; import com.amazonaws.services.qldb.AmazonQLDB; import com.amazonaws.services.qldb.AmazonQLDBClientBuilder; // This client will default to US East (Ohio) AmazonQLDB client = AmazonQLDBClientBuilder.standard() .withRegion(Regions.US_EAST_2) .build();

You can use the withRegion method to run your code against QLDB in any Region where it is available. For a complete list, see Amazon QLDB Endpoints and Quotas in the Amazon Web Services General Reference.

Installation (Driver Only)

QLDB supports the following Java driver versions and their AWS SDK dependencies.

Driver version AWS SDK Status Latest release date
1.x AWS SDK for Java 1.x Production release March 20, 2020
2.0.0-rc.1 AWS SDK for Java 2.x Release candidate June 22, 2020

To install the QLDB Driver and the AWS SDK for Java, we recommend using a dependency management system, such as Gradle or Maven. Add the following artifacts as dependencies in your Java project:

2.x
  1. amazon-qldb-driver-java – The QLDB Driver for Java. The latest version is 2.0.0-rc.1.

    Warning

    This version is a release candidate and is subject to change. It might not be production ready.

    This artifact automatically includes the AWS SDK for Java 2.x core module, Amazon Ion libraries, and other required dependencies.

  2. aws-java-sdk-qldb – The QLDB module of the AWS SDK for Java. The minimum QLDB-supported version is 1.11.785.

    This module enables your application to interact with the control plane API operations listed in the Amazon QLDB API Reference.

  3. jackson-dataformat-ion – (Optional) The open source Jackson data format module for Ion. You need this artifact to run the code in the Java Tutorial. The sample application requires version 2.10.0.pr1 or later.

    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 Gradle or Maven as your build tool, add the following dependencies in your build.gradle (Gradle) or pom.xml (Maven) configuration file.

Example — Gradle

dependencies { compile group: 'software.amazon.qldb', name: 'amazon-qldb-driver-java', version: '2.0.0-rc.1' 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.pr1' }

Example — Maven

<dependencies> <dependency> <groupId>software.amazon.qldb</groupId> <artifactId>amazon-qldb-driver-java</artifactId> <version>2.0.0-rc.1</version> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-java-sdk-qldb</artifactId> <version>1.11.785</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.dataformat</groupId> <artifactId>jackson-dataformat-ion</artifactId> <version>2.10.0.pr1</version> </dependency> </dependencies>
1.x
  1. amazon-qldb-driver-java – The QLDB Driver for Java. The latest version is 1.1.0.

    This artifact automatically includes the AWS SDK for Java core module, Amazon Ion libraries, and other required dependencies.

    Important

    Amazon Ion namespace – You must use the Amazon Ion package that is under the namespace com.amazon.ion in your application. The AWS SDK for Java depends on another Ion package under the namespace software.amazon.ion, but this is a legacy package that is not compatible with the QLDB driver.

  2. aws-java-sdk-qldb – The QLDB module of the AWS SDK for Java. The minimum QLDB-supported version is 1.11.785.

    This module enables your application to interact with the control plane API operations listed in the Amazon QLDB API Reference.

  3. jackson-dataformat-ion – (Optional) The open source Jackson data format module for Ion. You need this artifact to run the code in the Java Tutorial. The sample application requires version 2.10.0.pr1 or later.

    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 Gradle or Maven as your build tool, add the following dependencies in your build.gradle (Gradle) or pom.xml (Maven) configuration file.

Example — Gradle

dependencies { compile group: 'software.amazon.qldb', name: 'amazon-qldb-driver-java', version: '1.1.0' 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.pr1' }

Example — Maven

<dependencies> <dependency> <groupId>software.amazon.qldb</groupId> <artifactId>amazon-qldb-driver-java</artifactId> <version>1.1.0</version> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-java-sdk-qldb</artifactId> <version>1.11.785</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.dataformat</groupId> <artifactId>jackson-dataformat-ion</artifactId> <version>2.10.0.pr1</version> </dependency> </dependencies>

For code examples that demonstrate operations such as how to create a ledger and run data transactions on a ledger, see the Java Tutorial.