Support DescribeTable operation in DynamoDbTable and DynamodbAsyncTable (#2844)

* Support DescribeTable operation in DynamoDbTable and DynamodbAsyncTable

* Change DescribeTableEnhancedResponse to expose getters of the low level response

Author: zoewangg

.changes/next-release/feature-DynamoDBEnhancedClient-2d0150f.json

@@ -0,0 +1,6 @@
+{
+    "category": "DynamoDB Enhanced Client", 
+    "contributor": "", 
+    "type": "feature", 
+    "description": "Implement `DescribeTable` operation in `DynamoDbTable` and `DynamoDbAsyncTable`"
+}

services-custom/dynamodb-enhanced/pom.xml

@@ -170,6 +170,11 @@
             <artifactId>wiremock</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>nl.jqno.equalsverifier</groupId>
+            <artifactId>equalsverifier</artifactId>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>com.amazonaws</groupId>
             <artifactId>DynamoDBLocal</artifactId>

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

@@ -21,6 +21,7 @@
 import software.amazon.awssdk.enhanced.dynamodb.model.CreateTableEnhancedRequest;
 import software.amazon.awssdk.enhanced.dynamodb.model.DeleteItemEnhancedRequest;
 import software.amazon.awssdk.enhanced.dynamodb.model.DeleteItemEnhancedResponse;
+import software.amazon.awssdk.enhanced.dynamodb.model.DescribeTableEnhancedResponse;
 import software.amazon.awssdk.enhanced.dynamodb.model.GetItemEnhancedRequest;
 import software.amazon.awssdk.enhanced.dynamodb.model.Page;
 import software.amazon.awssdk.enhanced.dynamodb.model.PagePublisher;
@@ -33,6 +34,8 @@
 import software.amazon.awssdk.enhanced.dynamodb.model.UpdateItemEnhancedResponse;
 import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
 import software.amazon.awssdk.services.dynamodb.model.ConsumedCapacity;
+import software.amazon.awssdk.services.dynamodb.model.DescribeTableRequest;
+import software.amazon.awssdk.services.dynamodb.waiters.DynamoDbAsyncWaiter;
 
 /**
  * Asynchronous interface for running commands against an object that is linked to a specific DynamoDb table resource
@@ -63,7 +66,7 @@ public interface DynamoDbAsyncTable<T> extends MappedTableResource<T> {
      * <p>
      * This operation calls the low-level DynamoDB API CreateTable operation. Note that this is an asynchronous operation and that
      * the table may not immediately be available for writes and reads.
-     * Consult the CreateTable documentation for further details and constraints.
+     * You can use {@link DynamoDbAsyncWaiter#waitUntilTableExists(DescribeTableRequest)} to wait for the resource to be ready.
      * <p>
      * Example:
      * <pre>
@@ -77,6 +80,7 @@ public interface DynamoDbAsyncTable<T> extends MappedTableResource<T> {
      *                                                   .provisionedThroughput(provisionedThroughput)
      *                                                   .build())
      *            .join();
+     * asyncClient.waiter().waitUntilTableExists(b -> b.tableName(tableName)).join();
      * }
      * </pre>
      *
@@ -94,8 +98,8 @@ default CompletableFuture<Void> createTable(CreateTableEnhancedRequest request)
      * Use {@link DynamoDbEnhancedClient#table(String, TableSchema)} to define the mapped table resource.
      * <p>
      * This operation calls the low-level DynamoDB API CreateTable operation. Note that this is an asynchronous operation and that
-     * the table may not immediately be available for writes and reads.
-     * Consult the CreateTable documentation for further details and constraints.
+     * the table may not immediately be available for writes and reads. You can use
+     * {@link DynamoDbAsyncWaiter#waitUntilTableExists(DescribeTableRequest)} to wait for the resource to be ready.
      * <p>
      * <b>Note:</b> This is a convenience method that creates an instance of the request builder avoiding the need to create one
      * manually via {@link CreateTableEnhancedRequest#builder()}.
@@ -109,6 +113,7 @@ default CompletableFuture<Void> createTable(CreateTableEnhancedRequest request)
      *                                                                    .writeCapacityUnits(50L)
      *                                                                    .build();
      * mappedTable.createTable(r -> r.provisionedThroughput(provisionedThroughput)).join();
+     * asyncClient.waiter().waitUntilTableExists(b -> b.tableName(tableName)).join();
      * }
      * </pre>
      *
@@ -126,15 +131,15 @@ default CompletableFuture<Void> createTable(Consumer<CreateTableEnhancedRequest.
      * Use {@link DynamoDbEnhancedClient#table(String, TableSchema)} to define the mapped table resource.
      * <p>
      * This operation calls the low-level DynamoDB API CreateTable operation. Note that this is an asynchronous operation and that
-     * the table may not immediately be available for writes and reads. Currently, there is no mechanism supported within this
-     * library to wait for/check the status of a created table. You must provide this functionality yourself.
-     * Consult the CreateTable documentation for further details and constraints.
+     * the table may not immediately be available for writes and reads.  You can use
+     * {@link DynamoDbAsyncWaiter#waitUntilTableExists(DescribeTableRequest)} to wait for the resource to be ready.
      * <p>
      * Example:
      * <pre>
      * {@code
      *
      * mappedTable.createTable().join();
+     * asyncClient.waiter().waitUntilTableExists(b -> b.tableName(tableName)).join();
      * }
      * </pre>
      *
@@ -861,4 +866,22 @@ default CompletableFuture<UpdateItemEnhancedResponse<T>> updateItemWithResponse(
     default CompletableFuture<Void> deleteTable() {
         throw new UnsupportedOperationException();
     }
+
+    /**
+     * Describes a table in DynamoDb with the name defined for this {@link DynamoDbAsyncTable).
+     * This operation calls the low-level DynamoDB API DescribeTable operation,
+     * see {@link DynamoDbAsyncClient#describeTable(DescribeTableRequest)}
+     *
+     * <p>
+     * Example:
+     * <pre>
+     * {@code
+     *
+     * DescribeTableEnhancedResponse response = mappedTable.describeTable().join();
+     * }
+     * </pre>
+     */
+    default CompletableFuture<DescribeTableEnhancedResponse> describeTable() {
+        throw new UnsupportedOperationException();
+    }
 }

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

