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 int 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 integer)
• 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

[zoewangg]

Hmm, this is odd, can you paste the error logs? If we have to add exclusion, we should add it to the top level pom https://github.com/aws/aws-sdk-java-v2/blob/master/pom.xml#L681

[RanVaknin]

the error only was shown on CI, but I was able to raise with running mvn japicmp:cmp -pl :dynamodb-enhanced

[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  4.557 s
[INFO] Finished at: 2025-04-21T11:29:14-07:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal com.github.siom79.japicmp:japicmp-maven-plugin:0.15.6:cmp (default-cli) on project dynamodb-enhanced: There is at least one incompatibility: software.amazon.awssdk.enhanced.dynamodb.extensions.annotations.DynamoDbVersionAttribute.incrementBy():METHOD_ABSTRACT_ADDED_TO_CLASS,software.amazon.awssdk.enhanced.dynamodb.extensions.annotations.DynamoDbVersionAttribute.startAt():METHOD_ABSTRACT_ADDED_TO_CLASS -> [Help 1]
[ERROR] 
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR] 
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoFailureException

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

[sonarqubecloud]

Quality Gate passed

Issues
7 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud