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();
```
Contoh skema statis sebelumnya menggunakan kelas data berikut.
#### Kelas data
------
#### [ 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;
}
```
------
Anda dapat menggunakan pola pembangun untuk meratakan sebanyak mungkin kelas yang memenuhi syarat yang Anda butuhkan.
## Implikasi untuk kode lain
Bila Anda menggunakan `@DynamoDbFlatten` atribut (atau metode `flatten()` builder), item di DynamoDB berisi atribut untuk setiap atribut dari objek yang disusun. Ini juga mencakup atribut dari objek penulisan.
Sebaliknya, jika Anda membuat anotasi kelas data dengan kelas tersusun dan tidak menggunakan`@DynamoDbFlatten`, item disimpan dengan objek tersusun sebagai atribut tunggal.
Misalnya, bandingkan `Customer` kelas yang ditunjukkan dalam [perataan dengan contoh komposisi dengan](#ddb-en-client-adv-features-flatmap-comp-anno) dan tanpa perataan atribut. `record` Anda dapat memvisualisasikan perbedaannya dengan JSON seperti yang ditunjukkan pada tabel berikut.
****
| Dengan perataan | Tanpa perataan |
| --- | --- |
| 3 atribut | 2 atribut |
| {
"id": "1",
"createdDate": "today",
"name": "my name"
} | {
"id": "1",
"record": {
"createdDate": "today",
"name": "my name"
}
} |
Perbedaannya menjadi penting jika Anda memiliki kode lain yang mengakses tabel DynamoDB yang mengharapkan untuk menemukan atribut tertentu.
# Bekerja dengan atribut yang kacang, peta, daftar, dan set
Definisi kacang, seperti `Person` kelas yang ditunjukkan di bawah ini, mungkin mendefinisikan properti (atau atribut) yang merujuk ke tipe dengan atribut tambahan. Misalnya, di `Person` kelas, `mainAddress` adalah properti yang mengacu pada `Address` kacang yang mendefinisikan atribut nilai tambahan. `addresses`mengacu pada Peta Jawa, yang unsur-unsurnya mengacu pada `Address` kacang. Tipe kompleks ini dapat dianggap sebagai wadah atribut sederhana yang Anda gunakan untuk nilai datanya dalam konteks DynamoDB.
*DynamoDB mengacu pada properti nilai elemen bersarang, seperti peta, daftar, atau kacang, sebagai atribut bersarang.* *Panduan [Pengembang Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes) mengacu pada bentuk yang disimpan dari peta Java, daftar atau kacang sebagai jenis dokumen.* Atribut sederhana yang Anda gunakan untuk nilai data mereka di Java disebut sebagai *tipe skalar* di DynamoDB. Set, yang berisi beberapa elemen skalar dari jenis yang sama, dan disebut sebagai *tipe set*.
Penting untuk diketahui bahwa DynamoDB Enhanced Client API mengonversi properti yang bean ke jenis dokumen peta DynamoDB saat disimpan.
## `Person` kelas
```
@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` kelas
```
@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` kelas
```
@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 + '\'' +
'}';
}
}
```
## Simpan tipe kompleks
### Gunakan kelas data beranotasi
Anda menyimpan atribut bersarang untuk kelas khusus hanya dengan membuat anotasi. `Address`Kelas dan `PhoneNumber` kelas yang ditampilkan sebelumnya dianotasi hanya dengan anotasi. `@DynamoDbBean` Saat DynamoDB Enhanced Client API membangun skema tabel untuk `Person` kelas dengan cuplikan berikut, API akan menemukan penggunaan class `PhoneNumber` dan dan membangun pemetaan yang sesuai agar berfungsi dengan DynamoDB. `Address`
```
TableSchema personTableSchema = TableSchema.fromBean(Person.class);
```
### Gunakan skema abstrak dengan pembangun
Pendekatan alternatifnya adalah dengan menggunakan pembangun skema tabel statis untuk setiap kelas kacang bersarang seperti yang ditunjukkan pada kode berikut.
Skema tabel untuk `PhoneNumber` kelas `Address` dan abstrak dalam arti bahwa mereka tidak dapat digunakan dengan tabel DynamoDB. Ini karena mereka tidak memiliki definisi untuk kunci utama. Mereka digunakan, bagaimanapun, sebagai skema bersarang dalam skema tabel untuk kelas. `Person`
Setelah baris komentar 1 dan 2 dalam definisi`PERSON_TABLE_SCHEMA`, Anda melihat kode yang menggunakan skema tabel abstrak. Penggunaan `documentOf` dalam `EnhanceType.documentOf(...)` metode tidak menunjukkan bahwa metode mengembalikan `EnhancedDocument` jenis API Dokumen yang Ditingkatkan. `documentOf(...)`Metode dalam konteks ini mengembalikan objek yang tahu bagaimana memetakan argumen kelasnya ke dan dari DynamoDB atribut tabel dengan menggunakan argumen skema tabel.
#### Kode skema statis
```
// 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();
```
## Atribut proyek dari tipe kompleks
Untuk `query()` dan `scan()` metode, Anda dapat menentukan atribut mana yang ingin Anda kembalikan dalam hasil dengan menggunakan panggilan metode seperti `addNestedAttributeToProject()` dan`attributesToProject()`. DynamoDB Enhanced Client API mengubah parameter panggilan metode Java [menjadi ekspresi proyeksi sebelum permintaan dikirim](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html).
Contoh berikut mengisi `Person` tabel dengan dua item, kemudian melakukan tiga operasi pemindaian.
Pemindaian pertama mengakses semua item dalam tabel untuk membandingkan hasilnya dengan operasi pemindaian lainnya.
Pemindaian kedua menggunakan metode [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/ScanEnhancedRequest.Builder.html#addNestedAttributeToProject(software.amazon.awssdk.enhanced.dynamodb.NestedAttributeName)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/ScanEnhancedRequest.Builder.html#addNestedAttributeToProject(software.amazon.awssdk.enhanced.dynamodb.NestedAttributeName))builder untuk mengembalikan hanya nilai `street` atribut.
Operasi pemindaian ketiga menggunakan metode [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/ScanEnhancedRequest.Builder.html#attributesToProject(java.lang.String...)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/ScanEnhancedRequest.Builder.html#attributesToProject(java.lang.String...))builder untuk mengembalikan data untuk atribut tingkat pertama,`hobbies`. Jenis atribut `hobbies` adalah daftar. Untuk mengakses item daftar individual, lakukan `get()` operasi pada daftar.
```
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
```
**catatan**
Jika `attributesToProject()` metode mengikuti metode pembangun lain yang menambahkan atribut yang ingin Anda proyeksikan, daftar nama atribut yang diberikan ke `attributesToProject()` menggantikan semua nama atribut lainnya.
Pemindaian yang dilakukan dengan `ScanEnhancedRequest` instance dalam cuplikan berikut hanya mengembalikan data hobi.
```
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]}
```
Cuplikan kode berikut menggunakan `attributesToProject()` metode terlebih dahulu. Urutan ini mempertahankan semua atribut lain yang diminta.
```
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]}
```
## Gunakan tipe kompleks dalam ekspresi
Anda dapat menggunakan tipe kompleks dalam ekspresi, seperti ekspresi filter dan ekspresi kondisi, dengan menggunakan operator dereferencing untuk menavigasi struktur tipe kompleks. Untuk objek dan peta, gunakan `. (dot)` dan untuk elemen daftar gunakan `[n]` (tanda kurung siku di sekitar nomor urut elemen). Anda tidak dapat merujuk ke elemen individual dari satu set, tetapi Anda dapat menggunakan [`contains`fungsi](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions) tersebut.
Contoh berikut menunjukkan dua ekspresi filter yang digunakan dalam operasi scan. Ekspresi filter menentukan kondisi kecocokan untuk item yang Anda inginkan dalam hasil. Contoh menggunakan`Person`,`Address`, dan `PhoneNumber` kelas yang ditampilkan sebelumnya.
```
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");
}
```
### Metode pembantu yang mengisi tabel
```
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);
}
```
### Representasi JSON item dalam database
```
{
"id": 1,
"addresses": {
"billing": {
"city": "BillingTown1",
"state": "BS1",
"street": null,
"zipCode": null
},
"mailing": {
"city": "MailingTown1",
"state": "MS1",
"street": null,
"zipCode": null
}
},
"firstName": "FirstName1",
"lastName": "LastName1",
"phoneNumbers": [
{
"number": "111-111-1111",
"type": "work"
},
{
"number": "222-222-2222",
"type": "home"
}
]
}
{
"id": 2,
"addresses": {
"billing": {
"city": "BillingTown2",
"state": "BS2",
"street": null,
"zipCode": null
},
"mailing": {
"city": "MailingTown2",
"state": "MS2",
"street": null,
"zipCode": null
}
},
"firstName": "FirstName2",
"lastName": "LastName2",
"phoneNumbers": [
{
"number": "333-333-3333",
"type": "work"
},
{
"number": "444-444-4444",
"type": "cell"
}
]
}
```
## Perbarui item yang berisi tipe kompleks
Untuk memperbarui item yang berisi tipe kompleks, Anda memiliki dua pendekatan dasar:
+ Pendekatan 1: Pertama ambil item (dengan menggunakan`getItem`), perbarui objek, lalu panggil`DynamoDbTable#updateItem`.
+ Pendekatan 2: Jangan mengambil item, tetapi buat instance baru, atur properti yang ingin Anda perbarui, dan kirimkan instance `DynamoDbTable#updateItem` dengan menyetel nilai yang sesuai dari. [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) Pendekatan ini tidak mengharuskan Anda mengambil item sebelum memperbaruinya.
Contoh yang ditunjukkan di bagian ini menggunakan`Person`,`Address`, dan `PhoneNumber` kelas yang ditunjukkan sebelumnya.
### Perbarui pendekatan 1: ambil, lalu perbarui
Dengan menggunakan pendekatan ini, Anda memastikan bahwa tidak ada data yang hilang pada pembaruan. DynamoDB Enhanced Client API membuat ulang bean dengan atribut dari item yang disimpan di DynamoDB termasuk nilai tipe kompleks. Anda kemudian perlu menggunakan getter dan setter untuk memperbarui kacang. Kelemahan dari pendekatan ini adalah biaya yang Anda keluarkan untuk mengambil item terlebih dahulu.
Contoh berikut menunjukkan bahwa tidak ada data yang hilang jika Anda pertama kali mengambil item sebelum memperbaruinya.
```
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;
}
```
### Pendekatan pembaruan 2: Gunakan `IgnoreNullsMode` enum tanpa mengambil item terlebih dahulu
Untuk memperbarui item di DynamoDB, Anda dapat memberikan objek baru yang hanya memiliki properti yang ingin diperbarui dan membiarkan nilai lainnya sebagai null. Dengan pendekatan ini, Anda perlu mengetahui bagaimana nilai nol dalam objek diperlakukan oleh SDK dan bagaimana Anda dapat mengontrol perilaku.
Untuk menentukan properti bernilai nol mana yang ingin diabaikan oleh SDK, berikan `IgnoreNullsMode` enum saat Anda membuat. [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) Sebagai contoh menggunakan salah satu nilai yang disebutkan, cuplikan berikut menggunakan mode. `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"
}
}
*/
```
[Panduan Pengembang Amazon DynamoDB berisi informasi lebih lanjut tentang ekspresi pembaruan.](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)
#### Deskripsi opsi `IgnoreNullsMode`
+ `IgnoreNullsMode.SCALAR_ONLY`- Gunakan pengaturan ini untuk memperbarui atribut skalar di tingkat manapun. SDK membuat pernyataan pembaruan yang hanya mengirimkan atribut skalar non-null ke DynamoDB. SDK mengabaikan atribut skalar bernilai nol dari kacang atau peta, mempertahankan nilai yang disimpan di DynamoDB.
Saat Anda memperbarui atribut skalar map atau bean, peta harus sudah ada di DynamoDB. Jika Anda menambahkan peta atau kacang ke objek yang belum ada untuk objek di DynamoDB, Anda mendapatkan dengan *pesan Jalur dokumen `DynamoDbException` yang disediakan dalam ekspresi pembaruan tidak valid untuk pembaruan*. Anda harus menggunakan `MAPS_ONLY` mode untuk menambahkan kacang atau peta ke DynamoDB sebelum Anda memperbarui salah satu atributnya.
+ `IgnoreNullsMode.MAPS_ONLY`- Gunakan pengaturan ini untuk menambah atau mengganti properti yang merupakan kacang atau peta. SDK menggantikan atau menambahkan peta atau kacang apa pun yang disediakan dalam objek. Setiap kacang atau peta yang null dalam objek diabaikan, mempertahankan peta yang ada di DynamoDB.
+ `IgnoreNullsMode.DEFAULT`- Dengan pengaturan ini, SDK tidak pernah mengabaikan nilai null. Atribut skalar pada tingkat manapun yang null diperbarui ke null. SDK memperbarui properti bean, map, list, atau set bernilai nol dalam objek ke null di DynamoDB. Saat Anda menggunakan mode ini—atau tidak menyediakan mode karena ini adalah mode default—Anda harus mengambil item terlebih dahulu sehingga nilai di DynamoDB tidak disetel ke null yang disediakan dalam objek untuk diperbarui, kecuali niat Anda adalah untuk mengatur nilai ke null.
Dalam semua mode, jika Anda memberikan objek `updateItem` yang memiliki daftar atau set non-null, daftar atau set disimpan ke DynamoDB.
#### Mengapa mode?
Saat Anda memberikan objek dengan kacang atau peta ke `updateItem` metode, SDK tidak dapat mengetahui apakah objek tersebut harus menggunakan nilai properti dalam kacang (atau nilai entri di peta) untuk memperbarui item, atau apakah keseluruhan bean/map harus menggantikan apa yang telah disimpan ke DynamoDB.
Bekerja dari contoh sebelumnya yang menunjukkan pengambilan item terlebih dahulu, mari kita coba memperbarui `city` atribut `mainAddress` tanpa pengambilan.
```
/* 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'.
*/
```
Dua contoh berikut menunjukkan penggunaan nilai `MAPS_ONLY` dan `SCALAR_ONLY` enumerasi. `MAPS_ONLY`menambahkan peta dan `SCALAR_ONLY` memperbarui peta.
##### Contoh `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.
}
```
Lihat tabel berikut untuk melihat nilai null mana yang diabaikan untuk setiap mode. Anda sering dapat bekerja dengan salah satu `SCALAR_ONLY` dan `MAPS_ONLY` kecuali ketika Anda bekerja dengan kacang atau peta.
**Properti bernilai nol mana dalam objek yang dikirimkan yang diabaikan SDK untuk `updateItem` setiap mode?**
| Jenis properti | dalam mode SCALAR\$1ONLY | dalam mode MAPS\$1ONLY | dalam mode DEFAULT |
| --- | --- | --- | --- |
| Skalar teratas | Ya | Ya | Tidak |
| Kacang atau peta | Ya | Ya | Tidak |
| Nilai skalar entri kacang atau peta | Ya1 | Tidak 2 | Tidak |
| Daftar atau set | Ya | Ya | Tidak |
1 Ini mengasumsikan peta sudah ada di DynamoDB. Nilai skalar apa pun—null atau bukan null—dari kacang atau peta yang Anda berikan di objek untuk pembaruan mengharuskan jalur ke nilai ada di DynamoDB. SDK membuat jalur ke atribut dengan menggunakan operator `. (dot)` dereference sebelum mengirimkan permintaan.
2 Karena Anda menggunakan `MAPS_ONLY` mode untuk sepenuhnya mengganti atau menambahkan kacang atau peta, semua nilai nol dalam kacang atau peta dipertahankan di peta yang disimpan ke DynamoDB.
# Pertahankan benda kosong dengan `@DynamoDbPreserveEmptyObject`
Jika Anda menyimpan kacang ke Amazon DynamoDB dengan objek kosong dan Anda ingin SDK membuat ulang objek kosong saat pengambilan, beri anotasi pengambil kacang bagian dalam dengan. `@DynamoDbPreserveEmptyObject`
Untuk mengilustrasikan cara kerja anotasi, contoh kode menggunakan dua kacang berikut.
## Contoh kacang
Kelas data berikut berisi dua `InnerBean` bidang. Metode getter,`getInnerBeanWithoutAnno()`, tidak dijelaskan dengan. `@DynamoDbPreserveEmptyObject` `getInnerBeanWithAnno()`Metode ini dijelaskan.
```
@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();
}
}
```
Contoh dari `InnerBean` kelas berikut adalah bidang `MyBean` dan diinisialisasi sebagai objek kosong dalam kode contoh.
```
@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 + '\'' +
'}';
}
}
```
Contoh kode berikut menyimpan `MyBean` objek dengan kacang dalam yang diinisialisasi ke DynamoDB dan kemudian mengambil item tersebut. Output yang dicatat menunjukkan bahwa tidak `innerBeanWithoutAnno` diinisialisasi, tetapi `innerBeanWithAnno` telah dibuat.
```
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;
}
```
## Skema statis alternatif
Anda dapat menggunakan `StaticTableSchema` versi skema tabel berikut sebagai pengganti anotasi pada kacang.
```
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();
}
```
# Hindari menyimpan atribut null dari objek bersarang
Anda dapat melewati atribut null dari objek bersarang saat menyimpan objek kelas data ke DynamoDB dengan menerapkan anotasi. `@DynamoDbIgnoreNulls` Sebaliknya, atribut tingkat atas dengan nilai null tidak pernah disimpan ke database.
Untuk mengilustrasikan cara kerja anotasi, contoh kode menggunakan dua kacang berikut.
## Contoh kacang
Kelas data berikut berisi dua `InnerBean` bidang. Metode getter,`getInnerBeanWithoutAnno()`, tidak dijelaskan. `getInnerBeanWithIgnoreNullsAnno()`Metode ini dianotasi dengan. `@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();
}
}
```
Contoh dari `InnerBean` kelas berikut adalah bidang `MyBean` dan digunakan dalam kode contoh berikut.
```
@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();
}
}
```
Contoh kode berikut menciptakan `InnerBean` objek dan menetapkan hanya satu dari dua atribut dengan nilai.
```
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);
}
```
Untuk memvisualisasikan data tingkat rendah yang dikirim ke DynamoDB, kode mencatat peta atribut sebelum menyimpan objek. `MyBean`
Output yang dicatat menunjukkan bahwa `innerBeanWithIgnoreNullsAnno` output satu atribut,
```
innerBeanWithIgnoreNullsAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200)})
```
`innerBeanWithoutAnno`Instance menghasilkan dua atribut. Satu atribut memiliki nilai 200 dan yang lainnya adalah atribut bernilai nol.
```
innerBeanWithoutAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200), innerBeanFieldString=AttributeValue(NUL=true)})
```
## Representasi JSON dari peta atribut
Representasi JSON berikut membuatnya lebih mudah untuk melihat data yang disimpan ke DynamoDB.
```
{
"id": {
"S": "1"
},
"innerBeanWithIgnoreNullsAnno": {
"M": {
"innerBeanFieldInteger": {
"N": "200"
}
}
},
"innerBeanWithoutAnno": {
"M": {
"innerBeanFieldInteger": {
"N": "200"
},
"innerBeanFieldString": {
"NULL": true
}
}
}
}
```
## Skema statis alternatif
Anda dapat menggunakan `StaticTableSchema` versi berikut dari skema tabel di tempat anotasi kelas data.
```
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();
}
```
# Bekerja dengan dokumen JSON dengan Enhanced Document API untuk DynamoDB
[Enhanced Document API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/package-summary.html) for AWS SDK for Java 2.x dirancang untuk bekerja dengan data berorientasi dokumen yang tidak memiliki skema tetap. Namun, ini juga memungkinkan Anda menggunakan kelas khusus untuk memetakan atribut individual.
Enhanced Document API adalah penerus [Document API](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/DynamoDB.html) dari AWS SDK untuk Java v1.x.
**Contents**
+ [Mulai menggunakan Enhanced Document API](ddb-en-client-doc-api-steps.md)
+ [Buat `DocumentTableSchema` dan a `DynamoDbTable`](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema)
+ [Membangun dokumen yang disempurnakan](ddb-en-client-doc-api-steps-create-ed.md)
+ [Membangun dari string JSON](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromJson)
+ [Membangun dari elemen individu](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts)
+ [Lakukan operasi CRUD](ddb-en-client-doc-api-steps-use.md)
+ [Akses atribut dokumen yang disempurnakan sebagai objek khusus](ddb-en-client-doc-api-convert.md)
+ [Gunakan `EnhancedDocument` tanpa DynamoDB](ddb-en-client-doc-api-standalone.md)
# Mulai menggunakan Enhanced Document API
Enhanced Document API memerlukan [dependensi](ddb-en-client-getting-started.md#ddb-en-client-gs-dep) yang sama yang diperlukan untuk DynamoDB Enhanced Client API. Ini juga membutuhkan [`DynamoDbEnhancedClient`contoh](ddb-en-client-getting-started-dynamodbTable.md#ddb-en-client-getting-started-dynamodbTable-eclient) seperti yang ditunjukkan di awal topik ini.
Karena API Dokumen yang Ditingkatkan dirilis dengan versi 2.20.3 AWS SDK for Java 2.x, Anda memerlukan versi itu atau lebih tinggi.
## Buat `DocumentTableSchema` dan a `DynamoDbTable`
Untuk menjalankan perintah terhadap tabel DynamoDB menggunakan Enhanced Document API, kaitkan tabel dengan objek resource < > sisi [DynamoDbTableklien EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html).
`table()`Metode klien yang disempurnakan membuat `DynamoDbTable` instance dan membutuhkan parameter untuk nama tabel DynamoDB dan a. `DocumentTableSchema`
Pembangun untuk a [DocumentTableSchema](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/DocumentTableSchema.html)memerlukan kunci indeks utama dan satu atau lebih penyedia konverter atribut. `AttributeConverterProvider.defaultProvider()`Metode ini menyediakan konverter untuk [tipe default](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/internal/converter/attribute/package-summary.html). Itu harus ditentukan bahkan jika Anda menyediakan penyedia konverter atribut khusus. Anda dapat menambahkan kunci indeks sekunder opsional ke pembangun.
Cuplikan kode berikut menunjukkan kode yang menghasilkan representasi sisi klien dari tabel DynamoDB yang menyimpan objek tanpa skema. `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.
```
Berikut ini menunjukkan representasi JSON dari `person` objek yang digunakan di seluruh bagian ini.
### Objek 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"
}
]
}
```
# Membangun dokumen yang disempurnakan
An `[EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html)` merupakan objek tipe dokumen yang memiliki struktur kompleks dengan atribut bersarang. Sebuah `EnhancedDocument` membutuhkan atribut tingkat atas yang cocok dengan atribut kunci utama yang ditentukan untuk atribut. `DocumentTableSchema` Konten yang tersisa bersifat arbitrer dan dapat terdiri dari atribut tingkat atas dan juga atribut yang sangat bersarang.
Anda membuat `EnhancedDocument` instance dengan menggunakan builder yang menyediakan beberapa cara untuk menambahkan elemen.
## Membangun dari string JSON
Dengan string JSON, Anda dapat membangun panggilan `EnhancedDocument` dalam satu metode. Cuplikan berikut membuat `EnhancedDocument` dari string JSON dikembalikan oleh metode helper. `jsonPerson()` `jsonPerson()`Metode mengembalikan versi string JSON dari [objek orang](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema-obj) yang ditunjukkan sebelumnya.
```
EnhancedDocument document =
EnhancedDocument.builder()
.json( jsonPerson() )
.build());
```
## Membangun dari elemen individu
Atau, Anda dapat membangun sebuah `EnhancedDocument` instance dari komponen individual menggunakan metode type-safe dari builder.
Contoh berikut membangun dokumen yang `person` disempurnakan mirip dengan dokumen yang disempurnakan yang dibangun dari string JSON pada contoh sebelumnya.
```
/* 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();
```
### Metode pembantu
```
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"));
}
```
# Lakukan operasi CRUD
Setelah Anda mendefinisikan sebuah `EnhancedDocument` instance, Anda dapat menyimpannya ke tabel DynamoDB. Cuplikan kode berikut menggunakan [personDocument](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts) yang dibuat dari elemen individual.
```
documentDynamoDbTable.putItem(personDocument);
```
Setelah Anda membaca instance dokumen yang disempurnakan dari DynamoDB, Anda dapat mengekstrak nilai atribut individual menggunakan getter seperti yang ditunjukkan dalam cuplikan kode berikut yang mengakses data yang disimpan dari. `personDocument` Atau, Anda dapat mengekstrak konten lengkap ke string JSON seperti yang ditunjukkan pada bagian terakhir dari kode contoh.
```
// 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`instance dapat digunakan dengan metode apa pun dari `[DynamoDbTable](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html)` atau [DynamoDbEnhancedClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.html)di tempat kelas data yang dipetakan.
# Akses atribut dokumen yang disempurnakan sebagai objek khusus
Selain menyediakan API untuk membaca dan menulis atribut dengan struktur tanpa skema, API Dokumen yang Ditingkatkan memungkinkan Anda mengonversi atribut ke dan dari instance kelas khusus.
Enhanced Document API menggunakan `AttributeConverterProvider` s dan `AttributeConverter` s yang ditampilkan di bagian [konversi atribut kontrol](ddb-en-client-adv-features-conversion.md) sebagai bagian dari DynamoDB Enhanced Client API.
Dalam contoh berikut, kita menggunakan a `CustomAttributeConverterProvider` dengan `AddressConverter` kelas bersarang untuk mengkonversi `Address` objek.
Contoh ini menunjukkan bahwa Anda dapat mencampur data dari kelas dan juga data dari struktur yang dibangun sesuai kebutuhan. Contoh ini juga menunjukkan bahwa kelas kustom dapat digunakan pada setiap tingkat struktur bersarang. `Address`Objek dalam contoh ini adalah nilai yang digunakan dalam peta.
```
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`kode
```
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` kelas
```
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;
}
}
```
## Metode pembantu yang menyediakan alamat
Metode pembantu berikut menyediakan peta yang menggunakan `Address` instance kustom untuk nilai daripada `Map` contoh generik untuk nilai.
```
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);
}
```
# Gunakan `EnhancedDocument` tanpa DynamoDB
Meskipun Anda biasanya menggunakan instance `EnhancedDocument` untuk membaca dan menulis item DynamoDB tipe dokumen, itu juga dapat digunakan secara independen dari DynamoDB.
Anda dapat menggunakan kemampuan mereka `EnhancedDocuments` untuk mengkonversi antara string JSON atau objek kustom ke peta tingkat rendah `AttributeValues` seperti yang ditunjukkan dalam contoh berikut.
```
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'}
*/
```
**catatan**
Bila Anda menggunakan dokumen yang disempurnakan independen dari tabel DynamoDB, pastikan Anda secara eksplisit menetapkan penyedia konverter atribut pada pembangun.
Sebaliknya, skema tabel dokumen memasok penyedia konverter ketika dokumen yang disempurnakan digunakan dengan tabel DynamoDB.
# Gunakan ekstensi untuk menyesuaikan operasi DynamoDB Enhanced Client
DynamoDB Enhanced Client API mendukung ekstensi plugin yang menyediakan fungsionalitas di luar operasi pemetaan. Ekstensi menggunakan dua metode hook untuk memodifikasi data selama operasi baca dan tulis:
+ `beforeWrite()`- Memodifikasi operasi tulis sebelum itu terjadi
+ `afterRead()`- Memodifikasi hasil operasi baca setelah itu terjadi
Beberapa operasi (seperti pembaruan item) melakukan penulisan dan kemudian membaca, sehingga kedua metode kait dipanggil.
## Bagaimana ekstensi dimuat
Ekstensi dimuat dalam urutan yang Anda tentukan di pembuat klien yang disempurnakan. Urutan pemuatan dapat menjadi penting karena satu ekstensi dapat bertindak berdasarkan nilai yang telah diubah oleh ekstensi sebelumnya.
Secara default, klien yang disempurnakan memuat dua ekstensi:
+ `[VersionedRecordExtension](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/extensions/VersionedRecordExtension.html)`- Memberikan penguncian optimis
+ `[AtomicCounterExtension](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/extensions/AtomicCounterExtension.html)`- Secara otomatis menambah atribut penghitung
Anda dapat mengganti perilaku default dengan pembuat klien yang disempurnakan dan memuat ekstensi apa pun. Anda juga dapat menentukan none jika Anda tidak ingin ekstensi default.
**penting**
Jika Anda memuat ekstensi Anda sendiri, klien yang disempurnakan tidak memuat ekstensi default apa pun. Jika Anda menginginkan perilaku yang disediakan oleh salah satu ekstensi default, Anda perlu menambahkannya secara eksplisit ke daftar ekstensi.
Contoh berikut menunjukkan cara memuat ekstensi kustom yang `verifyChecksumExtension` dinamai`VersionedRecordExtension`. `AtomicCounterExtension`Tidak dimuat dalam contoh ini.
```
DynamoDbEnhancedClientExtension versionedRecordExtension = VersionedRecordExtension.builder().build();
DynamoDbEnhancedClient enhancedClient =
DynamoDbEnhancedClient.builder()
.dynamoDbClient(dynamoDbClient)
.extensions(versionedRecordExtension, verifyChecksumExtension)
.build();
```
## Detail dan konfigurasi ekstensi yang tersedia
Bagian berikut memberikan informasi rinci tentang setiap ekstensi yang tersedia di SDK.
### Terapkan penguncian optimis dengan `VersionedRecordExtension`
`VersionedRecordExtension`Ekstensi ini memberikan penguncian optimis dengan menambah dan melacak nomor versi item saat item ditulis ke database. Kondisi ditambahkan ke setiap penulisan yang menyebabkan penulisan gagal jika nomor versi item tetap yang sebenarnya tidak cocok dengan nilai yang terakhir dibaca aplikasi.
#### Konfigurasi
Untuk menentukan atribut mana yang akan digunakan untuk melacak nomor versi item, beri tag atribut numerik dalam skema tabel.
Cuplikan berikut menentukan bahwa `version` atribut harus menyimpan nomor versi item.
```
@DynamoDbVersionAttribute
public Integer getVersion() {...};
public void setVersion(Integer version) {...};
```
Pendekatan skema tabel statis setara ditunjukkan dalam cuplikan berikut.
```
.addAttribute(Integer.class, a -> a.name("version")
.getter(Customer::getVersion)
.setter(Customer::setVersion)
// Apply the 'version' tag to the attribute.
.tags(VersionedRecordExtension.AttributeTags.versionAttribute())
```
#### Cara kerjanya
Penguncian optimis dengan `VersionedRecordExtension` memiliki dampak berikut pada ini `DynamoDbEnhancedClient` dan `DynamoDbTable` metode:
**`putItem`**
Item baru diberi nilai versi awal 0. Ini dapat dikonfigurasi dengan`@DynamoDbVersionAttribute(startAt = X)`.
**`updateItem`**
Jika Anda mengambil item, memperbarui satu atau beberapa propertinya, dan mencoba menyimpan perubahan, operasi hanya berhasil jika nomor versi di sisi klien dan sisi server cocok.
Jika berhasil, nomor versi secara otomatis bertambah 1. Ini dapat dikonfigurasi dengan`@DynamoDbVersionAttribute(incrementBy = X)`.
**`deleteItem`**
`DynamoDbVersionAttribute`Anotasi tidak berpengaruh. Anda harus menambahkan ekspresi kondisi secara manual saat menghapus item.
Contoh berikut menambahkan ekspresi bersyarat untuk memastikan bahwa item yang dihapus adalah item yang telah dibaca. Dalam contoh berikut `recordVersion` adalah atribut kacang yang dianotasi dengan. `@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`: Metode ini memiliki perilaku yang sama dengan`putItem`.
+ `addUpdateItem`: Metode ini memiliki perilaku yang sama dengan`updateItem`.
+ `addDeleteItem`: Metode ini memiliki perilaku yang sama dengan`deleteItem`.
**`batchWriteItem`**
+ `addPutItem`: Metode ini memiliki perilaku yang sama dengan`putItem`.
+ `addDeleteItem`: Metode ini memiliki perilaku yang sama dengan`deleteItem`.
**catatan**
Tabel global DynamoDB menggunakan rekonsiliasi ['penulis terakhir menang'](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/V2globaltables_HowItWorks.html#V2globaltables_HowItWorks.consistency-modes) antara pembaruan bersamaan, di mana DynamoDB melakukan upaya terbaik untuk menentukan penulis terakhir. Jika Anda menggunakan tabel global, kebijakan 'penulis terakhir menang' ini berarti bahwa strategi penguncian mungkin tidak berfungsi seperti yang diharapkan, karena semua replika pada akhirnya akan bertemu berdasarkan penulisan terakhir yang ditentukan oleh DynamoDB.
#### Cara menonaktifkan
Untuk menonaktifkan penguncian optimis, jangan gunakan `@DynamoDbVersionAttribute` anotasi.
### Menerapkan penghitung dengan `AtomicCounterExtension`
`AtomicCounterExtension`Ekstensi menambah atribut numerik yang ditandai setiap kali catatan ditulis ke database. Anda dapat menentukan nilai awal dan kenaikan. Jika tidak ada nilai yang ditentukan, nilai awal diatur ke 0 dan nilai atribut meningkat sebesar 1.
#### Konfigurasi
Untuk menentukan atribut mana yang merupakan penghitung, beri tag atribut tipe `Long` dalam skema tabel.
Cuplikan berikut menunjukkan penggunaan nilai awal dan kenaikan default untuk atribut. `counter`
```
@DynamoDbAtomicCounter
public Long getCounter() {...};
public void setCounter(Long counter) {...};
```
Pendekatan skema tabel statis ditunjukkan dalam cuplikan berikut. Ekstensi penghitung atom menggunakan nilai awal 10 dan menambah nilai sebesar 5 setiap kali catatan ditulis.
```
.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))
```
### Tambahkan stempel waktu dengan `AutoGeneratedTimestampRecordExtension`
`AutoGeneratedTimestampRecordExtension`Ekstensi secara otomatis memperbarui atribut tipe yang ditandai `[Instant](https://docs.oracle.com/javase/8/docs/api/java/time/Instant.html)` dengan stempel waktu saat ini setiap kali item berhasil ditulis ke database. Ekstensi ini tidak dimuat secara default.
#### Konfigurasi
Untuk menentukan atribut mana yang akan diperbarui dengan stempel waktu saat ini, beri tag `Instant` atribut dalam skema tabel.
`lastUpdate`Atribut adalah target perilaku ekstensi dalam cuplikan berikut. Perhatikan persyaratan bahwa atribut harus berupa `Instant` tipe.
```
@DynamoDbAutoGeneratedTimestampAttribute
public Instant getLastUpdate() {...}
public void setLastUpdate(Instant lastUpdate) {...}
```
Pendekatan skema tabel statis setara ditunjukkan dalam cuplikan berikut.
```
.addAttribute(Instant.class, a -> a.name("lastUpdate")
.getter(Customer::getLastUpdate)
.setter(Customer::setLastUpdate)
// Applying the 'autoGeneratedTimestamp' tag to the attribute.
.tags(AutoGeneratedTimestampRecordExtension.AttributeTags.autoGeneratedTimestampAttribute())
```
### Hasilkan UUID dengan AutoGeneratedUuidExtension
`AutoGeneratedUuidExtension`Ekstensi menghasilkan UUID unik (Universally Unique Identifier) untuk atribut ketika catatan baru ditulis ke database. Menggunakan metode Java JDK [UUID.randomUUId ()](https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html#randomUUID--) dan berlaku untuk atribut tipe. `java.lang.String` Ekstensi ini tidak dimuat secara default.
#### Konfigurasi
`uniqueId`Atribut adalah target perilaku ekstensi dalam cuplikan berikut.
```
@AutoGeneratedUuidExtension
public String getUniqueId() {...}
public void setUniqueId(String uniqueId) {...}
```
Pendekatan skema tabel statis setara ditunjukkan dalam cuplikan berikut.
```
.addAttribute(String.class, a -> a.name("uniqueId")
.getter(Customer::getUniqueId)
.setter(Customer::setUniqueId)
// Applying the 'autoGeneratedUuid' tag to the attribute.
.tags(AutoGeneratedUuidExtension.AttributeTags.autoGeneratedUuidAttribute())
```
Jika Anda ingin ekstensi mengisi UUID hanya untuk `putItem` metode dan bukan untuk `updateItem` metode, tambahkan anotasi [perilaku pembaruan](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/mapper/UpdateBehavior.html) seperti yang ditunjukkan pada cuplikan berikut.
```
@AutoGeneratedUuidExtension
@DynamoDbUpdateBehavior(UpdateBehavior.WRITE_IF_NOT_EXISTS)
public String getUniqueId() {...}
public void setUniqueId(String uniqueId) {...}
```
Jika Anda menggunakan pendekatan skema tabel statis, gunakan kode setara berikut.
```
.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))
```
# Contoh ekstensi kustom
Anda dapat membuat ekstensi khusus dengan mengimplementasikan `DynamoDbEnhancedClientExtension` antarmuka. Kelas ekstensi kustom berikut menunjukkan `beforeWrite()` metode yang menggunakan ekspresi pembaruan untuk mengatur `registrationDate` atribut jika item dalam database belum memilikinya.
```
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();
}
}
```
# Gunakan DynamoDB Enhanced Client API secara asinkron
Jika aplikasi Anda memerlukan panggilan asinkron non-pemblokiran ke DynamoDB, Anda dapat menggunakan file. [DynamoDbEnhancedAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.html) Ini mirip dengan implementasi sinkron tetapi dengan perbedaan utama berikut:
1. Ketika Anda membangun`DynamoDbEnhancedAsyncClient`, Anda harus menyediakan versi asinkron dari klien standar,`DynamoDbAsyncClient`, seperti yang ditunjukkan dalam cuplikan berikut.
```
DynamoDbEnhancedAsyncClient enhancedClient =
DynamoDbEnhancedAsyncClient.builder()
.dynamoDbClient(dynamoDbAsyncClient)
.build();
```
1. Metode yang mengembalikan objek data tunggal `CompletableFuture` mengembalikan hasil bukan hanya hasilnya. Aplikasi Anda kemudian dapat melakukan pekerjaan lain tanpa harus memblokir hasilnya. Cuplikan berikut menunjukkan metode `getItem()` asinkron.
```
CompletableFuture result = customerDynamoDbTable.getItem(customer);
// Perform other work here.
return result.join(); // Now block and wait for the result.
```
1. Metode yang mengembalikan daftar hasil paginasi mengembalikan sebuah [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)alih-alih [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)yang dikembalikan sinkron `DynamoDbEnhanceClient` untuk metode yang sama. Aplikasi Anda kemudian dapat berlangganan handler ke penerbit itu untuk menangani hasil secara asinkron tanpa harus memblokir.
```
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.
```
Untuk contoh yang lebih lengkap tentang bekerja dengan`SdkPublisher API`, lihat [contoh di](ddb-en-client-use-multirecord.md#ddb-en-client-use-multirecord-scan-async) bagian yang membahas `scan()` metode asinkron dari panduan ini.
# Anotasi kelas data
Tabel berikut mencantumkan anotasi yang dapat digunakan pada kelas data dan menyediakan tautan ke informasi dan contoh dalam panduan ini. Tabel diurutkan dalam urutan abjad menaik dengan nama anotasi.
**Anotasi kelas data yang digunakan dalam panduan ini**
| Nama anotasi | Anotasi berlaku untuk 1 | Apa yang dilakukannya | Dimana itu ditampilkan dalam panduan ini |
| --- | --- | --- | --- |
| DynamoDbAtomicCounter | atribut 2 | Menambah atribut numerik yang ditandai setiap kali catatan ditulis ke database. | [Pengantar dan diskusi.](ddb-en-client-extensions.md#ddb-en-client-extensions-ACE) |
| DynamoDbAttribute | atribut | Mendefinisikan atau mengganti nama properti kacang yang dipetakan ke atribut tabel DynamoDB. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbAutoGeneratedTimestampAttribute | atribut | Memperbarui atribut yang ditandai dengan stempel waktu saat ini setiap kali item berhasil ditulis ke database | [Pengantar dan diskusi](ddb-en-client-extensions.md#ddb-en-client-extensions-AGTE). |
| DynamoDbAutoGeneratedUuid | atribut | Menghasilkan UUID unik (Universally Unique Identifier) untuk atribut ketika catatan baru ditulis ke database. | [Pengantar dan diskusi.](ddb-en-client-extensions.md#ddb-en-client-extensions-AGUE) |
| DynamoDbBean | class | Menandai kelas data sebagai dapat dipetakan ke skema tabel. | Pertama gunakan pada [kelas Pelanggan](ddb-en-client-gs-tableschema.md#ddb-en-client-gs-tableschema-anno-bean-cust) di bagian Memulai. Beberapa penggunaan muncul di seluruh panduan. |
| DynamoDbConvertedBy | atribut | Mengaitkan kustom AttributeConverter dengan atribut beranotasi. | [Diskusi awal dan contoh.](ddb-en-client-adv-features-conversion.md#ddb-en-client-adv-features-conversion-single) |
| DynamoDbFlatten | atribut | Meratakan semua atribut dari kelas data DynamoDB terpisah dan menambahkannya sebagai atribut tingkat atas ke catatan yang dibaca dan ditulis ke database. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbIgnore | atribut | Menghasilkan atribut yang tersisa tidak dipetakan. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbIgnoreNulls | atribut | Mencegah menyimpan atribut null dari objek bersarang DynamoDb . | [Diskusi dan contoh.](ddb-en-client-adv-features-ignore-null.md) |
| DynamoDbImmutable | class | Menandai kelas data yang tidak dapat diubah sebagai dapat dipetakan ke skema tabel. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbPartitionKey | atribut | Menandai atribut sebagai kunci partisi primer (kunci hash) dari DynamoDb tabel. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbPreserveEmptyObject | atribut | Menentukan bahwa jika tidak ada data hadir untuk objek dipetakan ke atribut beranotasi, objek harus diinisialisasi dengan semua bidang null. | [Diskusi dan contoh.](ddb-en-client-adv-features-empty.md) |
| DynamoDbSecondaryPartitionKey | atribut | Menandai atribut sebagai kunci partisi untuk indeks sekunder global. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbSecondarySortKey | atribut | Menandai atribut sebagai kunci pengurutan opsional untuk indeks sekunder global atau lokal. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbSortKey | atribut | Menandai atribut sebagai kunci sortir primer opsional (range key). | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbUpdateBehavior | atribut | Menentukan perilaku ketika atribut ini diperbarui sebagai bagian dari operasi 'update' seperti UpdateItem. | [Pendahuluan dan contoh.](ddb-en-client-adv-features-upd-behavior.md) |
| DynamoDbVersionAttribute | atribut | Menambah nomor versi item. | [Pengantar dan diskusi.](ddb-en-client-extensions.md#ddb-en-client-extensions-VRE) |
1 Anda dapat menerapkan anotasi tingkat atribut ke pengambil atau penyetel, tetapi tidak keduanya. Panduan ini menunjukkan anotasi tentang getter.
2 Istilah `property` ini biasanya digunakan untuk nilai yang dienkapsulasi dalam kelas data. JavaBean Namun, panduan ini menggunakan istilah `attribute` sebagai gantinya, agar konsisten dengan terminologi yang digunakan oleh DynamoDB.