com.amazonaws.services.dynamodbv2.datamodeling

Class DynamoDBTableMapper<T,H,R>

java.lang.Object

com.amazonaws.services.dynamodbv2.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,

 AmazonDynamoDB 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,?> mapper = dbMapper.newTableMapper(TestClass.class);
 

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

 mapper.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 {
     mapper.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 = mapper.queryExpressionOf(1234L)
     .withRangeKeyCondition(mapper..rangeKey().name(), mapper.rangeKey().ge("ABAA"))
     .withQueryFilterEntry("amount", mapper.field("amount").gt(100D))
     .withConsistentReads(true);

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

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

See Also:

DynamoDBMapper, AmazonDynamoDB

Method Summary

Modifier and Type	Method and 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.
S3Link	createS3Link(Region s3region, String bucketName, String key) Creates an S3Link with the specified region, bucket name and key.
S3Link	createS3Link(String bucketName, String key) Creates an S3Link with the specified bucket name and key using the default S3 region.
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.
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.
S3ClientCache	getS3ClientCache() Returns the underlying S3ClientCache for accessing S3.
<H> 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.
QueryResultPage<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.
<R> 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 <H> 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 <R> 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 final 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>)

batchSave

public final 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:

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

batchDelete

public final 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:

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

batchWrite

public final 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>)

load

public final 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(java.lang.Class<T>, java.lang.Object, com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBMapperConfig)

load

public final 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(java.lang.Class<T>, java.lang.Object, com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBMapperConfig)

save

public final void save(T object)

Saves the object given into DynamoDB.

Parameters:

object - The object to save.

See Also:

DynamoDBMapper.save(T)

save

public final 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)

saveIfNotExists

public final 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), DynamoDBSaveExpression, ExpectedAttributeValue

saveIfExists

public final 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), 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(java.lang.Object)

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(java.lang.Object)

deleteIfExists

public final 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(java.lang.Object), DynamoDBDeleteExpression, ExpectedAttributeValue

count

public final 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<?>, com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBScanExpression)

query

public final QueryResultPage<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>, com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBQueryExpression<T>)

queryPage

public final 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>, com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBQueryExpression<T>)

count

public final 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<?>, com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBScanExpression)

scan

public final 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>, com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBScanExpression)

scanPage

public final 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>, com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBScanExpression, com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBMapperConfig)

parallelScan

public final 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>, com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBScanExpression, int)

createS3Link

public final S3Link createS3Link(Region s3region,
                                 String bucketName,
                                 String key)

Creates an S3Link with the specified region, bucket name and key.

Parameters:

s3region - The S3 region.

bucketName - The bucket name.

key - The key.

Returns:

The created S3Link.

See Also:

DynamoDBMapper.createS3Link(java.lang.String, java.lang.String)

createS3Link

public final S3Link createS3Link(String bucketName,
                                 String key)

Creates an S3Link with the specified bucket name and key using the default S3 region.

Parameters:

bucketName - The bucket name.

key - The key.

Returns:

The created S3Link.

See Also:

DynamoDBMapper.createS3Link(java.lang.String, java.lang.String)

getS3ClientCache

public final S3ClientCache getS3ClientCache()

Returns the underlying S3ClientCache for accessing S3.

Returns:

The underlying S3ClientCache.

See Also:

DynamoDBMapper.getS3ClientCache()

describeTable

public final 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:

AmazonDynamoDB.describeTable(com.amazonaws.services.dynamodbv2.model.DescribeTableRequest)

createTableIfNotExists

public final 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:

AmazonDynamoDB.createTable(com.amazonaws.services.dynamodbv2.model.CreateTableRequest), CreateTableRequest

deleteTableIfExists

public final 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:

AmazonDynamoDB.deleteTable(com.amazonaws.services.dynamodbv2.model.DeleteTableRequest), DeleteTableRequest