Amazon QLDB Java tutorial

• Amazon QLDB Node.js tutorial (p. 320)

• Amazon QLDB Python tutorial (p. 358)

In this implementation of the tutorial sample application, you use the Amazon QLDB driver with the AWS SDK for Java to create a QLDB ledger and populate it with sample data.

As you work through this tutorial, you can refer to the AWS SDK for Java API Reference for control plane operations. For transactional data operations, you can refer to the QLDB Driver for Java API Reference.

Note

Where applicable, some tutorial steps have diﬀerent commands or code examples for each supported major version of the QLDB driver for Java.

Topics

• Installing the Amazon QLDB Java sample application (p. 183)

• Step 1: Create a new ledger (p. 186)

• Step 2: Test connectivity to the ledger (p. 195)

• Step 3: Create tables, indexes, and sample data (p. 201)

• Step 4: Query the tables in a ledger (p. 246)

• Step 5: Modify documents in a ledger (p. 250)

• Step 6: View the revision history for a document (p. 261)

• Step 7: Verify a document in a ledger (p. 264)

• Step 8: Export and validate journal data in a ledger (p. 309)

• Step 9 (optional): Clean up resources (p. 316)

Java tutorial

Installing the Amazon QLDB Java sample application

This section describes how to install and run the provided Amazon QLDB sample application for the step-by-step Java tutorial. The use case for this sample application is a department of motor vehicles (DMV) database that tracks the complete historical information about vehicle registrations.

The DMV sample application for Java is open-sourced in the GitHub repository aws-samples/amazon-qldb-dmv-sample-java.

Prerequisites

Before you get started, make sure that you complete the QLDB driver for Java Prerequisites (p. 50).

This includes the following:

1. Sign up for AWS.

2. Create an AWS Identity and Access Management (IAM) user with the appropriate QLDB permissions.

To complete all of the steps in this tutorial, you need full administrative access to your ledger resource through the QLDB API.

3. If you're using an IDE other than AWS Cloud9, install Java and get an IAM access key for development.

Installation

The following steps describe how to download and set up the sample application with a local

development environment. Or, you can automate setup of the sample application by using AWS Cloud9 as your IDE, and an AWS CloudFormation template to provision your development resources.

Local development environment

These instructions describe how to download and install the QLDB Java sample application using your own resources and development environment.

To download and run the sample application

1. Enter the following command to clone the sample application from GitHub.

2.x

git clone -b v2.0.0 https://github.com/aws-samples/amazon-qldb-dmv-sample-java.git

1.x

git clone -b v1.2.0 https://github.com/aws-samples/amazon-qldb-dmv-sample-java.git

This package includes the Gradle conﬁguration and complete code from the Java tutorial (p. 182).

2. Load and run the provided application.

• If you are using Eclipse:

a. Start Eclipse, and on the Eclipse menu, choose File, Import, and then Existing Gradle Project.

b. In the project root directory, browse and select the application directory that contains the build.gradle ﬁle. Then, choose Finish to use the default Gradle settings for the import.

c. You can try running the ListLedgers program as an example. Open the context (right-click) menu for the ListLedgers.java ﬁle, and choose Run as Java Application.

• If you are using IntelliJ:

Java tutorial

a. Start IntelliJ, and on the IntelliJ menu, choose File and then Open.

b. In the project root directory, browse and select the application directory that contains the build.gradle ﬁle. Then, choose OK. Keep the default settings, and choose OK again.

c. You can try running the ListLedgers program as an example. Open the context (right-click) menu for the ListLedgers.java ﬁle, and choose Run 'ListLedgers'.

3. Proceed to Step 1: Create a new ledger (p. 186) to start the tutorial and create a ledger.

AWS Cloud9

These instructions describe how to automate setup of the Amazon QLDB vehicle registration sample application for Java, using AWS Cloud9 as your IDE. In this guide, you use an AWS CloudFormation template to provision your development resources.

For more information about AWS Cloud9, see the AWS Cloud9 User Guide. To learn more about AWS CloudFormation, see the AWS CloudFormation User Guide.

Topics

• Part 1: Provision your resources (p. 184)

• Part 2: Set up your IDE (p. 185)

• Part 3: Run the QLDB DMV sample application (p. 186)

Part 1: Provision your resources

In this ﬁrst step, you use AWS CloudFormation to provision the resources required to set up your development environment with the Amazon QLDB sample application.

To open the AWS CloudFormation console and load the QLDB sample application template 1. Sign in to the AWS Management Console and open the AWS CloudFormation console at https://

console.aws.amazon.com/cloudformation.

Switch to a Region that supports QLDB. For a complete list, see Amazon QLDB endpoints and quotas in the AWS General Reference.

2. On the AWS CloudFormation console, choose Create stack, and then choose With new resources (standard).

