Added support for DynamoDbAutoGeneratedKey annotation

[anasatirbasa]

Description

Added the facility of using an annotation that will auto-generate a key for an attribute in a class,
similar to the legacy V1 @DynamoDBAutoGeneratedKey, now ported and adapted for V2 with the Enhanced Client.

Important Restriction

This annotation is only valid for primary keys (PK/SK) or secondary index keys (GSI/LSI PK/SK).
If applied to a non-key attribute, the extension will throw an IllegalArgumentException.

If the attribute is not provided by the client, the SDK will automatically generate a value (UUID by default)
during serialization. If the attribute already has a value, it will be preserved depending on the update policy applied.
The implementation reuses the concept from V1 but leverages the V2 Enhanced Client extension model to achieve parity.

A key aspect of this feature is its combination with @DynamoDbUpdateBehavior for secondary index keys only. This determines whether a generated key is one-time only or is regenerated on every update:

• Default (WRITE_ALWAYS) → The attribute will be regenerated on every write if missing, even during updates. Useful for attributes like lastUpdatedKey that are meant to refresh often.
• WRITE_IF_NOT_EXISTS → The attribute will only be generated once (on the first insert) and preserved across updates. This is the recommended option for stable identifiers like createdKey.

Motivation and Context

#5497

This functionality was present in V1 under @DynamoDBAutoGeneratedKey. Many users requested its reintroduction in V2.
By introducing this annotation and the supporting extension, we align the Enhanced Client API with developer expectations and provide a familiar migration path.

Modifications

• Added the new annotation @DynamoDbAutoGeneratedKey in the software.amazon.awssdk.enhanced.dynamodb.extensions.annotations package.
• Introduced AutoGeneratedKeyExtension, which ensures attributes annotated with @DynamoDbAutoGeneratedKey are populated with a UUID when absent. This uses UUID.randomUUID() under the hood.
• Added AutoGeneratedKeyTag as the annotation tag integration point.
• Integrated with @DynamoDbUpdateBehavior to support both stable one-time keys - works for secondary index keys only (WRITE_IF_NOT_EXISTS) and regenerating keys (WRITE_ALWAYS).
• Validated attribute type constraints (only String is supported).
• Enforced placement rules (only PK/SK, LSI/GSI keys are allowed).
• Added corresponding unit tests (AutoGeneratedKeyExtensionTest) and functional integration tests (AutoGeneratedKeyRecordTest) to verify correct behavior with real DynamoDB operations.
• Tests validate multiple scenarios, including updates, conditional writes, composite annotations,
  and integration with VersionedRecordExtension.

Testing

The changes have already been tested by running the existing tests and also added new unit/integration tests
for the new flow, ensuring parity with V1 behavior while also validating V2-specific integration points.

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()	[ ]
d. StaticTableSchema.builder(Customer.class)	[x]
2. Nesting of Different TableSchema Types
a. @DynamoDbBean with annotated auto-generated key	[x]
b. @DynamoDbImmutable with annotated auto-generated key	[x]
c. Auto-generated key combined with partition/sort key	[x]
3. CRUD Operations
a. scan()	[ ]
b. query()	[x]
c. updateItem() preserves existing value or generates when absent	[x]
d. putItem() with no key set (auto-generation occurs)	[x]
e. putItem() with key set manually	[x]
f. getItem() retrieves auto-generated key	[x]
g. deleteItem()	[ ]
h. batchGetItem()	[ ]
i. batchWriteItem()	[ ]
j. transactGetItems()	[ ]
k. transactWriteItems()	[ ]
4. Data Types and Null Handling
a. Annotated attribute is null → key auto-generated	[x]
b. Annotated attribute non-null → value preserved	[x]
c. Validation rejects non-String annotated attribute	[x]
5. AsyncTable and SyncTable
a. DynamoDbAsyncTable Testing	[x]
b. DynamoDbTable Testing	[x]
6. New/Modification in Extensions
a. Works with other extensions like VersionedRecordExtension	[x]
b. Test with Default Values in Annotations	[ ]
c. Combination of Annotation and Builder passes extension	[ ]
7. New/Modification in Converters
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

[marcusvoltolim]

