DynamoDB: add support for transactional writes that include update operations with custom update and condition expressions

[RenesansJG]

Description

DynamoDB transactional writes that are created using the document model or the object model can now include update operations with custom update and condition expressions:

• Document model:
  • AddKeyToUpdate methods have been added to the DocumentTransactWrite class. The methods enable adding an update operation to the transaction with an arbitrary update expression instead of providing a Document.
  • Since the TransactWriteItemOperationConfig can also include a condition expression, the AddKeyToUpdate call can include both an update expression and a condition expression. This enables conflicts to occur between the two expressions if they use the same parameter names for attribute names and/or values. If both expressions contain the same parameter, but with different values, an exception is thrown.
• Object model:
  • AddSaveKey methods have been added to the TransactWrite class. The methods enable adding a save operation with an arbitrary update expression instead of providing an object. Optionally, a condition expression can be provided because due to the lack of object, no version check can occur. This also enables more complex condition expressions than the simple version check.
  • The AddDeleteKey methods now include an optional parameter for the condition expression. This is comparable to the same parameter of the AddSaveKey methods and is added for symmetry.

Motivation and Context

The new operations are useful in scenarios when an item needs to be updated without retrieving it first. This can help avoid conflicts in some cases.

Example scenario:

• A table includes items with a partition key and a range key.
• We want to limit the number of items per partition.
• Another table contains items which include a counter. The partition key is the same as for the other table and there is no range key. Thus, the counters count the number of items per partition in the other table.
• Adding an item to the first table with checking the limit can be implemented the following way using the existing object model and document model operations:
  • Retrieve the counter.
  • Check whether the counter will reach its limit when incremented.
  • Add the new item and update the counter in a transaction.
• However, conflicts can occur if many such operations happen concurrently. The counter needs to include a version property to ensure each added item increments the counter by one. The version check may fail if the counter has been updated by another concurrent operation and the operation needs to be retried with retrieving the counter again. Multiple retries may be necessary if there are lots of concurrent operations.

DynamoDB update expressions can be used to increment a value by a given amount (e.g SET counter = counter + 1). Using an update expression without needing to use low-level operations is possible with the changes in this PR.

The example above can be implemented by using a transaction that includes the an operation that adds the new item and an update operation with an update expression that increments the counter and a condition expression that checks that the counter cannot surpass the limit.

Testing

Existing DynamoDB integration tests have been extended to test the new operations for both models. All tests passed.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• My code follows the code style of this project
• My change requires a change to the documentation
• I have updated the documentation accordingly
• I have read the README document
• I have added tests to cover my changes
• All new and existing tests passed

License

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