@@ -21,6 +21,7 @@
 import software.amazon.awssdk.enhanced.dynamodb.model.CreateTableEnhancedRequest;
 import software.amazon.awssdk.enhanced.dynamodb.model.DeleteItemEnhancedRequest;
 import software.amazon.awssdk.enhanced.dynamodb.model.DeleteItemEnhancedResponse;
+import software.amazon.awssdk.enhanced.dynamodb.model.DescribeTableEnhancedResponse;
 import software.amazon.awssdk.enhanced.dynamodb.model.GetItemEnhancedRequest;
 import software.amazon.awssdk.enhanced.dynamodb.model.Page;
 import software.amazon.awssdk.enhanced.dynamodb.model.PageIterable;
@@ -33,6 +34,8 @@
 import software.amazon.awssdk.enhanced.dynamodb.model.UpdateItemEnhancedResponse;
 import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
 import software.amazon.awssdk.services.dynamodb.model.ConsumedCapacity;
+import software.amazon.awssdk.services.dynamodb.model.DescribeTableRequest;
+import software.amazon.awssdk.services.dynamodb.waiters.DynamoDbWaiter;
 
 /**
  * Synchronous interface for running commands against an object that is linked to a specific DynamoDb table resource
@@ -62,9 +65,8 @@ public interface DynamoDbTable<T> extends MappedTableResource<T> {
      * Use {@link DynamoDbEnhancedClient#table(String, TableSchema)} to define the mapped table resource.
      * <p>
      * This operation calls the low-level DynamoDB API CreateTable operation. Note that this is an asynchronous
-     * operation and that the table may not immediately be available for writes and reads. Currently, there is no
-     * mechanism supported within this library to wait for/check the status of a created table. You must provide this
-     * functionality yourself. Consult the CreateTable documentation for further details and constraints.
+     * operation and that the table may not immediately be available for writes and reads. You can use
+     * {@link DynamoDbWaiter#waitUntilTableExists(DescribeTableRequest)} to wait for the resource to be ready.
      * <p>
      * Example:
      * <pre>
@@ -77,6 +79,8 @@ public interface DynamoDbTable<T> extends MappedTableResource<T> {
      * mappedTable.createTable(CreateTableEnhancedRequest.builder()
      *                                                   .provisionedThroughput(provisionedThroughput)
      *                                                   .build());
+     *
+     * dynamoDbClient.waiter().waitUntilTableExists(b -> b.tableName(tableName));
      * }
      * </pre>
      *
@@ -93,9 +97,8 @@ default void createTable(CreateTableEnhancedRequest request) {
      * Use {@link DynamoDbEnhancedClient#table(String, TableSchema)} to define the mapped table resource.
      * <p>
      * This operation calls the low-level DynamoDB API CreateTable operation. Note that this is an asynchronous
-     * operation and that the table may not immediately be available for writes and reads. Currently, there is no
-     * mechanism supported within this library to wait for/check the status of a created table. You must provide this
-     * functionality yourself. Consult the CreateTable documentation for further details and constraints.
+     * operation and that the table may not immediately be available for writes and reads. You can use
+     * {@link DynamoDbWaiter#waitUntilTableExists(DescribeTableRequest)} to wait for the resource to be ready.
      * <p>
      * <b>Note:</b> This is a convenience method that creates an instance of the request builder avoiding the need to
      * create one manually via {@link CreateTableEnhancedRequest#builder()}.
@@ -109,6 +112,7 @@ default void createTable(CreateTableEnhancedRequest request) {
      *                                                                    .writeCapacityUnits(50L)
      *                                                                    .build();
      * mappedTable.createTable(r -> r.provisionedThroughput(provisionedThroughput));
+     * dynamoDbClient.waiter().waitUntilTableExists(b -> b.tableName(tableName));
      * }
      * </pre>
      *
@@ -125,15 +129,15 @@ default void createTable(Consumer<CreateTableEnhancedRequest.Builder> requestCon
      * Use {@link DynamoDbEnhancedClient#table(String, TableSchema)} to define the mapped table resource.
      * <p>
      * This operation calls the low-level DynamoDB API CreateTable operation. Note that this is an asynchronous
-     * operation and that the table may not immediately be available for writes and reads. Currently, there is no
-     * mechanism supported within this library to wait for/check the status of a created table. You must provide this
-     * functionality yourself. Consult the CreateTable documentation for further details and constraints.
+     * operation and that the table may not immediately be available for writes and reads. You can use
+     * {@link DynamoDbWaiter#waitUntilTableExists(DescribeTableRequest)} to wait for the resource to be ready.
      * <p>
      * Example:
      * <pre>
      * {@code
      *
      * mappedTable.createTable();
+     * dynamoDbClient.waiter().waitUntilTableExists(b -> b.tableName(tableName));
      * }
      * </pre>
      *
@@ -827,8 +831,8 @@ default UpdateItemEnhancedResponse<T> updateItemWithResponse(Consumer<UpdateItem
      * Use {@link DynamoDbEnhancedClient#table(String, TableSchema)} to define the mapped table resource.
      * <p>
      * This operation calls the low-level DynamoDB API DeleteTable operation.
-     * Note that this is an asynchronousoperation and that the table may not immediately be deleted. You can use
-     * {@link software.amazon.awssdk.services.dynamodb.waiters.DynamoDbWaiter#waitUntilTableNotExists}
+     * Note that this is an asynchronous operation and that the table may not immediately be deleted. You can use
+     * {@link DynamoDbWaiter#waitUntilTableNotExists}
      * in the underlying client.
      * <p>
      * Example:
@@ -843,4 +847,22 @@ default UpdateItemEnhancedResponse<T> updateItemWithResponse(Consumer<UpdateItem
     default void deleteTable() {
         throw new UnsupportedOperationException();
     }
+
+    /**
+     * Describes a table in DynamoDb with the name defined for this {@link DynamoDbTable).
+     * This operation calls the low-level DynamoDB API DescribeTable operation,
+     * see {@link DynamoDbClient#describeTable(DescribeTableRequest)}
+     * <p>
+     * Example:
+     * <pre>
+     * {@code
+     *
+     * DescribeTableEnhancedResponse response = mappedTable.describeTable();
+     * }
+     * </pre>
+     *
+     */
+    default DescribeTableEnhancedResponse describeTable() {
+        throw new UnsupportedOperationException();
+    }
 }

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/internal/client/DefaultDynamoDbAsyncTable.java

