com.amazonaws.services.dynamodb.datamodeling
Class DynamoDBMapper

java.lang.Object
  com.amazonaws.services.dynamodb.datamodeling.DynamoDBMapper

public class DynamoDBMapper
extends Object

Object mapper for domain-object interaction with DynamoDB.

To use, annotate domain classes with the annotations found in the com.amazonaws.services.dynamodb.datamodeling package. A minimal example:

 @DynamoDBTable(tableName = "TestTable")
 public class TestClass {
 
     private Long key;
     private double rangeKey;
     private Long version;
 
     private Set<Integer> integerSetAttribute;
 
     @DynamoDBHashKey
     public Long getKey() {
         return key;
     }
 
     public void setKey(Long key) {
         this.key = key;
     }
 
     @DynamoDBRangeKey
     public double getRangeKey() {
         return rangeKey;
     }
 
     public void setRangeKey(double rangeKey) {
         this.rangeKey = rangeKey;
     }
 
     @DynamoDBAttribute(attributeName = "integerSetAttribute")
     public Set<Integer> getIntegerAttribute() {
         return integerSetAttribute;
     }
 
     public void setIntegerAttribute(Set<Integer> integerAttribute) {
         this.integerSetAttribute = integerAttribute;
     }
 
     @DynamoDBVersionAttribute
     public Long getVersion() {
         return version;
     }
 
     public void setVersion(Long version) {
         this.version = version;
     }
 }
 

Save instances of annotated classes to DynamoDB, retrieve them, and delete them using the DynamoDBMapper class, as in the following example.

 DynamoDBMapper mapper = new DynamoDBMapper(dynamoDBClient);
 Long hashKey = 105L;
 double rangeKey = 1.0d;
 TestClass obj = mapper.load(TestClass.class, hashKey, rangeKey);
 obj.getIntegerAttribute().add(42);
 mapper.save(obj);
 mapper.delete(obj);
 

When using the save, load, and delete methods, DynamoDBMapper will throw DynamoDBMappingExceptions to indicate that domain classes are incorrectly annotated or otherwise incompatible with this class. Service exceptions will always be propagated as AmazonClientException, and DynamoDB-specific subclasses such as ConditionalCheckFailedException will be used when possible.

This class is thread-safe and can be shared between threads. It's also very lightweight, so it doesn't need to be.

See Also:

DynamoDBTable, DynamoDBHashKey, DynamoDBRangeKey, DynamoDBAutoGeneratedKey, DynamoDBAttribute, DynamoDBVersionAttribute, DynamoDBIgnore, DynamoDBMarshalling, DynamoDBMapperConfig

Constructor Summary

DynamoDBMapper(AmazonDynamoDB dynamoDB)
Constructs a new mapper with the service object given, using the default configuration.

DynamoDBMapper(AmazonDynamoDB dynamoDB, DynamoDBMapperConfig config)
Constructs a new mapper with the service object and configuration given.

Method Summary

