Package software.amazon.awssdk.services.dynamodb.datamodeling

Class DynamoDbTableMapper<T,H,R>

java.lang.Object

software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbTableMapper<T,H,R>

Type Parameters:

T - The object type which this mapper operates.

H - The hash key value type.

R - The range key value type; use ? if no range key.

public final class DynamoDbTableMapper<T,H,R>
extends Object

A wrapper for DynamoDBMapper which operates only on a specified class/table. All calls are forwarded to the underlying DynamoDBMapper which was used to create this table mapper. A minimal example using get annotations,

 @DynamoDBTable(tableName="TestTable")
 public class TestClass {
     private Long key;
     private String rangeKey;
     private Double amount;
     private Long version;

     @DynamoDBHashKey
     public Long getKey() { return key; }
     public void setKey(Long key) { this.key = key; }

     @DynamoDBRangeKey
     public String getRangeKey() { return rangeKey; }
     public void setRangeKey(String rangeKey) { this.rangeKey = rangeKey; }

     @DynamoDBAttribute(attributeName="amount")
     public Double getAmount() { return amount; }
     public void setAmount(Double amount) { this.amount = amount; }

     @DynamoDBVersionAttribute
     public Long getVersion() { return version; }
     public void setVersion(Long version) { this.version = version; }
 }
 

Initialize the DynamoDB mapper,

 DynamoDBClient dbClient = new AmazonDynamoDBClient();
 DynamoDBMapper dbMapper = new DynamoDBMapper(dbClient);
 

Then, create a new table mapper with hash and range key,

 DynamoDBTableMapper<TestClass,Long,String> mapper = dbMapper.newTableMapper(TestClass.class);
 

Or, if the table does not have a range key,

 DynamoDBTableMapper<TestClass,Long,?> table = dbMapper.newTableMapper(TestClass.class);
 

If you don't have your DynamoDB table set up yet, you can use,

 table.createTableIfNotExists(new ProvisionedThroughput(25L, 25L));
 

Save instances of annotated classes and retrieve them,

 TestClass object = new TestClass();
 object.setKey(1234L);
 object.setRangeKey("ABCD");
 object.setAmount(101D);

 try {
     table.saveIfNotExists(object);
 } catch (ConditionalCheckFailedException e) {
     // handle already existing
 }
 

Execute a query operation,

 int limit = 10;
 List<TestClass> objects = new ArrayList<TestClass>(limit);

 DynamoDBQueryExpression<TestClass> query = new DynamoDBQueryExpression()
     .withRangeKeyCondition(table.rangeKey().name(), table.rangeKey().ge("ABAA"))
     .withQueryFilterEntry("amount", table.field("amount").gt(100D))
     .withHashKeyValues(1234L)
     .withConsistentReads(true);

 QueryResponsePage<TestClass> results = new QueryResponsePage<TestClass>();

 do {
     if (results.lastEvaluatedKey() != null) {
         query.setExclusiveStartKey(results.lastEvaluatedKey());
     }
     query.setLimit(limit - objects.size());
     results = mapper.query(query);
     for (TestClass object : results.getResults()) {
         objects.add(object);
     }
 } while (results.lastEvaluatedKey() != null && objects.size() < limit)
 

See Also:

DynamoDbMapper, DynamoDBClient

Method Summary

