Installing the Amazon QLDB Java sample application - Amazon Quantum Ledger Database (Amazon QLDB)
PrerequisitesInstallation

Installing the Amazon QLDB Java sample application

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.

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

  1. Sign up for AWS.

  2. Create a 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 grant programmatic access 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.

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 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 configuration and complete code from the Java tutorial.

  2. Load and run the provided application.

    • If you're using Eclipse:

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

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

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

    • If you're using IntelliJ:

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

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

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

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

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.

Part 1: Provision your resources

In this first 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. The following screenshot of the AWS Management Console shows US East (N. Virginia) as the selected AWS Region.

    AWS Management Console showing US East (N. Virginia) as the selected AWS Region.

  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 finish.

    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 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 finish 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 preconfigured with the system dependencies that you need to run the tutorial. In the Environment navigation pane of your console, confirm that you see a folder named QLDB DMV Sample Application. The following screenshot of the AWS Cloud9 console shows the QLDB DMV Sample Application environment folder pane.

    AWS Cloud9 console showing the QLDB DMV Sample Application environment folder pane.

    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 ( 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.

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're 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 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.

    1. 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.

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