@@ -28,6 +28,7 @@
 import software.amazon.awssdk.enhanced.dynamodb.internal.operations.CreateTableOperation;
 import software.amazon.awssdk.enhanced.dynamodb.internal.operations.DeleteItemOperation;
 import software.amazon.awssdk.enhanced.dynamodb.internal.operations.DeleteTableOperation;
+import software.amazon.awssdk.enhanced.dynamodb.internal.operations.DescribeTableOperation;
 import software.amazon.awssdk.enhanced.dynamodb.internal.operations.GetItemOperation;
 import software.amazon.awssdk.enhanced.dynamodb.internal.operations.PaginatedTableOperation;
 import software.amazon.awssdk.enhanced.dynamodb.internal.operations.PutItemOperation;
@@ -38,6 +39,7 @@
 import software.amazon.awssdk.enhanced.dynamodb.model.CreateTableEnhancedRequest;
 import software.amazon.awssdk.enhanced.dynamodb.model.DeleteItemEnhancedRequest;
 import software.amazon.awssdk.enhanced.dynamodb.model.DeleteItemEnhancedResponse;
+import software.amazon.awssdk.enhanced.dynamodb.model.DescribeTableEnhancedResponse;
 import software.amazon.awssdk.enhanced.dynamodb.model.GetItemEnhancedRequest;
 import software.amazon.awssdk.enhanced.dynamodb.model.PagePublisher;
 import software.amazon.awssdk.enhanced.dynamodb.model.PutItemEnhancedRequest;
