Support AutoGeneratedTimestamp and UpdateBehavior annotation in nested objects

[roamariei]

Description

Added support for @DynamoDbAutoGeneratedTimestampAttribute and @DynamoDbUpdateBehavior on attributes within nested objects. The @DynamoDbUpdateBehavior annotation will only take effect for nested attributes when using IgnoreNullsMode.SCALAR_ONLY.

Motivation and Context

@DynamoDbUpdateBehavior and @DynamoDbAutoGeneratedTimestampAttribute to work on nested objects too.

Modifications

The AutoGeneratedTimestampRecordExtension has been enhanced to support detection of the timestamp annotation on nested objects. Depending on the operation and the IgnoreNullsMode setting, nested attributes may either be treated as complete maps or flattened using the NESTED_ATTR_UPDATE convention (handled in transformItemToMapForUpdateExpression within UpdateItemOperation). Both scenarios are now supported, and the same generated timestamp is applied consistently across top-level and nested fields.

In parallel, the handling of the IgnoreNullsMode parameter within update requests was reviewed. As a result, UpdateExpressionUtils has been updated to evaluate the @DynamoDbUpdateBehavior annotation only when IgnoreNullsMode.SCALAR_ONLY is used, targeting flattened nested attributes identified via NESTED_ATTR_UPDATE. When applied to a list of nested objects, the annotation is not supported, as individual elements cannot be updated — the entire list is replaced during an update operation.

Testing

Existing tests were updated, and new tests were added to validate the extended functionality.

Screenshots (if appropriate)

Types of changes

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)

Checklist

• [x] I have read the CONTRIBUTING document
• [x] Local run of mvn install succeeds
• [x] My code follows the code style of this project
• [ ] My change requires a change to the Javadoc documentation
• [ ] I have updated the Javadoc documentation accordingly
• [x] I have added tests to cover my changes
• [x] All new and existing tests passed
• [x] I have added a changelog entry. Adding a new entry must be accomplished by running the scripts/new-change script and following the instructions. Commit the new file created by the script in .changes/next-release with your changes.
• [ ] My change is to implement 1.11 parity feature and I have updated LaunchChangelog

License

• [x] I confirm that this pull request can be released under the Apache 2 license

Test Coverage Checklist

Scenario	Done	Comments if Not Done
1. Different TableSchema Creation Methods		Not impacted, existing tests passed
a. TableSchema.fromBean(Customer.class)	[ ]
b. TableSchema.fromImmutableClass(Customer.class) for immutable classes	[ ]
c. TableSchema.documentSchemaBuilder().build()	[ ]
d. StaticTableSchema.builder(Customer.class)	[ ]
2. Nesting of Different TableSchema Types
a. @DynamoDbBean with nested @DynamoDbBean as NonNull	[x]
b. @DynamoDbBean with nested @DynamoDbImmutable as NonNull	[ ]
c. @DynamoDbImmutable with nested @DynamoDbBean as NonNull	[ ]
d. @DynamoDbBean with nested @DynamoDbBean as Null	[x]
e. @DynamoDbBean with nested @DynamoDbImmutable as Null	[ ]
f. @DynamoDbImmutable with nested @DynamoDbBean as Null	[ ]
3. CRUD Operations		Existing tests passed
a. scan()	[ ]
b. query()	[ ]
c. updateItem()	[x]
d. putItem()	[x]
e. getItem()	[x]
f. deleteItem()	[ ]
g. batchGetItem()	[ ]
h. batchWriteItem()	[ ]
i. transactGetItems()	[ ]
j. transactWriteItems()	[ ]
4. Data Types and Null Handling
a. top-level null attributes	[x]
b. collections with null elements	[ ]
c. maps with null values	[ ]
d. conversion between null Java values and AttributeValue	[ ]
e. full serialization/deserialization cycle with null values	[ ]
5. AsyncTable and SyncTable		Existing tests passed
a. DynamoDbAsyncTable Testing	[ ]
b. DynamoDbTable Testing	[ ]
6. New/Modification in Extensions
a. Tables with Scenario in ScenarioSl No.1 (All table schemas are Must)	[x]
b. Test with Default Values in Annotations	[x]
c. Combination of Annotation and Builder passes extension	[x]
7. New/Modification in Converters		Not impacted, existing tests passed
a. Tables with Scenario in ScenarioSl No.1 (All table schemas are Must)	[ ]
b. Test with Default Values in Annotations	[ ]
c. Test All Scenarios from 1 to 5	[ ]

