Quarkus - Amazon DynamoDB Client

DynamoDB is a scalable AWS managed NoSQL database. It supports both key-value and document data models, that enables to have a flexible schema for your data. This extension provides functionality that allows the client to communicate with the service when running in Quarkus. You can find more information about DynamoDB at the Amazon DynamoDB website.

The Quarkus extension supports two programming models:

• Blocking access using URL Connection HTTP client (by default) or the Apache HTTP Client

• Asynchronous programming based on JDK’s CompletableFuture objects and the Netty HTTP client.

In this guide, we see how you can get your REST services to use the DynamoDB locally and on AWS.

Prerequisites

To complete this guide, you need:

• JDK 1.8+ installed with JAVA_HOME configured appropriately

• an IDE

• Apache Maven 3.6.2+

• An AWS Account to access the DynamoDB service

• Optionally, Docker for your system to run DynamoDB locally for testing purposes

Setup DynamoDB locally

The easiest way to start working with DynamoDB is to run a local instance as a container.

docker run --publish 8000:8000 amazon/dynamodb-local:1.11.477 -jar DynamoDBLocal.jar -inMemory -sharedDb

This starts a DynamoDB instance that is accessible on port 8000. You can check it’s running by accessing the web shell on [http://localhost:8000/shell](http://localhost:8000/shell).

Have a look at the Setting Up DynamoDB Local guide for other options to run DynamoDB.

Open [http://localhost:8000/shell](http://localhost:8000/shell) in your browser.

Copy and paste the following code to the shell and run it:

var params = {
    TableName: 'QuarkusFruits',
    KeySchema: [{ AttributeName: 'fruitName', KeyType: 'HASH' }],
    AttributeDefinitions: [{  AttributeName: 'fruitName', AttributeType: 'S', }],
    ProvisionedThroughput: { ReadCapacityUnits: 1, WriteCapacityUnits: 1, }
};
dynamodb.createTable(params, function(err, data) {
    if (err) ppJson(err);
    else ppJson(data);
});

Set up Dynamodb on AWS

Before you can use the AWS SDKs with DynamoDB, you must get an AWS access key ID and secret access key. For more information, see Setting Up DynamoDB (Web Service).

We recommend to use the AWS CLI to provision the table:

aws dynamodb create-table --table-name QuarkusFruits \
                          --attribute-definitions AttributeName=fruitName,AttributeType=S \
                          --key-schema AttributeName=fruitName,KeyType=HASH \
                          --provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1

Solution

The application built here allows to manage elements (fruits) stored in Amazon DynamoDB.

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Clone the Git repository: git clone [https://github.com/quarkusio/quarkus-quickstarts.git](https://github.com/quarkusio/quarkus-quickstarts.git), or download an archive.

The solution is located in the amazon-dynamodb-quickstart directory.

Creating the Maven project

First, we need a new project. Create a new project with the following command:

mvn io.quarkus:quarkus-maven-plugin:1.7.6.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=amazon-dynamodb-quickstart \
    -DclassName="org.acme.dynamodb.FruitResource" \
    -Dpath="/fruits" \
    -Dextensions="resteasy-jsonb,amazon-dynamodb,resteasy-mutiny"
cd amazon-dynamodb-quickstart

This command generates a Maven structure importing the RESTEasy/JAX-RS, Mutiny and DynamoDB Client extensions. After this, the amazon-dynamodb extension has been added to your pom.xml as well as the Mutiny support for RESTEasy.

Creating JSON REST service

In this example, we will create an application to manage a list of fruits. The example application will demonstrate the two programming models supported by the extension.

First, let’s create the Fruit bean as follows:

package org.acme.dynamodb;
import java.util.Map;
import java.util.Objects;
import io.quarkus.runtime.annotations.RegisterForReflection;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
@RegisterForReflection
public class Fruit {
    private String name;
    private String description;
    public Fruit() {
    }
    public static Fruit from(Map<String, AttributeValue> item) {
        Fruit fruit = new Fruit();
        if (item != null && !item.isEmpty()) {
            fruit.setName(item.get(AbstractService.FRUIT_NAME_COL).s());
            fruit.setDescription(item.get(AbstractService.FRUIT_DESC_COL).s());
        }
        return fruit;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public String getDescription() {
        return description;
    }
    public void setDescription(String description) {
        this.description = description;
    }
    @Override
    public boolean equals(Object obj) {
        if (!(obj instanceof Fruit)) {
            return false;
        }
        Fruit other = (Fruit) obj;
        return Objects.equals(other.name, this.name);
    }
    @Override
    public int hashCode() {
        return Objects.hash(this.name);
    }
}

Nothing fancy. One important thing to note is that having a default constructor is required by the JSON serialization layer. The static from method creates a bean based on the Map object provided by the DynamoDB client response.

Now create a org.acme.dynamodb.AbstractService that will consist of helper methods that prepare DynamoDB request objects for reading and adding items to the table.

package org.acme.dynamodb;
import java.util.HashMap;
import java.util.Map;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.GetItemRequest;
import software.amazon.awssdk.services.dynamodb.model.PutItemRequest;
import software.amazon.awssdk.services.dynamodb.model.ScanRequest;
public abstract class AbstractService {
    public final static String FRUIT_NAME_COL = "fruitName";
    public final static String FRUIT_DESC_COL = "fruitDescription";
    public String getTableName() {
        return "QuarkusFruits";
    }
    protected ScanRequest scanRequest() {
        return ScanRequest.builder().tableName(getTableName())
                .attributesToGet(FRUIT_NAME_COL, FRUIT_DESC_COL).build();
    }
    protected PutItemRequest putRequest(Fruit fruit) {
        Map<String, AttributeValue> item = new HashMap<>();
        item.put(FRUIT_NAME_COL, AttributeValue.builder().s(fruit.getName()).build());
        item.put(FRUIT_DESC_COL, AttributeValue.builder().s(fruit.getDescription()).build());
        return PutItemRequest.builder()
                .tableName(getTableName())
                .item(item)
                .build();
    }
    protected GetItemRequest getRequest(String name) {
        Map<String, AttributeValue> key = new HashMap<>();
        key.put(FRUIT_NAME_COL, AttributeValue.builder().s(name).build());
        return GetItemRequest.builder()
                .tableName(getTableName())
                .key(key)
                .attributesToGet(FRUIT_NAME_COL, FRUIT_DESC_COL)
                .build();
    }
}

Then, create a org.acme.dynamodb.FruitSyncService that will be the business layer of our application and stores/loads the fruits from DynamoDB using the synchronous client.

package org.acme.dynamodb;
import java.util.List;
import java.util.stream.Collectors;
import javax.enterprise.context.ApplicationScoped;
import javax.inject.Inject;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
@ApplicationScoped
public class FruitSyncService extends AbstractService {
    @Inject
    DynamoDbClient dynamoDB;
    public List<Fruit> findAll() {
        return dynamoDB.scanPaginator(scanRequest()).items().stream()
                .map(Fruit::from)
                .collect(Collectors.toList());
    }
    public List<Fruit> add(Fruit fruit) {
        dynamoDB.putItem(putRequest(fruit));
        return findAll();
    }
    public Fruit get(String name) {
        return Fruit.from(dynamoDB.getItem(getRequest(name)).item());
    }
}

Now, edit the org.acme.dynamodb.FruitResource class as follows:

package org.acme.dynamodb;
import java.util.List;
import javax.inject.Inject;
import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
@Path("/fruits")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class FruitResource {
    @Inject
    FruitSyncService service;
    @GET
    public List<Fruit> getAll() {
        return service.findAll();
    }
    @GET
    @Path("{name}")
    public Fruit getSingle(@PathParam("name") String name) {
        return service.get(name);
    }
    @POST
    public List<Fruit> add(Fruit fruit) {
        service.add(fruit);
        return getAll();
    }
}

The implementation is pretty straightforward and you just need to define your endpoints using the JAX-RS annotations and use the FruitSyncService to list/add new fruits.

Configuring DynamoDB clients

Both DynamoDB clients (sync and async) are configurable via the application.properties file that can be provided in the src/main/resources directory. Additionally, you need to add to the classpath a proper implementation of the sync client. By default the extension uses the java.net.URLConnection HTTP client, so you need to add a URL connection client dependency to the pom.xml file:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>url-connection-client</artifactId>
</dependency>

If you want to use the Apache HTTP client instead, configure it as follows:

quarkus.dynamodb.sync-client.type=apache

And add following dependency to the application pom.xml:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>apache-client</artifactId>
</dependency>

If you’re going to use a local DynamoDB instance, configure it as follows:

quarkus.dynamodb.endpoint-override=http://localhost:8000
quarkus.dynamodb.aws.region=eu-central-1
quarkus.dynamodb.aws.credentials.type=static
quarkus.dynamodb.aws.credentials.static-provider.access-key-id=test-key
quarkus.dynamodb.aws.credentials.static-provider.secret-access-key=test-secret

• quarkus.dynamodb.aws.region - It’s required by the client, but since you’re using a local DynamoDB instance you can pick any valid AWS region.

• quarkus.dynamodb.aws.credentials.type - Set static credentials provider with any values for access-key-id and secret-access-key

• quarkus.dynamodb.endpoint-override - Override the DynamoDB client to use a local instance instead of an AWS service

If you want to work with an AWS account, you’d need to set it with:

quarkus.dynamodb.aws.region=<YOUR_REGION>
quarkus.dynamodb.aws.credentials.type=default

• quarkus.dynamodb.aws.region you should set it to the region where you provisioned the DynamoDB table,

• quarkus.dynamodb.aws.credentials.type - use the default credentials provider chain that looks for credentials in this order:

  • Java System Properties - aws.accessKeyId and aws.secretAccessKey

  • Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY

  • Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI

  • Credentials delivered through the Amazon ECS if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable,

  • Instance profile credentials delivered through the Amazon EC2 metadata service

Next steps

Packaging

Packaging your application is as simple as ./mvnw clean package. It can be run with java -jar target/amazon-dynamodb-quickstart-1.0-SNAPSHOT-runner.jar.

With GraalVM installed, you can also create a native executable binary: ./mvnw clean package -Dnative. Depending on your system, that will take some time.

Going asynchronous

Thanks to the AWS SDK v2.x used by the Quarkus extension, you can use the asynchronous programming model out of the box.

Create a org.acme.dynamodb.FruitAsyncService that will be similar to our FruitSyncService but using an asynchronous programming model.

package org.acme.dynamodb;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.stream.Collectors;
import javax.enterprise.context.ApplicationScoped;
import javax.inject.Inject;
import io.smallrye.mutiny.Uni;
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
@ApplicationScoped
public class FruitAsyncService extends AbstractService {
    @Inject
    DynamoDbAsyncClient dynamoDB;
    public Uni<List<Fruit>> findAll() {
        return Uni.createFrom().completionStage(() -> dynamoDB.scan(scanRequest()))
                .onItem().transform(res -> res.items().stream().map(Fruit::from).collect(Collectors.toList()));
    }
    public Uni<List<Fruit>> add(Fruit fruit) {
        return Uni.createFrom().completionStage(() -> dynamoDB.putItem(putRequest(fruit)))
                .onItem().ignore().andSwitchTo(this::findAll);
    }
    public Uni<Fruit> get(String name) {
        return Uni.createFrom().completionStage(() -> dynamoDB.getItem(getRequest(name)))
                .onItem().transform(resp -> Fruit.from(resp.item()));
    }
}

In the previous code, we create Uni instances from the CompletionStage objects returned by the asynchronous DynamoDB client, and then transform the emitted item.

Then, create an asynchronous REST resource that consumes this async service:

package org.acme.dynamodb;
import io.smallrye.mutiny.Uni;
import javax.inject.Inject;
import javax.ws.rs.*;
import javax.ws.rs.core.MediaType;
import java.util.List;
@Path("/async-fruits")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class FruitAsyncResource {
    @Inject
    FruitAsyncService service;
    @GET
    public Uni<List<Fruit>> getAll() {
        return service.findAll();
    }
    @GET
    @Path("{name}")
    public Uni<Fruit> getSingle(@PathParam("name") String name) {
        return service.get(name);
    }
    @POST
    public Uni<List<Fruit>> add(Fruit fruit) {
        return service.add(fruit)
                .onItem().ignore().andSwitchTo(this::getAll);
    }
}

And add Netty HTTP client dependency to the pom.xml:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>netty-nio-client</artifactId>
</dependency>

Configuration Reference