3. On the Create stack page under Specify template, choose Amazon S3 URL.

4. Enter the following URL, and choose Next.

https://amazon-qldb-assets.s3.amazonaws.com/templates/QLDB-DMV-SampleApp.yml 5. Enter a Stack name (such as qldb-sample-app), and choose Next.

6. You can add any tags as appropriate and keep the default options. Then choose Next.

7. Review your stack settings, and choose Create stack. The AWS CloudFormation script might take a few minutes to ﬁnish.

This script provisions your AWS Cloud9 environment with an associated Amazon Elastic Compute Cloud (Amazon EC2) instance that you use to run the QLDB sample application in this tutorial. It

Java tutorial

also clones the aws-samples/amazon-qldb-dmv-sample-java repository from GitHub into your AWS Cloud9 development environment.

Part 2: Set up your IDE

In this step, you ﬁnish the setup of your cloud development environment. You download and run a provided shell script to set up your AWS Cloud9 IDE with sample application's dependencies.

To set up your AWS Cloud9 environment

1. Open the AWS Cloud9 console at https://console.aws.amazon.com/cloud9/.

2. Under Your environments, locate the card for the environment named QLDB DMV Sample

Application, and choose Open IDE. Your environment might take a minute to load as the underlying EC2 instance launches.

Your AWS Cloud9 environment is preconﬁgured with the system dependencies that you need to run the tutorial. In the Environment navigation pane of your console, conﬁrm that you see a folder named QLDB DMV Sample Application.

If you don't see a navigation pane, toggle the Environment tab on the left side of your console. If you don't see any folders in the pane, enable Show Environment Root using the settings icon ( ).

3. On the bottom pane of your console, you should see an open bash terminal window. If you don't see this, choose New Terminal from the Window menu at the top of your console.

4. Next, download and run a setup script to install OpenJDK 8 and—if applicable—check out the appropriate branch from the Git repository. In the AWS Cloud9 terminal that you created in the previous step, run the following two commands in order:

2.x

aws s3 cp s3://amazon-qldb-assets/setup-scripts/dmv-setup-v2.sh .

sh dmv-setup-v2.sh 1.x

aws s3 cp s3://amazon-qldb-assets/setup-scripts/dmv-setup.sh .

sh dmv-setup.sh

Upon completion, you should see the following message printed in the terminal:

** DMV Sample App setup completed , enjoy!! **

5. Take a moment to browse the sample application code in AWS Cloud9, particularly in the following directory path: src/main/java/software/amazon/qldb/tutorial.

Java tutorial Part 3: Run the QLDB DMV sample application

In this step, you learn how to run the Amazon QLDB DMV sample application tasks using AWS Cloud9. To run the sample code, go back to your AWS Cloud9 terminal or create a new terminal window as you did in Part 2: Set Up Your IDE.

To run the sample application

1. Run the following command in your terminal to switch to the project root directory:

cd ~/environment/amazon-qldb-dmv-sample-java

Ensure that you are running the examples in the following directory path.

/home/ec2-user/environment/amazon-qldb-dmv-sample-java/

2. The following command shows the Gradle syntax to run each task.

./gradlew run -Dtutorial=Task

For example, run the following command to list all of the ledgers in your AWS account and current Region.

./gradlew run -Dtutorial=ListLedgers

3. Proceed to Step 1: Create a new ledger (p. 186) to start the tutorial and create a ledger.

4. (Optional) After you complete the tutorial, clean up your AWS CloudFormation resources if you no longer need them.

a. Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation, and delete the stack that you created in Part 1: Provision Your Resources.

b. Also delete the AWS Cloud9 stack that the AWS CloudFormation template created for you.

Step 1: Create a new ledger

In this step, you create a new Amazon QLDB ledger named vehicle-registration.

To create a new ledger

1. Review the following ﬁle (Constants.java), which contains constant values that are used by all of the other programs in this tutorial.

2.x

* SPDX-License-Identifier: MIT-0

* * Permission is hereby granted, free of charge, to any person obtaining a copy of this

* software and associated documentation files (the "Software"), to deal in the Software

* without restriction, including without limitation the rights to use, copy, modify,

* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to * permit persons to whom the Software is furnished to do so.

Java tutorial *

* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,

* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT

* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION

* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

* Constant values used throughout this tutorial.

