Package software.amazon.awssdk.enhanced.dynamodb.internal.client

Class DefaultDynamoDbTable<T>

    • Method Detail

      • tableName

        public String tableName()
        Description copied from interface: MappedTableResource
        Gets the physical table name that operations performed by this object will be executed against.
        Specified by:
        tableName in interface MappedTableResource<T>
        Returns:
        The physical table name.

      • index

        public DefaultDynamoDbIndex<T> index​(String indexName)
        Description copied from interface: DynamoDbTable
        Returns a mapped index that can be used to execute commands against a secondary index belonging to the table being mapped by this object. Note that only a subset of the commands that work against a table will work against a secondary index.
        Specified by:
        index in interface DynamoDbTable<T>
        Parameters:
        indexName - The name of the secondary index to build the command interface for.
        Returns:
        A DynamoDbIndex object that can be used to execute database commands against.

      • createTable

        public void createTable​(CreateTableEnhancedRequest request)
        Description copied from interface: DynamoDbTable
        Creates a new table in DynamoDb with the name and schema already defined for this DynamoDbTable together with additional parameters specified in the supplied request object, CreateTableEnhancedRequest.

        Use DynamoDbEnhancedClient.table(String, TableSchema) to define the mapped table resource.

        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. You can use DynamoDbWaiter.waitUntilTableExists(DescribeTableRequest) to wait for the resource to be ready.

        Example: 

         

 ProvisionedThroughput provisionedThroughput = ProvisionedThroughput.builder()
                                                                    .readCapacityUnits(50L)
                                                                    .writeCapacityUnits(50L)
                                                                    .build();
 mappedTable.createTable(CreateTableEnhancedRequest.builder()
                                                   .provisionedThroughput(provisionedThroughput)
                                                   .build());

 dynamoDbClient.waiter().waitUntilTableExists(b -> b.tableName(tableName));
        Specified by:
        createTable in interface DynamoDbTable<T>
        Parameters:
        request - A CreateTableEnhancedRequest containing optional parameters for table creation.

      • createTable

        public void createTable()
        Description copied from interface: DynamoDbTable
        Creates a new table in DynamoDb with the name and schema already defined for this DynamoDbTable.

        Use DynamoDbEnhancedClient.table(String, TableSchema) to define the mapped table resource.

        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. You can use DynamoDbWaiter.waitUntilTableExists(DescribeTableRequest) to wait for the resource to be ready.

        Example: 

         

 mappedTable.createTable();
 dynamoDbClient.waiter().waitUntilTableExists(b -> b.tableName(tableName));
        Specified by:
        createTable in interface DynamoDbTable<T>

      • deleteItem

        public T deleteItem​(DeleteItemEnhancedRequest request)
        Description copied from interface: DynamoDbTable
        Deletes a single item from the mapped table using a supplied primary Key.

        The additional configuration parameters that the enhanced client supports are defined in the DeleteItemEnhancedRequest.

        This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for further details and constraints.

        Example: 

         

 MyItem previouslyPersistedItem = mappedTable.delete(DeleteItemEnhancedRequest.builder().key(key).build());
        Specified by:
        deleteItem in interface DynamoDbTable<T>
        Parameters:
        request - A DeleteItemEnhancedRequest with key and optional directives for deleting an item from the table.
        Returns:
        The item that was persisted in the database before it was deleted.

      • deleteItem

        public T deleteItem​(Consumer<DeleteItemEnhancedRequest.Builder> requestConsumer)
        Description copied from interface: DynamoDbTable
        Deletes a single item from the mapped table using a supplied primary Key.

        The additional configuration parameters that the enhanced client supports are defined in the DeleteItemEnhancedRequest.

        This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for further details and constraints.

        Note: This is a convenience method that creates an instance of the request builder avoiding the need to create one manually via DeleteItemEnhancedRequest.builder().

        Example: 

         

 MyItem previouslyPersistedItem = mappedTable.delete(r -> r.key(key));
        Specified by:
        deleteItem in interface DynamoDbTable<T>
        Parameters:
        requestConsumer - A Consumer of DeleteItemEnhancedRequest with key and optional directives for deleting an item from the table.
        Returns:
        The item that was persisted in the database before it was deleted.

      • deleteItem

        public T deleteItem​(Key key)
        Description copied from interface: DynamoDbTable
        Deletes a single item from the mapped table using a supplied primary Key.

        This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for further details and constraints.

        Example: 

         

 MyItem previouslyPersistedItem = mappedTable.delete(key);
        Specified by:
        deleteItem in interface DynamoDbTable<T>
        Parameters:
        key - A Key that will be used to match a specific record to delete from the database table.
        Returns:
        The item that was persisted in the database before it was deleted.

      • deleteItem

        public T deleteItem​(T keyItem)
        Description copied from interface: DynamoDbTable
        Deletes a single item from the mapped table using just the key of a supplied modelled 'key item' object.

        This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for further details and constraints.

        Example: 

         

 MyItem previouslyPersistedItem = mappedTable.deleteItem(keyItem);
        Specified by:
        deleteItem in interface DynamoDbTable<T>
        Parameters:
        keyItem - A modelled item with the primary key fields set that will be used to match a specific record to delete from the database table.
        Returns:
        The item that was persisted in the database before it was deleted.

      • deleteItemWithResponse

        public DeleteItemEnhancedResponse<T> deleteItemWithResponse​(DeleteItemEnhancedRequest request)
        Description copied from interface: DynamoDbTable
        Deletes a single item from the mapped table using a supplied primary Key.

        The additional configuration parameters that the enhanced client supports are defined in the DeleteItemEnhancedRequest.

        This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for further details and constraints. Unlike DynamoDbTable.deleteItem(DeleteItemEnhancedRequest), this returns a response object, allowing the user to retrieve additional information from DynamoDB related to the API call, such as ConsumedCapacity if specified on the request.

        Example: 

         

 DeleteItemEnhancedRequest request = DeleteItemEnhancedRequest.builder().key(key).build();
 DeleteItemEnhancedResponse<MyItem> response = mappedTable.deleteItemWithResponse(request);
        Specified by:
        deleteItemWithResponse in interface DynamoDbTable<T>
        Parameters:
        request - A DeleteItemEnhancedRequest with key and optional directives for deleting an item from the table.
        Returns:
        The response returned by DynamoDB.

      • getItem

        public T getItem​(GetItemEnhancedRequest request)
        Description copied from interface: DynamoDbTable
        Retrieves a single item from the mapped table using a supplied primary Key.

        The additional configuration parameters that the enhanced client supports are defined in the GetItemEnhancedRequest.

        This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for further details and constraints.

        Example: 

         

 MyItem item = mappedTable.getItem(GetItemEnhancedRequest.builder().key(key).build());
        Specified by:
        getItem in interface DynamoDbTable<T>
        Parameters:
        request - A GetItemEnhancedRequest with key and optional directives for retrieving an item from the table.
        Returns:
        The retrieved item

      • getItem

        public T getItem​(Consumer<GetItemEnhancedRequest.Builder> requestConsumer)
        Description copied from interface: DynamoDbTable
        Retrieves a single item from the mapped table using a supplied primary Key.

        The additional configuration parameters that the enhanced client supports are defined in the GetItemEnhancedRequest.

        This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for further details and constraints.

        Note: This is a convenience method that creates an instance of the request builder avoiding the need to create one manually via GetItemEnhancedRequest.builder().

        Example: 

         

 MyItem item = mappedTable.getItem(r -> r.key(key));
        Specified by:
        getItem in interface DynamoDbTable<T>
        Parameters:
        requestConsumer - A Consumer of GetItemEnhancedRequest.Builder with key and optional directives for retrieving an item from the table.
        Returns:
        The retrieved item

      • getItem

        public T getItem​(Key key)
        Description copied from interface: DynamoDbTable
        Retrieves a single item from the mapped table using a supplied primary Key.

        This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for further details and constraints.

        Example: 

         

 MyItem item = mappedTable.getItem(key);
        Specified by:
        getItem in interface DynamoDbTable<T>
        Parameters:
        key - A Key that will be used to match a specific record to retrieve from the database table.
        Returns:
        The retrieved item

      • getItem

        public T getItem​(T keyItem)
        Description copied from interface: DynamoDbTable
        Retrieves a single item from the mapped table using just the key of a supplied modelled 'key item'.

        This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for further details and constraints.

        Example: 

         

 MyItem item = mappedTable.getItem(keyItem);
        Specified by:
        getItem in interface DynamoDbTable<T>
        Parameters:
        keyItem - A modelled item with the primary key fields set that will be used to match a specific record to retrieve from the database table.
        Returns:
        The retrieved item

      • query

        public PageIterable<T> query​(QueryEnhancedRequest request)
        Description copied from interface: DynamoDbTable
        Executes a query against the primary index of the table using a QueryConditional expression to retrieve a list of items matching the given conditions.

        The result can be accessed either through iterable Pages or Page.items() directly. If you are iterating the pages, the result is accessed through iterable pages (see Page) in an interactive way; each time a result page is retrieved, a query call is made to DynamoDb to get those entries. If no matches are found, the resulting iterator will contain an empty page. Results are sorted by sort key value in ascending order by default; this behavior can be overridden in the QueryEnhancedRequest.

        The additional configuration parameters that the enhanced client supports are defined in the QueryEnhancedRequest.

        This operation calls the low-level DynamoDB API Query operation. Consult the Query documentation for further details and constraints.

        Example:

        1) Iterating through pages 

         
 QueryConditional queryConditional = QueryConditional.keyEqualTo(Key.builder().partitionValue("id-value").build());
 PageIterable<MyItem> results = table.query(QueryEnhancedRequest.builder()
                                                                        .queryConditional(queryConditional)
                                                                        .build());
 results.stream().forEach(p -> p.items().forEach(item -> System.out.println(item)))
        2) Iterating through items 
         
 results.items().stream().forEach(item -> System.out.println(item));
        Specified by:
        query in interface DynamoDbTable<T>
        Parameters:
        request - A QueryEnhancedRequest defining the query conditions and how to handle the results.
        Returns:
        an iterator of type SdkIterable with paginated results (see Page).
        See Also:
        DynamoDbTable.query(QueryConditional), DynamoDbTable.query(Consumer), DynamoDbClient.queryPaginator(software.amazon.awssdk.services.dynamodb.model.QueryRequest)

      • putItem

        public void putItem​(PutItemEnhancedRequest<T> request)
        Description copied from interface: DynamoDbTable
        Puts a single item in the mapped table. If the table contains an item with the same primary key, it will be replaced with this item.

        The additional configuration parameters that the enhanced client supports are defined in the PutItemEnhancedRequest.

        This operation calls the low-level DynamoDB API PutItem operation. Consult the PutItem documentation for further details and constraints.

        Example: 

         

 mappedTable.putItem(PutItemEnhancedRequest.builder(MyItem.class).item(item).build());
        Specified by:
        putItem in interface DynamoDbTable<T>
        Parameters:
        request - A PutItemEnhancedRequest that includes the item to enter into the table, its class and optional directives.

      • putItem

        public void putItem​(Consumer<PutItemEnhancedRequest.Builder<T>> requestConsumer)
        Description copied from interface: DynamoDbTable
        Puts a single item in the mapped table. If the table contains an item with the same primary key, it will be replaced with this item.

        The additional configuration parameters that the enhanced client supports are defined in the PutItemEnhancedRequest.

        This operation calls the low-level DynamoDB API PutItem operation. Consult the PutItem documentation for further details and constraints.

        Example: 

         

 mappedTable.putItem(r -> r.item(item));
        Specified by:
        putItem in interface DynamoDbTable<T>
        Parameters:
        requestConsumer - A Consumer of PutItemEnhancedRequest.Builder that includes the item to enter into the table, its class and optional directives.

      • putItem

        public void putItem​(T item)
        Description copied from interface: DynamoDbTable
        Puts a single item in the mapped table. If the table contains an item with the same primary key, it will be replaced with this item.

        This operation calls the low-level DynamoDB API PutItem operation. Consult the PutItem documentation for further details and constraints.

        Example: 

         

 mappedTable.putItem(item);
        Specified by:
        putItem in interface DynamoDbTable<T>
        Parameters:
        item - the modelled item to be inserted into or overwritten in the database table.

      • scan

        public PageIterable<T> scan​(ScanEnhancedRequest request)
        Description copied from interface: DynamoDbTable
        Scans the table and retrieves all items.

        The result can be accessed either through iterable Pages or items across all pages directly. Each time a result page is retrieved, a query call is made to DynamoDb to get those entries. If no matches are found, the resulting iterator will contain an empty page.

        The additional configuration parameters that the enhanced client supports are defined in the ScanEnhancedRequest.

        Example:

        1) Iterating through pages 

         

 PageIterable<MyItem> results = mappedTable.scan(ScanEnhancedRequest.builder().consistentRead(true).build());
 results.stream().forEach(p -> p.items().forEach(item -> System.out.println(item)))

        2) Iterating through items 

         

 PageIterable<MyItem> results = mappedTable.scan(ScanEnhancedRequest.builder().consistentRead(true).build());
 results.items().stream().forEach(item -> System.out.println(item));
        Specified by:
        scan in interface DynamoDbTable<T>
        Parameters:
        request - A ScanEnhancedRequest defining how to handle the results.
        Returns:
        an iterator of type SdkIterable with paginated results (see Page).
        See Also:
        DynamoDbTable.scan(Consumer), DynamoDbTable.scan(), DynamoDbClient.scanPaginator(software.amazon.awssdk.services.dynamodb.model.ScanRequest)

      • updateItem

        public T updateItem​(UpdateItemEnhancedRequest<T> request)
        Description copied from interface: DynamoDbTable
        Updates an item in the mapped table, or adds it if it doesn't exist.

        The additional configuration parameters that the enhanced client supports are defined in the UpdateItemEnhancedRequest.

        This operation calls the low-level DynamoDB API UpdateItem operation. Consult the UpdateItem documentation for further details and constraints.

        Example: 

         

 MyItem item = mappedTable.updateItem(UpdateItemEnhancedRequest.builder(MyItem.class).item(item).build());
        Specified by:
        updateItem in interface DynamoDbTable<T>
        Parameters:
        request - A UpdateItemEnhancedRequest that includes the item to be updated, its class and optional directives.
        Returns:
        The updated item

      • updateItem

        public T updateItem​(Consumer<UpdateItemEnhancedRequest.Builder<T>> requestConsumer)
        Description copied from interface: DynamoDbTable
        Updates an item in the mapped table, or adds it if it doesn't exist.

        The additional configuration parameters that the enhanced client supports are defined in the UpdateItemEnhancedRequest.

        This operation calls the low-level DynamoDB API UpdateItem operation. Consult the UpdateItem documentation for further details and constraints.

        Example: 

         

 MyItem item = mappedTable.updateItem(r -> r.item(item));
        Specified by:
        updateItem in interface DynamoDbTable<T>
        Parameters:
        requestConsumer - A Consumer of UpdateItemEnhancedRequest.Builder that includes the item to be updated, its class and optional directives.
        Returns:
        The updated item

      • updateItem

        public T updateItem​(T item)
        Description copied from interface: DynamoDbTable
        Updates an item in the mapped table, or adds it if it doesn't exist.

        This operation calls the low-level DynamoDB API UpdateItem operation. Consult the UpdateItem documentation for further details and constraints.

        Example: 

         

 MyItem item = mappedTable.updateItem(item);
        Specified by:
        updateItem in interface DynamoDbTable<T>
        Parameters:
        item - the modelled item to be inserted into or updated in the database table.
        Returns:
        The updated item

      • updateItemWithResponse

        public UpdateItemEnhancedResponse<T> updateItemWithResponse​(UpdateItemEnhancedRequest<T> request)
        Description copied from interface: DynamoDbTable
        Updates an item in the mapped table, or adds it if it doesn't exist. This is similar to DynamoDbTable.updateItem(UpdateItemEnhancedRequest)} but returns UpdateItemEnhancedResponse for additional information.

        This operation calls the low-level DynamoDB API UpdateItem operation. Consult the UpdateItem documentation for further details and constraints.

        Example: 

         
 UpdateItemEnhancedRequest<MyItem> request = UpdateItemEnhancedRequest.builder(MyItem.class).item(myItem).build();
 UpdateItemEnhancedResponse<MyItem> response = mappedTable.updateItemWithResponse(request);

        Specified by:
        updateItemWithResponse in interface DynamoDbTable<T>
        Parameters:
        request - the modelled item to be inserted into or updated in the database table.
        Returns:
        The response returned by DynamoDB.

      • keyFrom

        public Key keyFrom​(T item)
        Description copied from interface: MappedTableResource
        Creates a Key object from a modelled item. This key can be used in query conditionals and get operations to locate a specific record.
        Specified by:
        keyFrom in interface MappedTableResource<T>
        Parameters:
        item - The item to extract the key fields from.
        Returns:
        A key that has been initialized with the index values extracted from the modelled object.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object