Amazon QLDB driver for Java

Important

End of support notice: Existing customers will be able to use Amazon QLDB until end of support on 07/31/2025. For more details, see Migrate an Amazon QLDB Ledger to Amazon Aurora PostgreSQL.

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 topics describe how to get started with the QLDB driver for Java.

Topics

• Driver resources
• Prerequisites
• Setting your default AWS credentials and Region
• Installation
• Quick start tutorial
• Cookbook reference

Driver resources

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

• API reference: 2.x, 1.x

• Driver source code (GitHub)

• Sample application source code (GitHub)

• Ledger loader framework (GitHub)

• Amazon Ion code examples

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. This includes the following:

   1. Sign up for AWS.

   2. Create a user with the appropriate QLDB permissions.

   3. Grant programmatic access for development.

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

   1. Java SE Development Kit 8, such as Amazon Corretto 8.

   2. (Optional) Java integrated development environment (IDE) of your choice, such as Eclipse or IntelliJ.

3. Configure your development environment for the AWS SDK for Java by Setting your default AWS credentials and Region.

Next, you can download the complete tutorial sample application—or you can install only the driver in a Java project and run short code examples.

• To install the QLDB driver and the AWS SDK for Java in an existing project, proceed to Installation.

• To set up a project and run short code examples that demonstrate basic data transactions on a ledger, see the Quick start tutorial.

• To run more in-depth examples of both data and management API operations in the complete tutorial sample application, see the Java tutorial.

Setting your default AWS credentials and Region

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

As part of these steps, you should also set your default AWS Region to determine your default QLDB endpoint. The code examples connect to QLDB in your default AWS Region. For a complete list of Regions where QLDB is available, see Amazon QLDB endpoints and quotas in the AWS General Reference.

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 = your_access_key_id
aws_secret_access_key = your_secret_access_key

Substitute your own AWS credentials values for the values your_access_key_id and your_secret_access_key.

Installation

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.x	AWS SDK for Java 2.x	Production release	June 4, 2021

To install the QLDB driver, we recommend using a dependency management system, such as Gradle or Maven. For example, add the following artifact as a dependency in your Java project.

2.x

Gradle

Add this dependency in your build.gradle configuration file.

dependencies {
    compile group: 'software.amazon.qldb', name: 'amazon-qldb-driver-java', version: '2.3.1'
}

Maven

Add this dependency in your pom.xml configuration file.

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

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

1.x

Gradle

Add this dependency in your build.gradle configuration file.

dependencies {
    compile group: 'software.amazon.qldb', name: 'amazon-qldb-driver-java', version: '1.1.0'
}

Maven

Add this dependency in your pom.xml configuration file.

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

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

Important

Amazon Ion namespace – When importing Amazon Ion classes in your application, you must use the package that is under the namespace com.amazon.ion. 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.

For short code examples of how to run basic data transactions on a ledger, see the Cookbook reference.

Other optional libraries

Optionally, you can also add the following useful libraries in your project. These artifacts are required dependencies in the Java tutorial sample application.

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

   Use this module in your application to interact directly with the management API operations listed in the Amazon QLDB API reference.

2. jackson-dataformat-ion – FasterXML's Jackson data format module for Ion. The sample application requires version 2.10.0 or later.

Gradle

Add these dependencies in your build.gradle configuration file.

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

Add these dependencies in your pom.xml configuration file.

<dependencies>
  <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</version>
  </dependency>
</dependencies>