[L-Applin]

Please run the checkstyle plugin on dynamodb-enhanced, there is some checkstyle violations.

When I do it by runing the following command mvn org.apache.maven.plugins:maven-checkstyle-plugin:3.1.2:check -pl :dynamodb-enhanced I get these violations:

[ERROR] /Users/olapplin/Develop/GitHub/aws-sdk-java-v2/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/internal/update/UpdateExpressionUtils.java:93:80: WhitespaceAround: '-' is not followed by whitespace. Empty blocks may only be represented as {} when not part of a multi-block statement. [WhitespaceAround]
[ERROR] /Users/olapplin/Develop/GitHub/aws-sdk-java-v2/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/internal/update/UpdateExpressionUtils.java:93:80: WhitespaceAround: '-' is not preceded with whitespace. [WhitespaceAround]
[ERROR] /Users/olapplin/Develop/GitHub/aws-sdk-java-v2/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/internal/update/UpdateExpressionUtils.java:95:17: 'for' is not followed by whitespace. [WhitespaceAfter]
[ERROR] /Users/olapplin/Develop/GitHub/aws-sdk-java-v2/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/internal/update/UpdateExpressionUtils.java:95:17: WhitespaceAround: 'for' is not followed by whitespace. Empty blocks may only be represented as {} when not part of a multi-block statement. [WhitespaceAround]
[ERROR] /Users/olapplin/Develop/GitHub/aws-sdk-java-v2/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/internal/update/UpdateExpressionUtils.java:95:67: ')' is preceded with whitespace. [ParenPad]
[ERROR] /Users/olapplin/Develop/GitHub/aws-sdk-java-v2/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/internal/update/UpdateExpressionUtils.java:102: Line is longer than 130 characters (found 135). [LineLength]
[ERROR] /Users/olapplin/Develop/GitHub/aws-sdk-java-v2/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/extensions/AutoGeneratedTimestampRecordExtension.java:158: Line is longer than 130 characters (found 189). [LineLength]
[ERROR] /Users/olapplin/Develop/GitHub/aws-sdk-java-v2/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/extensions/AutoGeneratedTimestampRecordExtension.java:168: Line is longer than 130 characters (found 134). [LineLength]
[ERROR] /Users/olapplin/Develop/GitHub/aws-sdk-java-v2/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/extensions/AutoGeneratedTimestampRecordExtension.java:206: Line is longer than 130 characters (found 143). [LineLength]
[ERROR] /Users/olapplin/Develop/GitHub/aws-sdk-java-v2/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/extensions/AutoGeneratedTimestampRecordExtension.java:256:33: WhitespaceAround: '!=' is not preceded with whitespace. [WhitespaceAround]
[ERROR] /Users/olapplin/Develop/GitHub/aws-sdk-java-v2/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/extensions/AutoGeneratedTimestampRecordExtension.java:271: Line is longer than 130 characters (found 142). [LineLength]
[ERROR] /Users/olapplin/Develop/GitHub/aws-sdk-java-v2/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/extensions/AutoGeneratedTimestampRecordExtension.java:274: Line is longer than 130 characters (found 199). [LineLength]

[L-Applin]

The test coverage checklist is not complete, could you comment on the test that aren't run to validate they are not required for this change?

[L-Applin]

UpdateExpressionUtils has been updated to evaluate the @DynamoDbUpdateBehavior annotation only when IgnoreNullsMode.SCALAR_ONLY is used

Could you explain why are we also making this change? Could this impact existing customers usingIgnoreNullsMode.DEFAULT (the default value if IgnoreNullsMode is not not specified) with UpdateBehavior.WRITE_IF_NOT_EXISTS, is there any breaking behaviour change here we should be concerned about?

[roamariei]

UpdateExpressionUtils has been updated to evaluate the @DynamoDbUpdateBehavior annotation only when IgnoreNullsMode.SCALAR_ONLY is used

Could you explain why are we also making this change? Could this impact existing customers usingIgnoreNullsMode.DEFAULT (the default value if IgnoreNullsMode is not not specified) with UpdateBehavior.WRITE_IF_NOT_EXISTS, is there any breaking behaviour change here we should be concerned about?

