Moved dynamodb-enhanced to services-custom directory, to eventually include all hand-written service-specific libraries that aren't in the service's module. Improved JavaDoc.

Author: millems

pom.xml

@@ -53,7 +53,7 @@
         <module>aws-sdk-java</module>
         <module>core</module>
         <module>services</module>
-        <module>services-hll/dynamodb-enhanced</module>
+        <module>services-custom/dynamodb-enhanced</module>
         <module>bom</module>
         <module>bom-internal</module>
         <module>codegen</module>

services-hll/dynamodb-enhanced/README.md renamed to services-custom/dynamodb-enhanced/README.md

@@ -18,28 +18,33 @@
 import static org.assertj.core.api.Assertions.assertThat;
 
 import java.time.Instant;
-import java.util.Arrays;
 import java.util.Collections;
 import java.util.LinkedHashMap;
 import java.util.Map;
 import java.util.UUID;
-import java.util.function.Consumer;
 import org.junit.AfterClass;
 import org.junit.BeforeClass;
 import org.junit.Test;
 import software.amazon.awssdk.enhanced.dynamodb.model.RequestItem;
 import software.amazon.awssdk.enhanced.dynamodb.model.ResponseItem;
+import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
 import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
 import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
 import software.amazon.awssdk.services.dynamodb.model.KeyType;
 import software.amazon.awssdk.services.dynamodb.model.ResourceInUseException;
 import software.amazon.awssdk.services.dynamodb.model.ScalarAttributeType;
 import software.amazon.awssdk.services.dynamodb.model.TableStatus;
 import software.amazon.awssdk.testutils.Waiter;
+import software.amazon.awssdk.testutils.service.AwsTestBase;
 