void	batchDelete(List<? extends Object> objectsToDelete) Deletes the objects given using one or more calls to the AmazonDynamoDB.batchWriteItem(BatchWriteItemRequest) API.
void	batchDelete(Object... objectsToDelete) Deletes the objects given using one or more calls to the AmazonDynamoDB.batchWriteItem(BatchWriteItemRequest) API.
Map<String,List<Object>>	batchLoad(Map<Class<?>,List<KeyPair>> itemsToGet) Retrieves the attributes for multiple items from multiple tables using their primary keys.
Map<String,List<Object>>	batchLoad(Map<Class<?>,List<KeyPair>> itemsToGet, DynamoDBMapperConfig config) Retrieves the attributes for multiple items from multiple tables using their primary keys.
void	batchSave(List<? extends Object> objectsToSave) Saves the objects given using one or more calls to the AmazonDynamoDB.batchWriteItem(BatchWriteItemRequest) API.
void	batchSave(Object... objectsToSave) Saves the objects given using one or more calls to the AmazonDynamoDB.batchWriteItem(BatchWriteItemRequest) API.
void	batchWrite(List<? extends Object> objectsToWrite, List<? extends Object> objectsToDelete) Saves and deletes the objects given using one or more calls to the AmazonDynamoDB.batchWriteItem(BatchWriteItemRequest) API.
void	batchWrite(List<? extends Object> objectsToWrite, List<? extends Object> objectsToDelete, DynamoDBMapperConfig config) Saves and deletes the objects given using one or more calls to the AmazonDynamoDB.batchWriteItem(BatchWriteItemRequest) API.
int	count(Class<?> clazz, DynamoDBQueryExpression queryExpression) Evaluates the specified query expression and returns the count of matching items, without returning any of the actual item data, using the default configuration.
int	count(Class<?> clazz, DynamoDBQueryExpression queryExpression, DynamoDBMapperConfig config) Evaluates the specified query expression and returns the count of matching items, without returning any of the actual item data.
int	count(Class<?> clazz, DynamoDBScanExpression scanExpression) Evaluates the specified scan expression and returns the count of matching items, without returning any of the actual item data, using the default configuration.
int	count(Class<?> clazz, DynamoDBScanExpression scanExpression, DynamoDBMapperConfig config) Evaluates the specified scan expression and returns the count of matching items, without returning any of the actual item data.
void	delete(Object object) Deletes the given object from its DynamoDB table.
void	delete(Object object, DynamoDBMapperConfig config) Deletes the given object from its DynamoDB table.
<T> T	load(Class<T> clazz, Object hashKey) Loads an object with the hash key given, using the default configuration.
<T> T	load(Class<T> clazz, Object hashKey, DynamoDBMapperConfig config) Loads an object with the hash key given and a configuration override.
<T> T	load(Class<T> clazz, Object hashKey, Object rangeKey) Loads an object with a hash and range key, using the default configuration.
<T> T	load(Class<T> clazz, Object hashKey, Object rangeKey, DynamoDBMapperConfig config) Returns an object with the given hash key, or null if no such object exists.
<T> T	marshallIntoObject(Class<T> clazz, Map<String,AttributeValue> itemAttributes) Creates and fills in the attributes on an instance of the class given with the attributes given.
<T> List<T>	marshallIntoObjects(Class<T> clazz, List<Map<String,AttributeValue>> itemAttributes) Marshalls the list of item attributes into objects of type clazz
<T> PaginatedQueryList<T>	query(Class<T> clazz, DynamoDBQueryExpression queryExpression) Queries an AWS DynamoDB table and returns the matching results as an unmodifiable list of instantiated objects, using the default configuration.
<T> PaginatedQueryList<T>	query(Class<T> clazz, DynamoDBQueryExpression queryExpression, DynamoDBMapperConfig config) Queries an AWS DynamoDB table and returns the matching results as an unmodifiable list of instantiated objects.
<T> void	save(T object) Saves the object given into DynamoDB, using the default configuration.
<T> void	save(T object, DynamoDBMapperConfig config) Saves an item in DynamoDB.
<T> PaginatedScanList<T>	scan(Class<T> clazz, DynamoDBScanExpression scanExpression) Scans through an AWS DynamoDB table and returns the matching results as an unmodifiable list of instantiated objects, using the default configuration.
<T> PaginatedScanList<T>	scan(Class<T> clazz, DynamoDBScanExpression scanExpression, DynamoDBMapperConfig config) Scans through an AWS DynamoDB table and returns the matching results as an unmodifiable list of instantiated objects.

Methods inherited from class java.lang.Object

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

Constructor Detail

DynamoDBMapper

public DynamoDBMapper(AmazonDynamoDB dynamoDB)

Constructs a new mapper with the service object given, using the default configuration.

Parameters:

dynamoDB - The service object to use for all service calls.

See Also:

DynamoDBMapperConfig.DEFAULT

DynamoDBMapper

public DynamoDBMapper(AmazonDynamoDB dynamoDB,
                      DynamoDBMapperConfig config)

Constructs a new mapper with the service object and configuration given.

Parameters:

dynamoDB - The service object to use for all service calls.

config - The default configuration to use for all service calls. It can be overridden on a per-operation basis.

Method Detail

load

public <T> T load(Class<T> clazz,
                  Object hashKey,
                  DynamoDBMapperConfig config)

Loads an object with the hash key given and a configuration override. This configuration overrides the default provided at object construction.

See Also:

load(Class, Object, Object, DynamoDBMapperConfig)

load

public <T> T load(Class<T> clazz,
                  Object hashKey)

Loads an object with the hash key given, using the default configuration.

See Also:

load(Class, Object, Object, DynamoDBMapperConfig)

load

public <T> T load(Class<T> clazz,
                  Object hashKey,
                  Object rangeKey)

Loads an object with a hash and range key, using the default configuration.

See Also:

load(Class, Object, Object, DynamoDBMapperConfig)

load

public <T> T load(Class<T> clazz,
                  Object hashKey,
                  Object rangeKey,
                  DynamoDBMapperConfig config)

Returns an object with the given hash key, or null if no such object exists.

Parameters:

clazz - The class to load, corresponding to a DynamoDB table.

hashKey - The key of the object.

rangeKey - The range key of the object, or null for tables without a range key.

