CUSTOMER_SCHEMA =
StaticTableSchema.builder(Customer.class)
.newItemSupplier(Customer::new)
.addAttribute(String.class, a -> a.name("name")
.getter(Customer::getName)
.setter(Customer::setName))
// Because we are flattening a component object, we supply a getter and setter so the
// mapper knows how to access it.
.flatten(GENERIC_RECORD_SCHEMA, Customer::getRecord, Customer::setRecord)
.build();
```
The previous static schema example uses the following data classes.
#### Data classes
------
#### [ Standard data class ]
```
public class Customer {
private String name;
private GenericRecord record;
public String getName() { return this.name; }
public void setName(String name) { this.name = name; }
public GenericRecord getRecord() { return this.record; }
public void setRecord(GenericRecord record) { this.record = record; }
public class GenericRecord {
private String id;
private String createdDate;
public String getId() { return this.id; }
public void setId(String id) { this.id = id; }
public String getCreatedDate() { return this.createdDate; }
public void setCreatedDate(String createdDate) { this.createdDate = createdDate; }
}
```
------
#### [ Lombok ]
```
@Data
public class Customer {
private String name;
private GenericRecord record;
}
@Data
public class GenericRecord {
private String id;
private String createdDate;
}
```
------
You can use the builder pattern to flatten as many different eligible classes as you need to.
## Implications for other code
When you use the `@DynamoDbFlatten` attribute (or `flatten()` builder method), the item in DynamoDB contains an attribute for each attribute of the composed object. It also includes the attributes of the composing object.
In contrast, if you annotate a data class with a composed class and don't use `@DynamoDbFlatten`, the item is saved with the composed object as a single attribute.
For example, compare the `Customer` class shown in the [flattening with composition example](#ddb-en-client-adv-features-flatmap-comp-anno) with and without flattening of the `record` attribute. You can visualize the difference with JSON as shown in the following table.
****
| With flattening | Without flattening |
| --- | --- |
| 3 attributes | 2 attributes |
| {
"id": "1",
"createdDate": "today",
"name": "my name"
} | {
"id": "1",
"record": {
"createdDate": "today",
"name": "my name"
}
} |
The difference becomes important if you have other code accessing the DynamoDB table that expects to find certain attributes.
# Work with attributes that are beans, maps, lists and sets
A bean definition, such as the `Person` class shown below, might define properties (or attributes) that refer to types with additional attributes. For instance, in the `Person` class, `mainAddress` is a property that refers to an `Address` bean that defines additional value attributes. `addresses` refers to a Java Map, whose elements refer to `Address` beans. These complex types can be thought of a containers of simple attributes that you use for their data value in the context of DynamoDB.
DynamoDB refers to the value properties of nested elements, such as maps, lists, or beans, as *nested attributes*. The [Amazon DynamoDB Developer Guide](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes) refers to the saved form of a Java map, list or bean as a *document type*. Simple attributes that you use for their data value in Java are referred to as *scalar types* in DynamoDB. Sets, which contains multiple scalar elements of the same type, and referred to as *set types*.
It is important to know that the DynamoDB Enhanced Client API converts a property that is bean to a DynamoDB map document type when it is save.
## `Person` class
```
@DynamoDbBean
public class Person {
private Integer id;
private String firstName;
private String lastName;
private Integer age;
private Address mainAddress;
private Map addresses;
private List phoneNumbers;
private Set hobbies;
@DynamoDbPartitionKey
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getFirstName() {
return firstName;
}
public void setFirstName(String firstName) {
this.firstName = firstName;
}
public String getLastName() {
return lastName;
}
public void setLastName(String lastName) {
this.lastName = lastName;
}
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
public Address getMainAddress() {
return mainAddress;
}
public void setMainAddress(Address mainAddress) {
this.mainAddress = mainAddress;
}
public Map getAddresses() {
return addresses;
}
public void setAddresses(Map addresses) {
this.addresses = addresses;
}
public List getPhoneNumbers() {
return phoneNumbers;
}
public void setPhoneNumbers(List phoneNumbers) {
this.phoneNumbers = phoneNumbers;
}
public Set getHobbies() {
return hobbies;
}
public void setHobbies(Set hobbies) {
this.hobbies = hobbies;
}
@Override
public String toString() {
return "Person{" +
"addresses=" + addresses +
", id=" + id +
", firstName='" + firstName + '\'' +
", lastName='" + lastName + '\'' +
", age=" + age +
", mainAddress=" + mainAddress +
", phoneNumbers=" + phoneNumbers +
", hobbies=" + hobbies +
'}';
}
}
```
## `Address` class
```
@DynamoDbBean
public class Address {
private String street;
private String city;
private String state;
private String zipCode;
public Address() {
}
public String getStreet() {
return this.street;
}
public String getCity() {
return this.city;
}
public String getState() {
return this.state;
}
public String getZipCode() {
return this.zipCode;
}
public void setStreet(String street) {
this.street = street;
}
public void setCity(String city) {
this.city = city;
}
public void setState(String state) {
this.state = state;
}
public void setZipCode(String zipCode) {
this.zipCode = zipCode;
}
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (o == null || getClass() != o.getClass()) return false;
Address address = (Address) o;
return Objects.equals(street, address.street) && Objects.equals(city, address.city) && Objects.equals(state, address.state) && Objects.equals(zipCode, address.zipCode);
}
@Override
public int hashCode() {
return Objects.hash(street, city, state, zipCode);
}
@Override
public String toString() {
return "Address{" +
"street='" + street + '\'' +
", city='" + city + '\'' +
", state='" + state + '\'' +
", zipCode='" + zipCode + '\'' +
'}';
}
}
```
## `PhoneNumber` class
```
@DynamoDbBean
public class PhoneNumber {
String type;
String number;
public String getType() {
return type;
}
public void setType(String type) {
this.type = type;
}
public String getNumber() {
return number;
}
public void setNumber(String number) {
this.number = number;
}
@Override
public String toString() {
return "PhoneNumber{" +
"type='" + type + '\'' +
", number='" + number + '\'' +
'}';
}
}
```
## Save complex types
### Use annotated data classes
You save nested attributes for custom classes by simply annotating them. The `Address` class and `PhoneNumber` class shown previously are annotated with only the `@DynamoDbBean` annotation. When the DynamoDB Enhanced Client API builds the table schema for the `Person` class with the following snippet, the API discovers the use of the `Address` and `PhoneNumber` classes and builds the corresponding mappings to work with DynamoDB.
```
TableSchema personTableSchema = TableSchema.fromBean(Person.class);
```
### Use abstract schemas with builders
The alternative approach is to use static table schema builders for each nested bean class as shown in the following code.
The table schemas for the `Address` and `PhoneNumber` classes are abstract in the sense that they cannot be used with a DynamoDB table. This is because they lack definitions for the primary key. They are used, however, as nested schemas in the table schema for the `Person` class.
After comment lines 1 and 2 in the definition of `PERSON_TABLE_SCHEMA`, you see the code that uses the abstract table schemas. The use of `documentOf` in the `EnhanceType.documentOf(...)` method does not indicate that the method returns an `EnhancedDocument` type of the Enhanced Document API. The `documentOf(...)` method in this context returns an object that knows how to map its class argument to and from DynamoDB table attributes by using the table schema argument.
#### Static schema code
```
// Abstract table schema that cannot be used to work with a DynamoDB table,
// but can be used as a nested schema.
public static final TableSchema TABLE_SCHEMA_ADDRESS = TableSchema.builder(Address.class)
.newItemSupplier(Address::new)
.addAttribute(String.class, a -> a.name("street")
.getter(Address::getStreet)
.setter(Address::setStreet))
.addAttribute(String.class, a -> a.name("city")
.getter(Address::getCity)
.setter(Address::setCity))
.addAttribute(String.class, a -> a.name("zipcode")
.getter(Address::getZipCode)
.setter(Address::setZipCode))
.addAttribute(String.class, a -> a.name("state")
.getter(Address::getState)
.setter(Address::setState))
.build();
// Abstract table schema that cannot be used to work with a DynamoDB table,
// but can be used as a nested schema.
public static final TableSchema TABLE_SCHEMA_PHONENUMBER = TableSchema.builder(PhoneNumber.class)
.newItemSupplier(PhoneNumber::new)
.addAttribute(String.class, a -> a.name("type")
.getter(PhoneNumber::getType)
.setter(PhoneNumber::setType))
.addAttribute(String.class, a -> a.name("number")
.getter(PhoneNumber::getNumber)
.setter(PhoneNumber::setNumber))
.build();
// A static table schema that can be used with a DynamoDB table.
// The table schema contains two nested schemas that are used to perform mapping to/from DynamoDB.
public static final TableSchema PERSON_TABLE_SCHEMA =
TableSchema.builder(Person.class)
.newItemSupplier(Person::new)
.addAttribute(Integer.class, a -> a.name("id")
.getter(Person::getId)
.setter(Person::setId)
.addTag(StaticAttributeTags.primaryPartitionKey()))
.addAttribute(String.class, a -> a.name("firstName")
.getter(Person::getFirstName)
.setter(Person::setFirstName))
.addAttribute(String.class, a -> a.name("lastName")
.getter(Person::getLastName)
.setter(Person::setLastName))
.addAttribute(Integer.class, a -> a.name("age")
.getter(Person::getAge)
.setter(Person::setAge))
.addAttribute(EnhancedType.documentOf(Address.class, TABLE_SCHEMA_ADDRESS), a -> a.name("mainAddress")
.getter(Person::getMainAddress)
.setter(Person::setMainAddress))
.addAttribute(EnhancedType.listOf(String.class), a -> a.name("hobbies")
.getter(Person::getHobbies)
.setter(Person::setHobbies))
.addAttribute(EnhancedType.mapOf(
EnhancedType.of(String.class),
// 1. Use mapping functionality of the Address table schema.
EnhancedType.documentOf(Address.class, TABLE_SCHEMA_ADDRESS)), a -> a.name("addresses")
.getter(Person::getAddresses)
.setter(Person::setAddresses))
.addAttribute(EnhancedType.listOf(
// 2. Use mapping functionality of the PhoneNumber table schema.
EnhancedType.documentOf(PhoneNumber.class, TABLE_SCHEMA_PHONENUMBER)), a -> a.name("phoneNumbers")
.getter(Person::getPhoneNumbers)
.setter(Person::setPhoneNumbers))
.build();
```
## Project attributes of complex types
For `query()` and `scan()` methods, you can specify which attributes you want to be returned in the results by using method calls such as `addNestedAttributeToProject()` and `attributesToProject()`. The DynamoDB Enhanced Client API converts the Java method call parameters into [projection expressions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html) before the request is sent.
The following example populates the `Person` table with two items, then performs three scan operations.
The first scan accesses all items in the table in order to compare the results to the other scan operations.
The second scan uses the [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/ScanEnhancedRequest.Builder.html#addNestedAttributeToProject(software.amazon.awssdk.enhanced.dynamodb.NestedAttributeName)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/ScanEnhancedRequest.Builder.html#addNestedAttributeToProject(software.amazon.awssdk.enhanced.dynamodb.NestedAttributeName)) builder method to return only the `street` attribute value.
The third scan operation uses the [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/ScanEnhancedRequest.Builder.html#attributesToProject(java.lang.String...)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/ScanEnhancedRequest.Builder.html#attributesToProject(java.lang.String...)) builder method to return the data for the first-level attribute, `hobbies`. The attribute type of `hobbies` is a list. To access individual list items, perform a `get()` operation on the list.
```
personDynamoDbTable = getDynamoDbEnhancedClient().table("Person", PERSON_TABLE_SCHEMA);
PersonUtils.createPersonTable(personDynamoDbTable, getDynamoDbClient());
// Use a utility class to add items to the Person table.
List personList = PersonUtils.getItemsForCount(2);
// This utility method performs a put against DynamoDB to save the instances in the list argument.
PersonUtils.putCollection(getDynamoDbEnhancedClient(), personList, personDynamoDbTable);
// The first scan logs all items in the table to compare to the results of the subsequent scans.
final PageIterable allItems = personDynamoDbTable.scan();
allItems.items().forEach(p ->
// 1. Log what is in the table.
logger.info(p.toString()));
// Scan for nested attributes.
PageIterable streetScanResult = personDynamoDbTable.scan(b -> b
// Use the 'addNestedAttributeToProject()' or 'addNestedAttributesToProject()' to access data nested in maps in DynamoDB.
.addNestedAttributeToProject(
NestedAttributeName.create("addresses", "work", "street")
));
streetScanResult.items().forEach(p ->
//2. Log the results of requesting nested attributes.
logger.info(p.toString()));
// Scan for a top-level list attribute.
PageIterable hobbiesScanResult = personDynamoDbTable.scan(b -> b
// Use the 'attributesToProject()' method to access first-level attributes.
.attributesToProject("hobbies"));
hobbiesScanResult.items().forEach((p) -> {
// 3. Log the results of the request for the 'hobbies' attribute.
logger.info(p.toString());
// To access an item in a list, first get the parent attribute, 'hobbies', then access items in the list.
String hobby = p.getHobbies().get(1);
// 4. Log an item in the list.
logger.info(hobby);
});
```
```
// Logged results from comment line 1.
Person{id=2, firstName='first name 2', lastName='last name 2', age=11, addresses={work=Address{street='street 21', city='city 21', state='state 21', zipCode='33333'}, home=Address{street='street 2', city='city 2', state='state 2', zipCode='22222'}}, phoneNumbers=[PhoneNumber{type='home', number='222-222-2222'}, PhoneNumber{type='work', number='333-333-3333'}], hobbies=[hobby 2, hobby 21]}
Person{id=1, firstName='first name 1', lastName='last name 1', age=11, addresses={work=Address{street='street 11', city='city 11', state='state 11', zipCode='22222'}, home=Address{street='street 1', city='city 1', state='state 1', zipCode='11111'}}, phoneNumbers=[PhoneNumber{type='home', number='111-111-1111'}, PhoneNumber{type='work', number='222-222-2222'}], hobbies=[hobby 1, hobby 11]}
// Logged results from comment line 2.
Person{id=null, firstName='null', lastName='null', age=null, addresses={work=Address{street='street 21', city='null', state='null', zipCode='null'}}, phoneNumbers=null, hobbies=null}
Person{id=null, firstName='null', lastName='null', age=null, addresses={work=Address{street='street 11', city='null', state='null', zipCode='null'}}, phoneNumbers=null, hobbies=null}
// Logged results from comment lines 3 and 4.
Person{id=null, firstName='null', lastName='null', age=null, addresses=null, phoneNumbers=null, hobbies=[hobby 2, hobby 21]}
hobby 21
Person{id=null, firstName='null', lastName='null', age=null, addresses=null, phoneNumbers=null, hobbies=[hobby 1, hobby 11]}
hobby 11
```
**Note**
If the `attributesToProject()` method follows any other builder method that adds attributes that you want to project, the list of attribute names supplied to the `attributesToProject()` replaces all other attribute names.
A scan performed with the `ScanEnhancedRequest` instance in the following snippet returns only hobby data.
```
ScanEnhancedRequest lastOverwrites = ScanEnhancedRequest.builder()
.addNestedAttributeToProject(
NestedAttributeName.create("addresses", "work", "street"))
.addAttributeToProject("firstName")
// If the 'attributesToProject()' method follows other builder methods that add attributes for projection,
// its list of attributes replace all previous attributes.
.attributesToProject("hobbies")
.build();
PageIterable hobbiesOnlyResult = personDynamoDbTable.scan(lastOverwrites);
hobbiesOnlyResult.items().forEach(p ->
logger.info(p.toString()));
// Logged results.
Person{id=null, firstName='null', lastName='null', age=null, addresses=null, phoneNumbers=null, hobbies=[hobby 2, hobby 21]}
Person{id=null, firstName='null', lastName='null', age=null, addresses=null, phoneNumbers=null, hobbies=[hobby 1, hobby 11]}
```
The following code snippet uses the `attributesToProject()` method first. This ordering preserves all other requested attributes.
```
ScanEnhancedRequest attributesPreserved = ScanEnhancedRequest.builder()
// Use 'attributesToProject()' first so that the method call does not replace all other attributes
// that you want to project.
.attributesToProject("firstName")
.addNestedAttributeToProject(
NestedAttributeName.create("addresses", "work", "street"))
.addAttributeToProject("hobbies")
.build();
PageIterable allAttributesResult = personDynamoDbTable.scan(attributesPreserved);
allAttributesResult.items().forEach(p ->
logger.info(p.toString()));
// Logged results.
Person{id=null, firstName='first name 2', lastName='null', age=null, addresses={work=Address{street='street 21', city='null', state='null', zipCode='null'}}, phoneNumbers=null, hobbies=[hobby 2, hobby 21]}
Person{id=null, firstName='first name 1', lastName='null', age=null, addresses={work=Address{street='street 11', city='null', state='null', zipCode='null'}}, phoneNumbers=null, hobbies=[hobby 1, hobby 11]}
```
## Use complex types in expressions
You can use complex types in expressions, such as filter expressions and condition expressions, by using dereferencing operators to navigate the structure of the complex type. For objects and maps, use the `. (dot)` and for list elements use `[n]` (square brackets around the sequence number of the element). You can't refer to individual elements of a set, but you can use the [`contains` function](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions).
The following example show two filter expressions that are used in scan operations. The filter expressions specify the match conditions for items you want in the results. The example uses `Person`, `Address`, and `PhoneNumber` classes shown previously.
```
public void scanUsingFilterOfNestedAttr() {
// The following is a filter expression for an attribute that is a map of Address objects.
// By using this filter expression, the SDK returns Person objects that have an address
// with 'mailing' as a key and 'MS2' for a state value.
Expression addressFilter = Expression.builder()
.expression("addresses.#type.#field = :value")
.putExpressionName("#type", "mailing")
.putExpressionName("#field", "state")
.putExpressionValue(":value", AttributeValue.builder().s("MS2").build())
.build();
PageIterable addressFilterResults = personDynamoDbTable.scan(rb -> rb.
filterExpression(addressFilter));
addressFilterResults.items().stream().forEach(p -> logger.info("Person: {}", p));
assert addressFilterResults.items().stream().count() == 1;
// The following is a filter expression for an attribute that is a list of phone numbers.
// By using this filter expression, the SDK returns Person objects whose second phone number
// in the list has a type equal to 'cell'.
Expression phoneFilter = Expression.builder()
.expression("phoneNumbers[1].#type = :type")
.putExpressionName("#type", "type")
.putExpressionValue(":type", AttributeValue.builder().s("cell").build())
.build();
PageIterable phoneFilterResults = personDynamoDbTable.scan(rb -> rb
.filterExpression(phoneFilter)
.attributesToProject("id", "firstName", "lastName", "phoneNumbers")
);
phoneFilterResults.items().stream().forEach(p -> logger.info("Person: {}", p));
assert phoneFilterResults.items().stream().count() == 1;
assert phoneFilterResults.items().stream().findFirst().get().getPhoneNumbers().get(1).getType().equals("cell");
}
```
### Helper method that populates the table
```
public static void populateDatabase() {
Person person1 = new Person();
person1.setId(1);
person1.setFirstName("FirstName1");
person1.setLastName("LastName1");
Address billingAddr1 = new Address();
billingAddr1.setState("BS1");
billingAddr1.setCity("BillingTown1");
Address mailing1 = new Address();
mailing1.setState("MS1");
mailing1.setCity("MailingTown1");
person1.setAddresses(Map.of("billing", billingAddr1, "mailing", mailing1));
PhoneNumber pn1_1 = new PhoneNumber();
pn1_1.setType("work");
pn1_1.setNumber("111-111-1111");
PhoneNumber pn1_2 = new PhoneNumber();
pn1_2.setType("home");
pn1_2.setNumber("222-222-2222");
List phoneNumbers1 = List.of(pn1_1, pn1_2);
person1.setPhoneNumbers(phoneNumbers1);
personDynamoDbTable.putItem(person1);
Person person2 = person1;
person2.setId(2);
person2.setFirstName("FirstName2");
person2.setLastName("LastName2");
Address billingAddress2 = billingAddr1;
billingAddress2.setCity("BillingTown2");
billingAddress2.setState("BS2");
Address mailing2 = mailing1;
mailing2.setCity("MailingTown2");
mailing2.setState("MS2");
person2.setAddresses(Map.of("billing", billingAddress2, "mailing", mailing2));
PhoneNumber pn2_1 = new PhoneNumber();
pn2_1.setType("work");
pn2_1.setNumber("333-333-3333");
PhoneNumber pn2_2 = new PhoneNumber();
pn2_2.setType("cell");
pn2_2.setNumber("444-444-4444");
List phoneNumbers2 = List.of(pn2_1, pn2_2);
person2.setPhoneNumbers(phoneNumbers2);
personDynamoDbTable.putItem(person2);
}
```
### JSON representation of items in the database
```
{
"id": 1,
"addresses": {
"billing": {
"city": "BillingTown1",
"state": "BS1",
"street": null,
"zipCode": null
},
"mailing": {
"city": "MailingTown1",
"state": "MS1",
"street": null,
"zipCode": null
}
},
"firstName": "FirstName1",
"lastName": "LastName1",
"phoneNumbers": [
{
"number": "111-111-1111",
"type": "work"
},
{
"number": "222-222-2222",
"type": "home"
}
]
}
{
"id": 2,
"addresses": {
"billing": {
"city": "BillingTown2",
"state": "BS2",
"street": null,
"zipCode": null
},
"mailing": {
"city": "MailingTown2",
"state": "MS2",
"street": null,
"zipCode": null
}
},
"firstName": "FirstName2",
"lastName": "LastName2",
"phoneNumbers": [
{
"number": "333-333-3333",
"type": "work"
},
{
"number": "444-444-4444",
"type": "cell"
}
]
}
```
## Update items that contain complex types
To update an item that contains complex types, you have two basic approaches:
+ Approach 1: First retrieve the item (by using `getItem`), update the object, then call `DynamoDbTable#updateItem`.
+ Approach 2: Don't retrieve the item, but construct a new instance, set the properties you want to update, and submit the instance to `DynamoDbTable#updateItem` by setting the appropriate value of [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/IgnoreNullsMode.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/IgnoreNullsMode.html) . This approach does not require that you fetch the item before updating it.
The examples shown in this section use the `Person`, `Address`, and `PhoneNumber` classes shown previously.
### Update approach 1: retrieve, then update
By using this approach, you ensure that no data is lost on update. The DynamoDB Enhanced Client API recreates the bean with the attributes from the item saved in DynamoDB including values of complex types. You then need to use the getters and setters to update the bean. The downside of this approach is the cost you incur retrieving the item first.
The following example demonstrates that no data is lost if you first retrieve the item before updating it.
```
public void retrieveThenUpdateExample() {
// Assume that we ran this code yesterday.
Person person = new Person();
person.setId(1);
person.setFirstName("FirstName");
person.setLastName("LastName");
Address mainAddress = new Address();
mainAddress.setStreet("123 MyStreet");
mainAddress.setCity("MyCity");
mainAddress.setState("MyState");
mainAddress.setZipCode("MyZipCode");
person.setMainAddress(mainAddress);
PhoneNumber homePhone = new PhoneNumber();
homePhone.setNumber("1111111");
homePhone.setType("HOME");
person.setPhoneNumbers(List.of(homePhone));
personDynamoDbTable.putItem(person);
// Assume that we are running this code now.
// First, retrieve the item
Person retrievedPerson = personDynamoDbTable.getItem(Key.builder().partitionValue(1).build());
// Make any updates.
retrievedPerson.getMainAddress().setCity("YourCity");
// Save the updated bean. 'updateItem' returns the bean as it appears after the update.
Person updatedPerson = personDynamoDbTable.updateItem(retrievedPerson);
// Verify for this example.
Address updatedMainAddress = updatedPerson.getMainAddress();
assert updatedMainAddress.getCity().equals("YourCity");
assert updatedMainAddress.getState().equals("MyState"); // Unchanged.
// The list of phone numbers remains; it was not set to null;
assert updatedPerson.getPhoneNumbers().size() == 1;
}
```
### Update approach 2: Use an `IgnoreNullsMode` enum without retrieving the item first
To update an item in DynamoDB, you can provide a new object that has only the properties that you want updated and leave the other values as null. With this approach, you need to be aware of how null values in the object are treated by the SDK and how you can control the behavior.
To specify which null-valued properties you want the SDK to ignore, provide an `IgnoreNullsMode` enum when you build the [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/UpdateItemEnhancedRequest.Builder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/UpdateItemEnhancedRequest.Builder.html). As an example of using one of the enumerated values, the following snippet uses the `IgnoreNullsMode.SCALAR_ONLY` mode.
```
// Create a new Person object to update the existing item in DynamoDB.
Person personForUpdate = new Person();
personForUpdate.setId(1);
personForUpdate.setFirstName("updatedFirstName"); // 'firstName' is a top scalar property.
Address addressForUpdate = new Address();
addressForUpdate.setCity("updatedCity");
personForUpdate.setMainAddress(addressForUpdate);
personDynamoDbTable.updateItem(r -> r
.item(personForUpdate)
.ignoreNullsMode(IgnoreNullsMode.SCALAR_ONLY));
/* With IgnoreNullsMode.SCALAR_ONLY provided, The SDK ignores all null properties. The SDK adds or replaces
the 'firstName' property with the provided value, "updatedFirstName". The SDK updates the 'city' value of
'mainAddress', as long as the 'mainAddress' attribute already exists in DynamoDB.
In the background, the SDK generates an update expression that it sends in the request to DynamoDB.
The following JSON object is a simplified version of what it sends. Notice that the SDK includes the paths
to 'mainAddress.city' and 'firstName' in the SET clause of the update expression. No null values in
'personForUpdate' are included.
{
"TableName": "PersonTable",
"Key": {
"id": {
"N": "1"
}
},
"ReturnValues": "ALL_NEW",
"UpdateExpression": "SET #mainAddress.#city = :mainAddress_city, #firstName = :firstName",
"ExpressionAttributeNames": {
"#city": "city",
"#firstName": "firstName",
"#mainAddress": "mainAddress"
},
"ExpressionAttributeValues": {
":firstName": {
"S": "updatedFirstName"
},
":mainAddress_city": {
"S": "updatedCity"
}
}
}
Had we chosen 'IgnoreNullsMode.DEFAULT' instead of 'IgnoreNullsMode.SCALAR_ONLY', the SDK would have included
null values in the "ExpressionAttributeValues" section of the request as shown in the following snippet.
"ExpressionAttributeValues": {
":mainAddress": {
"M": {
"zipCode": {
"NULL": true
},
"city": {
"S": "updatedCity"
},
"street": {
"NULL": true
},
"state": {
"NULL": true
}
}
},
":firstName": {
"S": "updatedFirstName"
}
}
*/
```
The Amazon DynamoDB Developer Guide contains more information about [update expressions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html).
#### Descriptions of the `IgnoreNullsMode` options
+ `IgnoreNullsMode.SCALAR_ONLY` - Use this setting to update scalar attributes at any level. The SDK constructs an update statement that sends only non-null, scalar attributes to DynamoDB. The SDK ignores null-valued, scalar attributes of a bean or map, retaining the saved value in DynamoDB.
When you update a scalar attribute of map or bean, the map must already exists in DynamoDB. If you add a map or a bean to the object that does not already exist for the object in DynamoDB, you get a `DynamoDbException` with the message *The document path provided in the update expression is invalid for update*. You must use `MAPS_ONLY` mode to add a bean or map to DynamoDB before you update any of its attributes.
+ `IgnoreNullsMode.MAPS_ONLY` - Use this setting to add or replace properties that are a bean or a map. The SDK replaces or adds any map or bean provided in the object. Any beans or maps that are null in the object are ignored, retaining the map that exists in DynamoDB.
+ `IgnoreNullsMode.DEFAULT` - With this setting, the SDK never ignores null values. Scalar attributes at any level that are null are updated to null. The SDK updates any null-valued bean, map, list, or set property in the object to null in DynamoDB. When you use this mode—or don't provide a mode since it's the default mode—you should retrieve the item first so that values in DynamoDB are not set to null that are provided in the object for updating, unless your intention is to set the values to null.
In all modes, if you provide an object to `updateItem` that has a non-null list or set, the list or set is saved to DynamoDB.
#### Why the modes?
When you provide an object with a bean or map to the `updateItem` method, the SDK can't tell if it should use the property values in the bean (or entry values in the map) to update the item, or if the entire bean/map should replace what's been saved to DynamoDB.
Working from our previous example that shows the retrieval of the item first, let's attempt to update the `city` attribute of `mainAddress` without the retrieval.
```
/* The retrieval example saved the Person object with a 'mainAddress' property whose 'city' property value is "MyCity".
/* Note that we create a new Person with only the necessary information to update the city value
of the mainAddress. */
Person personForUpdate = new Person();
personForUpdate.setId(1);
// The update we want to make changes the city.
Address mainAddressForUpdate = new Address();
mainAddressForUpdate.setCity("YourCity");
personForUpdate.setMainAddress(mainAddressForUpdate);
// Lets' try the following:
Person updatedPerson = personDynamoDbTable.updateItem(personForUpdate);
/*
Since we haven't retrieved the item, we don't know if the 'mainAddress' property
already exists, so what update expression should the SDK generate?
A) Should it replace or add the 'mainAddress' with the provided object (setting all attributes to null other than city)
as shown in the following simplified JSON?
{
"TableName": "PersonTable",
"Key": {
"id": {
"N": "1"
}
},
"ReturnValues": "ALL_NEW",
"UpdateExpression": "SET #mainAddress = :mainAddress",
"ExpressionAttributeNames": {
"#mainAddress": "mainAddress"
},
"ExpressionAttributeValues": {
":mainAddress": {
"M": {
"zipCode": {
"NULL": true
},
"city": {
"S": "YourCity"
},
"street": {
"NULL": true
},
"state": {
"NULL": true
}
}
}
}
}
B) Or should it update only the 'city' attribute of an existing 'mainAddress' as shown in the following simplified JSON?
{
"TableName": "PersonTable",
"Key": {
"id": {
"N": "1"
}
},
"ReturnValues": "ALL_NEW",
"UpdateExpression": "SET #mainAddress.#city = :mainAddress_city",
"ExpressionAttributeNames": {
"#city": "city",
"#mainAddress": "mainAddress"
},
"ExpressionAttributeValues": {
":mainAddress_city": {
"S": "YourCity"
}
}
}
However, assume that we don't know if the 'mainAddress' already exists. If it doesn't exist, the SDK would try to update
an attribute of a non-existent map, which results in an exception.
In this particular case, we would likely select option B (SCALAR_ONLY) to retain the other values of the 'mainAddress'.
*/
```
The following two examples show uses of the `MAPS_ONLY` and `SCALAR_ONLY` enumerated values. `MAPS_ONLY` adds a map and `SCALAR_ONLY` updates a map.
##### `IgnoreNullsMode.MAPS_ONLY` example
```
public void mapsOnlyModeExample() {
// Assume that we ran this code yesterday.
Person person = new Person();
person.setId(1);
person.setFirstName("FirstName");
personDynamoDbTable.putItem(person);
// Assume that we are running this code now.
/* Note that we create a new Person with only the necessary information to update the city value
of the mainAddress. */
Person personForUpdate = new Person();
personForUpdate.setId(1);
// The update we want to make changes the city.
Address mainAddressForUpdate = new Address();
mainAddressForUpdate.setCity("YourCity");
personForUpdate.setMainAddress(mainAddressForUpdate);
Person updatedPerson = personDynamoDbTable.updateItem(r -> r
.item(personForUpdate)
.ignoreNullsMode(IgnoreNullsMode.MAPS_ONLY)); // Since the mainAddress property does not exist, use MAPS_ONLY mode.
assert updatedPerson.getMainAddress().getCity().equals("YourCity");
assert updatedPerson.getMainAddress().getState() == null;
}
```
##### `IgnoreNullsMode.SCALAR_ONLY example`
```
public void scalarOnlyExample() {
// Assume that we ran this code yesterday.
Person person = new Person();
person.setId(1);
Address mainAddress = new Address();
mainAddress.setCity("MyCity");
mainAddress.setState("MyState");
person.setMainAddress(mainAddress);
personDynamoDbTable.putItem(person);
// Assume that we are running this code now.
/* Note that we create a new Person with only the necessary information to update the city value
of the mainAddress. */
Person personForUpdate = new Person();
personForUpdate.setId(1);
// The update we want to make changes the city.
Address mainAddressForUpdate = new Address();
mainAddressForUpdate.setCity("YourCity");
personForUpdate.setMainAddress(mainAddressForUpdate);
Person updatedPerson = personDynamoDbTable.updateItem(r -> r
.item(personForUpdate)
.ignoreNullsMode(IgnoreNullsMode.SCALAR_ONLY)); // SCALAR_ONLY mode ignores null properties in the in mainAddress.
assert updatedPerson.getMainAddress().getCity().equals("YourCity");
assert updatedPerson.getMainAddress().getState().equals("MyState"); // The state property remains the same.
}
```
Refer to the following table to see which null values are ignored for each mode. You can often work with either `SCALAR_ONLY` and `MAPS_ONLY` except when you work with beans or maps.
**Which null-valued properties in the object submitted to `updateItem` does the SDK ignore for each mode?**
| Type of property | in SCALAR\$1ONLY mode | in MAPS\$1ONLY mode | in DEFAULT mode |
| --- | --- | --- | --- |
| Top scalar | Yes | Yes | No |
| Bean or map | Yes | Yes | No |
| Scalar value of a bean or map entry | Yes1 | No2 | No |
| List or set | Yes | Yes | No |
1This assumes the map already exists in DynamoDB. Any scalar value—null or not null—of the bean or map that you provide in the object for update requires that a path to the value exists in DynamoDB. The SDK constructs a path to the attribute by using the `. (dot)` dereference operator before it submits the request.
2Since you use `MAPS_ONLY` mode to fully replace or to add a bean or map, all null values in the bean or map are retained in the map saved to DynamoDB.
# Preserve empty objects with `@DynamoDbPreserveEmptyObject`
If you save a bean to Amazon DynamoDB with empty objects and you want the SDK to recreate the empty objects upon retrieval, annotate the getter of the inner bean with `@DynamoDbPreserveEmptyObject`.
To illustrate how the annotation works, the code example uses the following two beans.
## Example beans
The following data class contains two `InnerBean` fields. The getter method, `getInnerBeanWithoutAnno()`, is not annotated with `@DynamoDbPreserveEmptyObject`. The `getInnerBeanWithAnno()` method is annotated.
```
@DynamoDbBean
public class MyBean {
private String id;
private String name;
private InnerBean innerBeanWithoutAnno;
private InnerBean innerBeanWithAnno;
@DynamoDbPartitionKey
public String getId() { return id; }
public void setId(String id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public InnerBean getInnerBeanWithoutAnno() { return innerBeanWithoutAnno; }
public void setInnerBeanWithoutAnno(InnerBean innerBeanWithoutAnno) { this.innerBeanWithoutAnno = innerBeanWithoutAnno; }
@DynamoDbPreserveEmptyObject
public InnerBean getInnerBeanWithAnno() { return innerBeanWithAnno; }
public void setInnerBeanWithAnno(InnerBean innerBeanWithAnno) { this.innerBeanWithAnno = innerBeanWithAnno; }
@Override
public String toString() {
return new StringJoiner(", ", MyBean.class.getSimpleName() + "[", "]")
.add("innerBeanWithoutAnno=" + innerBeanWithoutAnno)
.add("innerBeanWithAnno=" + innerBeanWithAnno)
.add("id='" + id + "'")
.add("name='" + name + "'")
.toString();
}
}
```
Instances of the following `InnerBean` class are fields of `MyBean` and are initialized as empty objects in the example code.
```
@DynamoDbBean
public class InnerBean {
private String innerBeanField;
public String getInnerBeanField() {
return innerBeanField;
}
public void setInnerBeanField(String innerBeanField) {
this.innerBeanField = innerBeanField;
}
@Override
public String toString() {
return "InnerBean{" +
"innerBeanField='" + innerBeanField + '\'' +
'}';
}
}
```
The following code example saves a `MyBean` object with initialized inner beans to DynamoDB and then retrieves the item. The logged output shows that the `innerBeanWithoutAnno` is not initialized, but `innerBeanWithAnno` has been created.
```
public MyBean preserveEmptyObjectAnnoUsingGetItemExample(DynamoDbTable myBeanTable) {
// Save an item to DynamoDB.
MyBean bean = new MyBean();
bean.setId("1");
bean.setInnerBeanWithoutAnno(new InnerBean()); // Instantiate the inner bean.
bean.setInnerBeanWithAnno(new InnerBean()); // Instantiate the inner bean.
myBeanTable.putItem(bean);
GetItemEnhancedRequest request = GetItemEnhancedRequest.builder()
.key(Key.builder().partitionValue("1").build())
.build();
MyBean myBean = myBeanTable.getItem(request);
logger.info(myBean.toString());
// Output 'MyBean[innerBeanWithoutAnno=null, innerBeanWithAnno=InnerBean{innerBeanField='null'}, id='1', name='null']'.
return myBean;
}
```
## Alternative static schema
You can use the following `StaticTableSchema` version of the table schemas in place of the annotations on the beans.
```
public static TableSchema buildStaticSchemas() {
StaticTableSchema innerBeanStaticTableSchema =
StaticTableSchema.builder(InnerBean.class)
.newItemSupplier(InnerBean::new)
.addAttribute(String.class, a -> a.name("innerBeanField")
.getter(InnerBean::getInnerBeanField)
.setter(InnerBean::setInnerBeanField))
.build();
return StaticTableSchema.builder(MyBean.class)
.newItemSupplier(MyBean::new)
.addAttribute(String.class, a -> a.name("id")
.getter(MyBean::getId)
.setter(MyBean::setId)
.addTag(primaryPartitionKey()))
.addAttribute(String.class, a -> a.name("name")
.getter(MyBean::getName)
.setter(MyBean::setName))
.addAttribute(EnhancedType.documentOf(InnerBean.class,
innerBeanStaticTableSchema),
a -> a.name("innerBean1")
.getter(MyBean::getInnerBeanWithoutAnno)
.setter(MyBean::setInnerBeanWithoutAnno))
.addAttribute(EnhancedType.documentOf(InnerBean.class,
innerBeanStaticTableSchema,
b -> b.preserveEmptyObject(true)),
a -> a.name("innerBean2")
.getter(MyBean::getInnerBeanWithAnno)
.setter(MyBean::setInnerBeanWithAnno))
.build();
}
```
# Avoid saving null attributes of nested objects
You can skip null attributes of nested objects when saving a data class object to DynamoDB by applying the `@DynamoDbIgnoreNulls` annotation. By contrast, top-level attributes with null values are never saved to the database.
To illustrate how the annotation works, the code example uses the following two beans.
## Example beans
The following data class contains two `InnerBean` fields. The getter method, `getInnerBeanWithoutAnno()`, is not annotated. The `getInnerBeanWithIgnoreNullsAnno()` method is annotated with `@DynamoDbIgnoreNulls`.
```
@DynamoDbBean
public class MyBean {
private String id;
private String name;
private InnerBean innerBeanWithoutAnno;
private InnerBean innerBeanWithIgnoreNullsAnno;
@DynamoDbPartitionKey
public String getId() { return id; }
public void setId(String id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public InnerBean getInnerBeanWithoutAnno() { return innerBeanWithoutAnno; }
public void setInnerBeanWithoutAnno(InnerBean innerBeanWithoutAnno) { this.innerBeanWithoutAnno = innerBeanWithoutAnno; }
@DynamoDbIgnoreNulls
public InnerBean getInnerBeanWithIgnoreNullsAnno() { return innerBeanWithIgnoreNullsAnno; }
public void setInnerBeanWithIgnoreNullsAnno(InnerBean innerBeanWithAnno) { this.innerBeanWithIgnoreNullsAnno = innerBeanWithAnno; }
@Override
public String toString() {
return new StringJoiner(", ", MyBean.class.getSimpleName() + "[", "]")
.add("innerBeanWithoutAnno=" + innerBeanWithoutAnno)
.add("innerBeanWithIgnoreNullsAnno=" + innerBeanWithIgnoreNullsAnno)
.add("id='" + id + "'")
.add("name='" + name + "'")
.toString();
}
}
```
Instances of the following `InnerBean` class are fields of `MyBean` and are used in the following example code.
```
@DynamoDbBean
public class InnerBean {
private String innerBeanFieldString;
private Integer innerBeanFieldInteger;
public String getInnerBeanFieldString() { return innerBeanFieldString; }
public void setInnerBeanFieldString(String innerBeanFieldString) { this.innerBeanFieldString = innerBeanFieldString; }
public Integer getInnerBeanFieldInteger() { return innerBeanFieldInteger; }
public void setInnerBeanFieldInteger(Integer innerBeanFieldInteger) { this.innerBeanFieldInteger = innerBeanFieldInteger; }
@Override
public String toString() {
return new StringJoiner(", ", InnerBean.class.getSimpleName() + "[", "]")
.add("innerBeanFieldString='" + innerBeanFieldString + "'")
.add("innerBeanFieldInteger=" + innerBeanFieldInteger)
.toString();
}
}
```
The following code example creates an `InnerBean` object and sets only one of its two attributes with a value.
```
public void ignoreNullsAnnoUsingPutItemExample(DynamoDbTable myBeanTable) {
// Create an InnerBean object and give only one attribute a value.
InnerBean innerBeanOneAttributeSet = new InnerBean();
innerBeanOneAttributeSet.setInnerBeanFieldInteger(200);
// Create a MyBean instance and use the same InnerBean instance both for attributes.
MyBean bean = new MyBean();
bean.setId("1");
bean.setInnerBeanWithoutAnno(innerBeanOneAttributeSet);
bean.setInnerBeanWithIgnoreNullsAnno(innerBeanOneAttributeSet);
Map itemMap = myBeanTable.tableSchema().itemToMap(bean, true);
logger.info(itemMap.toString());
// Log the map that is sent to the database.
// {innerBeanWithIgnoreNullsAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200)}), id=AttributeValue(S=1), innerBeanWithoutAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200), innerBeanFieldString=AttributeValue(NUL=true)})}
// Save the MyBean object to the table.
myBeanTable.putItem(bean);
}
```
To visualize the low-level data that is sent to DynamoDB, the code logs the attribute map before saving the `MyBean` object.
The logged output shows that the `innerBeanWithIgnoreNullsAnno` outputs one attribute,
```
innerBeanWithIgnoreNullsAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200)})
```
The `innerBeanWithoutAnno` instance outputs two attributes. One attribute has a value of 200 and the other is a null-valued attribute.
```
innerBeanWithoutAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200), innerBeanFieldString=AttributeValue(NUL=true)})
```
## JSON representation of the attribute map
The following JSON representation makes it easier to see the data that is saved to DynamoDB.
```
{
"id": {
"S": "1"
},
"innerBeanWithIgnoreNullsAnno": {
"M": {
"innerBeanFieldInteger": {
"N": "200"
}
}
},
"innerBeanWithoutAnno": {
"M": {
"innerBeanFieldInteger": {
"N": "200"
},
"innerBeanFieldString": {
"NULL": true
}
}
}
}
```
## Alternative static schema
You can use the following `StaticTableSchema` version of the table schemas in place data class annotations.
```
public static TableSchema buildStaticSchemas() {
StaticTableSchema innerBeanStaticTableSchema =
StaticTableSchema.builder(InnerBean.class)
.newItemSupplier(InnerBean::new)
.addAttribute(String.class, a -> a.name("innerBeanFieldString")
.getter(InnerBean::getInnerBeanFieldString)
.setter(InnerBean::setInnerBeanFieldString))
.addAttribute(Integer.class, a -> a.name("innerBeanFieldInteger")
.getter(InnerBean::getInnerBeanFieldInteger)
.setter(InnerBean::setInnerBeanFieldInteger))
.build();
return StaticTableSchema.builder(MyBean.class)
.newItemSupplier(MyBean::new)
.addAttribute(String.class, a -> a.name("id")
.getter(MyBean::getId)
.setter(MyBean::setId)
.addTag(primaryPartitionKey()))
.addAttribute(String.class, a -> a.name("name")
.getter(MyBean::getName)
.setter(MyBean::setName))
.addAttribute(EnhancedType.documentOf(InnerBean.class,
innerBeanStaticTableSchema),
a -> a.name("innerBeanWithoutAnno")
.getter(MyBean::getInnerBeanWithoutAnno)
.setter(MyBean::setInnerBeanWithoutAnno))
.addAttribute(EnhancedType.documentOf(InnerBean.class,
innerBeanStaticTableSchema,
b -> b.ignoreNulls(true)),
a -> a.name("innerBeanWithIgnoreNullsAnno")
.getter(MyBean::getInnerBeanWithIgnoreNullsAnno)
.setter(MyBean::setInnerBeanWithIgnoreNullsAnno))
.build();
}
```
# Work with JSON documents with the Enhanced Document API for DynamoDB
The [Enhanced Document API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/package-summary.html) for AWS SDK for Java 2.x is designed to work with document-oriented data that has no fixed schema. However, it also lets you use custom classes to map individual attributes.
The Enhanced Document API is the successor to the [Document API](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/DynamoDB.html) of the AWS SDK for Java v1.x.
**Contents**
+ [Get started using the Enhanced Document API](ddb-en-client-doc-api-steps.md)
+ [Create a `DocumentTableSchema` and a `DynamoDbTable`](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema)
+ [Build enhanced documents](ddb-en-client-doc-api-steps-create-ed.md)
+ [Build from a JSON string](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromJson)
+ [Build from individual elements](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts)
+ [Perform CRUD operations](ddb-en-client-doc-api-steps-use.md)
+ [Access enhanced document attributes as custom objects](ddb-en-client-doc-api-convert.md)
+ [Use an `EnhancedDocument` without DynamoDB](ddb-en-client-doc-api-standalone.md)
# Get started using the Enhanced Document API
The Enhanced Document API requires the same [dependencies](ddb-en-client-getting-started.md#ddb-en-client-gs-dep) that are needed for the DynamoDB Enhanced Client API. It also requires a [`DynamoDbEnhancedClient` instance](ddb-en-client-getting-started-dynamodbTable.md#ddb-en-client-getting-started-dynamodbTable-eclient) as shown at the start of this topic.
Because the Enhanced Document API was released with version 2.20.3 of the AWS SDK for Java 2.x, you need that version or greater.
## Create a `DocumentTableSchema` and a `DynamoDbTable`
To invoke commands against a DynamoDB table using the Enhanced Document API, associate the table with a client-side [DynamoDbTable](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html) resource object.
The enhanced client's `table()` method creates a `DynamoDbTable` instance and requires parameters for the DynamoDB table name and a `DocumentTableSchema`.
The builder for a [DocumentTableSchema](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/DocumentTableSchema.html) requires a primary index key and one or more attribute converter providers. The `AttributeConverterProvider.defaultProvider()` method provides converters for [default types](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/internal/converter/attribute/package-summary.html). It should be specified even if you provide a custom attribute converter provider. You can add an optional secondary index key to the builder.
The following code snippet shows the code that generates the client-side representation of a DynamoDB `person` table that stores schemaless `EnhancedDocument` objects.
```
DynamoDbTable documentDynamoDbTable =
enhancedClient.table("person",
TableSchema.documentSchemaBuilder()
// Specify the primary key attributes.
.addIndexPartitionKey(TableMetadata.primaryIndexName(),"id", AttributeValueType.S)
.addIndexSortKey(TableMetadata.primaryIndexName(), "lastName", AttributeValueType.S)
// Specify attribute converter providers. Minimally add the default one.
.attributeConverterProviders(AttributeConverterProvider.defaultProvider())
.build());
// Call documentTable.createTable() if "person" does not exist in DynamoDB.
// createTable() should be called only one time.
```
The following shows the JSON representation of a `person` object that is used throughout this section.
### JSON `person` object
```
{
"id": 1,
"firstName": "Richard",
"lastName": "Roe",
"age": 25,
"addresses":
{
"home": {
"zipCode": "00000",
"city": "Any Town",
"state": "FL",
"street": "123 Any Street"
},
"work": {
"zipCode": "00001",
"city": "Anywhere",
"state": "FL",
"street": "100 Main Street"
}
},
"hobbies": [
"Hobby 1",
"Hobby 2"
],
"phoneNumbers": [
{
"type": "Home",
"number": "555-0100"
},
{
"type": "Work",
"number": "555-0119"
}
]
}
```
# Build enhanced documents
An `[EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html)` represents a document-type object that has complex structure with nested attributes. An `EnhancedDocument` requires top-level attributes that match the primary key attributes specified for the `DocumentTableSchema`. The remaining content is arbitrary and can consist of top-level attributes and also deeply nested attributes.
You create an `EnhancedDocument` instance by using a builder that provides several ways to add elements.
## Build from a JSON string
With a JSON string, you can build an `EnhancedDocument` in one method call. The following snippet creates an `EnhancedDocument` from a JSON string returned by the `jsonPerson()` helper method. The `jsonPerson()` method returns the JSON string version of the [person object](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema-obj) shown previously.
```
EnhancedDocument document =
EnhancedDocument.builder()
.json( jsonPerson() )
.build());
```
## Build from individual elements
Alternatively, you can build an `EnhancedDocument` instance from individual components using type-safe methods of the builder.
The following example builds a `person` enhanced document similar to the enhanced document that is built from the JSON string in the previous example.
```
/* Define the shape of an address map whose JSON representation looks like the following.
Use 'addressMapEnhancedType' in the following EnhancedDocument.builder() to simplify the code.
"home": {
"zipCode": "00000",
"city": "Any Town",
"state": "FL",
"street": "123 Any Street"
}*/
EnhancedType> addressMapEnhancedType =
EnhancedType.mapOf(EnhancedType.of(String.class), EnhancedType.of(String.class));
// Use the builder's typesafe methods to add elements to the enhanced document.
EnhancedDocument personDocument = EnhancedDocument.builder()
.putNumber("id", 50)
.putString("firstName", "Shirley")
.putString("lastName", "Rodriguez")
.putNumber("age", 53)
.putNull("nullAttribute")
.putJson("phoneNumbers", phoneNumbersJSONString())
/* Add the map of addresses whose JSON representation looks like the following.
{
"home": {
"zipCode": "00000",
"city": "Any Town",
"state": "FL",
"street": "123 Any Street"
}
} */
.putMap("addresses", getAddresses(), EnhancedType.of(String.class), addressMapEnhancedType)
.putList("hobbies", List.of("Theater", "Golf"), EnhancedType.of(String.class))
.build();
```
### Helper methods
```
private static String phoneNumbersJSONString() {
return " [" +
" {" +
" \"type\": \"Home\"," +
" \"number\": \"555-0140\"" +
" }," +
" {" +
" \"type\": \"Work\"," +
" \"number\": \"555-0155\"" +
" }" +
" ]";
}
private static Map> getAddresses() {
return Map.of(
"home", Map.of(
"zipCode", "00002",
"city", "Any Town",
"state", "ME",
"street", "123 Any Street"));
}
```
# Perform CRUD operations
After you define an `EnhancedDocument` instance, you can save it to a DynamoDB table. The following code snippet uses the [personDocument](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts) that was created from individual elements.
```
documentDynamoDbTable.putItem(personDocument);
```
After you read an enhanced document instance from DynamoDB, you can extract the individual attribute values using getters as shown in the following code snippet that access the data saved from the `personDocument`. Alternatively, you can extract the complete content to a JSON string as shown in the last part of the example code.
```
// Read the item.
EnhancedDocument personDocFromDb = documentDynamoDbTable.getItem(Key.builder().partitionValue(50).build());
// Access top-level attributes.
logger.info("Name: {} {}", personDocFromDb.getString("firstName"), personDocFromDb.getString("lastName"));
// Name: Shirley Rodriguez
// Typesafe access of a deeply nested attribute. The addressMapEnhancedType shown previously defines the shape of an addresses map.
Map> addresses = personDocFromDb.getMap("addresses", EnhancedType.of(String.class), addressMapEnhancedType);
addresses.keySet().forEach(k -> logger.info(addresses.get(k).toString()));
// {zipCode=00002, city=Any Town, street=123 Any Street, state=ME}
// Alternatively, work with AttributeValue types checking along the way for deeply nested attributes.
Map addressesMap = personDocFromDb.getMapOfUnknownType("addresses");
addressesMap.keySet().forEach((String k) -> {
logger.info("Looking at data for [{}] address", k);
// Looking at data for [home] address
AttributeValue value = addressesMap.get(k);
AttributeValue cityValue = value.m().get("city");
if (cityValue != null) {
logger.info(cityValue.s());
// Any Town
}
});
List phoneNumbers = personDocFromDb.getListOfUnknownType("phoneNumbers");
phoneNumbers.forEach((AttributeValue av) -> {
if (av.hasM()) {
AttributeValue type = av.m().get("type");
if (type.s() != null) {
logger.info("Type of phone: {}", type.s());
// Type of phone: Home
// Type of phone: Work
}
}
});
String jsonPerson = personDocFromDb.toJson();
logger.info(jsonPerson);
// {"firstName":"Shirley","lastName":"Rodriguez","addresses":{"home":{"zipCode":"00002","city":"Any Town","street":"123 Any Street","state":"ME"}},"hobbies":["Theater","Golf"],
// "id":50,"nullAttribute":null,"age":53,"phoneNumbers":[{"number":"555-0140","type":"Home"},{"number":"555-0155","type":"Work"}]}
```
`EnhancedDocument` instances can be used with any method of `[DynamoDbTable](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html)` or [DynamoDbEnhancedClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.html) in place of mapped data classes.
# Access enhanced document attributes as custom objects
In addition to providing an API to read and write attributes with schemaless structures, the Enhanced Document API lets you convert attributes to and from instances of custom classes.
The Enhanced Document API uses `AttributeConverterProvider`s and `AttributeConverter`s that were shown in the [control attribute conversion](ddb-en-client-adv-features-conversion.md) section as part of the DynamoDB Enhanced Client API.
In the following example, we use a `CustomAttributeConverterProvider` with its nested `AddressConverter` class to convert `Address` objects.
This example shows that you can mix data from classes and also data from structures that are built as needed. This example also shows that custom classes can be used at any level of a nested structure. The `Address` objects in this example are values used in a map.
```
public static void attributeToAddressClassMappingExample(DynamoDbEnhancedClient enhancedClient, DynamoDbClient standardClient) {
String tableName = "customer";
// Define the DynamoDbTable for an enhanced document.
// The schema builder provides methods for attribute converter providers and keys.
DynamoDbTable documentDynamoDbTable = enhancedClient.table(tableName,
DocumentTableSchema.builder()
// Add the CustomAttributeConverterProvider along with the default when you build the table schema.
.attributeConverterProviders(
List.of(
new CustomAttributeConverterProvider(),
AttributeConverterProvider.defaultProvider()))
.addIndexPartitionKey(TableMetadata.primaryIndexName(), "id", AttributeValueType.N)
.addIndexSortKey(TableMetadata.primaryIndexName(), "lastName", AttributeValueType.S)
.build());
// Create the DynamoDB table if needed.
documentDynamoDbTable.createTable();
waitForTableCreation(tableName, standardClient);
// The getAddressesForCustomMappingExample() helper method that provides 'addresses' shows the use of a custom Address class
// rather than using a Map to hold the address data.
Map addresses = getAddressesForCustomMappingExample();
// Build an EnhancedDocument instance to save an item with a mix of structures defined as needed and static classes.
EnhancedDocument personDocument = EnhancedDocument.builder()
.putNumber("id", 50)
.putString("firstName", "Shirley")
.putString("lastName", "Rodriguez")
.putNumber("age", 53)
.putNull("nullAttribute")
.putJson("phoneNumbers", phoneNumbersJSONString())
// Note the use of 'EnhancedType.of(Address.class)' instead of the more generic
// 'EnhancedType.mapOf(EnhancedType.of(String.class), EnhancedType.of(String.class))' that was used in a previous example.
.putMap("addresses", addresses, EnhancedType.of(String.class), EnhancedType.of(Address.class))
.putList("hobbies", List.of("Hobby 1", "Hobby 2"), EnhancedType.of(String.class))
.build();
// Save the item to DynamoDB.
documentDynamoDbTable.putItem(personDocument);
// Retrieve the item just saved.
EnhancedDocument srPerson = documentDynamoDbTable.getItem(Key.builder().partitionValue(50).sortValue("Rodriguez").build());
// Access the addresses attribute.
Map srAddresses = srPerson.get("addresses",
EnhancedType.mapOf(EnhancedType.of(String.class), EnhancedType.of(Address.class)));
srAddresses.keySet().forEach(k -> logger.info(addresses.get(k).toString()));
documentDynamoDbTable.deleteTable();
// The content logged to the console shows that the saved maps were converted to Address instances.
Address{street='123 Main Street', city='Any Town', state='NC', zipCode='00000'}
Address{street='100 Any Street', city='Any Town', state='NC', zipCode='00000'}
```
## `CustomAttributeConverterProvider` code
```
public class CustomAttributeConverterProvider implements AttributeConverterProvider {
private final Map, AttributeConverter> converterCache = ImmutableMap.of(
// 1. Add AddressConverter to the internal cache.
EnhancedType.of(Address.class), new AddressConverter());
public static CustomAttributeConverterProvider create() {
return new CustomAttributeConverterProvider();
}
// 2. The enhanced client queries the provider for attribute converters if it
// encounters a type that it does not know how to convert.
@SuppressWarnings("unchecked")
@Override
public AttributeConverter converterFor(EnhancedType enhancedType) {
return (AttributeConverter) converterCache.get(enhancedType);
}
// 3. Custom attribute converter
private class AddressConverter implements AttributeConverter {
// 4. Transform an Address object into a DynamoDB map.
@Override
public AttributeValue transformFrom(Address address) {
Map attributeValueMap = Map.of(
"street", AttributeValue.fromS(address.getStreet()),
"city", AttributeValue.fromS(address.getCity()),
"state", AttributeValue.fromS(address.getState()),
"zipCode", AttributeValue.fromS(address.getZipCode()));
return AttributeValue.fromM(attributeValueMap);
}
// 5. Transform the DynamoDB map attribute to an Address oject.
@Override
public Address transformTo(AttributeValue attributeValue) {
Map m = attributeValue.m();
Address address = new Address();
address.setStreet(m.get("street").s());
address.setCity(m.get("city").s());
address.setState(m.get("state").s());
address.setZipCode(m.get("zipCode").s());
return address;
}
@Override
public EnhancedType type() {
return EnhancedType.of(Address.class);
}
@Override
public AttributeValueType attributeValueType() {
return AttributeValueType.M;
}
}
}
```
## `Address` class
```
public class Address {
private String street;
private String city;
private String state;
private String zipCode;
public Address() {
}
public String getStreet() {
return this.street;
}
public String getCity() {
return this.city;
}
public String getState() {
return this.state;
}
public String getZipCode() {
return this.zipCode;
}
public void setStreet(String street) {
this.street = street;
}
public void setCity(String city) {
this.city = city;
}
public void setState(String state) {
this.state = state;
}
public void setZipCode(String zipCode) {
this.zipCode = zipCode;
}
}
```
## Helper method that provides addresses
The following helper method provides the map that use custom `Address` instances for values rather than generic `Map` instances for values.
```
private static Map getAddressesForCustomMappingExample() {
Address homeAddress = new Address();
homeAddress.setStreet("100 Any Street");
homeAddress.setCity("Any Town");
homeAddress.setState("NC");
homeAddress.setZipCode("00000");
Address workAddress = new Address();
workAddress.setStreet("123 Main Street");
workAddress.setCity("Any Town");
workAddress.setState("NC");
workAddress.setZipCode("00000");
return Map.of("home", homeAddress,
"work", workAddress);
}
```
# Use an `EnhancedDocument` without DynamoDB
Although you usually use an instance of an `EnhancedDocument` to read and write document-type DynamoDB items, it can also be used independently of DynamoDB.
You can use `EnhancedDocuments` for their ability to convert between JSON strings or custom objects to low-level maps of `AttributeValues` as shown in the following example.
```
public static void conversionWithoutDynamoDbExample() {
Address address = new Address();
address.setCity("my city");
address.setState("my state");
address.setStreet("my street");
address.setZipCode("00000");
// Build an EnhancedDocument instance for its conversion functionality alone.
EnhancedDocument addressEnhancedDoc = EnhancedDocument.builder()
// Important: You must specify attribute converter providers when you build an EnhancedDocument instance not used with a DynamoDB table.
.attributeConverterProviders(new CustomAttributeConverterProvider(), DefaultAttributeConverterProvider.create())
.put("addressDoc", address, Address.class)
.build();
// Convert address to a low-level item representation.
final Map addressAsAttributeMap = addressEnhancedDoc.getMapOfUnknownType("addressDoc");
logger.info("addressAsAttributeMap: {}", addressAsAttributeMap.toString());
// Convert address to a JSON string.
String addressAsJsonString = addressEnhancedDoc.getJson("addressDoc");
logger.info("addressAsJsonString: {}", addressAsJsonString);
// Convert addressEnhancedDoc back to an Address instance.
Address addressConverted = addressEnhancedDoc.get("addressDoc", Address.class);
logger.info("addressConverted: {}", addressConverted.toString());
}
/* Console output:
addressAsAttributeMap: {zipCode=AttributeValue(S=00000), state=AttributeValue(S=my state), street=AttributeValue(S=my street), city=AttributeValue(S=my city)}
addressAsJsonString: {"zipCode":"00000","state":"my state","street":"my street","city":"my city"}
addressConverted: Address{street='my street', city='my city', state='my state', zipCode='00000'}
*/
```
**Note**
When you use an enhanced document independent of a DynamoDB table, make sure you explicitly set attribute converter providers on the builder.
In contrast, the document table schema supplies the converter providers when an enhanced document is used with a DynamoDB table.
# Use extensions to customize DynamoDB Enhanced Client operations
The DynamoDB Enhanced Client API supports plugin extensions that provide functionality beyond mapping operations. Extensions use two hook methods to modify data during read and write operations:
+ `beforeWrite()` - Modifies a write operation before it happens
+ `afterRead()` - Modifies the results of a read operation after it happens
Some operations (such as item updates) perform both a write and then a read, so both hook methods are called.
## How extensions are loaded
Extensions are loaded in the order that you specify in the enhanced client builder. The load order can be important because one extension can act on values that have been transformed by a previous extension.
By default, the enhanced client loads two extensions:
+ `[VersionedRecordExtension](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/extensions/VersionedRecordExtension.html)` - Provides optimistic locking
+ `[AtomicCounterExtension](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/extensions/AtomicCounterExtension.html)` - Automatically increments counter attributes
You can override the default behavior with the enhanced client builder and load any extension. You can also specify none if you don't want the default extensions.
**Important**
If you load your own extensions, the enhanced client doesn't load any default extensions. If you want the behavior provided by either default extension, you need to explicitly add it to the list of extensions.
The following example shows how to load a custom extension named `verifyChecksumExtension` after the `VersionedRecordExtension`. The `AtomicCounterExtension` is not loaded in this example.
```
DynamoDbEnhancedClientExtension versionedRecordExtension = VersionedRecordExtension.builder().build();
DynamoDbEnhancedClient enhancedClient =
DynamoDbEnhancedClient.builder()
.dynamoDbClient(dynamoDbClient)
.extensions(versionedRecordExtension, verifyChecksumExtension)
.build();
```
## Available extension details and configuration
The following sections provide detailed information about each available extension in the SDK.
### Implement optimistic locking with the `VersionedRecordExtension`
The `VersionedRecordExtension` extension provides optimistic locking by incrementing and tracking an item version number as items are written to the database. A condition is added to every write that causes the write to fail if the version number of the actual persisted item doesn't match the value that the application last read.
#### Configuration
To specify which attribute to use to track the item version number, tag a numeric attribute in the table schema.
The following snippet specifies that the `version` attribute should hold the item version number.
```
@DynamoDbVersionAttribute
public Integer getVersion() {...};
public void setVersion(Integer version) {...};
```
The equivalent static table schema approach is shown in the following snippet.
```
.addAttribute(Integer.class, a -> a.name("version")
.getter(Customer::getVersion)
.setter(Customer::setVersion)
// Apply the 'version' tag to the attribute.
.tags(VersionedRecordExtension.AttributeTags.versionAttribute())
```
#### How it works
Optimistic locking with the `VersionedRecordExtension` has the following impact on these `DynamoDbEnhancedClient` and `DynamoDbTable` methods:
**`putItem`**
New items are assigned a initial version value of 0. This can be configured with `@DynamoDbVersionAttribute(startAt = X)`.
**`updateItem`**
If you retrieve an item, update one or more of its properties, and attempt to save the changes, the operation succeeds only if the version number on the client side and the server side match.
If successful, the version number is automatically incremented by 1. This can be configured with `@DynamoDbVersionAttribute(incrementBy = X)`.
**`deleteItem`**
The `DynamoDbVersionAttribute` annotation has no effect. You must add a condition expressions manually when deleting an item.
The following example adds a conditional expression to ensure that the item deleted is the item that was read. In the following example `recordVersion` is the bean's attribute annotated with `@DynamoDbVersionAttribute`.
```
// 1. Read the item and get its current version.
Customer item = customerTable.getItem(Key.builder().partitionValue("someId").build());
// `recordVersion` is the bean's attribute that is annotated with `@DynamoDbVersionAttribute`.
AttributeValue currentVersion = item.getRecordVersion();
// 2. Create conditional delete with the `currentVersion` value.
DeleteItemEnhancedRequest deleteItemRequest =
DeleteItemEnhancedRequest.builder()
.key(KEY)
.conditionExpression(Expression.builder()
.expression("recordVersion = :current_version_value")
.putExpressionValue(":current_version_value", currentVersion)
.build()).build();
customerTable.deleteItem(deleteItemRequest);
```
**`transactWriteItems`**
+ `addPutItem`: This method has the same behavior as `putItem`.
+ `addUpdateItem`: This method has the same behavior as `updateItem`.
+ `addDeleteItem`: This method has the same behavior as `deleteItem`.
**`batchWriteItem`**
+ `addPutItem`: This method has the same behavior as `putItem`.
+ `addDeleteItem`: This method has the same behavior as `deleteItem`.
**Note**
DynamoDB global tables use a ['last writer wins' reconciliation](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/V2globaltables_HowItWorks.html#V2globaltables_HowItWorks.consistency-modes) between concurrent updates, where DynamoDB makes a best effort to determine the last writer. If you use global tables, this 'last writer wins' policy means that locking strategies may not work as expected, because all replicas will eventually converge based on the last write determined by DynamoDB.
#### How to disable
To disable optimistic locking, do not use the `@DynamoDbVersionAttribute` annotation.
### Implement counters with the `AtomicCounterExtension`
The `AtomicCounterExtension` extension increments a tagged numerical attribute each time a record is written to the database. You can specify start and increment values. If no values are specified, the start value is set to 0 and the attribute's value increments by 1.
#### Configuration
To specify which attribute is a counter, tag an attribute of type `Long` in the table schema.
The following snippet shows the use of the default start and increment values for the `counter` attribute.
```
@DynamoDbAtomicCounter
public Long getCounter() {...};
public void setCounter(Long counter) {...};
```
The static table schema approach is shown in the following snippet. The atomic counter extension uses a start value of 10 and increments the value by 5 each time the record is written.
```
.addAttribute(Integer.class, a -> a.name("counter")
.getter(Customer::getCounter)
.setter(Customer::setCounter)
// Apply the 'atomicCounter' tag to the attribute with start and increment values.
.tags(StaticAttributeTags.atomicCounter(10L, 5L))
```
### Add timestamps with the `AutoGeneratedTimestampRecordExtension`
The `AutoGeneratedTimestampRecordExtension` extension automatically updates tagged attributes of type `[Instant](https://docs.oracle.com/javase/8/docs/api/java/time/Instant.html)` with a current timestamp every time the item is successfully written to the database. This extension is not loaded by default.
#### Configuration
To specify which attribute to update with the current timestamp, tag the `Instant` attribute in the table schema.
The `lastUpdate` attribute is the target of the extension's behavior in the following snippet. Note the requirement that the attribute must be an `Instant` type.
```
@DynamoDbAutoGeneratedTimestampAttribute
public Instant getLastUpdate() {...}
public void setLastUpdate(Instant lastUpdate) {...}
```
The equivalent static table schema approach is shown in the following snippet.
```
.addAttribute(Instant.class, a -> a.name("lastUpdate")
.getter(Customer::getLastUpdate)
.setter(Customer::setLastUpdate)
// Applying the 'autoGeneratedTimestamp' tag to the attribute.
.tags(AutoGeneratedTimestampRecordExtension.AttributeTags.autoGeneratedTimestampAttribute())
```
### Generate a UUID with the AutoGeneratedUuidExtension
The `AutoGeneratedUuidExtension` extension generates a unique UUID (Universally Unique Identifier) for an attribute when a new record is written to the database. Uses the Java JDK [UUID.randomUUID()](https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html#randomUUID--) method and applies to attributes of type `java.lang.String`. This extension is not loaded by default.
#### Configuration
The `uniqueId` attribute is the target of the extension's behavior in the following snippet.
```
@AutoGeneratedUuidExtension
public String getUniqueId() {...}
public void setUniqueId(String uniqueId) {...}
```
The equivalent static table schema approach is shown in the following snippet.
```
.addAttribute(String.class, a -> a.name("uniqueId")
.getter(Customer::getUniqueId)
.setter(Customer::setUniqueId)
// Applying the 'autoGeneratedUuid' tag to the attribute.
.tags(AutoGeneratedUuidExtension.AttributeTags.autoGeneratedUuidAttribute())
```
If you want the extension to populate the UUID only for `putItem` methods and not for `updateItem` methods, add the [update behavior](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/mapper/UpdateBehavior.html) annotation as shown in the following snippet.
```
@AutoGeneratedUuidExtension
@DynamoDbUpdateBehavior(UpdateBehavior.WRITE_IF_NOT_EXISTS)
public String getUniqueId() {...}
public void setUniqueId(String uniqueId) {...}
```
If you use the static table schema approach, use the following equivalent code.
```
.addAttribute(String.class, a -> a.name("uniqueId")
.getter(Customer::getUniqueId)
.setter(Customer::setUniqueId)
// Applying the 'autoGeneratedUuid' tag to the attribute.
.tags(AutoGeneratedUuidExtension.AttributeTags.autoGeneratedUuidAttribute(),
StaticAttributeTags.updateBehavior(UpdateBehavior.WRITE_IF_NOT_EXISTS))
```
# Custom extension example
You can create custom extensions by implementing the `DynamoDbEnhancedClientExtension` interface. The following custom extension class shows a `beforeWrite()` method that uses an update expression to set a `registrationDate` attribute if the item in the database doesn't already have one.
```
public final class CustomExtension implements DynamoDbEnhancedClientExtension {
// 1. In a custom extension, use an UpdateExpression to define what action to take before
// an item is updated.
@Override
public WriteModification beforeWrite(DynamoDbExtensionContext.BeforeWrite context) {
if ( context.operationContext().tableName().equals("Customer")
&& context.operationName().equals(OperationName.UPDATE_ITEM)) {
return WriteModification.builder()
.updateExpression(createUpdateExpression())
.build();
}
return WriteModification.builder().build(); // Return an "empty" WriteModification instance if the extension should not be applied.
// In this case, if the code is not updating an item on the Customer table.
}
private static UpdateExpression createUpdateExpression() {
// 2. Use a SetAction, a subclass of UpdateAction, to provide the values in the update.
SetAction setAction =
SetAction.builder()
.path("registrationDate")
.value("if_not_exists(registrationDate, :regValue)")
.putExpressionValue(":regValue", AttributeValue.fromS(Instant.now().toString()))
.build();
// 3. Build the UpdateExpression with one or more UpdateAction.
return UpdateExpression.builder()
.addAction(setAction)
.build();
}
}
```
# Use the DynamoDB Enhanced Client API asynchronously
If your application requires non-blocking, asynchronous calls to DynamoDB, you can use the [DynamoDbEnhancedAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.html). It's similar to the synchronous implementation but with the following key differences:
1. When you build the `DynamoDbEnhancedAsyncClient`, you must provide the asynchronous version of the standard client, `DynamoDbAsyncClient`, as shown in the following snippet.
```
DynamoDbEnhancedAsyncClient enhancedClient =
DynamoDbEnhancedAsyncClient.builder()
.dynamoDbClient(dynamoDbAsyncClient)
.build();
```
1. Methods that return a single data object return a `CompletableFuture` of the result instead of only the result. Your application can then do other work without having to block on the result. The following snippet shows the asynchronous `getItem()` method.
```
CompletableFuture result = customerDynamoDbTable.getItem(customer);
// Perform other work here.
return result.join(); // Now block and wait for the result.
```
1. Methods that return paginated lists of results return an [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/async/SdkPublisher.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/async/SdkPublisher.html) instead of an [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/pagination/sync/SdkIterable.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/pagination/sync/SdkIterable.html) that the synchronous `DynamoDbEnhanceClient` returns for the same methods. Your application can then subscribe a handler to that publisher to deal with the results asynchronously without having to block.
```
PagePublisher results = customerDynamoDbTable.query(r -> r.queryConditional(keyEqualTo(k -> k.partitionValue("Smith"))));
results.subscribe(myCustomerResultsProcessor);
// Perform other work and let the processor handle the results asynchronously.
```
For a more complete example of working with the `SdkPublisher API`, see [the example](ddb-en-client-use-multirecord.md#ddb-en-client-use-multirecord-scan-async) in the section that discusses the asynchronous `scan()` method of this guide.
# Data class annotations
The following table lists the annotations that can be used on data classes and provides links to information and examples in this guide. The table is sorted in ascending alphabetical order by annotation name.
**Data class annotations used in this guide**
| Annotation name | Annotation applies to1 | What it does | Where it is shown in this guide |
| --- | --- | --- | --- |
| DynamoDbAtomicCounter | attribute2 | Increments a tagged numerical attribute each time a record is written to the database. | [Introduction and discussion.](ddb-en-client-extensions.md#ddb-en-client-extensions-ACE) |
| DynamoDbAttribute | attribute | Defines or renames a bean property that is mapped to a DynamoDB table attribute. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbAutoGeneratedTimestampAttribute | attribute | Updates a tagged attribute with a current timestamp every time the item is successfully written to the database | [Introduction and discussion](ddb-en-client-extensions.md#ddb-en-client-extensions-AGTE). |
| DynamoDbAutoGeneratedUuid | attribute | Generate a unique UUID (Universally Unique Identifier) for an attribute when a new record is written to the database. | [Introduction and discussion.](ddb-en-client-extensions.md#ddb-en-client-extensions-AGUE) |
| DynamoDbBean | class | Marks a data class as mappable to a table schema. | First use on the [Customer class](ddb-en-client-gs-tableschema.md#ddb-en-client-gs-tableschema-anno-bean-cust) in the Get started section. Several usages appear throughout the guide. |
| DynamoDbConvertedBy | attribute | Associates a custom AttributeConverter with the annotated attribute. | [Initial discussion and example.](ddb-en-client-adv-features-conversion.md#ddb-en-client-adv-features-conversion-single) |
| DynamoDbFlatten | attribute | Flattens all the attributes of a separate DynamoDB data class and adds them as top-level attributes to the record that is read and written to the database. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbIgnore | attribute | Results in the attribute remaining unmapped. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbIgnoreNulls | attribute | Prevents saving null attributes of nested DynamoDb objects. | [Discussion and examples.](ddb-en-client-adv-features-ignore-null.md) |
| DynamoDbImmutable | class | Marks an immutable data class as mappable to a table schema. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbPartitionKey | attribute | Marks an attribute as the primary partition key (hash key) of the DynamoDb table. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbPreserveEmptyObject | attribute | Specifies that if no data is present for the object mapped to the annotated attribute, the object should be initialized with all null fields. | [Discussion and examples.](ddb-en-client-adv-features-empty.md) |
| DynamoDbSecondaryPartitionKey | attribute | Marks an attribute as a partition key for a global secondary index. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbSecondarySortKey | attribute | Marks an attribute as an optional sort key for a global or local secondary index. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbSortKey | attribute | Marks an attribute as the optional primary sort key (range key). | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbUpdateBehavior | attribute | Specifies the behavior when this attribute is updated as part of an 'update' operation such as UpdateItem. | [Introduction and example.](ddb-en-client-adv-features-upd-behavior.md) |
| DynamoDbVersionAttribute | attribute | Increments an item version number. | [Introduction and discussion.](ddb-en-client-extensions.md#ddb-en-client-extensions-VRE) |
1You can apply an attribute-level annotations to the getter or setter, but not both. This guide shows annotations on getters.
2The term `property` is normally used for a value encapsulated in a JavaBean data class. However, this guide uses the term `attribute` instead, to be consistent with the terminology used by DynamoDB.