No tests with @DynamoDbSortKey

[marcusvoltolim]

This solution still doesn't work for PartitionKey or SortKey, because UpdateBehavior are not applied to either as shown in the print below.

This is a workaround because it doesn't generate new values ​​in primaryKeys because the new extension validates if the value is missing, but it doesn't solve the root problem. Therefore, each new extension that can be applied to a PK must address this issue. The best approach is to not pass PKs to WriteModification.

[anasatirbasa]

Hello @marcusvoltolim,

Thank you very much for your review.

I have added tests for @DynamoDbSortKey as you suggested. The test class (AutoGeneratedKeyRecordTest) now covers all 4 supported key types with @DynamoDbAutoGeneratedKey:

• Primary partition key (@DynamoDbPartitionKey)
• Primary sort key (@DynamoDbSortKey)
• GSI partition key (@DynamoDbSecondaryPartitionKey)
• GSI sort key (@DynamoDbSecondarySortKey)

Regarding your comment about @DynamoDbUpdateBehavior: You're absolutely correct. Based on the implementation, the @DynamoDbAutoGeneratedKey annotation works with @DynamoDbUpdateBehavior only for secondary index keys (GSI/LSI partition and sort keys). For primary keys (both partition and sort), UpdateBehavior has no effect since primary keys cannot be null in DynamoDB and are always required for update operations.

I have updated the tests, ticket description, and PR description to clearly reflect this.

Could you please take another look when you have a chance? Thank you!

[RanVaknin]

Hi @anasatirbasa ,

I read through the PR, I have a few concerns I wanted to raise with the entire team before providing feedback. Will update you soon.

[RanVaknin]

Hi @anasatirbasa, thanks for the wait.

I have reviewed this PR with the team and have a few points that we would ideally like to fix.

I agree that introducing this separate annotation would solve the problem in an "opt in" non invasive way.

Considerations:

1. I'm trying to verify is whether the following is correct:

If both @DynamoDbAutoGeneratedUuid and @DynamoDbAutoGeneratedKey are applied to the same field, both extensions will execute in chain order. Since AutoGeneratedKeyExtension checks for existing values before generating, the behavior depends on registration order:

• If AutoGeneratedUuidExtension (current) runs first: It generates a UUID, then AutoGeneratedKeyExtension (new) sees the value exists and skips generation
• If AutoGeneratedKeyExtension (current) runs first: It generates conditionally, then AutoGeneratedUuidExtension (old) overwrites it anyway

This creates unpredictable behavior. If this is the case, can we please add some tests that cover it, and throw an exception when both annotations (new and current) are applied to the same field?

---

2. Fix documentation for WRITE_IF_NOT_EXISTS:

In v1, @DynamoDBAutoGeneratedKey used DynamoDBAutoGenerateStrategy.CREATE, which only generated UUIDs when the annotated value was null.
The v2 Enhanced Client’s @DynamoDbAutoGeneratedUuid removed this conditional logic entirely - it always generates regardless of existing values. The javadoc documents this as intentional:

“Every time a record with this attribute is written to the database it will update the attribute with a UUID#randomUUID string.”

but also, misleadingly suggests using UpdateBehavior.WRITE_IF_NOT_EXISTS as a workaround, which doesn’t work for primary keys due to DynamoDB’s updateItem API not allowing conditional updates on primary key attributes.

We will likely ask you to add more test coverage similar to other extensions test coverage, but I will provide more concrete about testing gaps in the near future after another review.

Thanks,
Ran~

[RanVaknin]

Please refer to my comments on the PR.

[RanVaknin]

Please add a test that checks what happens if both annotations are added to the same field. If my assumption is correct, based on the extensions' load order you can get conflicting results. If I'm correct we want to prevent these annotations from being applied to the same field by throwing an exception:

1. Add a check to make sure this annotation is not applied to a field that already has the current AutoGeneratedUuidExtension since they can conflict based on load order.

2. Do the inverse logic for AutoGeneratedUuidExtension#beforeWrite()

[anasatirbasa]

Please refer to my comments on the PR.

Hello, @RanVaknin! Thank you very much for your feedback! I am in progress with the changes.