DDB Enhanced: Allow custom versioning

[RanVaknin]

Motivation and Context

This PR builds on the work started in issue #3894 where the VersionedRecordExtension didn't support starting version numbers at 0, requiring clients to use Integer objects (with null initial values) rather than long primitives. As mentioned by @akiesler in the original issue, developers might expect versions to start at 0 and increment from there, rather than having a special case where the value must be initialized to null.

This implementation allows the extension to be more flexible by allowing:

• Starting versions at 0 (or any non-negative long)
• Configuring custom increment values (only positive numbers)
• Supporting these configs both at the extension level and via annotations

Modifications

• Refactored the VersionedRecordExtension to support explicit startAt and incrementBy values via builder methods (making it opt-in).
• Expanded the DynamoDbVersionAttribute annotation to support startAt and incrementBy parameters
• Added validation to prevent negative startAt values and non-positive incrementBy values

Testing

• Custom startAt and incrementBy values through both builder and annotations
• Validation of illegal values (negative startAt, zero/negative incrementBy)
• Precedence rules between annotation and builder configurations
• Version incrementation for both initial and existing records
• Edge cases with different configuration combinations

[akiesler]

Thank you for picking up this change! It will greatly simplify our version handling. Please let me know if I can do anything to help.

[dagnir]

• This is a very complex expression. Let's move this to a separate function so it's easier to reason about and we can document it

[zoewangg]

+1. Why do we need to check existingVersionValue.get().n() != null && ((versionStartAtFromAnnotation.isPresent() && Long.parseLong(existingVersionValue.get().n()) == versionStartAtFromAnnotation.get()) || Long.parseLong(existingVersionValue.get().n()) == this.startAt)))?

Suggesting the following

if (existingValueNotAvailable(existingAttributeValue)) {
    long startVersion = versionStartAtFromAnnotation.orElse(this.startAt);
    long incrementVersion = versionIncrementByFromAnnotation.orElse(this.incrementBy);
  ...
} else {
  ....
}

[RanVaknin]

we need the expanded evaluation to see what constitutes an "initial version".
There are three ways a version can be considered "initial":

1. The version doesn't exist in DynamoDB yet (existing behavior)
2. The version is explicitly set to null (existing behavior)
3. The version equals a configured start value (new behavior)

For case 3, the extension must check if the version matches either:

• The start value from the annotation (@DynamoDbVersionAttribute(startAt = 3))
• The start value from the builder (builder().startAt(3).build())

[RanVaknin]

Fixed edge case in the isInitialVersion function. Previously it was not evaluating the precedence that annotation values should take over builder values.

This caused inconsistent behavior when both annotation and builder values were both provided with different values, potentially treating records as initial versions incorrectly when their version matched the builder's startAt value but not the annotation's value.

This is now fixed. Added a test case that combines input from both the builder and the annotation.

[zoewangg]

+1. Why do we need to check existingVersionValue.get().n() != null && ((versionStartAtFromAnnotation.isPresent() && Long.parseLong(existingVersionValue.get().n()) == versionStartAtFromAnnotation.get()) || Long.parseLong(existingVersionValue.get().n()) == this.startAt)))?

Suggesting the following

if (existingValueNotAvailable(existingAttributeValue)) {
    long startVersion = versionStartAtFromAnnotation.orElse(this.startAt);
    long incrementVersion = versionIncrementByFromAnnotation.orElse(this.incrementBy);
  ...
} else {
  ....
}

[sonarqubecloud]

Quality Gate passed

Issues
25 New issues
0 Accepted issues

Measures
0 Security Hotspots
93.6% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[RanVaknin]

Fixed edge case in the isInitialVersion function. Previously it was not evaluating the precedence that annotation values should take over builder values.

This caused inconsistent behavior when both annotation and builder values were both provided with different values, potentially treating records as initial versions incorrectly when their version matched the builder's startAt value but not the annotation's value.

This is now fixed. Added a test case that combines input from both the builder and the annotation.

[sonarqubecloud]

Quality Gate passed

Issues
11 New issues
0 Accepted issues

Measures
0 Security Hotspots
90.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull Request Overview

This PR enhances the DynamoDB Enhanced Client's VersionedRecordExtension to support custom versioning strategies. Instead of requiring versions to start at 1 and increment by 1, developers can now configure starting values (including 0) and custom increment amounts through both builder patterns and annotations.

Key Changes:

• Added configurable startAt and incrementBy parameters to VersionedRecordExtension.Builder
• Enhanced @DynamoDbVersionAttribute annotation with startAt and incrementBy parameters
• Implemented validation to prevent negative start values and non-positive increment values
• Added support for annotation-based configuration with precedence over builder configuration

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
VersionedRecordExtension.java	Core implementation with builder methods, validation, and version calculation logic
DynamoDbVersionAttribute.java	Added annotation parameters for startAt and incrementBy
VersionRecordAttributeTags.java	Updated to pass annotation parameters to version attribute tags
VersionedRecordExtensionTest.java	Comprehensive test coverage for new functionality
VersionedRecordTest.java	Integration tests with various configuration scenarios
FakeVersionedImmutableItem.java	Test model with annotation-based versioning
FakeVersionedStaticImmutableItem.java	Test model for static schema versioning
Expression.java	Added toString method for debugging
pom.xml	Temporary exclusion of new annotation methods from API checks
.changes/next-release/feature-DynamoDBEnhancedClient-2a501d8.json	Release notes entry

Comments suppressed due to low confidence (2)

[zoewangg]

nit: the convention for inline comment is // rather than /*

[github-actions]

This pull request has been closed and the conversation has been locked. Comments on closed PRs are hard for our team to see. If you need more assistance, please open a new issue that references this one.