Class AsyncTable<T>

java.lang.Object
dev.hogwai.dynamodb.simplified.async.AsyncTable<T>
Type Parameters:
T - the item type mapped to this table
public class AsyncTable<T> extends Object
Typed async entry point for DynamoDB operations on a single table.

Obtained via AsyncDynamoSimplifiedClient.table(String, Class). Provides async builders through query(), scan(), get(), put(), update(), delete(), batchGet(), and batchWrite(). Their terminal methods return CompletableFuture where applicable. It also provides convenience direct methods (getItem, putItem, updateItem, deleteItem) and asynchronous DDL operations (create, delete, describe).

  • Constructor Details

    • AsyncTable

      public AsyncTable(@NonNull software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient enhancedAsyncClient, @NonNull software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncTable<T> dynamoDbAsyncTable, @NonNull software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient dynamoDbAsyncClient)
      Creates a new AsyncTable wrapping the given clients and table mapping.
      Parameters:
      enhancedAsyncClient - the enhanced async DynamoDB client
      dynamoDbAsyncTable - the async DynamoDB table mapping
      dynamoDbAsyncClient - the low-level async DynamoDB client

  • Method Details

    • query

      public @NonNull AsyncQueryBuilder<T> query()
      Starts building an async query operation against this table.
      Returns:
      an AsyncQueryBuilder for configuring and executing the query

    • scan

      public @NonNull AsyncScanBuilder<T> scan()
      Starts building an async scan operation against this table.
      Returns:
      an AsyncScanBuilder for configuring and executing the scan

    • get

      public @NonNull AsyncGetItemBuilder<T> get(@NonNull Object partitionKey)
      Starts building a get operation by partition key.
      Parameters:
      partitionKey - the partition key value
      Returns:
      an AsyncGetItemBuilder for configuring and executing the get

    • get

      public @NonNull AsyncGetItemBuilder<T> get(@NonNull Object partitionKey, @NonNull Object sortKey)
      Starts building a get operation by partition and sort key.
      Parameters:
      partitionKey - the partition key value
      sortKey - the sort key value
      Returns:
      an AsyncGetItemBuilder for configuring and executing the get

    • getItem

      public @NonNull CompletableFuture<Optional<T>> getItem(@NonNull Object partitionKey)
      Fetches an item by partition key directly.
      Parameters:
      partitionKey - the partition key value
      Returns:
      a CompletableFuture containing an Optional with the item, or empty if not found

    • getItem

      public @NonNull CompletableFuture<Optional<T>> getItem(@NonNull Object partitionKey, @NonNull Object sortKey)
      Fetches an item by partition and sort key directly.
      Parameters:
      partitionKey - the partition key value
      sortKey - the sort key value
      Returns:
      a CompletableFuture containing an Optional with the item, or empty if not found

    • put

      public @NonNull AsyncPutBuilder<T> put(@NonNull T item)
      Starts building a put operation with optional conditions.
      Parameters:
      item - the item to put
      Returns:
      an AsyncPutBuilder for configuring and executing the put

    • putItem

      public @NonNull CompletableFuture<Void> putItem(@NonNull T item)
      Puts an item directly without conditions.
      Parameters:
      item - the item to put
      Returns:
      a CompletableFuture that completes when the item has been put

    • update

      public @NonNull AsyncUpdateBuilder<T> update(@NonNull T item)
      Starts building an update operation with optional conditions and partial expressions.
      Parameters:
      item - the item with updated values
      Returns:
      an AsyncUpdateBuilder for configuring and executing the update

    • update

      public @NonNull AsyncUpdateBuilder<T> update(@NonNull T item, @NonNull Consumer<UpdateExpression> expressionConsumer)
      Starts building a partial update operation with an expression consumer.

      This is a convenience shorthand for update(item).update(consumer). The returned builder can be further configured before calling execute().

      Parameters:
      item - the item identifying the record to update (key fields only)
      expressionConsumer - a consumer to configure the update expression (SET, REMOVE, ADD, DELETE)
      Returns:
      an async update builder for further configuration and execution

    • update

      public @NonNull CompletableFuture<Void> update(@NonNull Object partitionKey, @Nullable Object sortKey, @NonNull Consumer<UpdateExpression> expressionConsumer)
      Updates an item identified by partition and sort key using a partial update expression.

      This avoids creating a dummy item object when the key is already known. Pass null for the sort key when the table has no sort key.

      Parameters:
      partitionKey - the partition key value
      sortKey - the sort key value, or null if the table has no sort key
      expressionConsumer - a consumer to build the update expression
      Returns:
      a CompletableFuture that completes when the update has been executed

    • updateItem

      public @NonNull CompletableFuture<T> updateItem(@NonNull T item)
      Updates an item directly without conditions or partial expressions.
      Parameters:
      item - the item with updated values
      Returns:
      a CompletableFuture containing the updated item as returned by DynamoDB

    • delete

      public @NonNull AsyncDeleteBuilder<T> delete(@NonNull Object partitionKey)
      Starts building a delete operation by partition key with optional conditions.
      Parameters:
      partitionKey - the partition key value
      Returns:
      an AsyncDeleteBuilder for configuring and executing the delete

    • delete

      public @NonNull AsyncDeleteBuilder<T> delete(@NonNull Object partitionKey, @NonNull Object sortKey)
      Starts building a delete operation by partition and sort key with optional conditions.
      Parameters:
      partitionKey - the partition key value
      sortKey - the sort key value
      Returns:
      an AsyncDeleteBuilder for configuring and executing the delete

    • deleteItem

      public @NonNull CompletableFuture<T> deleteItem(@NonNull Object partitionKey)
      Deletes an item by partition key directly.
      Parameters:
      partitionKey - the partition key value
      Returns:
      a CompletableFuture that completes with the deleted item, or null if no item with the given key exists

    • deleteItem

      public @NonNull CompletableFuture<T> deleteItem(@NonNull Object partitionKey, @NonNull Object sortKey)
      Deletes an item by partition and sort key directly.
      Parameters:
      partitionKey - the partition key value
      sortKey - the sort key value
      Returns:
      a CompletableFuture that completes with the deleted item, or null if no item with the given key exists

    • index

      public @NonNull AsyncIndex<T> index(@NonNull String indexName)
      Returns a typed wrapper for the named secondary index (GSI or LSI).

      Use the returned AsyncIndex to perform query and scan operations scoped to that index.

      Parameters:
      indexName - the name of the secondary index
      Returns:
      an AsyncIndex<T> for the specified index

    • batchGet

      public @NonNull AsyncBatchGetBuilder<T> batchGet()
      Starts building an async batch get operation to retrieve multiple items by their keys.
      Returns:
      an AsyncBatchGetBuilder for configuring and executing the batch get

    • batchWrite

      public @NonNull AsyncBatchWriteBuilder<T> batchWrite()
      Starts building an async batch write operation to put and delete multiple items.
      Returns:
      an AsyncBatchWriteBuilder for configuring and executing the batch write

    • putAll

      public @NonNull CompletableFuture<BatchWriteResult> putAll(@NonNull Collection<T> items)
      Puts all items in a single async batch write operation.

      Equivalent to creating an AsyncBatchWriteBuilder, adding all items, and executing it. At most 25 items per call are allowed by DynamoDB.

      Parameters:
      items - the items to put
      Returns:
      a future containing the batch write result
      Throws:
      IllegalArgumentException - if more than 25 items are provided

    • getRawTable

      public @NonNull software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncTable<T> getRawTable()
      Returns the underlying DynamoDbAsyncTable for advanced operations.
      Returns:
      the raw async DynamoDB table instance

    • getEnhancedClient

      public @NonNull software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient getEnhancedClient()
      Returns the underlying DynamoDbEnhancedAsyncClient for advanced operations.
      Returns:
      the enhanced async DynamoDB client

    • getDynamoDbClient

      public @NonNull software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient getDynamoDbClient()
      Returns the underlying low-level DynamoDbAsyncClient.
      Returns:
      the low-level async DynamoDB client

    • create

      public @NonNull CompletableFuture<Void> create()
      Creates the DynamoDB table corresponding to this AsyncTable instance.

      Uses the table schema defined during AsyncDynamoSimplifiedClient.table(String, Class) to create the table.

      Returns:
      a CompletableFuture that completes when the table has been created

    • create

      public @NonNull CompletableFuture<Void> create(@NonNull software.amazon.awssdk.enhanced.dynamodb.model.CreateTableEnhancedRequest request)
      Creates the DynamoDB table with the given request options.
      Parameters:
      request - the create table request options
      Returns:
      a CompletableFuture that completes when the table has been created

    • create

      public @NonNull CompletableFuture<Void> create(@NonNull Consumer<software.amazon.awssdk.enhanced.dynamodb.model.CreateTableEnhancedRequest.Builder> configurator)
      Creates the DynamoDB table with options configured by a consumer.

      Example usage: 

      asyncTable.create(b -> b
    .provisionedThroughput(p -> p
        .readCapacityUnits(10L)
        .writeCapacityUnits(10L)));
      Parameters:
      configurator - a consumer to configure the CreateTableEnhancedRequest.Builder
      Returns:
      a CompletableFuture that completes when the table has been created

    • delete

      public @NonNull CompletableFuture<Void> delete()
      Deletes the DynamoDB table corresponding to this AsyncTable instance permanently.
      Returns:
      a CompletableFuture that completes when the table has been deleted

    • describe

      public @NonNull CompletableFuture<software.amazon.awssdk.enhanced.dynamodb.model.DescribeTableEnhancedResponse> describe()
      Returns information about the DynamoDB table, including its status, schema, throughput settings, and indexes.
      Returns:
      a CompletableFuture containing the table description response

    • updateTable

      public @NonNull CompletableFuture<Void> updateTable(@NonNull Consumer<software.amazon.awssdk.services.dynamodb.model.UpdateTableRequest.Builder> requestConsumer)
      Updates the DynamoDB table with the specified configuration.

      Example usage: 

      asyncTable.updateTable(b -> b
    .provisionedThroughput(p -> p
        .readCapacityUnits(10L)
        .writeCapacityUnits(10L)));
      Parameters:
      requestConsumer - a consumer to configure the UpdateTableRequest.Builder
      Returns:
      a CompletableFuture that completes when the table has been updated

    • exists

      public @NonNull CompletableFuture<Boolean> exists()
      Checks whether the DynamoDB table exists.

      Returns a CompletableFuture that completes with true if the table exists, or false if it does not.

      Returns:
      a future that completes with true if the table exists, false otherwise

    • enableTtl

      public @NonNull CompletableFuture<Void> enableTtl(@NonNull String attributeName)
      Enables Time To Live (TTL) on this table with the given attribute name.
      Parameters:
      attributeName - the attribute that stores the TTL epoch value
      Returns:
      a CompletableFuture that completes when TTL has been enabled

    • disableTtl

      public @NonNull CompletableFuture<Void> disableTtl(@NonNull String attributeName)
      Disables TTL on this table for the given attribute name.
      Parameters:
      attributeName - the TTL attribute name to disable
      Returns:
      a CompletableFuture that completes when TTL has been disabled

    • describeTtl

      public @NonNull CompletableFuture<software.amazon.awssdk.services.dynamodb.model.TimeToLiveDescription> describeTtl()
      Describes the current TTL configuration for this table.
      Returns:
      a CompletableFuture containing the TTL description