DynamoDB enhanced editing pass.

services-custom/dynamodb-enhanced/README.md

@@ -1,42 +1,45 @@
 # DynamoDB Enhanced Clients
 
-The enhanced DynamoDB client replaces the generated DynamoDB client with
-one that is easier for a Java customer to use. It does this by
-supporting conversions between Java objects and DynamoDB items, as well
-as converting between Java built-in types (eg. java.time.Instant) and
-DynamoDB attribute value types.
+The enhanced Amazon DynamoDB client replaces the generated DynamoDB
+client with one that is easier for a Java customer to use. It does this
+by converting Java types into DynamoDB types.
+
+For example, the client makes it possible to persist a Book object in
+DynamoDB, without needing to manually convert the fields (e.g.
+List<Author>) into DynamoDB-specific types (e.g. List<Map<String,
+AttributeValue>>).
 
 # Current Features
 
-1. Synchronous and asynchronous (non-blocking) clients.
+1. Synchronous and asynchronous (nonblocking) clients.
 2. Writing a single item to DynamoDB.
 3. Reading a single item from DynamoDB.
 
 # Installation
 
 The enhanced client is currently in preview, and **is subject to change
-in backwards-incompatible ways**. For this reason, it's not currently
+in backward-incompatible ways**. For this reason, it's not currently
 released to Maven.
 
-The client must be manually installed in your local maven repository to
-be used in your application.
+You must manually install the client in your local Maven repository to
+use it in your application.
 
 **Step 1:** Check out the project from GitHub.
 
 ```bash
 git clone [email protected]:aws/aws-sdk-java-v2.git -b dynamodb-enhanced
 ``` 
 
-**Step 2:** Compile and install the project to your local maven
-repository. This command must be run from the directory to which you
+**Step 2:** Compile and install the project to your local Maven
+repository. You must run this command from the directory to which you
 checked out the project.
 
 ```bash
 mvn clean install -pl :dynamodb-enhanced -Pquick
 ```
 
 **Step 3:** Add a dependency on the `dynamodb-enhanced` project to your
-pom.xml:
+pom.xml file:
 
 ```xml
 <dependency>
@@ -46,9 +49,24 @@ pom.xml:
 </dependency>
 ```
 