Based on my understanding while debugging the code, there are two distinct ways of handling nested objects during the update flow, which depend on the IgnoreNullsMode parameter. This influences whether or not the transformItemToMapForUpdateExpression() method is invoked to flatten the request.

For IgnoreNullsMode.MAPS_ONLY, the entire nested object is expected to be set as a map. In this case, UpdateExpressionUtils cannot apply if_not_exists() to individual fields annotated with @DynamoDbUpdateBehavior, since the update is applied at the object level. However, in IgnoreNullsMode.SCALAR_ONLY, where nested fields are flattened using NESTED_ATTR_UPDATE as a delimiter, if_not_exists() can be applied to each individual attribute in the final update expression. That’s how I interpret the current behavior from the code.

The existing logic for parent-level attributes remains unaffected by this behavior—regardless of the IgnoreNullsMode used. This is a limitation that applies only to annotated nested fields, which were not previously supported by this extension. As such, I don’t see any breaking changes for existing use cases involving parent-level attributes.

[sonarqubecloud[bot]]

Quality Gate passed

Issues
9 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[L-Applin]

Builds fail with :

[ERROR] Failures:
--
[ERROR]   PackageContainmentTest.internalAPIs_shouldResideInInternalPackage:74 
Architecture Violation [Priority: MEDIUM] - Rule 'classes that are annotated with @SdkInternalApi and 
are not nested classes and are not package private should reside in any package ['..internal..'], 
because Internal APIs MUST reside in internal subpackage' was violated (1 times):

Class <software.amazon.awssdk.enhanced.dynamodb.extensions.utility.NestedRecordUtils> 
does not reside in any package ['..internal..'] in (NestedRecordUtils.java:0)

NestedRecordUtils should be in the internal package if it's intended to be used only by the SDK

[anasatirbasa]

Hello @L-Applin,

The issue should be fixed now. We are waiting for the workflows to be approved from a maintainer. Can you please review the Pull Request again and let us know if there is any additional change needed?

Thank you!

[L-Applin]

Hello @L-Applin,

The issue should be fixed now. We are waiting for the workflows to be approved from a maintainer. Can you please review the Pull Request again and let us know if there is any additional change needed?

Thank you!

re-running tests now

[L-Applin]

there is still some checkstyle violations:

[ERROR] /codebuild/output/src4268556524/src/github.com/aws/aws-sdk-java-v2/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/extensions/AutoGeneratedTimestampRecordExtension.java:21:1: 
Wrong lexicographical order for 'software.amazon.awssdk.enhanced.dynamodb.internal.EnhancedClientUtils.getNestedSchema' import. Should be before 'software.amazon.awssdk.enhanced.dynamodb.internal.extensions.utility.NestedRecordUtils.resolveSchemasPerPath'. 

You can run the checkstyle plugin locally with mvn org.apache.maven.plugins:maven-checkstyle-plugin:3.1.2:check -pl :dynamodb-enhanced You can also make sure all compile time checks pass by building locally with the test target mvn test -pl :dynamodb-enhanced which should run all the checks like checkstyle, findbugs, etc as well as all unit tests.

Could you try to build locally to verify all these compile time checks pass when submitting new changes? Thanks!

[andreas-grafenberger]

Hello @L-Applin ,

Sorry for that rule violation. We executed the checkstyle plugin locally and tests (incl. it tests). All of them passed.

Could you please re-run it?

[L-Applin]

Hello @L-Applin ,

Sorry for that rule violation. We executed the checkstyle plugin locally and tests (incl. it tests). All of them passed.

Could you please re-run it?

Thanks! Rerunning unit & integ tests

[sonarqubecloud[bot]]

Quality Gate passed

Issues
14 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[andreas-grafenberger]

Hello @L-Applin / @alextwoods,

Thank you for review!

I see the bot removed the pull request from the merge queue due to failed status check. Could you please let me know if we can do anything from our end in order to complete the merge? Don't have access to (all) checks details...

[L-Applin]

Hello @L-Applin / @alextwoods,

Thank you for review!

I see the bot removed the pull request from the merge queue due to failed status check. Could you please let me know if we can do anything from our end in order to complete the merge? Don't have access to (all) checks details...

I have queued to merge again, but there seems to be an issue related to the maven version in Codebuild which triggers a build failure in an unrelated module of the sdk. This has affected other builds, and is not related to this PR, we are looking into it