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 の属性を使用する
以下に示す `Person` クラスなどの Bean 定義は、追加の属性を持つ型を参照するプロパティ (または属性) を定義する場合があります。例えば、 `Person` クラスでは、 `mainAddress` は追加の値属性を定義する `Address` Bean を参照するプロパティです。`addresses` は Java Map を参照し、その要素は `Address` Bean を参照します。これらの複合型は、DynamoDB のコンテキストでデータ値に使用するシンプルな属性のコンテナと考えることができます。
DynamoDB は、マップ、リスト、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 マップドキュメントタイプに変換することに注意してください。
## `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 Enhanced Client API が次のスニペットを使用して `Person` クラスのテーブルスキーマを構築すると、API は`Address` および `PhoneNumber` クラスの使用を検出し、DynamoDB と動作する対応するマッピングを構築します。
```
TableSchema personTableSchema = TableSchema.fromBean(Person.class);
```
### ビルダーで抽象スキーマを使用する
別の方法は、次のコードに示すように、ネストされた各 Bean クラスに静的テーブルスキーマビルダーを使用することです。
`Address` および `PhoneNumber` クラスのテーブルスキーマは、DynamoDB テーブルでは使用できないという意味で抽象的です。これは、プライマリキーの定義が不足しているためです。ただし、`Person` クラスのテーブルスキーマではネストされたスキーマとして使用されます。
`PERSON_TABLE_SCHEMA` の定義のコメント 1 行目と 2 行目の後に、抽象テーブルスキーマを使用するコードが表示されます。`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` テーブルに 2 つの項目を設定し、3 回のスキャンオペレーションを実行します。
1 回目のスキャンでは、結果を他のスキャンオペレーションと比較するために、テーブル内のすべての項目にアクセスします。
2 回目のスキャンでは、[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` 属性値のみを返します。
3 回目のスキャンオペレーションでは、[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...)) ビルダーメソッドを使用して第 1 レベルの属性のデータ、`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]}
```
## 式で複合型を使用する
フィルター式や条件式などの式で複合型を使用するには、参照解除演算子を使用して複合型の構造をたどります。Object と Map の場合は `. (dot)` を使用し、List 要素の場合は `[n]` (要素のシーケンス番号を囲む角括弧) を使用します。Set の個々の要素を参照することはできませんが、 [`contains` 関数](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions)を使用できます。
次の例は、スキャンオペレーションで使用される 2 つのフィルター式を示しています。フィルター式は、結果に含める項目の一致条件を指定します。次の例では、前に示した `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"
}
]
}
```
## 複合型を含む項目の更新
複合型を含む項目を更新するには、2 つの基本的なアプローチがあります。
+ アプローチ 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 を再作成します。次に、ゲッターとセッターを使用して 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 のままにします。このアプローチでは、オブジェクトの null 値が SDK によってどのように処理されるかと、動作を制御する方法に注意する必要があります。
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"
}
}
*/
```
[更新式](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)の詳細については、「Amazon DynamoDB デベロッパーガイド」を参照してください。
#### `IgnoreNullsMode` オプションの説明
+ `IgnoreNullsMode.SCALAR_ONLY` - この設定を使用して、任意のレベルでスカラー属性を更新します。SDK は、null 以外のスカラー属性のみを DynamoDB に送信する更新ステートメントを作成します。SDK は、Bean または Map の null 値のスカラー属性を無視し、DynamoDB に保存された値を保持します。
Map または Bean のスカラー属性を更新する場合、Map は DynamoDB に既に存在している必要があります。DynamoDB のオブジェクトにまだ存在しないオブジェクトに Map または Bean を追加すると、「*更新式で指定されたドキュメントパスが更新に対して無効です*」というメッセージと `DynamoDbException` が表示されます。属性を更新する前に、 `MAPS_ONLY` モードを使用して DynamoDB に Bean または Map を追加する必要があります。
+ `IgnoreNullsMode.MAPS_ONLY` - この設定を使用して、 Bean または Map プロパティを追加または置き換えます。SDK は、オブジェクトで提供される Map または Bean を置き換えるか、追加します。オブジェクト内の null の Bean または Map は無視され、DynamoDB に存在する Map が保持されます。
+ `IgnoreNullsMode.DEFAULT` - この設定では、SDK が null 値を無視することはありません。すべてのレベルの null のスカラー属性は、null に更新されます。SDK は、オブジェクト内の null 値の Bean、Map、List、または Set プロパティを DynamoDB で null に更新します。このモードを使用する場合、またはデフォルトモードであるためモードを指定しない場合、更新用のオブジェクトで提供されている値が DynamoDB で null に設定されないように、まず項目を取得する必要があります。ただし、値を null に設定することが意図されている場合は除きます。
すべてのモードで、null 以外の List または Set を持つオブジェクトを `updateItem` に提供すると、List または Set は DynamoDB に保存されます。
#### モードを使用する理由
Bean または Map のあるオブジェクトを `updateItem` メソッドに渡すと、SDK は Bean のプロパティ値 (または Map 内のエントリ値) を使用して項目を更新するか、または 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'.
*/
```
次の 2 つの例は、`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` のいずれかを使用できます。
**各モードで、 `updateItem` に渡されたオブジェクト内のどの null 値プロパティが SDK によって無視されますか?**
| プロパティの型 | 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 に空のオブジェクトを再作成させたい場合は、内部 Bean のゲッターに `@DynamoDbPreserveEmptyObject` の注釈を付けます。
注釈の仕組みを説明するために、コード例では次の 2 つの bean を使用しています。
## 例: Bean
次のデータクラスには 2 つの `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;
}
```
## 代わりの静的スキーマ
Bean の注釈の代わりに、以下の `StaticTableSchema` バージョンのテーブルスキーマを使用できます。
```
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();
}
```
# ネストされたオブジェクトの NULL 属性の保存を避ける
`@DynamoDbIgnoreNulls` 注釈を適用することで、データクラスオブジェクトを DynamoDB に保存するときに、ネストされたオブジェクトの null 属性をスキップできます。これとは対照的に、NULL 値を持つ最上位の属性はデータベースに保存されません。
注釈の仕組みを説明するために、コード例では次の 2 つの Bean を使用しています。
## 例: Bean
次のデータクラスには 2 つの `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` オブジェクトを作成し、その 2 つの属性のうち 1 つだけに値を設定します。
```
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` が 1 つの属性を出力していることが分かります。
```
innerBeanWithIgnoreNullsAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200)})
```
`innerBeanWithoutAnno` インスタンスは 2 つの属性を出力します。1 つの属性の値は 200 で、もう 1 つは NULL 値の属性です。
```
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 は、v1.x の[ドキュメント API](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/DynamoDB.html) AWS SDK for Java の後継です。
**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 には、DynamoDB 拡張クライアント API に必要なものと同じ[依存関係](ddb-en-client-getting-started.md#ddb-en-client-gs-dep)が必要です。また、このトピックの冒頭で示したように、[`DynamoDbEnhancedClient` インスタンス](ddb-en-client-getting-started-dynamodbTable.md#ddb-en-client-getting-started-dynamodbTable-eclient)も必要です。
Enhanced Document API は のバージョン 2.20.3 でリリースされたため AWS SDK for Java 2.x、そのバージョン以降が必要です。
## `DocumentTableSchema` および `DynamoDbTable` を作成する
拡張ドキュメント API を使用して DynamoDB テーブルに対してコマンドを呼び出すには、テーブルをクライアント側の [DynamoDbTable](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) のビルダーには、プライマリインデックスキーと 1 つ以上の属性コンバータープロバイダーが必要です。この `AttributeConverterProvider.defaultProvider()` メソッドは[デフォルトタイプ](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/internal/converter/attribute/package-summary.html)のコンバーターを提供します。カスタム属性コンバータープロバイダーを提供する場合でも、指定する必要があります。オプションのセカンダリインデックスキーをビルダーに追加できます。
次のコードスニペットは、スキーマレス `person` オブジェクトを格納する DynamoDB `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 文字列を使用して、1 つのメソッド呼び出しに `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` インスタンスを構築することもできます。
次の例では、前の例の JSON 文字列から作成された拡張ドキュメントと同様の `person` 拡張ドキュメントを作成します。
```
/* 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 から拡張ドキュメントインスタンスを読み取った後、`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` インスタンスは、マッピングされたデータクラスの代わりに、`[DynamoDbTable](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html)` または [DynamoDbEnhancedClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.html) の任意のメソッドで使用できます。
# 拡張ドキュメント属性にはカスタムオブジェクトとしてアクセスできます。
拡張ドキュメント API では、スキーマレス構造の属性を読み書きするための API を提供するだけでなく、カスタムクラスのインスタンスとの間で属性を変換できます。
拡張ドキュメント API は、DynamoDB 拡張クライアント API の一部として[コントロール属性変換](ddb-en-client-adv-features-conversion.md)セクションに表示された `AttributeConverterProvider` と `AttributeConverter` を使用します。
次の例では、`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;
}
}
```
## アドレスを提供するヘルパーメソッド
次のヘルパーメソッドは、値にジェネリック `Map` インスタンスではなく、値にカスタム `Address` インスタンスを使用するマップを提供します。
```
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 とは独立して使用することもできます。
JSON 文字列やカスタムオブジェクトを、次の例のように `AttributeValues` の低レベルのマップに変換できるようにするために `EnhancedDocuments` を使用できます。
```
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 は、マッピング操作以外の機能を提供するプラグイン拡張機能をサポートしています。拡張機能は、読み取りおよび書き込みオペレーション中に 2 つのフックメソッドを使用してデータを変更します。
+ `beforeWrite()` - 発生する前に書き込みオペレーションを変更する
+ `afterRead()` - 読み取りオペレーションの実行後にその結果を変更する
一部のオペレーション (アイテムの更新など) は書き込みと読み取りの両方を実行するため、両方のフックメソッドが呼び出されます。
## 拡張機能のロード方法
拡張機能は、拡張クライアントビルダーで指定された順序でロードされます。1 つのエクステンションが以前のエクステンションによって変換された値に作用する可能性があるため、ロード順序は重要な場合があります。
デフォルトでは、拡張クライアントは 2 つの拡張機能をロードします。
+ `[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)` - カウンター属性を自動的に増分する
拡張クライアントビルダーでデフォルトの動作を上書きして、任意の拡張機能を読み込むことができます。デフォルトの拡張機能を使いたくない場合は、none を指定することもできます。
**重要**
独自の拡張機能をロードしても、拡張クライアントはデフォルトの拡張機能をロードしません。いずれかのデフォルトの拡張機能と同じ動作をさせたい場合は、拡張機能のリストに明示的に追加する必要があります。
次の例は、 `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 つ以上のプロパティを更新して変更を保存する場合には、クライアント側とサーバー側のバージョン番号が一致する場合のみ、オペレーションが成功します。
成功すると、バージョン番号は自動的に 1 ずつ増加します。これは `@DynamoDbVersionAttribute(incrementBy = X)` で設定できます。
**`deleteItem`**
`DynamoDbVersionAttribute` 注釈は効力を発揮しません。アイテムを削除するときは、条件式を手動で追加する必要があります。
次の例では、条件式を追加して、削除されたアイテムが読み取られたアイテムであることを確認します。次の例では、`recordVersion` は `@DynamoDbVersionAttribute` で注釈を付けた Bean の属性です。
```
// 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())
```
### AutoGeneratedUuidExtension を使用して UUID を生成する
`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` メソッドに対しては入力されないようにするには、次のスニペットに示すように、[更新動作](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` インターフェイスを実装することで、カスタム拡張機能を作成できます。次のカスタム拡張機能クラスは、データベース内の項目にまだ属性がない場合に、更新式を使用して `registrationDate` 属性を設定する `beforeWrite()` メソッドを示しています。
```
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. 1 つのデータオブジェクトを返すメソッドは、結果だけではなく結果の `CompletableFuture` を返します。そうすることで、アプリケーションは結果をブロックせずに他の処理を行うことができます。次のスニペットは、非同期 `getItem()` メソッドを示しています。
```
CompletableFuture result = customerDynamoDbTable.getItem(customer);
// Perform other work here.
return result.join(); // Now block and wait for the result.
```
1. ページ分割された結果リストを返すメソッドは、同期 `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) の代わりに、[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) を返します。その後、アプリケーションはハンドラーをそのパブリッシャーにサブスクライブして、結果をブロックせずに非同期的に処理できます。
```
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/ja_jp/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 | データクラスをテーブルスキーマにマッピング可能としてマークします。 | 「はじめに」セクションの[カスタマークラス](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/ja_jp/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/ja_jp/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbIgnoreNulls | 属性 | ネストされた DynamoDB オブジェクトの NULL 属性が保存されないようにします。 | [ディスカッションと例。](ddb-en-client-adv-features-ignore-null.md) |
| DynamoDbImmutable | class | 変更不可能なデータクラスをテーブルスキーマにマッピング可能としてマークします。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/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/ja_jp/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbPreserveEmptyObject | 属性 | 注釈付き属性にマップされたオブジェクトにデータが存在しない場合、オブジェクトはすべて NULL フィールドで初期化されるように指定します。 | [ディスカッションと例。](ddb-en-client-adv-features-empty.md) |
| DynamoDbSecondaryPartitionKey | 属性 | グローバルセカンダリインデックスのパーティションキーとして属性をマークします。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/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/ja_jp/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/ja_jp/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属性レベルの注釈はゲッターまたはセッターに適用できますが、両方に適用することはできません。このガイドでは、ゲッターの注釈を示します。
2通常、`property` という用語は JavaBean データクラスにカプセル化された値に使用されます。ただし、このガイドでは、DynamoDB で使用されている用語との一貫性を保つため、代わりに `attribute` という用語を使用しています。