-public class EnhancedClientIntegrationTest {
+public class EnhancedClientIntegrationTest extends AwsTestBase {
     private static final String TABLE = "books-" + UUID.randomUUID();
-    private static final DynamoDbClient dynamo = DynamoDbClient.create();
+    private static final DynamoDbClient dynamo = DynamoDbClient.builder()
+                                                               .credentialsProvider(CREDENTIALS_PROVIDER_CHAIN)
+                                                               .build();
+    private static final DynamoDbAsyncClient dynamoAsync = DynamoDbAsyncClient.builder()
+                                                                              .credentialsProvider(CREDENTIALS_PROVIDER_CHAIN)
+                                                                              .build();
 
     @BeforeClass
     public static void setup() {
@@ -74,7 +79,7 @@ public static void cleanup() {
 
     @Test
     public void getCanReadTheResultOfPut() throws InterruptedException {
-        try (DynamoDbEnhancedClient client = DynamoDbEnhancedClient.create()) {
+        try (DynamoDbEnhancedClient client = DynamoDbEnhancedClient.builder().dynamoDbClient(dynamo).build()) {
             Table books = client.table("books");
 
             System.out.println("Putting item...");
@@ -93,7 +98,7 @@ public void getCanReadTheResultOfPut() throws InterruptedException {
 
     @Test
     public void getCanReadTheResultOfPutAsync() throws InterruptedException {
-        try (DynamoDbEnhancedAsyncClient client = DynamoDbEnhancedAsyncClient.create()) {
+        try (DynamoDbEnhancedAsyncClient client = DynamoDbEnhancedAsyncClient.builder().dynamoDbClient(dynamoAsync).build()) {
             AsyncTable books = client.table("books");
 
             System.out.println("Putting item...");

services-hll/dynamodb-enhanced/it/main/java/software/amazon/awssdk/enhanced/dynamodb/EnhancedClientIntegrationTest.java renamed to services-custom/dynamodb-enhanced/it/main/java/software/amazon/awssdk/enhanced/dynamodb/EnhancedClientIntegrationTest.java

@@ -71,6 +71,18 @@
             <version>2.5.25</version>
         </dependency>
 
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>service-test-utils</artifactId>
+            <version>2.5.25</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>test-utils</artifactId>
+            <version>2.5.25</version>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <artifactId>junit</artifactId>
             <groupId>junit</groupId>
@@ -86,11 +98,6 @@
             <artifactId>mockito-core</artifactId>
             <scope>test</scope>
         </dependency>
-        <dependency>
-            <groupId>software.amazon.awssdk</groupId>
-            <artifactId>test-utils</artifactId>
-            <scope>test</scope>
-        </dependency>
         <dependency>
             <groupId>log4j</groupId>
             <artifactId>log4j</artifactId>

services-hll/dynamodb-enhanced/pom.xml renamed to services-custom/dynamodb-enhanced/pom.xml

@@ -30,15 +30,18 @@
  * An asynchronous way of interacting with a DynamoDB table. This is usually created via
  * {@link DynamoDbEnhancedAsyncClient#table(String)}.
  *
+ * <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.
  *
+ * <p>
  * Supported operations:
  * <ol>
  *     <li>{@link #getItem(RequestItem)} to retrieve a single item from the table.</li>
  *     <li>{@link #putItem(RequestItem)} to write a single item to a table.</li>
  * </ol>
  *
+ * <p>
  * This {@link AsyncTable} will throw exceptions from all operations if the {@link DynamoDbEnhancedAsyncClient} that was used to
  * create it is closed.
  */
@@ -58,10 +61,13 @@ default String name() {
      * Call DynamoDB to write the requested item, potentially replacing an existing item that has a key matching this item. If
      * this does not throw an exception, the item was successfully written.
      *
+     * <p>
      * This has the same semantics as {@link DynamoDbAsyncClient#putItem(PutItemRequest)}.
      *
+     * <p>
      * This returns a future that will only be completed when the item is done being written.
      *
+     * <p>
      * Example Usage:
      * <code>
      * // Create a client to use for this example, and then close it. Usually, one client would be used throughout an application.
@@ -93,12 +99,16 @@ default CompletableFuture<Void> putItem(RequestItem item) {
      * Call DynamoDB to write the requested item, potentially replacing an existing item that has a key matching this item. If
      * this does not throw an exception, the item was successfully written.
      *
+     * <p>
      * This has the same semantics as {@link DynamoDbAsyncClient#putItem(PutItemRequest)}.
      *
+     * <p>
      * This returns a future that will only be completed when the item is done being written.
      *
+     * <p>
      * This is a less verbose way of calling {@link #putItem(RequestItem)}.
      *
+     * <p>
      * Example Usage:
      * <code>
      * // Create a client to use for this example, and then close it. Usually, one client would be used throughout an application.
@@ -129,11 +139,14 @@ default CompletableFuture<Void> putItem(Consumer<RequestItem.Builder> item) {
     /**
      * Call DynamoDB to read the item that matches the provided key. This will throw an exception if the item cannot be found.
      *
+     * <p>
      * This has the same semantics as {@link DynamoDbAsyncClient#getItem(GetItemRequest)}, which means this performs eventually
      * consistent reads by default.
      *
+     * <p>
      * This returns a future that will only be completed when the item is done being read.
      *
+     * <p>
      * Example Usage:
      * <code>
      * // Create a client to use for this example, and then close it. Usually, one client would be used throughout an application.
@@ -162,13 +175,17 @@ default CompletableFuture<ResponseItem> getItem(RequestItem key) {
     /**
      * Call DynamoDB to read the item that matches the provided key. This will throw an exception if the item cannot be found.
      *
+     * <p>
      * This has the same semantics as {@link DynamoDbAsyncClient#getItem(GetItemRequest)}, which means this performs eventually
      * consistent reads by default.
      *
+     * <p>
      * This returns a future that will only be completed when the item is done being read.
      *
+     * <p>
      * This is a less verbose way of calling {@link #getItem(RequestItem)}.
      *
+     * <p>
      * Example Usage:
      * <code>
      * // Create a client to use for this example, and then close it. Usually, one client would be used throughout an application.

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

@@ -31,15 +31,19 @@
 /**
  * An asynchronous client for interacting with DynamoDB.
  *
+ * <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.
  *
+ * <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
  * single {@code DynamoDbEnhancedAsyncClient} instance that is reused throughout your whole application.
  *
+ * <p>
  * Example Usage:
  * <code>
  * // Create a client to use for this example, and then close it. Usually, one client would be used throughout an application.
@@ -60,10 +64,13 @@ 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()}.
      *
+     * <p>
      * Equivalent to {@code DynamoDbEnhancedAsyncClient.builder().build()}.
      *
+     * <p>
      * Example Usage:
      * <code>
      * // Create a client to use for this example, and then close it. Usually, one client would be used throughout an application.
@@ -83,11 +90,14 @@ static DynamoDbEnhancedAsyncClient create() {
      * Create a {@link DynamoDbEnhancedAsyncClient.Builder} that can be used to create a {@link DynamoDbEnhancedAsyncClient}
      * with custom configuration.
      *
+     * <p>
      * The credentials and region will be loaded from the configured {@link DynamoDbAsyncClient} (or
      * {@link DynamoDbAsyncClient#create()} if one is not configured).
      *
+     * <p>
      * Sensible defaults will be used for any values not directly configured.
      *
+     * <p>
      * Example Usage:
      * <code>
      * // Create a client to use for this example, and then close it. Usually, one client would be used throughout an application.
@@ -109,9 +119,11 @@ static Builder builder() {
      * Retrieve an {@link AsyncTable} that can be used for interacting with DynamoDB. This does not make any remote calls,
      * and as a result does not validate that the requested table actually exists.
      *
+     * <p>
      * If the table does not exist, exceptions will be thrown when trying to load or retrieve data from the returned
      * {@link AsyncTable} object. The returned {@link AsyncTable} will stop working if the enhanced client is {@link #close()}d.
      *
+     * <p>
      * Example Usage:
      * <code>
      * // Create a client to use for this example, and then close it. Usually, one client would be used throughout an application.
@@ -126,11 +138,14 @@ static Builder builder() {
     /**
      * A builder for {@link DynamoDbEnhancedAsyncClient}.
      *
+     * <p>
      * 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
      * should not be used from multiple threads at the same time.
      *
+     * <p>
      * Example Usage:
      * <code>
      * // Create a client to use for this example, and then close it. Usually, one client would be used throughout an application.
@@ -148,9 +163,11 @@ interface Builder extends CopyableBuilder<Builder, DynamoDbEnhancedAsyncClient>,
          * 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.
          *
+         * <p>
          * The provided client <b>will not be closed</b> when {@link DynamoDbEnhancedAsyncClient#close()} is invoked, and
          * <b>must</b> be closed separately when it is done being used to prevent leaking resources.
          *
+         * <p>
          * If this is not configured, {@link DynamoDbAsyncClient#create()} will be used (and cleaned up with
          * {@link DynamoDbEnhancedAsyncClient#close()}).
          */

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

@@ -31,15 +31,19 @@
 /**
  * A synchronous client for interacting with DynamoDB.
  *
+ * <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.
  *
+ * <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
  * {@code DynamoDbEnhancedClient} instance that is reused throughout your whole application.
  *
+ * <p>
  * Example Usage:
  * <code>
  * // Create a client to use for this example, and then close it. Usually, one client would be used throughout an application.
@@ -59,10 +63,13 @@ 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()}.
      *
+     * <p>
      * Equivalent to {@code DynamoDbEnhancedClient.builder().build()}.
      *
+     * <p>
      * Example Usage:
      * <code>
      * // Create a client to use for this example, and then close it. Usually, one client would be used throughout an application.
@@ -82,11 +89,14 @@ static DynamoDbEnhancedClient create() {
      * Create a {@link DynamoDbEnhancedClient.Builder} that can be used to create a {@link DynamoDbEnhancedClient} with custom
      * configuration.
      *
+     * <p>
      * The credentials and 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.
      *
+     * <p>
      * Example Usage:
      * <code>
      * // Create a client to use for this example, and then close it. Usually, one client would be used throughout an application.
@@ -108,9 +118,11 @@ static DynamoDbEnhancedClient.Builder builder() {
      * Retrieve a {@link Table} that can be used for interacting with DynamoDB. This does not make any remote calls, and as a
      * result does not validate that the requested table actually exists.
      *
+     * <p>
      * If the table does not exist, exceptions will be thrown when trying to load or retrieve data from the returned
      * {@link Table} object. The returned {@link Table} will stop working if the enhanced client is {@link #close()}d.
      *
+     * <p>
      * Example Usage:
      * <code>
      * // Create a client to use for this example, and then close it. Usually, one client would be used throughout an application.
@@ -132,11 +144,14 @@ static DynamoDbEnhancedClient.Builder builder() {
     /**
      * A builder for {@link DynamoDbEnhancedClient}.
      *
+     * <p>
      * 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
      * should not be used from multiple threads at the same time.
      *
+     * <p>
      * Example Usage:
      * <code>
      * // Create a client to use for this example, and then close it. Usually, one client would be used throughout an application.
@@ -154,9 +169,11 @@ interface Builder extends CopyableBuilder<Builder, DynamoDbEnhancedClient>, Conv
          * 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.
          *
+         * <p>
          * The provided client <b>will not be closed</b> when {@link DynamoDbEnhancedClient#close()} is invoked, and <b>must</b>
          * be closed separately when it is done being used to prevent leaking resources.
          *
+         * <p>
          * If this is not configured, {@link DynamoDbClient#create()} will be used (and cleaned up with
          * {@link DynamoDbEnhancedClient#close()}).
          */