Support AutoGeneratedTimestamp annotations in nested objects

[anasatirbasa]

Description

This pull request adds support for applying @DynamoDbAutoGeneratedTimestampAttribute to attributes within nested objects. Auto-generated timestamps are now applied consistently across both top-level and nested attributes, including deeply nested and recursive object graphs.

The implementation also introduces a caching mechanism for nested schema resolution to improve performance and safely support recursive or circular references.

Motivation and Context

Previously, @DynamoDbAutoGeneratedTimestampAttribute was evaluated only for top-level attributes. As a result, timestamp auto-generation did not work for nested attributes, limiting its usefulness when modeling complex domain objects.

In addition, nested schema resolution relied on repeatedly invoking getNestedSchema() for each nested object instance. In deeply nested or recursive structures, this could lead to redundant processing and unnecessary performance overhead.

This change addresses both limitations by:

• Enabling timestamp auto-generation for nested attributes.
• Optimizing nested schema resolution through caching.

Modifications

Nested Timestamp Support

AutoGeneratedTimestampRecordExtension has been enhanced to detect and apply the timestamp annotation on nested attributes.

Depending on the operation type and the configured IgnoreNullsMode, nested objects may be represented during update operations in one of two ways:

• As complete maps, where the nested object is treated as a single attribute.
• As flattened attributes, using the internal _NESTED_ATTR_UPDATE_ marker, as produced by
  UpdateItemOperation.transformItemToMapForUpdateExpression.

Both representations are now supported, and a single generated timestamp value is applied consistently across top-level and nested attributes.

Testing

Existing tests were updated where necessary, and new tests were added to validate the new behavior.

Test Coverage on modified classes:

Test Coverage Checklist

Scenario	Done	Comments if Not Done
1. Different TableSchema Creation Methods
a. TableSchema.fromBean(Customer.class)	[x]
b. TableSchema.fromImmutableClass(Customer.class) for immutable classes	[x]
c. TableSchema.documentSchemaBuilder().build()	[x]
d. StaticTableSchema.builder(Customer.class)	[x]
**2. Nesting of Different TableSchema Types ** (Ref-1)
a. @DynamoDbBean with non-null nested @DynamoDbBean attribute	[x]
b. @DynamoDbBean with non-null nested @DynamoDbImmutable attribute	[ ]
c. @DynamoDbImmutable with non-null nested @DynamoDbBean attribute	[ ]
d. @DynamoDbBean with null nested @DynamoDbBean attribute	[x]
e. @DynamoDbBean with null nested @DynamoDbImmutable attribute	[ ]
f. @DynamoDbImmutable with null nested @DynamoDbBean attribute	[ ]
3. CRUD Operations (Ref-2)		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. Null Handling for Different Attribute types (Ref-3)
a. top-level null attributes	[x]
b. collections with null elements	[ ]
c. maps with null values	[ ]
d. full serialization/deserialization cycle with null values	[ ]
5. AsyncTable and SyncTable		Existing tests passed
a. DynamoDbAsyncTable Testing	[ ]
b. DynamoDbTable Testing	[x]
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	[ ]

Types of changes

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

Checklist

• I have read the CONTRIBUTING document
• Local run of mvn install succeeds
• 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
• I have added tests to cover my changes
• All new and existing tests passed
• 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

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

[shetsa-amzn]

What happens If user annotates (DynamoDbAutoGeneratedTimestampAttribute) a non-Instant field

[shetsa-amzn]

Overall, is there is any chance this fix will cause backward compatible issues for customers who relied on wrong behavior before?

[anasatirbasa]

Overall, is there is any chance this fix will cause backward compatible issues for customers who relied on wrong behavior before?

Hello @shetsa-amzn,

There should be no backward compatibility issues unless customers have used @DynamoDbAutoGeneratedTimestampAttribute or @DynamoDbUpdateBehavior annotations on nested fields.

If they previously relied on tests or validation to prevent these annotations on nested fields, those tests may now fail at compile time and the issues can be addressed with minor code changes.

In summary, customers who did not use these annotations on nested fields will not be affected, and any issues for those who did can be resolved with minor code changes.

[anasatirbasa]

What happens If user annotates (DynamoDbAutoGeneratedTimestampAttribute) a non-Instant field

Hello @shetsa-amzn,

For cases where a user annotates a non-Instant field with @DynamoDbAutoGeneratedTimestampAttribute, there is a validation in place within the AutoGeneratedTimestampRecordExtension class, in validateType() method:

public <R> void validateType(
        String attributeName,
        EnhancedType<R> type,
        AttributeValueType attributeValueType) {
    // ...
    if (!type.rawClass().equals(Instant.class)) {
        throw new IllegalArgumentException(String.format(
            "Attribute '%s' of Class type %s is not a suitable Java Class type to be used as a Auto Generated "
                + "Timestamp attribute. Only java.time.Instant Class type is supported.",
            attributeName,
            type.rawClass()));
    }
}

This behavior is also covered by autogenerateTimestamps_onNonInstantAttribute_throwsException() test in AutoGeneratedTimestampExtensionTest.java.