config - Configuration for the service call to retrieve the object from DynamoDB. This configuration overrides the default given at construction.

marshallIntoObject

public <T> T marshallIntoObject(Class<T> clazz,
                                Map<String,AttributeValue> itemAttributes)

Creates and fills in the attributes on an instance of the class given with the attributes given.

This is accomplished by looking for getter methods annotated with an appropriate annotation, then looking for matching attribute names in the item attribute map.

Parameters:

clazz - The class to instantiate and hydrate

itemAttributes - The set of item attributes, keyed by attribute name.

marshallIntoObjects

public <T> List<T> marshallIntoObjects(Class<T> clazz,
                                       List<Map<String,AttributeValue>> itemAttributes)

Marshalls the list of item attributes into objects of type clazz

See Also:

marshallIntoObject(Class, Map)

save

public <T> void save(T object)

Saves the object given into DynamoDB, using the default configuration.

See Also:

save(Object, DynamoDBMapperConfig)

save

public <T> void save(T object,
                     DynamoDBMapperConfig config)

Saves an item in DynamoDB. The service method used is determined by the DynamoDBMapperConfig.getSaveBehavior() value, to use either AWSDynamoDB#putItem(PutItemRequest) or AWSDynamoDB#updateItem(UpdateItemRequest). For updates, a null value for an object property will remove it from that item in DynamoDB. For puts, a null value will not be passed to the service. The effect is therefore the same, except when the item in DynamoDB contains attributes that aren't modeled by the domain object given.

Parameters:

object - The object to save into DynamoDB

config - The configuration to use, which overrides the default provided at object construction.

delete

public void delete(Object object)

Deletes the given object from its DynamoDB table.

delete

public void delete(Object object,
                   DynamoDBMapperConfig config)

Deletes the given object from its DynamoDB table.

Parameters:

config - Config override object. If DynamoDBMapperConfig.SaveBehavior.CLOBBER is supplied, version fields will not be considered when deleting the object.

batchDelete

public void batchDelete(List<? extends Object> objectsToDelete)

Deletes the objects given using one or more calls to the AmazonDynamoDB.batchWriteItem(BatchWriteItemRequest) API.

See Also:

batchWrite(List, List, DynamoDBMapperConfig)

batchDelete

public void batchDelete(Object... objectsToDelete)

Deletes the objects given using one or more calls to the AmazonDynamoDB.batchWriteItem(BatchWriteItemRequest) API.

See Also:

batchWrite(List, List, DynamoDBMapperConfig)

batchSave

public void batchSave(List<? extends Object> objectsToSave)

Saves the objects given using one or more calls to the AmazonDynamoDB.batchWriteItem(BatchWriteItemRequest) API.

See Also:

batchWrite(List, List, DynamoDBMapperConfig)

batchSave

public void batchSave(Object... objectsToSave)

Saves the objects given using one or more calls to the AmazonDynamoDB.batchWriteItem(BatchWriteItemRequest) API.

See Also:

batchWrite(List, List, DynamoDBMapperConfig)

batchWrite

public void batchWrite(List<? extends Object> objectsToWrite,
                       List<? extends Object> objectsToDelete)

Saves and deletes the objects given using one or more calls to the AmazonDynamoDB.batchWriteItem(BatchWriteItemRequest) API.

See Also:

batchWrite(List, List, DynamoDBMapperConfig)

batchWrite

public void batchWrite(List<? extends Object> objectsToWrite,
                       List<? extends Object> objectsToDelete,
                       DynamoDBMapperConfig config)

Saves and deletes the objects given using one or more calls to the AmazonDynamoDB.batchWriteItem(BatchWriteItemRequest) API.

Parameters:

objectsToWrite - A list of objects to save to DynamoDB. No version checks are performed, as required by the AmazonDynamoDB.batchWriteItem(BatchWriteItemRequest) API.

objectsToDelete - A list of objects to delete from DynamoDB. No version checks are performed, as required by the AmazonDynamoDB.batchWriteItem(BatchWriteItemRequest) API.

config - Only DynamoDBMapperConfig.getTableNameOverride() is considered; if specified, all objects in the two parameter lists will be considered to belong to the given table override.

batchLoad

public Map<String,List<Object>> batchLoad(Map<Class<?>,List<KeyPair>> itemsToGet)

Retrieves the attributes for multiple items from multiple tables using their primary keys. AmazonDynamoDB.batchGetItem(BatchGetItemRequest) API.

See Also:

DynamoDBMapper#batchLoad(Map, List, DynamoDBMapperConfig)

batchLoad

public Map<String,List<Object>> batchLoad(Map<Class<?>,List<KeyPair>> itemsToGet,
                                          DynamoDBMapperConfig config)

