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 topics 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:

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.

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.

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.

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>