Modifier and Type	Method	Description
List<DynamoDbMapper.FailedBatch>	batchDelete(Iterable<T> objectsToDelete)	Deletes the objects given using one or more calls to the batchWtiteItem API.
List<T>	batchLoad(Iterable<T> itemsToGet)	Retrieves multiple items from the table using their primary keys.
List<DynamoDbMapper.FailedBatch>	batchSave(Iterable<T> objectsToSave)	Saves the objects given using one or more calls to the batchWriteItem API.
List<DynamoDbMapper.FailedBatch>	batchWrite(Iterable<T> objectsToWrite, Iterable<T> objectsToDelete)	Saves and deletes the objects given using one or more calls to the batchWriteItem API.
int	count(DynamoDbQueryExpression<T> queryExpression)	Evaluates the specified query expression and returns the count of matching items, without returning any of the actual item data
int	count(DynamoDbScanExpression scanExpression)	Evaluates the specified scan expression and returns the count of matching items, without returning any of the actual item data.
TableDescription	createTable(ProvisionedThroughput throughput)	Creates the table with the specified throughput; also populates the same throughput for all global secondary indexes.
boolean	createTableIfNotExists(ProvisionedThroughput throughput)	Creates the table and ignores the ResourceInUseException if it ialready exists.
void	delete(T object)	Deletes the given object from its DynamoDB table.
void	delete(T object, DynamoDbDeleteExpression deleteExpression)	Deletes the given object from its DynamoDB table using the specified deleteExpression.
void	deleteIfExists(T object)	Deletes the given object from its DynamoDB table with the condition that the hash and, if applicable, the range key, already exist.
TableDescription	deleteTable()	Deletes the table.
boolean	deleteTableIfExists()	Deletes the table and ignores the ResourceNotFoundException if it does not already exist.
TableDescription	describeTable()	Returns information about the table, including the current status of the table, when it was created, the primary key schema, and any indexes on the table.
<V> DynamoDbMapperFieldModel<T,V>	field(String attributeName)	Gets the field model for a given attribute.
DynamoDbMapperFieldModel<T,H>	hashKey()	Gets the hash key field model for the specified type.
T	load(H hashKey)	Loads an object with the hash key given.
T	load(H hashKey, R rangeKey)	Loads an object with the hash and range key.
PaginatedParallelScanList<T>	parallelScan(DynamoDbScanExpression scanExpression, int totalSegments)	Scans through an Amazon DynamoDB table on logically partitioned segments in parallel and returns the matching results in one unmodifiable list of instantiated objects.
PaginatedQueryList<T>	query(DynamoDbQueryExpression<T> queryExpression)	Queries an Amazon DynamoDB table and returns the matching results as an unmodifiable list of instantiated objects.
QueryResultPage<T>	queryPage(DynamoDbQueryExpression<T> queryExpression)	Queries an Amazon DynamoDB table and returns a single page of matching results.
DynamoDbMapperFieldModel<T,R>	rangeKey()	Gets the range key field model for the specified type.
void	save(T object)	Saves the object given into DynamoDB.
void	save(T object, DynamoDbSaveExpression saveExpression)	Saves the object given into DynamoDB using the specified saveExpression.
void	saveIfExists(T object)	Saves the object given into DynamoDB with the condition that the hash and, if applicable, the range key, already exist.
void	saveIfNotExists(T object)	Saves the object given into DynamoDB with the condition that the hash and if applicable, the range key, does not already exist.
PaginatedScanList<T>	scan(DynamoDbScanExpression scanExpression)	Scans through an Amazon DynamoDB table and returns the matching results as an unmodifiable list of instantiated objects.
ScanResultPage<T>	scanPage(DynamoDbScanExpression scanExpression)	Scans through an Amazon DynamoDB table and returns a single page of matching results.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

field

public <V> DynamoDbMapperFieldModel<T,V> field(String attributeName)

Gets the field model for a given attribute.

Type Parameters:

V - The field model's value type.

Parameters:

attributeName - The attribute name.

Returns:

The field model.

hashKey

public DynamoDbMapperFieldModel<T,H> hashKey()

Gets the hash key field model for the specified type.

Type Parameters:

H - The hash key type.

Returns:

The hash key field model.

Throws:

DynamoDbMappingException - If the hash key is not present.

rangeKey

public DynamoDbMapperFieldModel<T,R> rangeKey()

Gets the range key field model for the specified type.

Type Parameters:

R - The range key type.

Returns:

The range key field model.

Throws:

DynamoDbMappingException - If the range key is not present.

batchLoad

public List<T> batchLoad(Iterable<T> itemsToGet)

Retrieves multiple items from the table using their primary keys.

Parameters:

itemsToGet - The items to get.

Returns:

The list of objects.

See Also:

DynamoDbMapper.batchLoad(java.lang.Iterable<? extends java.lang.Object>, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig)

batchSave

public List<DynamoDbMapper.FailedBatch> batchSave(Iterable<T> objectsToSave)

Saves the objects given using one or more calls to the batchWriteItem API.

