Class AsyncScanBuilder<T>

java.lang.Object
dev.hogwai.dynamodb.simplified.builder.base.AbstractScanBuilder<T, AsyncScanBuilder<T>>
dev.hogwai.dynamodb.simplified.async.AsyncScanBuilder<T>
Type Parameters:
T - the type of the item
public class AsyncScanBuilder<T> extends AbstractScanBuilder<T, AsyncScanBuilder<T>>
A fluent async builder for scanning a DynamoDB table with optional filter, projection, and pagination.

Mirrors the sync ScanBuilder but returns CompletableFuture from all execution methods and uses the AWS SDK's async PagePublisher under the hood.

  • Constructor Details

    • AsyncScanBuilder

      public AsyncScanBuilder(@NonNull software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncTable<T> table)
      Constructs a new AsyncScanBuilder for the given async table.
      Parameters:
      table - the async DynamoDB table

    • AsyncScanBuilder

      public AsyncScanBuilder(@NonNull software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncIndex<T> index)
      Constructs a new AsyncScanBuilder for scanning the given async secondary index.
      Parameters:
      index - the async DynamoDB secondary index

    • AsyncScanBuilder

      public AsyncScanBuilder(@NonNull software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncTable<T> table, @Nullable software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient dynamoDbAsyncClient)
      Constructs a new AsyncScanBuilder for the given async table with a low-level client.
      Parameters:
      table - the async DynamoDB table
      dynamoDbAsyncClient - the low-level async DynamoDB client (nullable)

    • AsyncScanBuilder

      public AsyncScanBuilder(@NonNull software.amazon.awssdk.enhanced.dynamodb.DynamoDbAsyncIndex<T> index, @Nullable software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient dynamoDbAsyncClient)
      Constructs a new AsyncScanBuilder for the given async index with a low-level client.
      Parameters:
      index - the async DynamoDB secondary index
      dynamoDbAsyncClient - the low-level async DynamoDB client (nullable)

  • Method Details

    • self

      protected @NonNull AsyncScanBuilder<T> self()
      Description copied from class: AbstractScanBuilder
      Returns this typed as S for fluent chaining.
      Specified by:
      self in class AbstractScanBuilder<T, AsyncScanBuilder<T>>
      Returns:
      this builder

    • tableName

      protected @NonNull String tableName()
      Description copied from class: AbstractScanBuilder
      Returns the DynamoDB table name.
      Specified by:
      tableName in class AbstractScanBuilder<T, AsyncScanBuilder<T>>
      Returns:
      the DynamoDB table name

    • indexName

      protected @Nullable String indexName()
      Description copied from class: AbstractScanBuilder
      Returns the DynamoDB index name, or null if the scan targets the base table.
      Specified by:
      indexName in class AbstractScanBuilder<T, AsyncScanBuilder<T>>
      Returns:
      the index name, or null for the base table

    • executeAll

      public @NonNull CompletableFuture<List<T>> executeAll()
      Executes the scan asynchronously and returns all matching items aggregated from all pages.

      Memory warning: This method collects all pages into a single in-memory list before returning. For scans that may return a large number of items, consider using executeWithPagination() or processing pages individually to avoid excessive memory usage.

      Returns:
      a CompletableFuture containing a list of matching items

    • executeWithPagination

      public @NonNull CompletableFuture<PagedResult<T>> executeWithPagination()
      Executes the scan asynchronously and returns only the first page of results along with the last evaluated key for pagination.
      Returns:
      a CompletableFuture containing a PagedResult with the first page of items and the last evaluated key (may be null if no more pages)

    • executeAndGetFirst

      public @NonNull CompletableFuture<Optional<T>> executeAndGetFirst()
      Executes the scan asynchronously and returns the first matching item, if any.

      Only the first page of results is loaded: subsequent pages are never fetched.

      Returns:
      a CompletableFuture containing an Optional with the first item, or empty if no items match

    • executeStream

      public @NonNull CompletableFuture<software.amazon.awssdk.core.async.SdkPublisher<T>> executeStream()
      Returns a reactive publisher that lazily emits items as pages arrive.

      Unlike executeAll() which loads all pages into memory, this method streams items one-by-one as each page is received from DynamoDB.

      Returns:
      a CompletableFuture containing an SdkPublisher that emits scan items
      Throws:
      IllegalStateException - if called with Select.COUNT

    • count

      public @NonNull CompletableFuture<Long> count()
      Returns the total number of items asynchronously by iterating all scan result pages.

      When a low-level DynamoDbAsyncClient is available, uses Select.COUNT server-side to avoid transferring item data. Falls back to the enhanced client page iteration otherwise.

      Returns:
      a CompletableFuture containing the total count of scanned items matching the filter