+# Getting Started
+
+The enhanced DynamoDB client is still in preview, and is changing
+constantly. Until the client is released, you can refer to the following
+for usage examples:
+
+* [The issue for this feature](https://github.com/aws/aws-sdk-java-v2/issues/35):
+  Here you can see development updates and code samples.
+* [The `DynamoDbEnhancedClient` source and JavaDocs](https://github.com/aws/aws-sdk-java-v2/blob/dynamodb-enhanced/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.java):
+  Here you can see up-to-date code samples using the
+  `DynamoDbEnhancedClient`.
+* [The `DynamoDbEnhancedAsyncClient` source and JavaDocs](https://github.com/aws/aws-sdk-java-v2/blob/dynamodb-enhanced/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.java):
+  Here you can see up-to-date code samples using the
+  `DynamoDbEnhancedAsyncClient`.
+
 # Examples
 
-### Writing a book to DynamoDB
+### Writing a Book to DynamoDB
 
 **Enhanced API Code**
 
@@ -85,7 +103,7 @@ requestItem.put("authors", AttributeValue.builder().ss("Douglas Adams").build())
 client.putItem(r -> r.tableName(TABLE).item(requestItem));
 ```
 
-### Reading a book from DynamoDB
+### Reading a Book from DynamoDB
 
 **Enhanced API Code**
 

services-custom/dynamodb-enhanced/pom.xml

@@ -26,11 +26,16 @@
     <artifactId>dynamodb-enhanced</artifactId>
     <version>preview-SNAPSHOT</version>
     <name>AWS Java SDK :: DynamoDB :: Enhanced Client</name>
-    <description>The enhanced DynamoDB client replaces the generated DynamoDB client with
-        one that is easier for a Java customer to use. It does this by
-        supporting conversions between Java objects and DynamoDB items, as well
-        as converting between Java built-in types (eg. java.time.Instant) and
-        DynamoDB attribute value types.</description>
+    <description>
+        The enhanced Amazon DynamoDB client replaces the generated DynamoDB
+        client with one that is easier for a Java customer to use. It does this
+        by converting Java types into DynamoDB types.
+
+        For example, the client makes it possible to persist a Book object in
+        DynamoDB, without needing to manually convert the fields (e.g.
+        List&gt;Author&lt;) into DynamoDB-specific types (e.g. List&gt;Map&gt;String,
+        AttributeValue&lt;&lt;).
+    </description>
     <url>https://aws.amazon.com/sdkforjava</url>
 
     <properties>

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/AsyncTable.java

@@ -32,7 +32,7 @@
  *
  * <p>
  * This provides facilities for writing {@link RequestItem}s to a table and reading {@link ResponseItem}s from a table. All
- * operations are non-blocking, returning a {@link CompletableFuture} for the result, instead of the result itself.
+ * operations are nonblocking, returning a {@link CompletableFuture} for the result, instead of the result itself.
  *
  * <p>
  * Supported operations:
@@ -81,7 +81,7 @@ default String name() {
      *                                           .putAttribute("title", "The Hitchhiker's Guide to the Galaxy")
      *                                           .build());
      *
-     *     // Log when the book is done being written
+     *     // Log when the book is done being written.
      *     CompletableFuture<Void> resultLoggedFuture = serviceCallCompleteFuture.thenAccept(() -> {
      *         System.out.println("Book was successfully written!");
      *     });
@@ -120,7 +120,7 @@ default CompletableFuture<Void> putItem(RequestItem item) {
      *             booksTable.putItem(item -> item.putAttribute("isbn", "0-330-25864-8")
      *                                            .putAttribute("title", "The Hitchhiker's Guide to the Galaxy"));
      *
-     *     // Log when the book is done being written
+     *     // Log when the book is done being written.
      *     CompletableFuture<Void> resultLoggedFuture = serviceCallCompleteFuture.thenAccept(ignored -> {
      *         System.out.println("Book was successfully written!");
      *     });

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.java

@@ -33,14 +33,18 @@
  *
  * <p>
  * This enhanced DynamoDB client replaces the generated {@link DynamoDbAsyncClient} with one that is easier for a Java customer to
- * use. It does this by converting between Java built-in types (eg. java.time.Instant) and DynamoDB attribute value types.
+ * use. It does this by converting Java types into DynamoDB types.
+ *
+ * <p>
+ * For example, the client makes it possible to persist a Book object in DynamoDB, without needing to manually convert the fields
+ * (e.g. {@code List<Author>}) into DynamoDB-specific types (e.g. {@code List<Map<String, AttributeValue>>}).
  *
  * <p>
  * This can be created using the static {@link #builder()} or {@link #create()} methods. The client must be {@link #close()}d
  * when it is done being used.
  *
  * <p>
- * A {@code DynamoDbEnhancedAsyncClient} is thread-safe and relatively expensive to create. It's strongly advised to create a
+ * A {@code DynamoDbEnhancedAsyncClient} is thread-safe and relatively expensive to create. We strongly advise you to create a
  * single {@code DynamoDbEnhancedAsyncClient} instance that is reused throughout your whole application.
  *
  * <p>
@@ -65,7 +69,8 @@ public interface DynamoDbEnhancedAsyncClient
      * Create a {@link DynamoDbEnhancedAsyncClient} with default configuration.
      *
      * <p>
-     * The credentials and region will be loaded automatically, using the same semantics as {@link DynamoDbAsyncClient#create()}.
+     * The credentials and AWS Region will be loaded automatically, using the same semantics as
+     * {@link DynamoDbAsyncClient#create()}.
      *
      * <p>
      * Equivalent to {@code DynamoDbEnhancedAsyncClient.builder().build()}.
@@ -91,7 +96,7 @@ static DynamoDbEnhancedAsyncClient create() {
      * with custom configuration.
      *
      * <p>
-     * The credentials and region will be loaded from the configured {@link DynamoDbAsyncClient} (or
+     * The credentials and AWS Region will be loaded from the configured {@link DynamoDbAsyncClient} (or
      * {@link DynamoDbAsyncClient#create()} if one is not configured).
      *
      * <p>
@@ -142,7 +147,7 @@ static Builder builder() {
      * This can be created using the static {@link DynamoDbEnhancedAsyncClient#builder()} method.
      *
      * <p>
-     * Multiple clients can be created by the same builder, but unlike clients the builder <b>is not thread safe</b> and
+     * Multiple clients can be created by the same builder, but unlike clients the builder <b>is not thread-safe</b> and
      * should not be used from multiple threads at the same time.
      *
      * <p>
@@ -161,7 +166,7 @@ static Builder builder() {
     interface Builder extends CopyableBuilder<Builder, DynamoDbEnhancedAsyncClient>, ConverterAware.Builder {
         /**
          * Configure a generated client to be used by the enhanced client to interact with DynamoDB. The enhanced client
-         * will use the credentials and region of the provided generated client.
+         * will use the credentials and AWS Region of the provided generated client.
          *
          * <p>
          * The provided client <b>will not be closed</b> when {@link DynamoDbEnhancedAsyncClient#close()} is invoked, and

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.java

@@ -33,14 +33,18 @@
  *
  * <p>
  * This enhanced DynamoDB client replaces the generated {@link DynamoDbClient} with one that is easier for a Java customer to
- * use. It does this by converting between Java built-in types (eg. java.time.Instant) and DynamoDB attribute value types.
+ * use.  It does this by converting Java types into DynamoDB types.
+ *
+ * <p>
+ * For example, the client makes it possible to persist a Book object in DynamoDB, without needing to manually convert the fields
+ * (e.g. {@code List<Author>}) into DynamoDB-specific types (e.g. {@code List<Map<String, AttributeValue>>}).
  *
  * <p>
  * This can be created using the static {@link #builder()} or {@link #create()} methods. The client must be {@link #close()}d
  * when it is done being used.
  *
  * <p>
- * A {@code DynamoDbEnhancedClient} is thread-safe and relatively expensive to create. It's strongly advised to create a single
+ * A {@code DynamoDbEnhancedClient} is thread-safe and relatively expensive to create. We strongly advise you to create a single
  * {@code DynamoDbEnhancedClient} instance that is reused throughout your whole application.
  *
  * <p>
@@ -64,7 +68,7 @@ public interface DynamoDbEnhancedClient extends ToCopyableBuilder<DynamoDbEnhanc
      * Create a {@link DynamoDbEnhancedClient} with default configuration.
      *
      * <p>
-     * The credentials and region will be loaded automatically, using the same semantics as {@link DynamoDbClient#create()}.
+     * The credentials and AWS Region will be loaded automatically, using the same semantics as {@link DynamoDbClient#create()}.
      *
      * <p>
      * Equivalent to {@code DynamoDbEnhancedClient.builder().build()}.
@@ -90,8 +94,8 @@ static DynamoDbEnhancedClient create() {
      * configuration.
      *
      * <p>
-     * The credentials and region will be loaded from the configured {@link DynamoDbClient} (or {@link DynamoDbClient#create()}
-     * if one is not configured).
+     * The credentials and AWS Region will be loaded from the configured {@link DynamoDbClient} (or
+     * {@link DynamoDbClient#create()} if one is not configured).
      *
      * <p>
      * Sensible defaults will be used for any values not directly configured.
@@ -148,7 +152,7 @@ static DynamoDbEnhancedClient.Builder builder() {
      * This can be created using the static {@link DynamoDbEnhancedClient#builder()} method.
      *
      * <p>
-     * Multiple clients can be created by the same builder, but unlike clients the builder <b>is not thread safe</b> and
+     * Multiple clients can be created by the same builder, but unlike clients the builder <b>is not thread-safe</b> and
      * should not be used from multiple threads at the same time.
      *
      * <p>
@@ -167,7 +171,7 @@ static DynamoDbEnhancedClient.Builder builder() {
     interface Builder extends CopyableBuilder<Builder, DynamoDbEnhancedClient>, ConverterAware.Builder {
         /**
          * Configure a generated client to be used by the enhanced client to interact with DynamoDB. The enhanced client
-         * will use the credentials and region of the provided generated client.
+         * will use the credentials and AWS Region of the provided generated client.
          *
          * <p>
          * The provided client <b>will not be closed</b> when {@link DynamoDbEnhancedClient#close()} is invoked, and <b>must</b>

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/converter/DefaultConverterChain.java

@@ -91,7 +91,7 @@ public final class DefaultConverterChain implements ItemAttributeValueConverter
 
                                                 // InstanceOf Converters
                                                 // Potential optimization: allow InstanceOf converters to specify a set of
-                                                // types that should be cached in an eager fashion (eg. DefaultRequestItem)
+                                                // types that should be cached in an eager fashion (e.g. DefaultRequestItem)
                                                 .addConverter(new RequestItemConverter())
                                                 .addConverter(new ResponseItemConverter())
                                                 .addConverter(new ListConverter())

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/model/ConvertableItemAttributeValue.java

@@ -67,7 +67,7 @@ public interface ConvertableItemAttributeValue {
      * {@link #asList(Class)}. Maps should use {@link #asMap(Class, Class)}.
      *
      * <p>
-     * When creating a {@link TypeToken}, you must create an anonymous sub-class, eg.
+     * When creating a {@link TypeToken}, you must create an anonymous sub-class, e.g.
      * {@code new TypeToken<Collection<String>>()&#123;&#125;} (note the extra {}).
      */
     <T> T as(TypeToken<T> type);

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/model/TypeToken.java

@@ -105,7 +105,7 @@ private static Type validateIsSupportedType(Type type) {
     /**
      * Retrieve the {@link Class} object that this type token represents.
      *
-     * Eg. For {@code TypeToken<String>}, this would return {@code String.class}.
+     * e.g. For {@code TypeToken<String>}, this would return {@code String.class}.
      */
     public Class<T> rawClass() {
         return rawClass;
@@ -115,7 +115,7 @@ public Class<T> rawClass() {
      * Retrieve the {@link Class} objects of any type parameters for the class that this type token represents.
      *
      * <p>
-     * Eg. For {@code TypeToken<List<String>>}, this would return {@code String.class}, and {@link #rawClass()} would
+     * e.g. For {@code TypeToken<List<String>>}, this would return {@code String.class}, and {@link #rawClass()} would
      * return {@code List.class}.
      *
      * <p>