Parameters:

objectsToSave - The objects to save.

Returns:

The list of failed batches.

See Also:

AbstractDynamoDbMapper.batchSave(java.lang.Iterable<? extends java.lang.Object>)

batchDelete

public List<DynamoDbMapper.FailedBatch> batchDelete(Iterable<T> objectsToDelete)

Deletes the objects given using one or more calls to the batchWtiteItem API.

Parameters:

objectsToDelete - The objects to delete.

Returns:

The list of failed batches.

See Also:

AbstractDynamoDbMapper.batchDelete(java.lang.Iterable<? extends java.lang.Object>)

batchWrite

public List<DynamoDbMapper.FailedBatch> batchWrite(Iterable<T> objectsToWrite,
                                                   Iterable<T> objectsToDelete)

Saves and deletes the objects given using one or more calls to the batchWriteItem API.

Parameters:

objectsToWrite - The objects to write.

objectsToDelete - The objects to delete.

Returns:

The list of failed batches.

See Also:

DynamoDbMapper.batchWrite(java.lang.Iterable<? extends java.lang.Object>, java.lang.Iterable<? extends java.lang.Object>, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig)

load

public T load(H hashKey)

Loads an object with the hash key given.

Parameters:

hashKey - The hash key value.

Returns:

The object.

See Also:

DynamoDbMapper.load(T, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig)

load

public T load(H hashKey,
              R rangeKey)

Loads an object with the hash and range key.

Parameters:

hashKey - The hash key value.

rangeKey - The range key value.

Returns:

The object.

See Also:

DynamoDbMapper.load(T, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig)

save

public void save(T object)

Saves the object given into DynamoDB.

Parameters:

object - The object to save.

See Also:

DynamoDbMapper.save(T, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbSaveExpression, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig)

save

public void save(T object,
                 DynamoDbSaveExpression saveExpression)

Saves the object given into DynamoDB using the specified saveExpression.

Parameters:

object - The object to save.

saveExpression - The save expression.

See Also:

DynamoDbMapper.save(T, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbSaveExpression, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig)

saveIfNotExists

public void saveIfNotExists(T object)
                     throws ConditionalCheckFailedException

Saves the object given into DynamoDB with the condition that the hash and if applicable, the range key, does not already exist.

Parameters:

object - The object to create.

Throws:

ConditionalCheckFailedException - If the object exists.

See Also:

DynamoDbMapper.save(T, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbSaveExpression, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig), DynamoDbSaveExpression, ExpectedAttributeValue

saveIfExists

public void saveIfExists(T object)
                  throws ConditionalCheckFailedException

Saves the object given into DynamoDB with the condition that the hash and, if applicable, the range key, already exist.

Parameters:

object - The object to update.

Throws:

ConditionalCheckFailedException - If the object does not exist.

See Also:

DynamoDbMapper.save(T, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbSaveExpression, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig), DynamoDbSaveExpression, ExpectedAttributeValue

delete

public final void delete(T object)

Deletes the given object from its DynamoDB table.

Parameters:

object - The object to delete.

See Also:

DynamoDbMapper.delete(T, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbDeleteExpression, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig)

delete

public final void delete(T object,
                         DynamoDbDeleteExpression deleteExpression)

Deletes the given object from its DynamoDB table using the specified deleteExpression.

Parameters:

object - The object to delete.

deleteExpression - The delete expression.

See Also:

DynamoDbMapper.delete(T, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbDeleteExpression, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig)

deleteIfExists

public void deleteIfExists(T object)
                    throws ConditionalCheckFailedException

Deletes the given object from its DynamoDB table with the condition that the hash and, if applicable, the range key, already exist.

Parameters:

object - The object to delete.

Throws:

ConditionalCheckFailedException - If the object does not exist.

See Also:

DynamoDbMapper.delete(T, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbDeleteExpression, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig), DynamoDbDeleteExpression, ExpectedAttributeValue

count

public int count(DynamoDbQueryExpression<T> queryExpression)

Evaluates the specified query expression and returns the count of matching items, without returning any of the actual item data

Parameters:

queryExpression - The query expression.

Returns:

The count.

See Also:

