DynamoDB Enhanced Native Image Substitutions

This library makes the AWS DynamoDB Enhanced Client compatible with GraalVM Native Image. It provides the necessary reflection registrations to allow the DynamoDB Enhanced Client to work properly in a native image context.

Problem

The AWS DynamoDB Enhanced Client uses reflection extensively, which doesn't work out-of-the-box with GraalVM Native Image. This library solves that problem by registering the required classes and methods for reflection.

Maven Dependency

Add the following dependency to your pom.xml:

<dependency>
    <groupId>com.github.eciuca</groupId>
    <artifactId>dynamodb-enhanced-native-image-substitutions</artifactId>
    <version>2.32.7</version>
</dependency>

Usage

To activate the native-image feature, add the following to your GraalVM native-image command:

--features=com.github.eciuca.awssdk.dynamodb.DynamoDbEnhancedNativeImageSubstitutions

Example with Maven and Native Image Plugin

If you're using the GraalVM Native Image Maven plugin, you can configure it like this:

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <version>${native-maven-plugin.version}</version>
    <configuration>
        <buildArgs>
            <buildArg>--features=com.github.eciuca.awssdk.dynamodb.DynamoDbEnhancedNativeImageSubstitutions</buildArg>
        </buildArgs>
    </configuration>
</plugin>

Example with Spring Boot

If you're using Spring Boot with GraalVM Native Image, add the following to your application.properties:

spring.native.args=--features=com.github.eciuca.awssdk.dynamodb.DynamoDbEnhancedNativeImageSubstitutions

What's Included

This library registers the following classes and methods for reflection:

• DefaultAttributeConverterProvider constructor
• BeanTableSchemaAttributeTags class and its methods
• AutoGeneratedUuidTag class and its methods
• AutoGeneratedTimestampRecordAttributeTags class and its methods
• VersionRecordAttributeTags class and its methods

The library supports the following DynamoDB Enhanced annotations:

• @DynamoDbBean
• @DynamoDbAtomicCounter
• @DynamoDbPartitionKey
• @DynamoDbSecondaryPartitionKey
• @DynamoDbSortKey
• @DynamoDbSecondarySortKey
• @DynamoDbAutoGeneratedUuid
• @DynamoDbAutoGeneratedTimestampAttribute
• @DynamoDbVersionAttribute
• @DynamoDbUpdateBehavior
• @BeanTableSchemaAttributeTag

(maybe not extensive, I have not actually used all of them)

If you need support for additional tags beyond those listed above, you can either:

1. Create a new feature class that registers the additional tags you need
2. Submit a Pull Request to this repository to add the tags to the existing implementation

Version Compatibility

The version of this library matches the version of the AWS SDK DynamoDB Enhanced Client it's compatible with. For example, version 2.32.7 of this library is compatible with version 2.32.7 of the AWS SDK DynamoDB Enhanced Client.

Information from Original Implementation

The following sections are taken directly from the README of the original implementation by Nithanim, which was the foundation for this library.

What does it do technically

In short, the AWS SDK tries to create and load lambdas at runtime but since the native-image is pre-compiled, this is not possible.

Instead, the predecessor, MethodHandles are used instead which are fully supported.

There is also an additional bugfix for quarkus in there that deals with multiple classloaders when running tests. Although this is a separate issue, the same fix described above conveniently fixed this too.

As a bonus, since the DynamoDbBeans are accessed by reflection, they are automatically registered for this purpose in the GraalVM native-image generation. This means that you do not need to add @RegisterForReflection to all your beans.

If want to know even more about the technical side, feel free to dive into the code. You can find extensive information in the javadoc (and of course the code itself)!

Can I use it in production?

Probably. You certainly have to decide for yourself if you want to take the risk. See the disclaimer in the license!

I just researched and spent weeks trying to fix all problems because I needed it for work. (However, there is no association! I did that in my free time!)

We deployed it in production and has been running happily since!

Credits

This library is based on the work from quarkus-dynamodb-enhanced by Nithanim. The original implementation was a crucial contribution to making AWS DynamoDB Enhanced Client work with GraalVM Native Image.