@@ -48,6 +50,8 @@
 import software.amazon.awssdk.enhanced.dynamodb.model.UpdateItemEnhancedRequest;
 import software.amazon.awssdk.enhanced.dynamodb.model.UpdateItemEnhancedResponse;
 import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
+import software.amazon.awssdk.services.dynamodb.model.DescribeTableRequest;
+import software.amazon.awssdk.services.dynamodb.model.DescribeTableResponse;
 
 @SdkInternalApi
 public final class DefaultDynamoDbAsyncTable<T> implements DynamoDbAsyncTable<T> {
@@ -290,6 +294,13 @@ public CompletableFuture<Void> deleteTable() {
         return operation.executeOnPrimaryIndexAsync(tableSchema, tableName, extension, dynamoDbClient);
     }
 
+    @Override
+    public CompletableFuture<DescribeTableEnhancedResponse> describeTable() {
+        TableOperation<T, DescribeTableRequest, DescribeTableResponse, DescribeTableEnhancedResponse> operation =
+            DescribeTableOperation.create();
+        return operation.executeOnPrimaryIndexAsync(tableSchema, tableName, extension, dynamoDbClient);
+    }
+
     @Override
     public boolean equals(Object o) {
         if (this == o) {

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/internal/client/DefaultDynamoDbTable.java

@@ -27,6 +27,7 @@
 import software.amazon.awssdk.enhanced.dynamodb.internal.operations.CreateTableOperation;
 import software.amazon.awssdk.enhanced.dynamodb.internal.operations.DeleteItemOperation;
 import software.amazon.awssdk.enhanced.dynamodb.internal.operations.DeleteTableOperation;
+import software.amazon.awssdk.enhanced.dynamodb.internal.operations.DescribeTableOperation;
 import software.amazon.awssdk.enhanced.dynamodb.internal.operations.GetItemOperation;
 import software.amazon.awssdk.enhanced.dynamodb.internal.operations.PaginatedTableOperation;
 import software.amazon.awssdk.enhanced.dynamodb.internal.operations.PutItemOperation;
@@ -37,6 +38,7 @@
 import software.amazon.awssdk.enhanced.dynamodb.model.CreateTableEnhancedRequest;
 import software.amazon.awssdk.enhanced.dynamodb.model.DeleteItemEnhancedRequest;
 import software.amazon.awssdk.enhanced.dynamodb.model.DeleteItemEnhancedResponse;
+import software.amazon.awssdk.enhanced.dynamodb.model.DescribeTableEnhancedResponse;
 import software.amazon.awssdk.enhanced.dynamodb.model.GetItemEnhancedRequest;
 import software.amazon.awssdk.enhanced.dynamodb.model.PageIterable;
 import software.amazon.awssdk.enhanced.dynamodb.model.PutItemEnhancedRequest;
@@ -47,6 +49,8 @@
 import software.amazon.awssdk.enhanced.dynamodb.model.UpdateItemEnhancedRequest;
 import software.amazon.awssdk.enhanced.dynamodb.model.UpdateItemEnhancedResponse;
 import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
+import software.amazon.awssdk.services.dynamodb.model.DescribeTableRequest;
+import software.amazon.awssdk.services.dynamodb.model.DescribeTableResponse;
 
 @SdkInternalApi
 public class DefaultDynamoDbTable<T> implements DynamoDbTable<T> {
@@ -286,6 +290,13 @@ public void deleteTable() {
         operation.executeOnPrimaryIndex(tableSchema, tableName, extension, dynamoDbClient);
     }
 
+    @Override
+    public DescribeTableEnhancedResponse describeTable() {
+        TableOperation<T, DescribeTableRequest, DescribeTableResponse, DescribeTableEnhancedResponse> operation =
+            DescribeTableOperation.create();
+        return operation.executeOnPrimaryIndex(tableSchema, tableName, extension, dynamoDbClient);
+    }
+
     @Override
     public boolean equals(Object o) {
         if (this == o) {