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();
```
前面的静态架构示例使用以下数据类。
#### 数据类
------
#### [ 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;
}
```
------
您可以根据需要，使用生成器模式对任意数量的符合条件的不同类进行扁平化。
## 对其他代码的影响
当您使用 `@DynamoDbFlatten` 属性（或 `flatten()` 生成器方法）时，DynamoDB 中的项目将针对组合成的对象的每个属性包含一个属性。它还包括进行组合的对象的属性。
相反，如果您使用组合成的类对数据类进行注释但不使用 `@DynamoDbFlatten`，则该项目将与组合成的对象一起保存为单个属性。
例如，我们可以比较[使用组合的扁平化示例](#ddb-en-client-adv-features-flatmap-comp-anno)中显示的 `Customer` 类在对 `record` 属性进行扁平化和不进行扁平化时的区别。您可以使用 JSON 可视化此区别，如下表所示。
****
| 进行扁平化 | 不进行扁平化 |
| --- | --- |
| 3 个属性 | 2 个属性 |
| {
"id": "1",
"createdDate": "today",
"name": "my name"
} | {
"id": "1",
"record": {
"createdDate": "today",
"name": "my name"
}
} |
如果您有其他代码访问 DynamoDB 表并希望找到某些属性，则此区别就变得很重要。
# 处理属性值为 bean、map、list 和 set 的对象
一个 bean 定义（例如下面所示的 `Person` 类）可能会定义一些属性，而这些属性所引用的类型本身还包含更多的属性。例如，在 `Person` 类中，`mainAddress` 是一个属性，该属性引用定义了额外值属性的 `Address` bean。`addresses` 引用一个 Java map，其元素引用 `Address` bean。这些复杂类型可以看作是包含简单属性的容器，在 DynamoDB 环境中，您使用这些容器是为了获取其所包含的实际数据值。
DynamoDB 将嵌套元素（例如 map、list 或 bean）的值属性称为*嵌套属性*。[Amazon DynamoDB 开发人员指南](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes)将 Java 中的 map、list 或 bean 对象保存后的形式称为*文档类型*。在 Java 中，用于其数据值的简单属性在 DynamoDB 中称为*标量类型*。set 包含多个相同类型的标量元素，所以称为*集类型*。
重要的是要知道，DynamoDB 增强型客户端 API 在保存时会将 bean 属性转换为 DynamoDB map 文档类型。
## `Person` 类
```
@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` 类
```
@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` 类
```
@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 + '\'' +
'}';
}
}
```
## 保存复杂类型
### 使用带注释的数据类
通过注释来保存自定义类的嵌套属性。前面显示的 `Address` 类和 `PhoneNumber` 类仅使用 `@DynamoDbBean` 注释进行注释。当 DynamoDB 增强型客户端 API 使用以下代码段为 `Person` 类生成表架构时，API 会发现 `Address` 和 `PhoneNumber` 类的使用，并生成相应的映射以与 DynamoDB 结合使用。
```
TableSchema personTableSchema = TableSchema.fromBean(Person.class);
```
### 在生成器中使用抽象架构
另一种方法是为每个嵌套 bean 类使用静态表架构生成器，如以下代码所示。
`Address` 和 `PhoneNumber` 类的表架构是抽象的，不能与 DynamoDB 表一起使用。这是因为它们缺少主键的定义。但是，它们在 `Person` 类的表架构中用作嵌套架构。
在注释行 1 和 2 之后的 `PERSON_TABLE_SCHEMA` 定义中，显示了使用抽象表架构的代码。在 `EnhanceType.documentOf(...)` 方法中使用 `documentOf` 并不表示该方法将返回增强型文档 API 的 `EnhancedDocument` 类型。在此上下文中，`documentOf(...)` 方法将返回一个对象，该对象知道如何使用表架构参数，在其类参数和 DynamoDB 表属性之间进行映射。
#### 静态架构代码
```
// 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();
```
## 复杂类型的项目属性
对于 `query()` 和 `scan()` 方法，您可以使用 `addNestedAttributeToProject()` 和 `attributesToProject()` 之类的方法调用来指定要在结果中返回哪些属性。在发送请求之前，DynamoDB 增强型客户端 API 会将 Java 方法调用参数转换为[投影表达式](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html)。
以下示例在 `Person` 表中填充两个项目，然后执行三个扫描操作。
第一个扫描访问表中的所有项目，以便将结果与其他扫描操作进行比较。
第二个扫描使用 [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)) 生成器方法仅返回 `street` 属性值。
第三个扫描操作使用 [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...)) 生成器方法返回第一级属性 `hobbies` 的数据。`hobbies` 的属性类型是列表。要访问单个列表项目，请对列表执行 `get()` 操作。
```
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
```
**注意**
如果 `attributesToProject()` 方法遵循任何其他用于添加要投影的属性的生成器方法，则提供给 `attributesToProject()` 的属性名称列表将替换所有其他属性名称。
在以下代码段中，使用 `ScanEnhancedRequest` 实例执行的扫描仅返回业余爱好数据。
```
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]}
```
以下代码段首先使用 `attributesToProject()` 方法。此排序保留了请求的所有其他属性。
```
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]}
```
## 在表达式中使用复杂类型
您可以在表达式（例如筛选表达式和条件表达式）中使用复杂类型，通过使用解除引用操作符来访问复杂类型的结构。对于对象和 map，使用 `. (dot)`；对于 list 元素，使用 `[n]`（元素序号加上方括号）。不能直接引用 set 中的单个元素，但可以使用 [`contains` 函数](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions)。
以下示例显示了在扫描操作中使用的两个筛选表达式。筛选表达式为要在结果中显示的项目指定匹配条件。该示例使用前面显示的 `Person`、`Address` 和 `PhoneNumber` 类。
```
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");
}
```
### 用于向表中填充数据的辅助方法
```
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 表示形式
```
{
"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"
}
]
}
```
## 更新包含复杂类型的项目
要更新包含复杂类型的项目，有两种基本方法：
+ 方法 1：先检索项目（使用 `getItem`），更新对象，然后调用 `DynamoDbTable#updateItem`。
+ 方法 2：不检索项目，而是构造一个新实例，设置要更新的属性，然后通过设置适当的 [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) 值将实例提交到 `DynamoDbTable#updateItem`。这种方法不需要在更新之前获取项目。
此部分中显示的示例使用前面显示的 `Person`、`Address` 和 `PhoneNumber` 类。
### 更新方法 1：检索，然后更新
通过使用这种方法，您可以确保更新时不会丢失任何数据。DynamoDB 增强型客户端 API 使用保存在 DynamoDB 中的项目中的属性（包括复杂类型的值）重新创建 bean。然后，您需要使用 getter 和 setter 来更新 bean。这种方法的缺点是先检索项目会产生费用。
下面的示例说明：如果在更新项目之前先检索项目，则不会丢失任何数据。
```
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;
}
```
### 更新方法 2：使用 `IgnoreNullsMode` 枚举而不先检索项目
要更新 DynamoDB 中的项目，您可以提供一个仅包含待更新属性的新对象，而将其他值保留为 null。使用这种方法，您需要了解 SDK 如何处理对象中的 null 值以及如何控制行为。
要指定希望 SDK 忽略哪些 null 值属性，请在构建 [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) 时提供 `IgnoreNullsMode` 枚举。作为枚举值使用的一个示例，以下代码段使用了 `IgnoreNullsMode.SCALAR_ONLY` 模式。
```
// 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"
}
}
*/
```
《Amazon DynamoDB 开发人员指南》包含了有关[更新表达式](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)的更多信息。
#### `IgnoreNullsMode` 选项的描述
+ `IgnoreNullsMode.SCALAR_ONLY` - 使用此设置在任何级别更新标量属性。SDK 会构造一个更新语句，该语句仅向 DynamoDB 发送非 null 的标量属性。SDK 会忽略 bean 或 map 的 null 值标量属性，保留在 DynamoDB 中保存的值。
更新 map 或 bean 的标量属性时，map 必须已存在于 DynamoDB 中。如果 DynamoDB 中的对象尚不存在您向对象添加的 map 或 bean，则您会收到 `DynamoDbException`，其中包含消息：*在更新表达式中提供的文档路径对于更新无效*。您必须使用 `MAPS_ONLY` 模式，先将 bean 或 map 添加到 DynamoDB 中，然后才能更新其属性。
+ `IgnoreNullsMode.MAPS_ONLY` - 使用此设置添加或替换 bean 或 map 的属性。SDK 会替换或添加对象中提供的任何 map 或 bean。系统会忽略对象中为 null 的任何 bean 或 map，并保留 DynamoDB 中存在的 map。
+ `IgnoreNullsMode.DEFAULT` - 使用此设置，SDK 永远不会忽略 null 值。任何级别的标量属性如果为 null，则更新为 null。在 DynamoDB 中，SDK 会将对象中的任何 null 值 bean、map、list 或 set 属性更新为 null。当您使用此模式（或者由于这是默认模式而不提供模式）时，应先检索项目，以便 DynamoDB 中的值不会设置为更新对象中提供的 null，除非您确实有意将这些值设置为 null。
在所有模式下，如果您将具有非 null 值 list 或 set 属性的对象提供给 `updateItem`，则 list 或 set 会保存到 DynamoDB 中。
#### 为什么使用这些模式？
当你为对象提供一个 Bean 或`updateItem`方法映射时，SDK 无法判断是否应该使用 Bean 中的属性值（或地图中的条目值）来更新项目，或者整个属性值是否 bean/map 应该替换保存到 DynamoDB 中的内容。
基于我们之前“先检索项再更新”的示例，现在尝试在不检索的情况下直接更新 `mainAddress` 的 `city` 属性。
```
/* 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'.
*/
```
以下两个示例展示了 `MAPS_ONLY` 和 `SCALAR_ONLY` 枚举值的用法。`MAPS_ONLY` 添加 map，而 `SCALAR_ONLY` 更新 map。
##### `IgnoreNullsMode.MAPS_ONLY` 示例
```
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.
}
```
请参阅下表，了解每种模式忽略哪些 null 值。除非您在处理 bean 或 map，否则通常可以使用 `SCALAR_ONLY` 或 `MAPS_ONLY` 中的任意一种。
**对于每种模式，SDK 会忽略提交给 `updateItem` 的对象中的哪些 null 值属性？**
| 属性的类型 | 在 SCALAR\$1ONLY 模式下 | 在 MAPS\$1ONLY 模式下 | 在 DEFAULT 模式下 |
| --- | --- | --- | --- |
| 顶层标量 | 支持 | 是 | 否 |
| bean 或 map | 支持 | 是 | 否 |
| bean 或 map 条目的标量值 | 是1 | 否2 | 否 |
| list 或 set | 支持 | 是 | 否 |
1假设 map 已存在于 DynamoDB 中。您在更新对象中提供的 bean 或 map 的任何标量值（null 或非 null）都要求 DynamoDB 中存在该值的路径。SDK 在提交请求之前会使用 `. (dot)` 解除引用操作符来构造指向该属性的路径。
2由于您使用 `MAPS_ONLY` 模式来完全替换或添加 bean 或 map，因此 bean 或 map 中的所有 null 值都将在保存到 DynamoDB 的 map 中保留。
# 使用 `@DynamoDbPreserveEmptyObject` 保留空对象
如果您将包含空对象的 Bean 保存到 Amazon DynamoDB 中，并且希望 SDK 在检索时重新创建空对象，请使用 `@DynamoDbPreserveEmptyObject` 注释内部 Bean 的 getter。
为了说明该注释的工作原理，代码示例使用了以下两个 Bean。
## 示例 Bean
以下数据类包含两个 `InnerBean` 字段。getter 方法 `getInnerBeanWithoutAnno()` 不使用 `@DynamoDbPreserveEmptyObject` 注释。`getInnerBeanWithAnno()` 方法使用注释。
```
@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();
}
}
```
以下 `InnerBean` 类的实例是 `MyBean` 的字段，并且在示例代码中被初始化为空对象。
```
@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 + '\'' +
'}';
}
}
```
以下代码示例将带有初始化内部 Bean 的 `MyBean` 对象保存到 DynamoDB，然后检索该项目。记录的输出显示 `innerBeanWithoutAnno` 未初始化，但已创建 `innerBeanWithAnno`。
```
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;
}
```
## 替代静态架构
您可以使用以下 `StaticTableSchema` 版本的表架构来代替 Bean 上的注释。
```
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();
}
```
# 避免保存嵌套对象的空属性
在将数据类对象保存到 DynamoDB 时，您可以通过应用 `@DynamoDbIgnoreNulls` 注释来跳过嵌套对象的空属性。相比之下，具有空值的顶级属性永远不会保存到数据库中。
为了说明该注释的工作原理，代码示例使用了以下两个 Bean。
## 示例 Bean
以下数据类包含两个 `InnerBean` 字段。getter 方法 `getInnerBeanWithoutAnno()` 不使用注释。`getInnerBeanWithIgnoreNullsAnno()` 方法使用注释 `@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();
}
}
```
以下 `InnerBean` 类的实例是 `MyBean` 的字段，用于以下示例代码。
```
@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();
}
}
```
以下代码示例创建一个 `InnerBean` 对象，并仅为其两个属性中的一个设置了值。
```
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);
}
```
为了可视化发送到 DynamoDB 的低级别数据，该代码会在保存 `MyBean` 对象之前记录属性映射。
记录的输出显示，`innerBeanWithIgnoreNullsAnno` 输出了一个属性，
```
innerBeanWithIgnoreNullsAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200)})
```
`innerBeanWithoutAnno` 实例输出了两个属性。一个属性的值为 200，另一个属性的值为空。
```
innerBeanWithoutAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200), innerBeanFieldString=AttributeValue(NUL=true)})
```
## 属性映射的 JSON 表示
以下 JSON 表示可以更轻松地查看保存到 DynamoDB 的数据。
```
{
"id": {
"S": "1"
},
"innerBeanWithIgnoreNullsAnno": {
"M": {
"innerBeanFieldInteger": {
"N": "200"
}
}
},
"innerBeanWithoutAnno": {
"M": {
"innerBeanFieldInteger": {
"N": "200"
},
"innerBeanFieldString": {
"NULL": true
}
}
}
}
```
## 替代静态架构
您可以使用以下 `StaticTableSchema` 版本的表架构来代替数据类标注。
```
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();
}
```
# 使用适用于 DynamoDB 的增强型文档 API 处理 JSON 文档
的[增强型文档 API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/package-summary.html) AWS SDK for Java 2.x 旨在处理没有固定架构的面向文档的数据。该 API 也允许您使用自定义类来映射单个属性。
增强型文档 API 是 适用于 Java 的 AWS SDK 1.x 版[文档 API](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/DynamoDB.html) 的继任者。
**Contents**
+ [开始使用增强型文档 API](ddb-en-client-doc-api-steps.md)
+ [创建 `DocumentTableSchema` 和 `DynamoDbTable`。](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema)
+ [生成增强型文档](ddb-en-client-doc-api-steps-create-ed.md)
+ [使用 JSON 字符串生成](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromJson)
+ [基于单个元素构建](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts)
+ [执行 CRUD 操作](ddb-en-client-doc-api-steps-use.md)
+ [将增强型文档属性作为自定义对象进行访问](ddb-en-client-doc-api-convert.md)
+ [在没有 DynamoDB 的情况下使用 `EnhancedDocument`](ddb-en-client-doc-api-standalone.md)
# 开始使用增强型文档 API
增强型文档 API 所需的[依赖项](ddb-en-client-getting-started.md#ddb-en-client-gs-dep)与 DynamoDB 增强型客户端 API 所需的依赖项相同。它还需要一个 [`DynamoDbEnhancedClient` 实例](ddb-en-client-getting-started-dynamodbTable.md#ddb-en-client-getting-started-dynamodbTable-eclient)，如本主题开头所示。
由于增强型文档 API 是在 2.20.3 版本中发布的 AWS SDK for Java 2.x，因此您需要该版本或更高版本。
## 创建 `DocumentTableSchema` 和 `DynamoDbTable`。
要使用增强文档 API 对 DynamoDB 表调用命令，请将该表与[DynamoDbTable客户端 EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html) < > 资源对象相关联。
增强型客户端的 `table()` 方法会创建一个 `DynamoDbTable` 实例，并且需要用于 DynamoDB 表名称和 `DocumentTableSchema` 的参数。
的生成器[DocumentTableSchema](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/DocumentTableSchema.html)需要主索引键和一个或多个属性转换器提供程序。`AttributeConverterProvider.defaultProvider()` 方法为[默认类型](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/internal/converter/attribute/package-summary.html)提供转换器。即使您提供了自定义属性转换器提供程序，也应指定它。您可以向生成器添加可选的二级索引键。
以下代码段显示的代码将生成一个 DynamoDB `person` 表的客户端表示形式，该表将存储无架构 `EnhancedDocument` 对象。
```
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.
```
以下显示了本部分中使用的 `person` 对象的 JSON 表示形式。
### JSON `person` 对象
```
{
"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"
}
]
}
```
# 生成增强型文档
`[EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html)` 表示具有复杂结构和嵌套属性的文档类型对象。`EnhancedDocument` 需要与为 `DocumentTableSchema` 指定的主键属性相匹配的顶级属性。其余内容是任意的，可以由顶级属性以及深度嵌套的属性组成。
您可以使用提供多种元素添加方法的生成器来创建 `EnhancedDocument` 实例。
## 使用 JSON 字符串生成
使用 JSON 字符串，您可以在一个方法调用中生成 `EnhancedDocument`。以下代码段从 `jsonPerson()` 帮助程序方法返回的 JSON 字符串创建一个 `EnhancedDocument`。`jsonPerson()` 方法返回前面显示的 [person 对象](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema-obj)的 JSON 字符串版本。
```
EnhancedDocument document =
EnhancedDocument.builder()
.json( jsonPerson() )
.build());
```
## 基于单个元素构建
或者，您可以使用生成器的类型安全方法从各个组件生成 `EnhancedDocument` 实例。
以下示例生成一个 `person` 增强型文档，该文档类似于上一个示例中从 JSON 字符串生成的增强型文档。
```
/* 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();
```
### 帮助程序方法
```
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"));
}
```
# 执行 CRUD 操作
定义 `EnhancedDocument` 实例后，您可以将其保存到 DynamoDB 表。以下代码段使用基于单个元素创建的 [personDocument](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts)。
```
documentDynamoDbTable.putItem(personDocument);
```
读取 DynamoDB 中的增强型文档实例后，您可以使用 getter 提取各个属性值，如以下代码段所示，这些代码段用于访问从 `personDocument` 中保存的数据。或者，您可以将完整内容提取为 JSON 字符串，如示例代码的最后一部分所示。
```
// 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`实例可以与映射的数据类的任何方法一起使用 [DynamoDbEnhancedClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.html)，`[DynamoDbTable](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html)`也可以代替映射的数据类。
# 将增强型文档属性作为自定义对象进行访问
除了提供用于读取和写入具有无架构结构的属性的 API 之外，增强型文档 API 还允许您在自定义类的实例之间转换属性。
增强型文档 API 使用[控制属性转换](ddb-en-client-adv-features-conversion.md)部分中显示的 `AttributeConverterProvider` 和 `AttributeConverter`，作为 DynamoDB 增强型客户端 API 的一部分。
在以下示例中，我们使用 `CustomAttributeConverterProvider` 及其嵌套 `AddressConverter` 类来转换 `Address` 对象。
此示例表明，您可以混合类中的数据以及根据需要构建的结构中的数据。此示例还表明，自定义类可以在嵌套结构的任何级别上使用。此示例中的 `Address` 对象是映射中使用的值。
```
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` 代码
```
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` 类
```
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;
}
}
```
## 提供地址的帮助程序方法
以下帮助程序方法提供的映射使用自定义 `Address` 实例作为值，而不是使用通用 `Map` 实例作为值。
```
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);
}
```
# 在没有 DynamoDB 的情况下使用 `EnhancedDocument`
尽管您通常使用 `EnhancedDocument` 的实例来读取和写入文档类型的 DynamoDB 项目，但它也可以独立于 DynamoDB 使用。
您可以使用 `EnhancedDocuments` 的功能，在 JSON 字符串或自定义对象之间，执行到 `AttributeValues` 的低级映射的转换，如以下示例所示。
```
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'}
*/
```
**注意**
当您独立于 DynamoDB 表使用增强型文档时，请务必在生成器上明确设置属性转换器提供程序。
相比之下，当增强型文档与 DynamoDB 表结合使用时，文档表架构会提供转换器提供程序。
# 使用扩展自定义 DynamoDB 增强型客户端操作
DynamoDB 增强型客户端 API 支持插件扩展，这些插件扩展提供的功能不仅限于映射操作。扩展使用两种钩子方法在读取和写入操作期间修改数据：
+ `beforeWrite()` - 在写入操作实际执行之前对其进行修改
+ `afterRead()` - 在读取操作完成之后对返回的结果进行修改
某些操作（例如项目更新）同时执行写入和读取，因此会调用两种钩子方法。
## 如何加载扩展
按照您在增强型客户端生成器中指定的顺序加载扩展。加载顺序可能很重要，因为一个扩展可以对前一个扩展变换过的值起作用。
默认情况下，增强版客户端会加载两个扩展：
+ `[VersionedRecordExtension](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/extensions/VersionedRecordExtension.html)` - 提供乐观锁
+ `[AtomicCounterExtension](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/extensions/AtomicCounterExtension.html)` - 自动增加计数器属性
您可以使用增强型客户端生成器覆盖默认行为并加载任何扩展。如果您不想使用默认扩展，也可以指定一个都不用。
**重要**
如果您加载自己的扩展，则增强型客户端不会加载任何默认扩展。如果您想要任一默认扩展提供的行为，则需要将其明确添加到扩展列表中。
以下示例说明如何在 `VersionedRecordExtension` 之后加载名为 `verifyChecksumExtension` 的自定义扩展。本示例中未加载 `AtomicCounterExtension`。
```
DynamoDbEnhancedClientExtension versionedRecordExtension = VersionedRecordExtension.builder().build();
DynamoDbEnhancedClient enhancedClient =
DynamoDbEnhancedClient.builder()
.dynamoDbClient(dynamoDbClient)
.extensions(versionedRecordExtension, verifyChecksumExtension)
.build();
```
## 可用的扩展详细信息和配置
以下部分提供有关 SDK 中每个可用扩展的详细信息。
### 使用 `VersionedRecordExtension` 实施乐观锁
`VersionedRecordExtension` 扩展提供乐观锁，当项目写入数据库时，它会递增和跟踪项目的版本号。如果实际永久保存的项目的版本号与应用程序上次读取的值不匹配，则会在每次写入时添加一个导致写入失败的条件。
#### 配置
要指定使用哪个属性来跟踪项目版本号，请在表架构中标记数字属性。
以下代码段指定 `version` 属性应包含项目版本号。
```
@DynamoDbVersionAttribute
public Integer getVersion() {...};
public void setVersion(Integer version) {...};
```
下面的代码段显示了等效的静态表架构方法。
```
.addAttribute(Integer.class, a -> a.name("version")
.getter(Customer::getVersion)
.setter(Customer::setVersion)
// Apply the 'version' tag to the attribute.
.tags(VersionedRecordExtension.AttributeTags.versionAttribute())
```
#### 工作原理
使用 `VersionedRecordExtension` 实现的乐观锁机制会对这些 `DynamoDbEnhancedClient` 和 `DynamoDbTable` 方法产生以下影响：
**`putItem`**
为新项目分配的初始版本值为 0。可以使用 `@DynamoDbVersionAttribute(startAt = X)` 进行配置。
**`updateItem`**
如果您检索项目，然后更新它的一个或多个属性，并尝试保存所做更改，那么只有在客户端和服务器端的版本号匹配时操作才能成功。
如果成功，版本号自动加 1。可以使用 `@DynamoDbVersionAttribute(incrementBy = X)` 进行配置。
**`deleteItem`**
`DynamoDbVersionAttribute` 注释没有效果。删除项目时，必须手动添加条件表达式。
以下示例添加了一个条件表达式，以确保删除的项目是读取的项目。在以下示例中，`recordVersion` 是 bean 使用 `@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`：此方法的行为与 `putItem` 相同。
+ `addUpdateItem`：此方法的行为与 `updateItem` 相同。
+ `addDeleteItem`：此方法的行为与 `deleteItem` 相同。
**`batchWriteItem`**
+ `addPutItem`：此方法的行为与 `putItem` 相同。
+ `addDeleteItem`：此方法的行为与 `deleteItem` 相同。
**注意**
DynamoDB 全局表在处理并发更新时，使用[‘最后一个写入方为准’协调](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/V2globaltables_HowItWorks.html#V2globaltables_HowItWorks.consistency-modes)策略，DynamoDB 会尽最大努力判断谁是最后一个写入方。如果您使用全局表，这个“最后一个写入方为准”策略意味着锁定策略可能无法按预期工作，因为所有副本最终会基于 DynamoDB 确定的最后一次写入结果达成一致。
#### 如何禁用
要禁用乐观锁，请不要使用 `@DynamoDbVersionAttribute` 注释。
### 使用 `AtomicCounterExtension` 实施计数器
每次向数据库写入记录时，`AtomicCounterExtension` 扩展都会增加一个带标签的数字属性。您可以指定起始值和增量值。如果未指定任何值，则将起始值设置为 0，属性的值以 1 为增量。
#### 配置
要指定哪个属性是计数器，请在表架构中标记一个类型为 `Long` 的属性。
以下代码段显示了为 `counter` 属性使用默认起始值和增量值的情况。
```
@DynamoDbAtomicCounter
public Long getCounter() {...};
public void setCounter(Long counter) {...};
```
下面的代码段显示了静态表架构方法。原子计数器扩展使用起始值 10，并在每次写入记录时将该值递增 5。
```
.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))
```
### 使用 `AutoGeneratedTimestampRecordExtension` 添加时间戳
每次成功将项目写入数据库时，`AutoGeneratedTimestampRecordExtension` 扩展都会自动使用当前时间戳更新类型为 `[Instant](https://docs.oracle.com/javase/8/docs/api/java/time/Instant.html)` 的已标记属性。默认情况下不加载此扩展。
#### 配置
要指定将使用当前时间戳更新的属性，请在表架构中标记 `Instant` 属性。
在以下代码段中，`lastUpdate` 属性是扩展行为的目标。请注意该属性必须是 `Instant` 类型的要求。
```
@DynamoDbAutoGeneratedTimestampAttribute
public Instant getLastUpdate() {...}
public void setLastUpdate(Instant lastUpdate) {...}
```
下面的代码段显示了等效的静态表架构方法。
```
.addAttribute(Instant.class, a -> a.name("lastUpdate")
.getter(Customer::getLastUpdate)
.setter(Customer::setLastUpdate)
// Applying the 'autoGeneratedTimestamp' tag to the attribute.
.tags(AutoGeneratedTimestampRecordExtension.AttributeTags.autoGeneratedTimestampAttribute())
```
### 使用生成一个 UUID AutoGeneratedUuidExtension
向数据库写入新记录时，`AutoGeneratedUuidExtension` 扩展为属性生成唯一的 UUID（通用唯一标识符）。使用 Java JDK [UUID.randomUUID()](https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html#randomUUID--) 方法并应用于 `java.lang.String` 类型的属性。默认情况下不加载此扩展。
#### 配置
在以下代码段中，`uniqueId` 属性是扩展行为的目标。
```
@AutoGeneratedUuidExtension
public String getUniqueId() {...}
public void setUniqueId(String uniqueId) {...}
```
下面的代码段显示了等效的静态表架构方法。
```
.addAttribute(String.class, a -> a.name("uniqueId")
.getter(Customer::getUniqueId)
.setter(Customer::setUniqueId)
// Applying the 'autoGeneratedUuid' tag to the attribute.
.tags(AutoGeneratedUuidExtension.AttributeTags.autoGeneratedUuidAttribute())
```
如果您希望扩展仅为 `putItem` 方法填充 UUID，而不为 `updateItem` 方法填充 UUID，请添加[更新行为](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/mapper/UpdateBehavior.html)注释，如以下代码段所示。
```
@AutoGeneratedUuidExtension
@DynamoDbUpdateBehavior(UpdateBehavior.WRITE_IF_NOT_EXISTS)
public String getUniqueId() {...}
public void setUniqueId(String uniqueId) {...}
```
如果您使用静态表架构方法，请使用以下等效代码。
```
.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))
```
# 自定义扩展示例
您可以通过实施 `DynamoDbEnhancedClientExtension` 接口来创建自定义扩展。以下自定义扩展类展示了 `beforeWrite()` 方法，如果数据库中的项目还没有 `registrationDate` 属性，则使用更新表达式来设置该属性。
```
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();
}
}
```
# 异步使用 DynamoDB 增强型客户端 API
如果您的应用程序需要对 DynamoDB 进行非阻塞异步调用，则可以使用 [DynamoDbEnhancedAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.html)。它与同步实现类似，但有以下主要区别：
1. 构建时 `DynamoDbEnhancedAsyncClient`，必须提供标准客户端的异步版本 `DynamoDbAsyncClient`，如以下代码段所示。
```
DynamoDbEnhancedAsyncClient enhancedClient =
DynamoDbEnhancedAsyncClient.builder()
.dynamoDbClient(dynamoDbAsyncClient)
.build();
```
1. 返回单个数据对象的方法会返回结果的 `CompletableFuture`，而不仅仅是结果。然后，您的应用程序可以执行其他工作，而不必因结果阻塞。以下代码段显示了异步 `getItem()` 方法。
```
CompletableFuture result = customerDynamoDbTable.getItem(customer);
// Perform other work here.
return result.join(); // Now block and wait for the result.
```
1. 返回分页结果列表的方法会返回 [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)，而不是同步 `DynamoDbEnhanceClient` 为相同方法返回的 [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)。然后，您的应用程序可以向该发布者订阅处理程序，以异步方式处理结果，而无需阻塞。
```
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.
```
有关更完整的 `SdkPublisher API` 使用示例，请参阅本指南中讨论异步 `scan()` 方法的部分中的[示例](ddb-en-client-use-multirecord.md#ddb-en-client-use-multirecord-scan-async)。
# 数据类注释
下表列出了可用于数据类的注释，并提供了指向本指南中信息和示例的链接。该表按注释名称的字母升序排序。
**本指南中使用的数据类注释**
| 注释名称 | 注释适用于1 | 作用 | 本指南中显示的位置 |
| --- | --- | --- | --- |
| DynamoDbAtomicCounter | 属性2 | 每次向数据库写入记录时都会增加一个带标签的数字属性。 | [介绍和讨论。](ddb-en-client-extensions.md#ddb-en-client-extensions-ACE) |
| DynamoDbAttribute | 属性 | 定义或重命名映射到 DynamoDB 表属性的 Bean 属性。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbAutoGeneratedTimestampAttribute | 属性 | 每次成功将项目写入数据库时，都使用当前时间戳更新已标记的属性 | [介绍和讨论](ddb-en-client-extensions.md#ddb-en-client-extensions-AGTE)。 |
| DynamoDbAutoGeneratedUuid | 属性 | 向数据库写入新记录时，为属性生成唯一的 UUID（通用唯一标识符）。 | [介绍和讨论。](ddb-en-client-extensions.md#ddb-en-client-extensions-AGUE) |
| DynamoDbBean | class | 将数据类标记为可映射到表架构。 | 第一次是在“入门”部分的 [Customer 类](ddb-en-client-gs-tableschema.md#ddb-en-client-gs-tableschema-anno-bean-cust)上使用。本指南中展示了几种用法。 |
| DynamoDbConvertedBy | 属性 | 将自定义 AttributeConverter 与带注释的属性相关联。 | [初步讨论和示例。](ddb-en-client-adv-features-conversion.md#ddb-en-client-adv-features-conversion-single) |
| DynamoDbFlatten | 属性 | 扁平化单独的 DynamoDB 数据类的所有属性，并将它们作为顶级属性添加到从数据库读取的记录和写入数据库的记录中。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbIgnore | 属性 | 导致属性保持未映射状态。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbIgnoreNulls | 属性 | 防止保存嵌套 DynamoDb 对象的空属性。 | [讨论和示例。](ddb-en-client-adv-features-ignore-null.md) |
| DynamoDbImmutable | class | 将不可变数据类标记为可映射到表架构。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbPartitionKey | 属性 | 将属性标记为 DynamoDb 表的主分区键（哈希键）。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbPreserveEmptyObject | 属性 | 如果映射到带注释的属性的对象没有数据，则指定应使用所有空字段初始化该对象。 | [讨论和示例。](ddb-en-client-adv-features-empty.md) |
| DynamoDbSecondaryPartitionKey | 属性 | 将属性标记为全局二级属性的分区键。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbSecondarySortKey | 属性 | 将属性标记为全局或本地二级索引的可选排序键。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbSortKey | 属性 | 将属性标记为可选的主排序键（范围键）。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbUpdateBehavior | 属性 | 指定在“更新”操作（例如 UpdateItem）中更新此属性时的行为。 | [简介和示例。](ddb-en-client-adv-features-upd-behavior.md) |
| DynamoDbVersionAttribute | 属性 | 递增项目版本号。 | [介绍和讨论。](ddb-en-client-extensions.md#ddb-en-client-extensions-VRE) |
1您可以对 getter 或 setter 应用属性级注释，但不能同时应用两者。本指南显示了有关 getter 的注释。
2对于封装在 JavaBean 数据类中的值，通常使用术语 `property`。但是，为了与 DynamoDB 使用的术语保持一致，本指南（英文版）改用术语 `attribute`。（中文版中，两者的翻译均为“属性”。）