*/public final class Constants {

public static final int RETRY_LIMIT = 4;

public static final String LEDGER_NAME = "vehicle-registration";

public static final String STREAM_NAME = "vehicle-registration-stream";

public static final String VEHICLE_REGISTRATION_TABLE_NAME = "VehicleRegistration";

public static final String VEHICLE_TABLE_NAME = "Vehicle";

public static final String PERSON_TABLE_NAME = "Person";

public static final String DRIVERS_LICENSE_TABLE_NAME = "DriversLicense";

public static final String VIN_INDEX_NAME = "VIN";

public static final String PERSON_GOV_ID_INDEX_NAME = "GovId";

public static final String VEHICLE_REGISTRATION_LICENSE_PLATE_NUMBER_INDEX_NAME = "LicensePlateNumber";

public static final String DRIVER_LICENSE_NUMBER_INDEX_NAME = "LicenseNumber";

public static final String DRIVER_LICENSE_PERSONID_INDEX_NAME = "PersonId";

public static final String JOURNAL_EXPORT_S3_BUCKET_NAME_PREFIX = "qldb-tutorial-journal-export";

public static final String USER_TABLES = "information_schema.user_tables";

public static final String LEDGER_NAME_WITH_TAGS = "tags";

public static final IonSystem SYSTEM = IonSystemBuilder.standard().build();

public static final IonObjectMapper MAPPER = new IonValueMapper(SYSTEM);

private Constants() { } static {

MAPPER.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);

} }

1.x

* SPDX-License-Identifier: MIT-0

* * Permission is hereby granted, free of charge, to any person obtaining a copy of this

* software and associated documentation files (the "Software"), to deal in the Software

* without restriction, including without limitation the rights to use, copy, modify,

Java tutorial

* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to * permit persons to whom the Software is furnished to do so.

* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,

* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT

* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION

* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

* Constant values used throughout this tutorial.

public final class Constants {

public static final int RETRY_LIMIT = 4;

public static final String LEDGER_NAME = "vehicle-registration";

public static final String STREAM_NAME = "vehicle-registration-stream";

public static final String VEHICLE_REGISTRATION_TABLE_NAME = "VehicleRegistration";

public static final String VEHICLE_TABLE_NAME = "Vehicle";

public static final String PERSON_TABLE_NAME = "Person";

public static final String DRIVERS_LICENSE_TABLE_NAME = "DriversLicense";

public static final String VIN_INDEX_NAME = "VIN";

public static final String PERSON_GOV_ID_INDEX_NAME = "GovId";

public static final String VEHICLE_REGISTRATION_LICENSE_PLATE_NUMBER_INDEX_NAME = "LicensePlateNumber";

public static final String DRIVER_LICENSE_NUMBER_INDEX_NAME = "LicenseNumber";

public static final String DRIVER_LICENSE_PERSONID_INDEX_NAME = "PersonId";

public static final String JOURNAL_EXPORT_S3_BUCKET_NAME_PREFIX = "qldb-tutorial-journal-export";

public static final String USER_TABLES = "information_schema.user_tables";

public static final String LEDGER_NAME_WITH_TAGS = "tags";

public static final IonSystem SYSTEM = IonSystemBuilder.standard().build();

public static final IonObjectMapper MAPPER = new IonValueMapper(SYSTEM);

private Constants() { } static {

MAPPER.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);

} }

Important

For the Amazon Ion package, you must use 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.

Java tutorial

NoteThis Constants class includes an instance of the open source Jackson IonValueMapper class. You can use this mapper to process your Amazon Ion (p. 697) data when doing read and write transactions.

The CreateLedger.java ﬁle also has a dependency on the following program (DescribeLedger.java), which describes the current status of your ledger.

2.x

* SPDX-License-Identifier: MIT-0 *

* Permission is hereby granted, free of charge, to any person obtaining a copy of this

* software and associated documentation files (the "Software"), to deal in the Software

* without restriction, including without limitation the rights to use, copy, modify,

* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to

* permit persons to whom the Software is furnished to do so.

* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,

* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT

* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION

* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package software.amazon.qldb.tutorial;

import com.amazonaws.services.qldb.AmazonQLDB;

import com.amazonaws.services.qldb.model.DescribeLedgerRequest;

import com.amazonaws.services.qldb.model.DescribeLedgerResult;

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

/** * Describe a QLDB ledger.

* This code expects that you have AWS credentials setup per:

* http://docs.aws.amazon.com/java-sdk/latest/developer-guide/setup-credentials.html

*/public final class DescribeLedger {

public static AmazonQLDB client = CreateLedger.getClient();

public static final Logger log = LoggerFactory.getLogger(DescribeLedger.class);

private DescribeLedger() { }

public static void main(final String... args) { try {

describe(Constants.LEDGER_NAME);

Java tutorial

* @return {@link DescribeLedgerResult} from QLDB.

public static DescribeLedgerResult describe(final String name) { log.info("Let's describe ledger with name: {}...", name);

DescribeLedgerRequest request = new DescribeLedgerRequest().withName(name);

DescribeLedgerResult result = client.describeLedger(request);

log.info("Success. Ledger description: {}", result);

return result;