# Programming with DynamoDB and the AWS SDKs
Where:
tableName - The Amazon DynamoDB table from which an item is retrieved (for example, Music3).\s
key - The key used in the Amazon DynamoDB table (for example, Artist).\s
keyval - The key value that represents the item to get (for example, Famous Band).
""";
if (args.length != 3) {
System.out.println(usage);
System.exit(1);
}
String tableName = args[0];
String key = args[1];
String keyVal = args[2];
System.out.format("Retrieving item \"%s\" from \"%s\"\n", keyVal, tableName);
Region region = Region.US_EAST_1;
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.build();
getDynamoDBItem(ddb, tableName, key, keyVal);
ddb.close();
}
public static void getDynamoDBItem(DynamoDbClient ddb, String tableName, String key, String keyVal) {
HashMap keyToGet = new HashMap<>();
keyToGet.put(key, AttributeValue.builder()
.s(keyVal)
.build());
GetItemRequest request = GetItemRequest.builder()
.key(keyToGet)
.tableName(tableName)
.build();
try {
// If there is no matching item, GetItem does not return any data.
Map returnedItem = ddb.getItem(request).item();
if (returnedItem.isEmpty())
System.out.format("No item found with the key %s!\n", key);
else {
Set keys = returnedItem.keySet();
System.out.println("Amazon DynamoDB table attributes: \n");
for (String key1 : keys) {
System.out.format("%s: %s\n", key1, returnedItem.get(key1).toString());
}
}
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
System.exit(1);
}
}
}
```
## Document interfaces that work with DynamoDB
table = enhancedClient.table("Customer", TableSchema.fromBean(Customer.class));
Key key = Key.builder()
.partitionValue("id101").sortValue("tred@noserver.com")
.build();
// Get the item by using the key.
result = table.getItem(
(GetItemEnhancedRequest.Builder requestBuilder) -> requestBuilder.key(key));
System.out.println("******* The description value is " + result.getCustName());
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
System.exit(1);
}
return result.getCustName();
}
}
```
# Higher-level programming interfaces for DynamoDB
bookAuthors;
private String someProp;
@DynamoDBHashKey(attributeName="Id")
public Integer getId() { return id; }
public void setId(Integer id) {this.id = id; }
@DynamoDBAttribute(attributeName="Title")
public String getTitle() {return title; }
public void setTitle(String title) { this.title = title; }
@DynamoDBAttribute(attributeName="ISBN")
public String getISBN() { return ISBN; }
public void setISBN(String ISBN) { this.ISBN = ISBN; }
@DynamoDBAttribute(attributeName="Authors")
public Set getBookAuthors() { return bookAuthors; }
public void setBookAuthors(Set bookAuthors) { this.bookAuthors = bookAuthors; }
@DynamoDBIgnore
public String getSomeProp() { return someProp; }
public void setSomeProp(String someProp) { this.someProp = someProp; }
}
```
In the preceding code, the `@DynamoDBTable` annotation maps the `CatalogItem` class to the `ProductCatalog` table. You can store individual class instances as items in the table. In the class definition, the `@DynamoDBHashKey` annotation maps the `Id` property to the primary key.
By default, the class properties map to the same name attributes in the table. The properties `Title` and `ISBN` map to the same name attributes in the table.
The `@DynamoDBAttribute` annotation is optional when the name of the DynamoDB attribute matches the name of the property declared in the class. When they differ, use this annotation with the `attributeName` parameter to specify which DynamoDB attribute this property corresponds to.
In the preceding example, the `@DynamoDBAttribute` annotation is added to each property to ensure that the property names match exactly with the tables created in a previous step, and to be consistent with the attribute names used in other code examples in this guide.
Your class definition can have properties that don't map to any attributes in the table. You identify these properties by adding the `@DynamoDBIgnore` annotation. In the preceding example, the `SomeProp` property is marked with the `@DynamoDBIgnore` annotation. When you upload a `CatalogItem` instance to the table, your `DynamoDBMapper` instance does not include the `SomeProp` property. In addition, the mapper does not return this attribute when you retrieve an item from the table.
After you define your mapping class, you can use `DynamoDBMapper` methods to write an instance of that class to a corresponding item in the `Catalog` table. The following code example demonstrates this technique.
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDBMapper mapper = new DynamoDBMapper(client);
CatalogItem item = new CatalogItem();
item.setId(102);
item.setTitle("Book 102 Title");
item.setISBN("222-2222222222");
item.setBookAuthors(new HashSet(Arrays.asList("Author 1", "Author 2")));
item.setSomeProp("Test");
mapper.save(item);
```
The following code example shows how to retrieve the item and access some of its attributes.
```
CatalogItem partitionKey = new CatalogItem();
partitionKey.setId(102);
DynamoDBQueryExpression queryExpression = new DynamoDBQueryExpression()
.withHashKeyValues(partitionKey);
List itemList = mapper.query(CatalogItem.class, queryExpression);
for (int i = 0; i < itemList.size(); i++) {
System.out.println(itemList.get(i).getTitle());
System.out.println(itemList.get(i).getBookAuthors());
}
```
`DynamoDBMapper` offers an intuitive, natural way of working with DynamoDB data within Java. It also provides several built-in features, such as optimistic locking, ACID transactions, autogenerated partition key and sort key values, and object versioning.
# DynamoDBMapper Class
eav = new HashMap();
eav.put(":v1", new AttributeValue().withS(partitionKey));
eav.put(":v2",new AttributeValue().withS(twoWeeksAgoStr.toString()));
DynamoDBQueryExpression queryExpression = new DynamoDBQueryExpression()
.withKeyConditionExpression("Id = :v1 and ReplyDateTime > :v2")
.withExpressionAttributeValues(eav);
List latestReplies = mapper.query(Reply.class, queryExpression);
```
The query returns a collection of `Reply` objects.
By default, the `query` method returns a "lazy-loaded" collection. It initially returns only one page of results, and then makes a service call for the next page if needed. To obtain all the matching items, iterate over the `latestReplies` collection.
Note that calling the `size()` method on the collection will load every result in order to provide an accurate count. This can result in a lot of provisioned throughput being consumed, and on a very large table could even exhaust all the memory in your JVM.
To query an index, you must first model the index as a mapper class. Suppose that the `Reply` table has a global secondary index named *PostedBy-Message-Index*. The partition key for this index is `PostedBy`, and the sort key is `Message`. The class definition for an item in the index would look like the following.
```
@DynamoDBTable(tableName="Reply")
public class PostedByMessage {
private String postedBy;
private String message;
@DynamoDBIndexHashKey(globalSecondaryIndexName = "PostedBy-Message-Index", attributeName = "PostedBy")
public String getPostedBy() { return postedBy; }
public void setPostedBy(String postedBy) { this.postedBy = postedBy; }
@DynamoDBIndexRangeKey(globalSecondaryIndexName = "PostedBy-Message-Index", attributeName = "Message")
public String getMessage() { return message; }
public void setMessage(String message) { this.message = message; }
// Additional properties go here.
}
```
The `@DynamoDBTable` annotation indicates that this index is associated with the `Reply` table. The `@DynamoDBIndexHashKey` annotation denotes the partition key (*PostedBy*) of the index, and `@DynamoDBIndexRangeKey` denotes the sort key (*Message*) of the index.
Now you can use `DynamoDBMapper` to query the index, retrieving a subset of messages that were posted by a particular user. You do not need to specify the index name if you do not have conflicting mappings across tables and indexes and the mappings are already made in the mapper. The mapper will infer based on the primary key and sort key. The following code queries a global secondary index. Because global secondary indexes support eventually consistent reads but not strongly consistent reads, you must specify `withConsistentRead(false)`.
```
HashMap eav = new HashMap();
eav.put(":v1", new AttributeValue().withS("User A"));
eav.put(":v2", new AttributeValue().withS("DynamoDB"));
DynamoDBQueryExpression queryExpression = new DynamoDBQueryExpression()
.withIndexName("PostedBy-Message-Index")
.withConsistentRead(false)
.withKeyConditionExpression("PostedBy = :v1 and begins_with(Message, :v2)")
.withExpressionAttributeValues(eav);
List iList = mapper.query(PostedByMessage.class, queryExpression);
```
The query returns a collection of `PostedByMessage` objects.
## queryPage
eav = new HashMap();
eav.put(":v1", new AttributeValue().withS("2015"));
DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
.withFilterExpression("begins_with(ReplyDateTime,:v1)")
.withExpressionAttributeValues(eav);
List replies = mapper.scan(Reply.class, scanExpression);
```
By default, the `scan` method returns a "lazy-loaded" collection. It initially returns only one page of results, and then makes a service call for the next page if needed. To obtain all the matching items, iterate over the `replies` collection.
Note that calling the `size()` method on the collection will load every result in order to provide an accurate count. This can result in a lot of provisioned throughput being consumed, and on a very large table could even exhaust all the memory in your JVM.
To scan an index, you must first model the index as a mapper class. Suppose that the `Reply` table has a global secondary index named `PostedBy-Message-Index`. The partition key for this index is `PostedBy`, and the sort key is `Message`. A mapper class for this index is shown in the [query](#DynamoDBMapper.Methods.query) section. It uses the `@DynamoDBIndexHashKey` and `@DynamoDBIndexRangeKey` annotations to specify the index partition key and sort key.
The following code example scans `PostedBy-Message-Index`. It does not use a scan filter, so all of the items in the index are returned to you.
```
DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
.withIndexName("PostedBy-Message-Index")
.withConsistentRead(false);
List iList = mapper.scan(PostedByMessage.class, scanExpression);
Iterator indexItems = iList.iterator();
```
## scanPage
eav = new HashMap();
eav.put(":n", new AttributeValue().withN("100"));
DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
.withFilterExpression("Price <= :n")
.withExpressionAttributeValues(eav);
List scanResult = mapper.parallelScan(Product.class, scanExpression, numberOfThreads);
```
## batchSave
itemsToGet = new ArrayList();
ForumItem forumItem = new ForumItem();
forumItem.setForumName("Amazon DynamoDB");
itemsToGet.add(forumItem);
ThreadItem threadItem = new ThreadItem();
threadItem.setForumName("Amazon DynamoDB");
threadItem.setSubject("Amazon DynamoDB thread 1 message text");
itemsToGet.add(threadItem);
Map> items = mapper.batchLoad(itemsToGet);
```
## batchDelete
objectsToWrite = Arrays.asList(forumItem, threadItem);
List objectsToDelete = Arrays.asList(book3);
mapper.batchWrite(objectsToWrite, objectsToDelete);
```
## transactionWrite
getBookAuthors() { return BookAuthors; }
public void setBookAuthors(List BookAuthors) { this.BookAuthors = BookAuthors; }
```
The `DynamoDBMapper` uses `Authors` as the attribute name when saving the object to the table.
## DynamoDBAutoGeneratedKey
bookAuthors;
private String someProp;
private Long version;
@DynamoDBHashKey(attributeName="Id")
public Integer getId() { return id; }
public void setId(Integer Id) { this.id = Id; }
@DynamoDBAttribute(attributeName="Title")
public String getTitle() { return title; }
public void setTitle(String title) { this.title = title; }
@DynamoDBAttribute(attributeName="ISBN")
public String getISBN() { return ISBN; }
public void setISBN(String ISBN) { this.ISBN = ISBN;}
@DynamoDBAttribute(attributeName = "Authors")
public Set getBookAuthors() { return bookAuthors; }
public void setBookAuthors(Set bookAuthors) { this.bookAuthors = bookAuthors; }
@DynamoDBIgnore
public String getSomeProp() { return someProp;}
public void setSomeProp(String someProp) {this.someProp = someProp;}
@DynamoDBVersionAttribute
public Long getVersion() { return version; }
public void setVersion(Long version) { this.version = version;}
}
```
You can apply the `@DynamoDBVersionAttribute` annotation to nullable types provided by the primitive wrappers classes that provide a nullable type, such as `Long` and `Integer`.
Optimistic locking has the following impact on these `DynamoDBMapper` methods:
+ `save` — For a new item, the `DynamoDBMapper` assigns an initial version number of 1. If you retrieve an item, update one or more of its properties, and attempt to save the changes, the save operation succeeds only if the version number on the client side and the server side match. The `DynamoDBMapper` increments the version number automatically.
+ `delete` — The `delete` method takes an object as a parameter, and the `DynamoDBMapper` performs a version check before deleting the item. The version check can be disabled if `DynamoDBMapperConfig.SaveBehavior.CLOBBER` is specified in the request.
The internal implementation of optimistic locking within `DynamoDBMapper` uses conditional update and conditional delete support provided by DynamoDB.
+ `transactionWrite` —
+ `Put` — For a new item, the `DynamoDBMapper` assigns an initial version number of 1. If you retrieve an item, update one or more of its properties, and attempt to save the changes, the put operation succeeds only if the version number on the client side and the server side match. The `DynamoDBMapper` increments the version number automatically.
+ `Update` — For a new item, the `DynamoDBMapper` assigns an initial version number of 1. If you retrieve an item, update one or more of its properties, and attempt to save the changes, the update operation succeeds only if the version number on the client side and the server side match. The `DynamoDBMapper` increments the version number automatically.
+ `Delete` — The `DynamoDBMapper` performs a version check before deleting the item. The delete operation succeeds only if the version number on the client side and the server side match.
+ `ConditionCheck` — The `@DynamoDBVersionAttribute` annotation is not supported for `ConditionCheck` operations. An SdkClientException will be thrown when a `ConditionCheck` item is annotated with `@DynamoDBVersionAttribute`.
## Disabling optimistic locking
(Arrays.asList("Author1", "Author2")));
book.setDimensions(dimType);
DynamoDBMapper mapper = new DynamoDBMapper(client);
mapper.save(book);
Book bookRetrieved = mapper.load(Book.class, 502);
System.out.println("Book info: " + "\n" + bookRetrieved);
bookRetrieved.getDimensions().setHeight("9.0");
bookRetrieved.getDimensions().setLength("12.0");
bookRetrieved.getDimensions().setThickness("2.0");
mapper.save(bookRetrieved);
bookRetrieved = mapper.load(Book.class, 502);
System.out.println("Updated book info: " + "\n" + bookRetrieved);
}
@DynamoDBTable(tableName = "ProductCatalog")
public static class Book {
private int id;
private String title;
private String ISBN;
private Set bookAuthors;
private DimensionType dimensionType;
// Partition key
@DynamoDBHashKey(attributeName = "Id")
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
@DynamoDBAttribute(attributeName = "Title")
public String getTitle() {
return title;
}
public void setTitle(String title) {
this.title = title;
}
@DynamoDBAttribute(attributeName = "ISBN")
public String getISBN() {
return ISBN;
}
public void setISBN(String ISBN) {
this.ISBN = ISBN;
}
@DynamoDBAttribute(attributeName = "Authors")
public Set getBookAuthors() {
return bookAuthors;
}
public void setBookAuthors(Set bookAuthors) {
this.bookAuthors = bookAuthors;
}
@DynamoDBTypeConverted(converter = DimensionTypeConverter.class)
@DynamoDBAttribute(attributeName = "Dimensions")
public DimensionType getDimensions() {
return dimensionType;
}
@DynamoDBAttribute(attributeName = "Dimensions")
public void setDimensions(DimensionType dimensionType) {
this.dimensionType = dimensionType;
}
@Override
public String toString() {
return "Book [ISBN=" + ISBN + ", bookAuthors=" + bookAuthors + ", dimensionType= "
+ dimensionType.getHeight() + " X " + dimensionType.getLength() + " X "
+ dimensionType.getThickness()
+ ", Id=" + id + ", Title=" + title + "]";
}
}
static public class DimensionType {
private String length;
private String height;
private String thickness;
public String getLength() {
return length;
}
public void setLength(String length) {
this.length = length;
}
public String getHeight() {
return height;
}
public void setHeight(String height) {
this.height = height;
}
public String getThickness() {
return thickness;
}
public void setThickness(String thickness) {
this.thickness = thickness;
}
}
// Converts the complex type DimensionType to a string and vice-versa.
static public class DimensionTypeConverter implements DynamoDBTypeConverter {
@Override
public String convert(DimensionType object) {
DimensionType itemDimensions = (DimensionType) object;
String dimension = null;
try {
if (itemDimensions != null) {
dimension = String.format("%s x %s x %s", itemDimensions.getLength(), itemDimensions.getHeight(),
itemDimensions.getThickness());
}
} catch (Exception e) {
e.printStackTrace();
}
return dimension;
}
@Override
public DimensionType unconvert(String s) {
DimensionType itemDimension = new DimensionType();
try {
if (s != null && s.length() != 0) {
String[] data = s.split("x");
itemDimension.setLength(data[0].trim());
itemDimension.setHeight(data[1].trim());
itemDimension.setThickness(data[2].trim());
}
} catch (Exception e) {
e.printStackTrace();
}
return itemDimension;
}
}
}
```
# DynamoDBMapper examples
BookAuthors { get; set; }
[DynamoDBIgnore]
public string CoverPage { get; set; }
}
```
In the preceding example, the `DynamoDBTable` attribute maps the `Book` class to the `ProductCatalog` table.
The object persistence model supports both the explicit and default mapping between class properties and table attributes.
+ **Explicit mapping—**To map a property to a primary key, you must use the `DynamoDBHashKey` and `DynamoDBRangeKey` object persistence model attributes. Additionally, for the nonprimary key attributes, if a property name in your class and the corresponding table attribute to which you want to map it are not the same, you must define the mapping by explicitly adding the `DynamoDBProperty` attribute.
In the preceding example, the `Id` property maps to the primary key with the same name, and the `BookAuthors` property maps to the `Authors` attribute in the `ProductCatalog` table.
+ **Default mapping—**By default, the object persistence model maps the class properties to the attributes with the same name in the table.
In the preceding example, the properties `Title` and `ISBN` map to the attributes with the same name in the `ProductCatalog` table.
You don't have to map every single class property. You identify these properties by adding the `DynamoDBIgnore` attribute. When you save a `Book` instance to the table, the `DynamoDBContext` does not include the `CoverPage` property. It also does not return this property when you retrieve the book instance.
You can map properties of .NET primitive types such as int and string. You also can map any arbitrary data types as long as you provide an appropriate converter to map the arbitrary data to one of the DynamoDB types. To learn about mapping arbitrary types, see [Mapping arbitrary data with DynamoDB using the AWS SDK for .NET object persistence model](DynamoDBContext.ArbitraryDataMapping.md).
The object persistence model supports optimistic locking. During an update operation, this ensures that you have the latest copy of the item you are about to update. For more information, see [Optimistic locking using DynamoDB and the AWS SDK for .NET object persistence model](DynamoDBContext.VersionSupport.md).
For more information, see the topics below.
**Topics**
+ [Supported data types](#DotNetDynamoDBContext.SupportedTypes)
+ [DynamoDB attributes from the .NET object persistence model](DeclarativeTagsList.md)
+ [DynamoDBContext class from the .NET object persistence model](DotNetDynamoDBContext.md)
+ [Optimistic locking using DynamoDB and the AWS SDK for .NET object persistence model](DynamoDBContext.VersionSupport.md)
+ [Mapping arbitrary data with DynamoDB using the AWS SDK for .NET object persistence model](DynamoDBContext.ArbitraryDataMapping.md)
## Supported data types
BookAuthors { get; set; }
```
`DynamoDBContext` uses this mapping information to create the `Authors` attribute when saving object data to the corresponding table.
## DynamoDBRenamable
(101);
```
**Note**
If your `Document` object implements the `IEnumerable` interface, you can use the `FromDocuments` method instead. This allows you to iterate over all of the class instances in the `Document`.
## FromQuery
/// Shows how to perform high-level CRUD operations on an Amazon DynamoDB
/// table.
///
public class HighLevelItemCrud
{
public static async Task Main()
{
var client = new AmazonDynamoDBClient();
DynamoDBContext context = new DynamoDBContext(client);
await PerformCRUDOperations(context);
}
public static async Task PerformCRUDOperations(IDynamoDBContext context)
{
int bookId = 1001; // Some unique value.
Book myBook = new Book
{
Id = bookId,
Title = "object persistence-AWS SDK for.NET SDK-Book 1001",
Isbn = "111-1111111001",
BookAuthors = new List { "Author 1", "Author 2" },
};
// Save the book to the ProductCatalog table.
await context.SaveAsync(myBook);
// Retrieve the book from the ProductCatalog table.
Book bookRetrieved = await context.LoadAsync(bookId);
// Update some properties.
bookRetrieved.Isbn = "222-2222221001";
// Update existing authors list with the following values.
bookRetrieved.BookAuthors = new List { " Author 1", "Author x" };
await context.SaveAsync(bookRetrieved);
// Retrieve the updated book. This time, add the optional
// ConsistentRead parameter using DynamoDBContextConfig object.
await context.LoadAsync(bookId, new DynamoDBContextConfig
{
ConsistentRead = true,
});
// Delete the book.
await context.DeleteAsync(bookId);
// Try to retrieve deleted book. It should return null.
Book deletedBook = await context.LoadAsync(bookId, new DynamoDBContextConfig
{
ConsistentRead = true,
});
if (deletedBook == null)
{
Console.WriteLine("Book is deleted");
}
}
}
```
## Query
latestReplies = context.Query(replyId, QueryOperator.GreaterThan, twoWeeksAgoDate);
```
This returns a collection of `Reply` objects.
The `Query` method returns a "lazy-loaded" `IEnumerable` collection. It initially returns only one page of results, and then makes a service call for the next page if needed. To obtain all the matching items, you need to iterate only over the `IEnumerable`.
If your table has a simple primary key (partition key), you can't use the `Query` method. Instead, you can use the `Load` method and provide the partition key to retrieve the item.
**Note**
To perform this operation in the background, use the `QueryAsync` method instead.
## Save
itemsWithWrongPrice = context.Scan(
new ScanCondition("Price", ScanOperator.LessThan, price),
new ScanCondition("ProductCategory", ScanOperator.Equal, "Book")
);
```
The `Scan` method returns a "lazy-loaded" `IEnumerable` collection. It initially returns only one page of results, and then makes a service call for the next page if needed. To obtain all the matching items, you only need to iterate over the `IEnumerable`.
For performance reasons, you should query your tables and avoid a table scan.
**Note**
To perform this operation in the background, use the `ScanAsync` method instead.
## ToDocument
(101); // Retrieve a forum by primary key.
Document doc = context.ToDocument(forum101);
```
## Specifying optional parameters for DynamoDBContext
(productId,new DynamoDBContextConfig{ ConsistentRead = true, SkipVersionCheck = true });
```
In this case, `DynamoDBContext` includes these parameters only when sending the `Get` request.
# Optimistic locking using DynamoDB and the AWS SDK for .NET object persistence model
BookAuthors { get; set; }
[DynamoDBVersion]
public int? VersionNumber { get; set; }
}
```
**Note**
You can apply the `DynamoDBVersion` attribute only to a nullable numeric primitive type (such as `int?`).
Optimistic locking has the following impact on `DynamoDBContext` operations:
+ For a new item, `DynamoDBContext` assigns initial version number 0. If you retrieve an existing item, update one or more of its properties, and try to save the changes, the save operation succeeds only if the version number on the client side and the server side match. `DynamoDBContext` increments the version number. You don't need to set the version number.
+ The `Delete` method provides overloads that can take either a primary key value or an object as parameter, as shown in the following C\$1 code example.
**Example**
```
DynamoDBContext context = new DynamoDBContext(client);
...
// Load a book.
Book book = context.Load(111);
// Do other operations.
// Delete 1 - Pass in the book object.
context.Delete(book);
// Delete 2 - Pass in the Id (primary key)
context.Delete(222);
```
If you provide an object as the parameter, the delete succeeds only if the object version matches the corresponding server-side item version. However, if you provide a primary key value as the parameter, `DynamoDBContext` is unaware of any version numbers, and it deletes the item without making the version check.
Note that the internal implementation of optimistic locking in the object persistence model code uses the conditional update and the conditional delete API actions in DynamoDB.
## Disabling optimistic locking
(111);
...
// Delete the book.
context.Delete(book, new DynamoDBContextConfig { SkipVersionCheck = true });
```
# Mapping arbitrary data with DynamoDB using the AWS SDK for .NET object persistence model
{ "Author 1", "Author 2" },
Dimensions = myBookDimensions
};
context.Save(myBook);
// 2. Retrieve the book.
Book bookRetrieved = context.Load(501);
// 3. Update property (book dimensions).
bookRetrieved.Dimensions.Height += 1;
bookRetrieved.Dimensions.Length += 1;
bookRetrieved.Dimensions.Thickness += 0.2M;
// Update the book.
context.Save(bookRetrieved);
Console.WriteLine("To continue, press Enter");
Console.ReadLine();
}
catch (AmazonDynamoDBException e) { Console.WriteLine(e.Message); }
catch (AmazonServiceException e) { Console.WriteLine(e.Message); }
catch (Exception e) { Console.WriteLine(e.Message); }
}
}
[DynamoDBTable("ProductCatalog")]
public class Book
{
[DynamoDBHashKey] //Partition key
public int Id
{
get; set;
}
[DynamoDBProperty]
public string Title
{
get; set;
}
[DynamoDBProperty]
public string ISBN
{
get; set;
}
// Multi-valued (set type) attribute.
[DynamoDBProperty("Authors")]
public List BookAuthors
{
get; set;
}
// Arbitrary type, with a converter to map it to DynamoDB type.
[DynamoDBProperty(typeof(DimensionTypeConverter))]
public DimensionType Dimensions
{
get; set;
}
}
public class DimensionType
{
public decimal Length
{
get; set;
}
public decimal Height
{
get; set;
}
public decimal Thickness
{
get; set;
}
}
// Converts the complex type DimensionType to string and vice-versa.
public class DimensionTypeConverter : IPropertyConverter
{
public DynamoDBEntry ToEntry(object value)
{
DimensionType bookDimensions = value as DimensionType;
if (bookDimensions == null) throw new ArgumentOutOfRangeException();
string data = string.Format("{1}{0}{2}{0}{3}", " x ",
bookDimensions.Length, bookDimensions.Height, bookDimensions.Thickness);
DynamoDBEntry entry = new Primitive
{
Value = data
};
return entry;
}
public object FromEntry(DynamoDBEntry entry)
{
Primitive primitive = entry as Primitive;
if (primitive == null || !(primitive.Value is String) || string.IsNullOrEmpty((string)primitive.Value))
throw new ArgumentOutOfRangeException();
string[] data = ((string)(primitive.Value)).Split(new string[] { " x " }, StringSplitOptions.None);
if (data.Length != 3) throw new ArgumentOutOfRangeException();
DimensionType complexData = new DimensionType
{
Length = Convert.ToDecimal(data[0]),
Height = Convert.ToDecimal(data[1]),
Thickness = Convert.ToDecimal(data[2])
};
return complexData;
}
}
}
```
# Running the code examples in this Developer Guide
```
At runtime, the program uses the `default` set of AWS credentials, as specified by the `AWSProfileName` entry. The AWS credentials themselves are kept in the SDK Store in encrypted form. The Toolkit for Visual Studio provides a graphical user interface for managing your credentials, all from within Visual Studio. For more information, see [Specifying credentials](https://docs.aws.amazon.com/AWSToolkitVS/latest/UserGuide/tkv_setup.html#creds) in the *AWS Toolkit for Visual Studio User Guide*.
**Note**
By default, the code examples access DynamoDB in the US West (Oregon) Region. You can change the Region by modifying the `AWSRegion` entry in the App.config file. You can set `AWSRegion` to any Region where DynamoDB is available. For a complete list, see [AWS regions and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#ddb_region) in the *Amazon Web Services General Reference*.
## .NET: Setting the AWS Region and endpoint
.;
Accept-Encoding: identity
Content-Length:
User-Agent:
Content-Type: application/x-amz-json-1.0
Authorization: AWS4-HMAC-SHA256 Credential=, SignedHeaders=, Signature=
X-Amz-Date:
X-Amz-Target: DynamoDB_20120810.GetItem
{
"TableName": "Pets",
"Key": {
"AnimalType": {"S": "Dog"},
"Name": {"S": "Fido"}
}
}
```
Note the following about this request:
+ The `Authorization` header contains information required for DynamoDB to authenticate the request. For more information, see [Signing AWS API requests](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html) and [Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) in the *Amazon Web Services General Reference*.
+ The `X-Amz-Target` header contains the name of a DynamoDB operation: `GetItem`. (This is also accompanied by the low-level API version, in this case `20120810`.)
+ The payload (body) of the request contains the parameters for the operation, in JSON format. For the `GetItem` operation, the parameters are `TableName` and `Key`.
## Response format
x-amz-crc32:
Content-Type: application/x-amz-json-1.0
Content-Length:
Date:
{
"Item": {
"Age": {"N": "8"},
"Colors": {
"L": [
{"S": "White"},
{"S": "Brown"},
{"S": "Black"}
]
},
"Name": {"S": "Fido"},
"Vaccinations": {
"M": {
"Rabies": {
"L": [
{"S": "2009-03-17"},
{"S": "2011-09-21"},
{"S": "2014-07-08"}
]
},
"Distemper": {"S": "2015-10-13"}
}
},
"Breed": {"S": "Beagle"},
"AnimalType": {"S": "Dog"}
}
}
```
At this point, the AWS SDK returns the response data to your application for further processing.
**Note**
If DynamoDB can't process a request, it returns an HTTP error code and message. The AWS SDK propagates these to your application in the form of exceptions. For more information, see [Error handling with DynamoDB](Programming.Errors.md).
## Data type descriptors
const results = await waitUntilTableExists({client: client, maxWaitTime: 180}, {TableName: "products"});
if (results.state == 'SUCCESS') {
return results.reason.Table
}
console.error(`${results.state} ${results.reason}`);
```
The `waitUntilTableExists` feature returns control only when it can perform a `describe-table` command that shows the table status **ACTIVE**. This ensures that you can use `waitUntilTableExists` to wait for the completion of creation, as well as modifications such as adding a GSI index, which may take some time to apply before the table returns to **ACTIVE** status.
## Error handling
4.0.0
org.example
getstarted
1.0-SNAPSHOT
jar
UTF-8
1.8
1.8
3.2.1
3.6.1
1.6.0
2.22.0 <-------- SDK version picked up from archetype version.
1.7.28
5.8.1
software.amazon.awssdk
bom
${aws.java.sdk.version}
pom
import
software.amazon.awssdk
dynamodb <-------- DynamoDB dependency
software.amazon.awssdk
netty-nio-client
software.amazon.awssdk
apache-client
software.amazon.awssdk
sso <-------- Required for identity center authentication.
software.amazon.awssdk
ssooidc <-------- Required for identity center authentication.
software.amazon.awssdk
apache-client <-------- HTTP client specified.
commons-logging
commons-logging
org.slf4j
slf4j-api
${slf4j.version}
org.slf4j
slf4j-simple
${slf4j.version}
org.slf4j
jcl-over-slf4j
${slf4j.version}
org.junit.jupiter
junit-jupiter
${junit5.version}
test
org.apache.maven.plugins
maven-compiler-plugin
${maven.compiler.plugin.version}
```
### Step 3: Write the code
DYNAMODB_TABLE = ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.fromBean(YourItem.class));
private static final Logger LOGGER = LoggerFactory.getLogger(PutItem.class);
private void putItem() {
PutItemEnhancedResponse response = DYNAMODB_TABLE.putItemWithResponse(PutItemEnhancedRequest.builder(YourItem.class)
.item(new YourItem("123", "cart#123", "YourItemData", 500))
.returnConsumedCapacity(ReturnConsumedCapacity.TOTAL)
.build());
LOGGER.info("PutItem call consumed [" + response.consumedCapacity().capacityUnits() + "] Write Capacity Unites (WCU)");
}
@DynamoDbBean
public static class YourItem {
public YourItem() {}
public YourItem(String pk, String sk, String itemData, int inventory) {
this.pk = pk;
this.sk = sk;
this.itemData = itemData;
this.inventory = inventory;
}
private String pk;
private String sk;
private String itemData;
private int inventory;
@DynamoDbPartitionKey
public void setPk(String pk) {
this.pk = pk;
}
public String getPk() {
return pk;
}
@DynamoDbSortKey
public void setSk(String sk) {
this.sk = sk;
}
public String getSk() {
return sk;
}
public void setItemData(String itemData) {
this.itemData = itemData;
}
public String getItemData() {
return itemData;
}
public void setInventory(int inventory) {
this.inventory = inventory;
}
public int getInventory() {
return inventory;
}
}
}
```
The AWS SDK for Java 1.x has its own high-level interface, which is often referred to by its main class `DynamoDBMapper`. The AWS SDK for Java 2.x is published in a separate package (and Maven artifact) named `software.amazon.awssdk.enhanced.dynamodb`. The Java 2.x SDK is often referred to by its main class `DynamoDbEnhancedClient`.
#### High-level interface using immutable data classes
DYNAMODB_TABLE = ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.fromImmutableClass(YourImmutableItem.class));
private static final Logger LOGGER = LoggerFactory.getLogger(DynamoDbEnhancedClientImmutablePutItem.class);
private void putItem() {
PutItemEnhancedResponse response = DYNAMODB_TABLE.putItemWithResponse(PutItemEnhancedRequest.builder(YourImmutableItem.class)
.item(YourImmutableItem.builder()
.pk("123")
.sk("cart#123")
.itemData("YourItemData")
.inventory(500)
.build())
.returnConsumedCapacity(ReturnConsumedCapacity.TOTAL)
.build());
LOGGER.info("PutItem call consumed [" + response.consumedCapacity().capacityUnits() + "] Write Capacity Unites (WCU)");
}
}
```
The following example shows the immutable data class.
```
@DynamoDbImmutable(builder = YourImmutableItem.YourImmutableItemBuilder.class)
class YourImmutableItem {
private final String pk;
private final String sk;
private final String itemData;
private final int inventory;
public YourImmutableItem(YourImmutableItemBuilder builder) {
this.pk = builder.pk;
this.sk = builder.sk;
this.itemData = builder.itemData;
this.inventory = builder.inventory;
}
public static YourImmutableItemBuilder builder() { return new YourImmutableItemBuilder(); }
@DynamoDbPartitionKey
public String getPk() {
return pk;
}
@DynamoDbSortKey
public String getSk() {
return sk;
}
public String getItemData() {
return itemData;
}
public int getInventory() {
return inventory;
}
static final class YourImmutableItemBuilder {
private String pk;
private String sk;
private String itemData;
private int inventory;
private YourImmutableItemBuilder() {}
public YourImmutableItemBuilder pk(String pk) { this.pk = pk; return this; }
public YourImmutableItemBuilder sk(String sk) { this.sk = sk; return this; }
public YourImmutableItemBuilder itemData(String itemData) { this.itemData = itemData; return this; }
public YourImmutableItemBuilder inventory(int inventory) { this.inventory = inventory; return this; }
public YourImmutableItem build() { return new YourImmutableItem(this); }
}
}
```
#### High-level interface using immutable data classes and third-party boilerplate generation libraries
DYNAMODB_TABLE = ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.fromImmutableClass(YourImmutableLombokItem.class));
private static final Logger LOGGER = LoggerFactory.getLogger(DynamoDbEnhancedClientImmutableLombokPutItem.class);
private void putItem() {
PutItemEnhancedResponse response = DYNAMODB_TABLE.putItemWithResponse(PutItemEnhancedRequest.builder(YourImmutableLombokItem.class)
.item(YourImmutableLombokItem.builder()
.pk("123")
.sk("cart#123")
.itemData("YourItemData")
.inventory(500)
.build())
.returnConsumedCapacity(ReturnConsumedCapacity.TOTAL)
.build());
LOGGER.info("PutItem call consumed [" + response.consumedCapacity().capacityUnits() + "] Write Capacity Unites (WCU)");
}
}
```
The following example shows the immutable data object of the immutable data class.
```
import lombok.*;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.*;
@Builder
@DynamoDbImmutable(builder = YourImmutableLombokItem.YourImmutableLombokItemBuilder.class)
@Value
public class YourImmutableLombokItem {
@Getter(onMethod_=@DynamoDbPartitionKey)
String pk;
@Getter(onMethod_=@DynamoDbSortKey)
String sk;
String itemData;
int inventory;
}
```
The `YourImmutableLombokItem` class uses the following annotations that Project Lombok and the AWS SDK provide:
+ [@Builder](https://projectlombok.org/features/Builder) – Produces complex builder APIs for data classes that Project Lombok provides.
+ [@DynamoDbImmutable](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/mapper/annotations/DynamoDbImmutable.html) – Identifies the `DynamoDbImmutable` class as a DynamoDB mappable entity annotation that the AWS SDK provides.
+ [@Value](https://projectlombok.org/features/Value) – The immutable variant of `@Data`. By default, all fields are made private and final, and setters are not generated. Project Lombok provides this annotation.
### Document interface
DYNAMODB_TABLE =
ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.documentSchemaBuilder()
.addIndexPartitionKey(TableMetadata.primaryIndexName(),"pk", AttributeValueType.S)
.addIndexSortKey(TableMetadata.primaryIndexName(), "sk", AttributeValueType.S)
.attributeConverterProviders(AttributeConverterProvider.defaultProvider())
.build());
private static final Logger LOGGER = LoggerFactory.getLogger(DynamoDbEnhancedDocumentClientPutItem.class);
private void putItem() {
PutItemEnhancedResponse response = DYNAMODB_TABLE.putItemWithResponse(
PutItemEnhancedRequest.builder(EnhancedDocument.class)
.item(
EnhancedDocument.builder()
.attributeConverterProviders(AttributeConverterProvider.defaultProvider())
.putString("pk", "123")
.putString("sk", "cart#123")
.putString("item_data", "YourItemData")
.putNumber("inventory", 500)
.build())
.returnConsumedCapacity(ReturnConsumedCapacity.TOTAL)
.build());
LOGGER.info("PutItem call consumed [" + response.consumedCapacity().capacityUnits() + "] Write Capacity Unites (WCU)");
}
}
```
To convert JSON documents to and from the native Amazon DynamoDB data types, you can use the following utility methods:
+ [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html#fromJson(java.lang.String)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html#fromJson(java.lang.String)) – Creates a new EnhancedDocument instance from a JSON string.
+ [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html#toJson()](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html#toJson()) – Creates a JSON string representation of the document that you can use in your application like any other JSON object.
### Comparing interfaces with a `Query` example
DYNAMODB_TABLE =
ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.documentSchemaBuilder()
.addIndexPartitionKey(TableMetadata.primaryIndexName(),"pk", AttributeValueType.S)
.addIndexSortKey(TableMetadata.primaryIndexName(), "sk", AttributeValueType.S)
.attributeConverterProviders(AttributeConverterProvider.defaultProvider())
.build());
private static final Logger LOGGER = LoggerFactory.getLogger(DynamoDbEnhancedDocumentClientQuery.class);
private void query() {
PageIterable response = DYNAMODB_TABLE.query(QueryEnhancedRequest.builder()
.filterExpression(Expression.builder()
.expression("#name = :name_val")
.expressionNames(Map.of("#name", "name"))
.expressionValues(Map.of(":name_val", AttributeValue.fromS("SomeName")))
.build())
.limit(100)
.queryConditional(QueryConditional.sortBeginsWith(Key.builder()
.partitionValue("id#1")
.sortValue("cart#")
.build()))
.scanIndexForward(false)
.build());
LOGGER.info("nr of items: " + response.items().stream().count());
LOGGER.info("First item pk: " + response.items().iterator().next().getString("pk"));
LOGGER.info("First item sk: " + response.items().iterator().next().getString("sk"));
}
}
```
**Example `Query` using the high-level interface**
The following example queries a table named `YourTableName` using the DynamoDB enhanced client API.
```
import org.slf4j.*;
import software.amazon.awssdk.enhanced.dynamodb.*;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.*;
import software.amazon.awssdk.enhanced.dynamodb.model.*;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import java.util.Map;
public class DynamoDbEnhancedClientQuery {
private static final DynamoDbEnhancedClient ENHANCED_DYNAMODB_CLIENT = DynamoDbEnhancedClient.builder().build();
private static final DynamoDbTable DYNAMODB_TABLE = ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.fromBean(DynamoDbEnhancedClientQuery.YourItem.class));
private static final Logger LOGGER = LoggerFactory.getLogger(DynamoDbEnhancedClientQuery.class);
private void query() {
PageIterable response = DYNAMODB_TABLE.query(QueryEnhancedRequest.builder()
.filterExpression(Expression.builder()
.expression("#name = :name_val")
.expressionNames(Map.of("#name", "name"))
.expressionValues(Map.of(":name_val", AttributeValue.fromS("SomeName")))
.build())
.limit(100)
.queryConditional(QueryConditional.sortBeginsWith(Key.builder()
.partitionValue("id#1")
.sortValue("cart#")
.build()))
.scanIndexForward(false)
.build());
LOGGER.info("nr of items: " + response.items().stream().count());
LOGGER.info("First item pk: " + response.items().iterator().next().getPk());
LOGGER.info("First item sk: " + response.items().iterator().next().getSk());
}
@DynamoDbBean
public static class YourItem {
public YourItem() {}
public YourItem(String pk, String sk, String name) {
this.pk = pk;
this.sk = sk;
this.name = name;
}
private String pk;
private String sk;
private String name;
@DynamoDbPartitionKey
public void setPk(String pk) {
this.pk = pk;
}
public String getPk() {
return pk;
}
@DynamoDbSortKey
public void setSk(String sk) {
this.sk = sk;
}
public String getSk() {
return sk;
}
public void setName(String name) {
this.name = name;
}
public String getName() {
return name;
}
}
}
```
**High-level interface using immutable data classes**
When you perform a `Query` with the high-level immutable data classes, the code is the same as the high-level interface example except for the construction of the entity class `YourItem` or `YourImmutableItem`. For more information, see the [PutItem](#HighLevelImmutableDataClassEg) example.
**High-level interface using immutable data classes and third-party boilerplate generation libraries**
When you perform a `Query` with the high-level immutable data classes, the code is the same as the high-level interface example except for the construction of the entity class `YourItem` or `YourImmutableLombokItem`. For more information, see the [PutItem](#HighLevelImmutableDataClassEg) example.
## Additional code examples
```
### AWS request ID logging
```
Here is an example of the log output:
```
2022-09-23 16:02:08 [main] DEBUG software.amazon.awssdk.request:85 - Sending Request: DefaultSdkHttpFullRequest(httpMethod=POST, protocol=https, host=dynamodb.us-east-1.amazonaws.com, encodedPath=/, headers=[amz-sdk-invocation-id, Content-Length, Content-Type, User-Agent, X-Amz-Target], queryParameters=[])
2022-09-23 16:02:08 [main] DEBUG software.amazon.awssdk.request:85 - Received successful response: 200, Request ID: QS9DUMME2NHEDH8TGT9N5V53OJVV4KQNSO5AEMVJF66Q9ASUAAJG, Extended Request ID: not available
```
## Pagination