diff --git a/services-custom/dynamodb-enhanced/README.md b/services-custom/dynamodb-enhanced/README.md index c197e6fc942b..587705b21f58 100644 --- a/services-custom/dynamodb-enhanced/README.md +++ b/services-custom/dynamodb-enhanced/README.md @@ -1,25 +1,28 @@ # 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) into DynamoDB-specific types (e.g. List>). # 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. @@ -27,8 +30,8 @@ be used in your application. git clone git@github.com: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 @@ -36,7 +39,7 @@ 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 @@ -46,9 +49,24 @@ pom.xml: ``` +# 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** diff --git a/services-custom/dynamodb-enhanced/pom.xml b/services-custom/dynamodb-enhanced/pom.xml index d0d9c9103a20..aa9968aa06cd 100644 --- a/services-custom/dynamodb-enhanced/pom.xml +++ b/services-custom/dynamodb-enhanced/pom.xml @@ -26,11 +26,16 @@ dynamodb-enhanced preview-SNAPSHOT AWS Java SDK :: DynamoDB :: Enhanced Client - 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<<). + https://aws.amazon.com/sdkforjava diff --git a/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/AsyncTable.java b/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/AsyncTable.java index d961ae242933..48f8ff89663a 100644 --- a/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/AsyncTable.java +++ b/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/AsyncTable.java @@ -32,7 +32,7 @@ * *

* 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. * *

* 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 resultLoggedFuture = serviceCallCompleteFuture.thenAccept(() -> { * System.out.println("Book was successfully written!"); * }); @@ -120,7 +120,7 @@ default CompletableFuture 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 resultLoggedFuture = serviceCallCompleteFuture.thenAccept(ignored -> { * System.out.println("Book was successfully written!"); * }); diff --git a/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.java b/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.java index 76c46829ab34..68ae0864eb94 100644 --- a/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.java +++ b/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.java @@ -33,14 +33,18 @@ * *

* 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. + * + *

+ * 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}) into DynamoDB-specific types (e.g. {@code List>}). * *

* 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. * *

- * 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. * *

@@ -65,7 +69,8 @@ public interface DynamoDbEnhancedAsyncClient * Create a {@link DynamoDbEnhancedAsyncClient} with default configuration. * *

- * 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()}. * *

* Equivalent to {@code DynamoDbEnhancedAsyncClient.builder().build()}. @@ -91,7 +96,7 @@ static DynamoDbEnhancedAsyncClient create() { * with custom configuration. * *

- * 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). * *

@@ -142,7 +147,7 @@ static Builder builder() { * This can be created using the static {@link DynamoDbEnhancedAsyncClient#builder()} method. * *

- * Multiple clients can be created by the same builder, but unlike clients the builder is not thread safe and + * Multiple clients can be created by the same builder, but unlike clients the builder is not thread-safe and * should not be used from multiple threads at the same time. * *

@@ -161,7 +166,7 @@ static Builder builder() { interface Builder extends CopyableBuilder, 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. * *

* The provided client will not be closed when {@link DynamoDbEnhancedAsyncClient#close()} is invoked, and diff --git a/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.java b/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.java index 59e944d2631a..a5a0a30e1ef7 100644 --- a/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.java +++ b/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.java @@ -33,14 +33,18 @@ * *

* 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. + * + *

+ * 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}) into DynamoDB-specific types (e.g. {@code List>}). * *

* 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. * *

- * 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. * *

@@ -64,7 +68,7 @@ public interface DynamoDbEnhancedClient extends ToCopyableBuilder - * 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()}. * *

* Equivalent to {@code DynamoDbEnhancedClient.builder().build()}. @@ -90,8 +94,8 @@ static DynamoDbEnhancedClient create() { * configuration. * *

- * 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). * *

* 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. * *

- * Multiple clients can be created by the same builder, but unlike clients the builder is not thread safe and + * Multiple clients can be created by the same builder, but unlike clients the builder is not thread-safe and * should not be used from multiple threads at the same time. * *

@@ -167,7 +171,7 @@ static DynamoDbEnhancedClient.Builder builder() { interface Builder extends CopyableBuilder, 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. * *

* The provided client will not be closed when {@link DynamoDbEnhancedClient#close()} is invoked, and must diff --git a/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/converter/DefaultConverterChain.java b/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/converter/DefaultConverterChain.java index f6f5dafcfd90..400af0f317b1 100644 --- a/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/converter/DefaultConverterChain.java +++ 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()) diff --git a/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/model/ConvertableItemAttributeValue.java b/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/model/ConvertableItemAttributeValue.java index 87ae9c9eba09..91aaa490bd16 100644 --- a/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/model/ConvertableItemAttributeValue.java +++ b/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)}. * *

- * 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>(){}} (note the extra {}). */ T as(TypeToken type); diff --git a/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/model/TypeToken.java b/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/model/TypeToken.java index 26a9cbbcb7ee..810971b762f6 100644 --- a/services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/model/TypeToken.java +++ b/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}, this would return {@code String.class}. + * e.g. For {@code TypeToken}, this would return {@code String.class}. */ public Class rawClass() { return rawClass; @@ -115,7 +115,7 @@ public Class rawClass() { * Retrieve the {@link Class} objects of any type parameters for the class that this type token represents. * *

- * Eg. For {@code TypeToken>}, this would return {@code String.class}, and {@link #rawClass()} would + * e.g. For {@code TypeToken>}, this would return {@code String.class}, and {@link #rawClass()} would * return {@code List.class}. * *