1**Design:** New Feature, **Status:** [Released](../../../../../services-custom/dynamodb-enhanced/README.md) 2 3## Tenets (unless you know better ones) 4 51. Meeting customers in their problem space allows them to deliver value 6 quickly. 72. Meeting customer expectations drives usability. 83. Discoverability drives usage. 94. Providing a Java-focused experience for DynamoDB reduces the coding 10 effort required to integrate with DynamoDB. 115. Reusing the same nouns and verbs as the generated DynamoDB client 12 meets customer expectations. 136. Optimizing for cold-start performance allows customers the 14 convenience of using object mapping in a Lambda environment. 15 16## Problem 17 18Customers on the AWS SDK for Java 2.x currently use the `DynamoDbClient` 19to communicate with DynamoDB. This client is generated from the model 20provided by the DynamoDB team. 21 22Because this client is generated, it does not provide an idiomatic Java 23experience. For example: (1) the client represents numbers as `String` 24instead of the more idiomatic `Number`, (2) customers must manually 25convert common Java data types like `Instant` into types supported by 26DynamoDB, (3) customers that represent their DynamoDB objects using Java 27objects must manually convert these objects into the item representation 28supported by DynamoDB. 29 30## Existing Solutions 31 32This problem is not currently addressed directly in the AWS SDK for Java 332.x by any known third-party tool. In 1.11.x, several solutions exist, 34including AWS's own Document and Mapper Clients. 35 36## Proposed Solution [Implemented] 37 38The AWS SDK for Java will add a new "enhanced DynamoDB client" that 39provides an alternative to the data-access portion of the generated 40DynamoDB APIs. Only limited control-plane operations will be available, 41specifically 'createTable'. 42 43This enhanced client will make DynamoDB easier to use for Java customers 44by: 451. Supporting conversions between Java objects and DynamoDB items 462. Directly supporting every data-plane operation of DynamoDB 473. Using the same verbs and nouns of DynamoDB 484. Support for tests, such as the ability to create tables using the 49 same models as the data plane operations. 50 51A fully functional public preview is available for this library. See 52[DynamoDb Enhanced Public Preview 53Library](../../../../../services-custom/dynamodb-enhanced/README.md). 54 55## Appendix A: Requested Features 56 57* [Immutable classes](https://github.com/aws/aws-sdk-java-v2/issues/35#issuecomment-315049138) 58* [Getter/setter-less fields](https://github.com/aws/aws-sdk-java/issues/547) 59* [Replace `PaginatedList` with `Stream`](https://github.com/aws/aws-sdk-java-v2/issues/35#issuecomment-318051305) 60* [Allow 'setters' and 'getters' to support different types](https://github.com/aws/aws-sdk-java-v2/issues/35#issuecomment-318792534) 61* [Have 'scan' respect the table's read throughput](https://github.com/aws/aws-sdk-java-v2/issues/35#issuecomment-329007523) 62* [Allow creating a table with an LSI that projects all attributes](https://github.com/aws/aws-sdk-java/issues/214#issue-31304615) 63* [Projection expressions in 'load' and 'batchLoad'](https://github.com/aws/aws-sdk-java/issues/527) 64* [New condition expressions](https://github.com/aws/aws-sdk-java/issues/534) 65* [Accessing un-modeled/dynamic attributes in a POJO](https://github.com/aws/aws-sdk-java/issues/674) 66* [Inheritance](https://github.com/aws/aws-sdk-java/issues/832) 67* [Service-side metrics](https://github.com/aws/aws-sdk-java/issues/953) 68 ([1](https://github.com/aws/aws-sdk-java/issues/1170), 69 [2](https://github.com/aws/aws-sdk-java-v2/issues/703), 70 [3](https://github.com/aws/aws-sdk-java-v2/issues/35#issuecomment-417656448)) 71* [Merging DynamoDB mapper configurations](https://github.com/aws/aws-sdk-java/issues/1201) 72* [Cache merged DynamoDB mapper configurations](https://github.com/aws/aws-sdk-java/issues/1235) 73* [Create one single type converter interface](https://github.com/aws/aws-sdk-java-v2/issues/35#issuecomment-330616648) 74* [Support `@DynamoDBGeneratedUuid` in objects nested within lists](https://github.com/aws/aws-sdk-java-v2/issues/35#issuecomment-332958299) 75* [Allow annotating fields in addition to methods](https://github.com/aws/aws-sdk-java-v2/issues/35#issuecomment-332968651) 76* [Non-string keys in maps](https://github.com/aws/aws-sdk-java-v2/issues/35#issuecomment-332974427) 77* [Multiple conditions on the same attribute, for save/delete](https://github.com/aws/aws-sdk-java-v2/issues/35#issuecomment-342586344) 78* [Persisting public getters from package-private classes](https://github.com/aws/aws-sdk-java-v2/issues/35#issuecomment-343006566) 79* [Return modified attributes when doing a save](https://github.com/aws/aws-sdk-java-v2/issues/35#issuecomment-417656448) 80* [More direct exposure of scan or filter expressions](https://github.com/aws/aws-sdk-java-v2/issues/35#issuecomment-430993224) 81* [Transactions support](https://github.com/aws/aws-sdk-java-v2/issues/35#issuecomment-443308198) 82* [Creating an Item from JSON (and vice-versa)](https://github.com/aws/aws-sdk-java-v2/issues/1240) 83* Straight-forward support for multiple classes in a single table (as 84 per 85 [here](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-general-nosql-design.html)) 86 (from email) 87* Support for `Optional` (from email) 88* Support for `Publisher` for async paginated responses (from email) 89* Create a table with partial projections (from email) 90* Better integration with DynamoDB streams (from email) 91* Configuring table auto-scaling when a table is created (from email) 92* Request-level credentials (from email) 93* Wrappers for transactional isolation (from email) 94* Dynamic attributes - ones with different types depending on the value 95 of other attributes, or attributes with names that are generated at 96 runtime (from email) 97* Structure versioning (from email) 98 99## Appendix B: Alternative Solutions 100 101### Alternative Solution 1: Level 3 Storage Library 102 103A "Level 2" high-level library is a service-specific library built on 104top of the "Level 1" generated client. The solution proposed above is a 105Level 2 high-level library for DynamoDB. 106 107A "Level 3" high-level library focuses on a specific customer problem 108instead of a specific AWS service. For example, customers frequently use 109DynamoDB to store time series data. An alternate to the proposed 110solution above, would be to build multiple Level 3 libraries, each 111focusing on a specific customer problem: a document database library, a 112time series database library, etc. These libraries would support 113DynamoDB as one of many backing data stores. 114 115Instead of using traditional DynamoDB nouns and verbs (e.g. Item), a 116Level 3 library would use words more aligned to the problem domain (e.g. 117Document for document databases or Entry for time-series data). They 118would also expose operations more constrained to the problem domain they 119were trying to solve, instead of trying to expose every piece of 120DynamoDB functionality. 121 122This solution would be better for customers that are more familiar with 123the problem they are trying to solve and less familiar with DynamoDB. 124This solution would be worse for customers that are familiar with 125DynamoDB and want to be "closer" to the service. 126 127**Customer Feedback** 128 129The Java SDK team collected customer feedback internally and 130[externally](https://github.com/aws/aws-sdk-java-v2/issues/35#issuecomment-468435660), 131comparing this alternate solution against the proposed solution. 132Customers were presented with the following option comparison: 133 134> Option 1: A DynamoDB-specific client that combines the functionality 135> of 1.11.x's Documents APIs and DynamoDB Mapper APIs in a 136> straight-forward manner. 137 138> Option 2: A generic document database client that creates an 139> abstraction over all document databases, like DynamoDB and MongoDB. 140> This would simplify using multiple document databases in the same 141> application, and make it easier to migrate between the two. 142> Unfortunately as a result, it also wouldn't be a direct DynamoDB 143> experience. 144 145We requested that customers review these two options as well as a 146[prototype of option 1](prototype/option-1/sync/Prototype.java) and a 147[prototype of option 2](prototype/option-2/sync/Prototype.java), to let 148us know which they prefer. 149 150The following anecdotes are from this customer feedback: 151 152> If \[Amazon] can make something like https://serverless.com/ or 153> https://onnx.ai/ which free customers from vendor lock-in, that would 154> be a great Think Big & Customer Obsession idea. If \[Amazon] cannot, 155> I feel that somebody who is more vendor-neutral can make a better 156> mapper than \[Amazon]. 157 158> Have you thought about contributing to projects which already exist, 159> like Spring Data? https://github.com/derjust/spring-data-dynamodb 160 161> Both options would work well for us. 162 163> I think \[doing option 1 and then creating a Spring Data plugin] might 164> get adoption from a broader audience than option 2. It could be used 165> as a stepping stone to move to DynamoDB. 166 167> I believe Option 2 does not make much sense. It would make sense to me 168> to go for Option 1 and start a bounty program to implement a module to 169> popular data access abstraction libraries such as spring-data 170> mentioned above or GORM. 171 172> Maybe you could implement/support JNOSQL spec http://www.jnosql.org/ 173 174**Decision** 175 176Based on customer feedback, it was decided to temporarily reject 177alternative solution 1, and build the proposed solution. At a later 178time, the SDK may build a Level 3 abstraction for DynamoDB or integrate 179with existing Java Level 3 abstractions like Spring Data, Hibernate OGM, 180and/or JNoSQL. This Level 3 abstraction will possibly leverage the Level 1812 solution "under the hood". 182 183## Links 184 185**[Features](features.md)** - The features intended for inclusion during 186and after the launch of the enhanced DynamoDB client. 187 188**Prototypes** 189 190During the design of the project, two prototype interfaces were created 191to solicit feedback from customers on potential design directions. 192 193* [Prototype 1](prototype/option-1/sync/Prototype.java) - A DynamoDB 194 specific API that focuses on making DynamoDB easy to use from Java. 195* [Prototype 2](prototype/option-2/sync/Prototype.java) - A 196 DynamoDB-agnostic API that focuses on creating a generic document 197 database abstraction, that could be backed by DynamoDB or other 198 document databases. 199 200**Feedback** 201 202* [DynamoDB Mapper Feature Request](https://github.com/aws/aws-sdk-java-v2/issues/35) 203 \- A github issue for tracking customer feature requests and feedback 204 for DynamoDB mapper-equivalent functionality in 2.x. 205* [DynamoDB Document API Feature Request](https://github.com/aws/aws-sdk-java-v2/issues/36) 206 \- A github issue for tracking customer feature requests and feedback 207 for DynamoDB document API-equivalent functionality in 2.x.