Retrieves the attributes for multiple items from multiple tables using their primary keys. AmazonDynamoDB.batchGetItem(BatchGetItemRequest) API.

Parameters:

itemsToGet - Container for the necessary parameters to execute the BatchGetItem service method on AmazonDynamoDB. AmazonDynamoDB#batchWriteItem(BatchGetItemRequest) API.

config - Only DynamoDBMapperConfig.getTableNameOverride() is considered; if specified, all objects in the two parameter lists will be considered to belong to the given table override.

scan

public <T> PaginatedScanList<T> scan(Class<T> clazz,
                                     DynamoDBScanExpression scanExpression)

Scans through an AWS DynamoDB table and returns the matching results as an unmodifiable list of instantiated objects, using the default configuration.

See Also:

scan(Class, DynamoDBScanExpression, DynamoDBMapperConfig)

scan

public <T> PaginatedScanList<T> scan(Class<T> clazz,
                                     DynamoDBScanExpression scanExpression,
                                     DynamoDBMapperConfig config)

Scans through an AWS DynamoDB table and returns the matching results as an unmodifiable list of instantiated objects. The table to scan is determined by looking at the annotations on the specified class, which declares where to store the object data in AWS DynamoDB, and the scan expression parameter allows the caller to filter results and control how the scan is executed.

Callers should be aware that the returned list is unmodifiable, and any attempts to modify the list will result in an UnsupportedOperationException.

The unmodifiable list returned is lazily loaded when possible, so calls to DynamoDB will be made only as needed.

Type Parameters:

T - The type of the objects being returned.

Parameters:

clazz - The class annotated with DynamoDB annotations describing how to store the object data in AWS DynamoDB.

scanExpression - Details on how to run the scan, including any filters to apply to limit results.

config - The configuration to use for this scan, which overrides the default provided at object construction.

Returns:

An unmodifiable list of the objects constructed from the results of the scan operation.

See Also:

PaginatedScanList

query

public <T> PaginatedQueryList<T> query(Class<T> clazz,
                                       DynamoDBQueryExpression queryExpression)

Queries an AWS DynamoDB table and returns the matching results as an unmodifiable list of instantiated objects, using the default configuration.

See Also:

query(Class, DynamoDBQueryExpression, DynamoDBMapperConfig)

query

public <T> PaginatedQueryList<T> query(Class<T> clazz,
                                       DynamoDBQueryExpression queryExpression,
                                       DynamoDBMapperConfig config)

Queries an AWS DynamoDB table and returns the matching results as an unmodifiable list of instantiated objects. The table to query is determined by looking at the annotations on the specified class, which declares where to store the object data in AWS DynamoDB, and the query expression parameter allows the caller to filter results and control how the query is executed.

Callers should be aware that the returned list is unmodifiable, and any attempts to modify the list will result in an UnsupportedOperationException.

The unmodifiable list returned is lazily loaded when possible, so calls to DynamoDB will be made only as needed.

Type Parameters:

T - The type of the objects being returned.

Parameters:

clazz - The class annotated with DynamoDB annotations describing how to store the object data in AWS DynamoDB.

queryExpression - Details on how to run the query, including any filters to apply to limit the results.

config - The configuration to use for this query, which overrides the default provided at object construction.

Returns:

An unmodifiable list of the objects constructed from the results of the query operation.

See Also:

PaginatedQueryList

count

public int count(Class<?> clazz,
                 DynamoDBScanExpression scanExpression)

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

See Also:

count(Class, DynamoDBScanExpression, DynamoDBMapperConfig)

count

public int count(Class<?> clazz,
                 DynamoDBScanExpression scanExpression,
                 DynamoDBMapperConfig config)

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

This operation will scan your entire table, and can therefore be very expensive. Use with caution.

Parameters:

clazz - The class mapped to a DynamoDB table.

scanExpression - The parameters for running the scan.

config - The configuration to use for this scan, which overrides the default provided at object construction.

Returns:

The count of matching items, without returning any of the actual item data.

count

public int count(Class<?> clazz,
                 DynamoDBQueryExpression queryExpression)

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

See Also:

count(Class, DynamoDBQueryExpression, DynamoDBMapperConfig)

count

public int count(Class<?> clazz,
                 DynamoDBQueryExpression queryExpression,
                 DynamoDBMapperConfig config)

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

Parameters:

clazz - The class mapped to a DynamoDB table.

scanExpression - The parameters for running the scan.

config - The mapper configuration to use for the query, which overrides the default provided at object construction.

Returns:

The count of matching items, without returning any of the actual item data.