DynamoDbMapper.count(java.lang.Class<?>, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbScanExpression, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig)

query

public PaginatedQueryList<T> query(DynamoDbQueryExpression<T> queryExpression)

Queries an Amazon DynamoDB table and returns the matching results as an unmodifiable list of instantiated objects.

Parameters:

queryExpression - The query expression.

Returns:

The query results.

See Also:

DynamoDbMapper.query(java.lang.Class<T>, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbQueryExpression<T>, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig)

queryPage

public QueryResultPage<T> queryPage(DynamoDbQueryExpression<T> queryExpression)

Queries an Amazon DynamoDB table and returns a single page of matching results.

Parameters:

queryExpression - The query expression.

Returns:

The query results.

See Also:

DynamoDbMapper.query(java.lang.Class<T>, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbQueryExpression<T>, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig)

count

public int count(DynamoDbScanExpression scanExpression)

Evaluates the specified scan expression and returns the count of matching items, without returning any of the actual item data.

Parameters:

scanExpression - The scan expression.

Returns:

The count.

See Also:

DynamoDbMapper.count(java.lang.Class<?>, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbScanExpression, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig)

scan

public PaginatedScanList<T> scan(DynamoDbScanExpression scanExpression)

Scans through an Amazon DynamoDB table and returns the matching results as an unmodifiable list of instantiated objects.

Parameters:

scanExpression - The scan expression.

Returns:

The scan results.

See Also:

DynamoDbMapper.scan(java.lang.Class<T>, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbScanExpression, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig)

scanPage

public ScanResultPage<T> scanPage(DynamoDbScanExpression scanExpression)

Scans through an Amazon DynamoDB table and returns a single page of matching results.

Parameters:

scanExpression - The scan expression.

Returns:

The scan results.

See Also:

DynamoDbMapper.scanPage(java.lang.Class<T>, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbScanExpression, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig)

parallelScan

public PaginatedParallelScanList<T> parallelScan(DynamoDbScanExpression scanExpression,
                                                 int totalSegments)

Scans through an Amazon DynamoDB table on logically partitioned segments in parallel and returns the matching results in one unmodifiable list of instantiated objects.

Parameters:

scanExpression - The scan expression.

totalSegments - The total segments.

Returns:

The scan results.

See Also:

DynamoDbMapper.parallelScan(java.lang.Class<T>, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbScanExpression, int, software.amazon.awssdk.services.dynamodb.datamodeling.DynamoDbMapperConfig)

describeTable

public TableDescription describeTable()

Returns information about the table, including the current status of the table, when it was created, the primary key schema, and any indexes on the table.

Returns:

The describe table results.

See Also:

DynamoDBClient.describeTable(software.amazon.awssdk.services.dynamodb.model.DescribeTableRequest)

createTable

public TableDescription createTable(ProvisionedThroughput throughput)

Creates the table with the specified throughput; also populates the same throughput for all global secondary indexes.

Parameters:

throughput - The provisioned throughput.

Returns:

The table decription.

See Also:

DynamoDBClient.createTable(software.amazon.awssdk.services.dynamodb.model.CreateTableRequest), CreateTableRequest

createTableIfNotExists

public boolean createTableIfNotExists(ProvisionedThroughput throughput)

Creates the table and ignores the ResourceInUseException if it ialready exists.

Parameters:

throughput - The provisioned throughput.

Returns:

True if created, or false if the table already existed.

See Also:

DynamoDBClient.createTable(software.amazon.awssdk.services.dynamodb.model.CreateTableRequest), CreateTableRequest

deleteTable

public TableDescription deleteTable()

Deletes the table.

Returns:

The table decription.

See Also:

DynamoDBClient.deleteTable(software.amazon.awssdk.services.dynamodb.model.DeleteTableRequest), DeleteTableRequest

deleteTableIfExists

public boolean deleteTableIfExists()

Deletes the table and ignores the ResourceNotFoundException if it does not already exist.

Returns:

True if the table was deleted, or false if the table did not exist.

See Also:

DynamoDBClient.deleteTable(software.amazon.awssdk.services.dynamodb.model.DeleteTableRequest), DeleteTableRequest