AWS DevOps & Developer Productivity Blog
Introducing the Enhanced Document API for DynamoDB in the AWS SDK for Java 2.x
We are excited to announce that the AWS SDK for Java 2.x now offers the Enhanced Document API for DynamoDB, providing an enhanced way of working with Amazon DynamoDb items.
This post covers using the Enhanced Document API for DynamoDB with the DynamoDB Enhanced Client. By using the Enhanced Document API, you can create an EnhancedDocument
instance to represent an item with no fixed schema, and then use the DynamoDB Enhanced Client to read and write to DynamoDB.
Furthermore, unlike the Document APIs of aws-sdk-java 1.x, which provided arguments and return types that were not type-safe, the EnhancedDocument provides strongly-typed APIs for working with documents. This interface simplifies the development process and ensures that the data is correctly typed.
Prerequisites:
Before getting started, ensure you are using an up-to-date version of the AWS Java SDK dependency with all the latest released bug-fixes and features. For Enhanced Document API support, you must use version 2.20.33 or later. See our “Set up an Apache Maven project” guide for details on how to manage the AWS Java SDK dependency in your project.
Add dependency for dynamodb-enhanced in pom.xml.
Quick walk-through for using Enhanced Document API to interact with DDB
Step 1 : Create a DynamoDB Enhanced Client
Create an instance of the DynamoDbEnhancedClient class, which provides a high-level interface for Amazon DynamoDB that simplifies working with DynamoDB tables.
Step 2 : Create a DynamoDbTable resource object with Document table schema
To execute commands against a DynamoDB table using the Enhanced Document API, you must associate the table with your Document table schema to create a DynamoDbTable
resource object. The Document table schema builder requires the primary index key and attribute converter providers. Use AttributeConverterProvider.defaultProvider()
to convert document attributes of default types. An optional secondary index key can be added to the builder.
Step 3 : Write a DynamoDB item using an EnhancedDocument
The EnhancedDocument
class has static factory methods along with a builder
method to add attributes to a document. The following snippet demonstrates the type safety provided by EnhancedDocument
when you construct a document item.
Step 4 : Read a Dynamo DB item as an EnhancedDocument
Attributes of the Documents retrieved from a DynamoDB table can be accessed with getter methods
AttributeConverterProviders for accessing document attributes as custom objects
You can provide a custom AttributeConverterProvider
instance to an EnhancedDocument
to convert document attributes to a specific object type.
These providers can be set on either DocumentTableSchema
or EnhancedDocument
to read or write attributes as custom objects.
Convert Documents to JSON and vice-versa
The Enhanced Document API allows you to convert a JSON string to an EnhancedDocument
and vice-versa.
Define a Custom Attribute Converter Provider
Custom attribute converter providers are implementations of AttributeConverterProvider
that provide converters for custom classes.
Below is an example for a CustomClassForDocumentAPI
which has as a single field stringAttribute
of type String and its corresponding AttributeConverterProvider implementation.
A custom attribute converter is an implementation of AttributeConverter
that converts a custom classes to and from a map of attribute values, as shown below.
Attribute Converter Provider for EnhancedDocument Builder
When working outside of a DynamoDB table context, make sure to set the attribute converter providers explicitly on the EnhancedDocument
builder. When used within a DynamoDB table context, the table schema’s converter provider will be used automatically for the EnhancedDocument
.
The code snippet below shows how to set an AttributeConverterProvider
using the EnhancedDocument
builder method.
Conclusion
In this blog post we showed you how to set up and begin using the Enhanced Document API with the DynamoDB Enhanced Client and standalone with the EnhancedDocument
class. The enhanced client is open-source and resides in the same repository as the AWS SDK for Java 2.0. For more examples related to this visit to our Developer Guide. We hope you’ll find this new feature useful. You can always share your feedback on our GitHub issues page.
About the author: