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();
```
L'exemple de schéma statique précédent utilise les classes de données suivantes.
#### Classes de données
------
#### [ 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;
}
```
------
Vous pouvez utiliser le modèle Builder pour aplatir autant de classes éligibles que nécessaire.
## Implications pour les autres codes
Lorsque vous utilisez l'`@DynamoDbFlatten`attribut (ou la méthode du `flatten()` générateur), l'élément de DynamoDB contient un attribut pour chaque attribut de l'objet composé. Il inclut également les attributs de l'objet composant.
En revanche, si vous annotez une classe de données avec une classe composée et que vous ne l'utilisez pas`@DynamoDbFlatten`, l'élément est enregistré avec l'objet composé en tant qu'attribut unique.
Par exemple, comparez la `Customer` classe indiquée dans l'[exemple d'aplatissement avec la composition avec](#ddb-en-client-adv-features-flatmap-comp-anno) et sans aplatissement de l'attribut. `record` Vous pouvez visualiser la différence avec JSON, comme indiqué dans le tableau suivant.
****
| Avec aplatissement | Sans aplatir |
| --- | --- |
| 3 attributs | 2 attributs |
| {
"id": "1",
"createdDate": "today",
"name": "my name"
} | {
"id": "1",
"record": {
"createdDate": "today",
"name": "my name"
}
} |
La différence devient importante si vous disposez d'un autre code accédant à la table DynamoDB qui devrait trouver certains attributs.
# Travaillez avec des attributs tels que des beans, des cartes, des listes et des ensembles
Une définition de bean, telle que la `Person` classe illustrée ci-dessous, peut définir des propriétés (ou des attributs) qui font référence à des types dotés d'attributs supplémentaires. Par exemple, dans la `Person` classe, se `mainAddress` trouve une propriété qui fait référence à un `Address` bean qui définit des attributs de valeur supplémentaires. `addresses`fait référence à une carte Java, dont les éléments font référence à des `Address` beans. Ces types complexes peuvent être considérés comme des conteneurs d'attributs simples que vous utilisez pour leur valeur de données dans le contexte de DynamoDB.
*DynamoDB désigne les propriétés de valeur des éléments imbriqués, tels que les cartes, les listes ou les beans, en tant qu'attributs imbriqués.* *Le guide du [développeur Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes) fait référence à la forme enregistrée d'une carte, d'une liste ou d'un bean Java en tant que type de document.* Les attributs simples que vous utilisez pour leur valeur de données en Java sont appelés *types scalaires* dans DynamoDB. Ensembles, qui contiennent plusieurs éléments scalaires du même type, appelés *types d'ensembles*.
Il est important de savoir que l'API DynamoDB Enhanced Client convertit une propriété qui est un bean en un type de document ArcMap DynamoDB lors de son enregistrement.
## classe `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 +
'}';
}
}
```
## classe `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 + '\'' +
'}';
}
}
```
## classe `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 + '\'' +
'}';
}
}
```
## Enregistrer des types complexes
### Utiliser des classes de données annotées
Pour enregistrer les attributs imbriqués des classes personnalisées, il suffit de les annoter. La `Address` classe et la `PhoneNumber` classe affichées précédemment sont annotées uniquement avec l'`@DynamoDbBean`annotation. Lorsque l'API DynamoDB Enhanced Client crée le schéma de table pour la classe à `Person` l'aide de l'extrait suivant, l'API découvre l'utilisation des classes et `PhoneNumber` et crée les mappages `Address` correspondants pour fonctionner avec DynamoDB.
```
TableSchema personTableSchema = TableSchema.fromBean(Person.class);
```
### Utiliser des schémas abstraits avec des constructeurs
L'approche alternative consiste à utiliser des générateurs de schémas de tables statiques pour chaque classe de bean imbriquée, comme indiqué dans le code suivant.
Les schémas de table des `PhoneNumber` classes `Address` et sont abstraits dans le sens où ils ne peuvent pas être utilisés avec une table DynamoDB. Cela est dû au fait qu'ils ne disposent pas de définitions pour la clé primaire. Ils sont toutefois utilisés comme schémas imbriqués dans le schéma de table de la `Person` classe.
Après les lignes de commentaire 1 et 2 de la définition de`PERSON_TABLE_SCHEMA`, vous pouvez voir le code qui utilise les schémas de table abstraits. L'utilisation de `documentOf` dans la `EnhanceType.documentOf(...)` méthode n'indique pas que la méthode renvoie un `EnhancedDocument` type d'API de document améliorée. Dans ce contexte, la `documentOf(...)` méthode renvoie un objet qui sait comment mapper son argument de classe vers et depuis les attributs de table DynamoDB en utilisant l'argument de schéma de table.
#### Code de schéma statique
```
// 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();
```
## Attributs de projet de types complexes
Pour les `scan()` méthodes `query()` et, vous pouvez spécifier les attributs que vous souhaitez voir renvoyés dans les résultats en utilisant des appels de méthode tels que `addNestedAttributeToProject()` et`attributesToProject()`. L'API DynamoDB Enhanced Client convertit les paramètres d'appel de méthode Java [en expressions de projection](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html) avant l'envoi de la demande.
L'exemple suivant remplit le `Person` tableau avec deux éléments, puis exécute trois opérations de numérisation.
Le premier scan accède à tous les éléments du tableau afin de comparer les résultats aux autres opérations d'analyse.
Le second scan utilise la méthode du [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))générateur pour renvoyer uniquement la valeur de `street` l'attribut.
La troisième opération d'analyse utilise la méthode du [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...))générateur pour renvoyer les données de l'attribut de premier niveau,`hobbies`. Le type d'attribut de `hobbies` est une liste. Pour accéder à des éléments de liste individuels, effectuez une `get()` opération sur la liste.
```
personDynamoDbTable = getDynamoDbEnhancedClient().table("Person", PERSON_TABLE_SCHEMA);
PersonUtils.createPersonTable(personDynamoDbTable, getDynamoDbClient());
// Use a utility class to add items to the Person table.
List personList = PersonUtils.getItemsForCount(2);
// This utility method performs a put against DynamoDB to save the instances in the list argument.
PersonUtils.putCollection(getDynamoDbEnhancedClient(), personList, personDynamoDbTable);
// The first scan logs all items in the table to compare to the results of the subsequent scans.
final PageIterable allItems = personDynamoDbTable.scan();
allItems.items().forEach(p ->
// 1. Log what is in the table.
logger.info(p.toString()));
// Scan for nested attributes.
PageIterable streetScanResult = personDynamoDbTable.scan(b -> b
// Use the 'addNestedAttributeToProject()' or 'addNestedAttributesToProject()' to access data nested in maps in DynamoDB.
.addNestedAttributeToProject(
NestedAttributeName.create("addresses", "work", "street")
));
streetScanResult.items().forEach(p ->
//2. Log the results of requesting nested attributes.
logger.info(p.toString()));
// Scan for a top-level list attribute.
PageIterable hobbiesScanResult = personDynamoDbTable.scan(b -> b
// Use the 'attributesToProject()' method to access first-level attributes.
.attributesToProject("hobbies"));
hobbiesScanResult.items().forEach((p) -> {
// 3. Log the results of the request for the 'hobbies' attribute.
logger.info(p.toString());
// To access an item in a list, first get the parent attribute, 'hobbies', then access items in the list.
String hobby = p.getHobbies().get(1);
// 4. Log an item in the list.
logger.info(hobby);
});
```
```
// Logged results from comment line 1.
Person{id=2, firstName='first name 2', lastName='last name 2', age=11, addresses={work=Address{street='street 21', city='city 21', state='state 21', zipCode='33333'}, home=Address{street='street 2', city='city 2', state='state 2', zipCode='22222'}}, phoneNumbers=[PhoneNumber{type='home', number='222-222-2222'}, PhoneNumber{type='work', number='333-333-3333'}], hobbies=[hobby 2, hobby 21]}
Person{id=1, firstName='first name 1', lastName='last name 1', age=11, addresses={work=Address{street='street 11', city='city 11', state='state 11', zipCode='22222'}, home=Address{street='street 1', city='city 1', state='state 1', zipCode='11111'}}, phoneNumbers=[PhoneNumber{type='home', number='111-111-1111'}, PhoneNumber{type='work', number='222-222-2222'}], hobbies=[hobby 1, hobby 11]}
// Logged results from comment line 2.
Person{id=null, firstName='null', lastName='null', age=null, addresses={work=Address{street='street 21', city='null', state='null', zipCode='null'}}, phoneNumbers=null, hobbies=null}
Person{id=null, firstName='null', lastName='null', age=null, addresses={work=Address{street='street 11', city='null', state='null', zipCode='null'}}, phoneNumbers=null, hobbies=null}
// Logged results from comment lines 3 and 4.
Person{id=null, firstName='null', lastName='null', age=null, addresses=null, phoneNumbers=null, hobbies=[hobby 2, hobby 21]}
hobby 21
Person{id=null, firstName='null', lastName='null', age=null, addresses=null, phoneNumbers=null, hobbies=[hobby 1, hobby 11]}
hobby 11
```
**Note**
Si la `attributesToProject()` méthode suit une autre méthode de création qui ajoute les attributs que vous souhaitez projeter, la liste des noms d'attributs fournie au `attributesToProject()` remplace tous les autres noms d'attributs.
Une analyse effectuée avec l'`ScanEnhancedRequest`instance figurant dans l'extrait suivant renvoie uniquement les données relatives aux loisirs.
```
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]}
```
L'extrait de code suivant utilise d'abord la `attributesToProject()` méthode. Cet ordre préserve tous les autres attributs demandés.
```
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]}
```
## Utiliser des types complexes dans les expressions
Vous pouvez utiliser des types complexes dans les expressions, telles que les expressions de filtre et les expressions de condition, en utilisant des opérateurs de déréférencement pour parcourir la structure du type complexe. Pour les objets et les cartes, utilisez le `. (dot)` et pour les éléments de liste `[n]` (crochets autour du numéro de séquence de l'élément). Vous ne pouvez pas faire référence à des éléments individuels d'un ensemble, mais vous pouvez utiliser la [`contains`fonction](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions).
L'exemple suivant montre deux expressions de filtre utilisées dans les opérations de numérisation. Les expressions de filtre spécifient les conditions de correspondance pour les éléments que vous souhaitez voir apparaître dans les résultats. L'exemple utilise`Person`,`Address`, et `PhoneNumber` les classes présentés précédemment.
```
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");
}
```
### Méthode d'assistance qui remplit le tableau
```
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);
}
```
### Représentation JSON des éléments de la base de données
```
{
"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"
}
]
}
```
## Mettre à jour les éléments contenant des types complexes
Pour mettre à jour un élément contenant des types complexes, vous avez deux approches de base :
+ Approche 1 : récupérez d'abord l'élément (en utilisant`getItem`), mettez à jour l'objet, puis appelez`DynamoDbTable#updateItem`.
+ Approche 2 : Ne récupérez pas l'élément, mais créez une nouvelle instance, définissez les propriétés que vous souhaitez mettre à jour et soumettez l'instance `DynamoDbTable#updateItem` en définissant la valeur appropriée de [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). Cette approche ne nécessite pas que vous récupériez l'élément avant de le mettre à jour.
Les exemples présentés dans cette section utilisent les `PhoneNumber` classes `Person``Address`,, et présentées précédemment.
### Approche de mise à jour 1 : récupération, puis mise à jour
En utilisant cette approche, vous vous assurez qu'aucune donnée n'est perdue lors de la mise à jour. L'API DynamoDB Enhanced Client recrée le bean avec les attributs de l'élément enregistré dans DynamoDB, y compris les valeurs de types complexes. Vous devez ensuite utiliser les getters et setters pour mettre à jour le bean. L'inconvénient de cette approche est le coût que vous devez engager pour récupérer l'article en premier.
L'exemple suivant montre qu'aucune donnée n'est perdue si vous récupérez l'élément avant de le mettre à jour.
```
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;
}
```
### Approche de mise à jour 2 : utilisez une `IgnoreNullsMode` énumération sans récupérer l'élément au préalable
Pour mettre à jour un élément dans DynamoDB, vous pouvez fournir un nouvel objet contenant uniquement les propriétés que vous souhaitez mettre à jour et laisser les autres valeurs nulles. Avec cette approche, vous devez être conscient de la manière dont les valeurs nulles de l'objet sont traitées par le SDK et de la manière dont vous pouvez contrôler le comportement.
Pour spécifier les propriétés à valeur nulle que vous souhaitez que le SDK ignore, fournissez une `IgnoreNullsMode` énumération lorsque vous créez le. [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) À titre d'exemple d'utilisation de l'une des valeurs énumérées, l'extrait de code suivant utilise le 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"
}
}
*/
```
[Le guide du développeur Amazon DynamoDB contient plus d'informations sur les expressions de mise à jour.](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)
#### Descriptions des `IgnoreNullsMode` options
+ `IgnoreNullsMode.SCALAR_ONLY`- Utilisez ce paramètre pour mettre à jour les attributs scalaires à tous les niveaux. Le SDK crée une instruction de mise à jour qui envoie uniquement des attributs scalaires non nuls à DynamoDB. Le SDK ignore les attributs scalaires à valeur nulle d'un bean ou d'une carte, en conservant la valeur enregistrée dans DynamoDB.
Lorsque vous mettez à jour un attribut scalaire de map ou bean, la carte doit déjà exister dans DynamoDB. Si vous ajoutez une carte ou un bean à l'objet qui n'existe pas déjà pour cet objet dans DynamoDB, le *message « Le chemin du document indiqué dans l'expression de mise à jour n'est pas `DynamoDbException` valide pour la mise à jour* » s'affiche. Vous devez utiliser `MAPS_ONLY` le mode pour ajouter un bean ou une carte à DynamoDB avant de mettre à jour l'un de ses attributs.
+ `IgnoreNullsMode.MAPS_ONLY`- Utilisez ce paramètre pour ajouter ou remplacer des propriétés qui sont un bean ou une carte. Le SDK remplace ou ajoute toute carte ou bean fourni dans l'objet. Tous les beans ou cartes dont la valeur est nulle dans l'objet sont ignorés, ce qui permet de conserver la carte qui existe dans DynamoDB.
+ `IgnoreNullsMode.DEFAULT`- Avec ce paramètre, le SDK n'ignore jamais les valeurs nulles. Les attributs scalaires de tous les niveaux qui sont nuls sont mis à jour à zéro. Le SDK met à jour toute propriété de type bean, map, list ou set dont la valeur est nulle dans l'objet en lui attribuant la valeur null dans DynamoDB. Lorsque vous utilisez ce mode (ou que vous n'en fournissez aucun puisqu'il s'agit du mode par défaut), vous devez d'abord récupérer l'élément afin que les valeurs fournies dans l'objet pour la mise à jour dans DynamoDB ne soient pas définies sur null, sauf si vous avez l'intention de définir les valeurs sur null.
Dans tous les modes, si vous fournissez un objet `updateItem` dont la liste ou l'ensemble n'est pas nul, la liste ou l'ensemble est enregistré dans DynamoDB.
#### Pourquoi les modes ?
Lorsque vous fournissez à un objet un bean ou un mappage vers la `updateItem` méthode, le SDK ne peut pas dire s'il doit utiliser les valeurs des propriétés du bean (ou les valeurs d'entrée dans la carte) pour mettre à jour l'élément, ou si l'intégralité bean/map doit remplacer ce qui a été enregistré dans DynamoDB.
À partir de notre exemple précédent qui montre d'abord la récupération de l'élément, essayons de mettre à jour l'`city`attribut de `mainAddress` sans la récupération.
```
/* 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'.
*/
```
Les deux exemples suivants montrent les utilisations des valeurs `SCALAR_ONLY` énumérées `MAPS_ONLY` et. `MAPS_ONLY`ajoute une carte et `SCALAR_ONLY` met à jour une carte.
##### Exemple de `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.
}
```
Reportez-vous au tableau suivant pour savoir quelles valeurs nulles sont ignorées pour chaque mode. Vous pouvez souvent travailler avec l'un ou `SCALAR_ONLY` l'autre`MAPS_ONLY`, sauf lorsque vous travaillez avec des beans ou des cartes.
**Quelles propriétés à valeur nulle de l'objet soumis le SDK `updateItem` ignore-t-il pour chaque mode ?**
| Type de propriété | en mode SCALAR\$1ONLY | en mode MAPS\$1ONLY | en mode DEFAULT |
| --- | --- | --- | --- |
| Meilleur scalaire | Oui | Oui | Non |
| Bean ou carte | Oui | Oui | Non |
| Valeur scalaire d'un bean ou d'une entrée de carte | Oui1 | No2 | Non |
| Liste ou ensemble | Oui | Oui | Non |
1 Cela suppose que la carte existe déjà dans DynamoDB. Toute valeur scalaire (nulle ou non nulle) du bean ou de la carte que vous fournissez dans l'objet à mettre à jour nécessite qu'un chemin d'accès à la valeur existe dans DynamoDB. Le SDK construit un chemin d'accès à l'attribut en utilisant l'opérateur de `. (dot)` déréférencement avant de soumettre la demande.
2 Puisque vous utilisez le `MAPS_ONLY` mode pour remplacer complètement ou ajouter un bean ou une map, toutes les valeurs nulles du bean ou de la map sont conservées dans la map enregistrée dans DynamoDB.
# Préservez les objets vides avec `@DynamoDbPreserveEmptyObject`
Si vous enregistrez un bean dans Amazon DynamoDB avec des objets vides et que vous souhaitez que le SDK recrée les objets vides lors de leur extraction, annotez le getter du bean interne avec. `@DynamoDbPreserveEmptyObject`
Pour illustrer le fonctionnement de l'annotation, l'exemple de code utilise les deux beans suivants.
## Exemple de haricots
La classe de données suivante contient deux `InnerBean` champs. La méthode getter`getInnerBeanWithoutAnno()`, n'est pas annotée avec. `@DynamoDbPreserveEmptyObject` La `getInnerBeanWithAnno()` méthode est annotée.
```
@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();
}
}
```
Les instances de la `InnerBean` classe suivante sont des champs de `MyBean` et sont initialisées en tant qu'objets vides dans l'exemple de code.
```
@DynamoDbBean
public class InnerBean {
private String innerBeanField;
public String getInnerBeanField() {
return innerBeanField;
}
public void setInnerBeanField(String innerBeanField) {
this.innerBeanField = innerBeanField;
}
@Override
public String toString() {
return "InnerBean{" +
"innerBeanField='" + innerBeanField + '\'' +
'}';
}
}
```
L'exemple de code suivant enregistre un `MyBean` objet avec des beans internes initialisés dans DynamoDB, puis récupère l'élément. La sortie enregistrée indique que le n'`innerBeanWithoutAnno`est pas initialisé, mais qu'il `innerBeanWithAnno` a été créé.
```
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;
}
```
## Schéma statique alternatif
Vous pouvez utiliser la `StaticTableSchema` version suivante des schémas de table à la place des annotations sur les beans.
```
public static TableSchema buildStaticSchemas() {
StaticTableSchema innerBeanStaticTableSchema =
StaticTableSchema.builder(InnerBean.class)
.newItemSupplier(InnerBean::new)
.addAttribute(String.class, a -> a.name("innerBeanField")
.getter(InnerBean::getInnerBeanField)
.setter(InnerBean::setInnerBeanField))
.build();
return StaticTableSchema.builder(MyBean.class)
.newItemSupplier(MyBean::new)
.addAttribute(String.class, a -> a.name("id")
.getter(MyBean::getId)
.setter(MyBean::setId)
.addTag(primaryPartitionKey()))
.addAttribute(String.class, a -> a.name("name")
.getter(MyBean::getName)
.setter(MyBean::setName))
.addAttribute(EnhancedType.documentOf(InnerBean.class,
innerBeanStaticTableSchema),
a -> a.name("innerBean1")
.getter(MyBean::getInnerBeanWithoutAnno)
.setter(MyBean::setInnerBeanWithoutAnno))
.addAttribute(EnhancedType.documentOf(InnerBean.class,
innerBeanStaticTableSchema,
b -> b.preserveEmptyObject(true)),
a -> a.name("innerBean2")
.getter(MyBean::getInnerBeanWithAnno)
.setter(MyBean::setInnerBeanWithAnno))
.build();
}
```
# Évitez de sauvegarder les attributs nuls des objets imbriqués
Vous pouvez ignorer les attributs nuls des objets imbriqués lorsque vous enregistrez un objet de classe de données dans DynamoDB en appliquant l'annotation. `@DynamoDbIgnoreNulls` En revanche, les attributs de niveau supérieur contenant des valeurs nulles ne sont jamais enregistrés dans la base de données.
Pour illustrer le fonctionnement de l'annotation, l'exemple de code utilise les deux beans suivants.
## Exemple de haricots
La classe de données suivante contient deux `InnerBean` champs. La méthode getter`getInnerBeanWithoutAnno()`, n'est pas annotée. La `getInnerBeanWithIgnoreNullsAnno()` méthode est annotée avec`@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();
}
}
```
Les instances de la `InnerBean` classe suivante sont des champs de `MyBean` et sont utilisées dans l'exemple de code suivant.
```
@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();
}
}
```
L'exemple de code suivant crée un `InnerBean` objet et attribue une valeur à un seul de ses deux attributs.
```
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);
}
```
Pour visualiser les données de bas niveau envoyées à DynamoDB, le code enregistre la carte attributaire avant d'enregistrer l'objet. `MyBean`
La sortie enregistrée montre qu'elle `innerBeanWithIgnoreNullsAnno` produit un attribut,
```
innerBeanWithIgnoreNullsAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200)})
```
L'`innerBeanWithoutAnno`instance génère deux attributs. L'un des attributs a une valeur de 200 et l'autre est un attribut de valeur nulle.
```
innerBeanWithoutAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200), innerBeanFieldString=AttributeValue(NUL=true)})
```
## Représentation JSON de la carte attributaire
La représentation JSON suivante permet de visualiser plus facilement les données enregistrées dans DynamoDB.
```
{
"id": {
"S": "1"
},
"innerBeanWithIgnoreNullsAnno": {
"M": {
"innerBeanFieldInteger": {
"N": "200"
}
}
},
"innerBeanWithoutAnno": {
"M": {
"innerBeanFieldInteger": {
"N": "200"
},
"innerBeanFieldString": {
"NULL": true
}
}
}
}
```
## Schéma statique alternatif
Vous pouvez utiliser la `StaticTableSchema` version suivante des schémas de table pour mettre en place des annotations de classe de données.
```
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();
}
```
# Travaillez avec des documents JSON avec l'API de document améliorée pour DynamoDB
L'[API de document améliorée](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/package-summary.html) pour AWS SDK for Java 2.x est conçue pour fonctionner avec des données orientées document qui n'ont aucun schéma fixe. Toutefois, il vous permet également d'utiliser des classes personnalisées pour mapper des attributs individuels.
L'Enhanced Document API est le successeur de l'[API Document](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/DynamoDB.html) de la AWS SDK pour Java v1.x.
**Contents**
+ [Commencez à utiliser l'API Enhanced Document](ddb-en-client-doc-api-steps.md)
+ [Créez un `DocumentTableSchema` et un `DynamoDbTable`](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema)
+ [Créez des documents améliorés](ddb-en-client-doc-api-steps-create-ed.md)
+ [Construire à partir d'une chaîne JSON](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromJson)
+ [Construisez à partir d'éléments individuels](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts)
+ [Effectuer des opérations CRUD](ddb-en-client-doc-api-steps-use.md)
+ [Accédez aux attributs de document améliorés sous forme d'objets personnalisés](ddb-en-client-doc-api-convert.md)
+ [Utiliser et `EnhancedDocument` sans DynamoDB](ddb-en-client-doc-api-standalone.md)
# Commencez à utiliser l'API Enhanced Document
L'API de document améliorée nécessite les mêmes [dépendances](ddb-en-client-getting-started.md#ddb-en-client-gs-dep) que celles requises pour l'API client améliorée DynamoDB. Cela nécessite également une [`DynamoDbEnhancedClient`instance](ddb-en-client-getting-started-dynamodbTable.md#ddb-en-client-getting-started-dynamodbTable-eclient), comme indiqué au début de cette rubrique.
Étant donné que l'API Enhanced Document a été publiée avec la version 2.20.3 du AWS SDK for Java 2.x, vous avez besoin de cette version ou d'une version ultérieure.
## Créez un `DocumentTableSchema` et un `DynamoDbTable`
Pour appeler des commandes sur une table DynamoDB à l'aide de l'API Enhanced Document, associez la table à un objet de ressource < > [DynamoDbTablecôté client EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html).
La `table()` méthode du client amélioré crée une `DynamoDbTable` instance et nécessite des paramètres pour le nom de la table DynamoDB et un. `DocumentTableSchema`
Le générateur d'un [DocumentTableSchema](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/DocumentTableSchema.html)nécessite une clé d'index principale et un ou plusieurs fournisseurs de convertisseurs d'attributs. La `AttributeConverterProvider.defaultProvider()` méthode fournit des convertisseurs pour les [types par défaut](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/internal/converter/attribute/package-summary.html). Il doit être spécifié même si vous fournissez un fournisseur de convertisseur d'attributs personnalisé. Vous pouvez ajouter une clé d'index secondaire facultative au générateur.
L'extrait de code suivant montre le code qui génère la représentation côté client d'une table DynamoDB qui stocke des objets sans schéma. `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.
```
Ce qui suit montre la représentation JSON d'un `person` objet utilisé dans cette section.
### `person`Objet JSON
```
{
"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"
}
]
}
```
# Créez des documents améliorés
An `[EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html)` représente un objet de type document doté d'une structure complexe avec des attributs imbriqués. An `EnhancedDocument` nécessite des attributs de haut niveau qui correspondent aux attributs de clé primaire spécifiés pour le`DocumentTableSchema`. Le contenu restant est arbitraire et peut être composé d'attributs de haut niveau ou d'attributs profondément imbriqués.
Vous créez une `EnhancedDocument` instance à l'aide d'un générateur qui propose plusieurs méthodes pour ajouter des éléments.
## Construire à partir d'une chaîne JSON
Avec une chaîne JSON, vous pouvez créer un appel de méthode `EnhancedDocument` en un. L'extrait suivant crée une chaîne `EnhancedDocument` à partir d'une chaîne JSON renvoyée par la méthode d'`jsonPerson()`assistance. La `jsonPerson()` méthode renvoie la version de chaîne JSON de l'[objet person](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema-obj) affiché précédemment.
```
EnhancedDocument document =
EnhancedDocument.builder()
.json( jsonPerson() )
.build());
```
## Construisez à partir d'éléments individuels
Vous pouvez également créer une `EnhancedDocument` instance à partir de composants individuels à l'aide des méthodes de type sécurisé du générateur.
L'exemple suivant crée un document `person` amélioré similaire au document amélioré créé à partir de la chaîne JSON de l'exemple précédent.
```
/* 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();
```
### Méthodes auxiliaires
```
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"));
}
```
# Effectuer des opérations CRUD
Après avoir défini une `EnhancedDocument` instance, vous pouvez l'enregistrer dans une table DynamoDB. L'extrait de code suivant utilise le [PersonDocument](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts) créé à partir d'éléments individuels.
```
documentDynamoDbTable.putItem(personDocument);
```
Après avoir lu une instance de document améliorée depuis DynamoDB, vous pouvez extraire les valeurs d'attribut individuelles à l'aide de getters, comme indiqué dans l'extrait de code suivant qui accède aux données enregistrées depuis le. `personDocument` Vous pouvez également extraire le contenu complet dans une chaîne JSON, comme indiqué dans la dernière partie de l'exemple de code.
```
// Read the item.
EnhancedDocument personDocFromDb = documentDynamoDbTable.getItem(Key.builder().partitionValue(50).build());
// Access top-level attributes.
logger.info("Name: {} {}", personDocFromDb.getString("firstName"), personDocFromDb.getString("lastName"));
// Name: Shirley Rodriguez
// Typesafe access of a deeply nested attribute. The addressMapEnhancedType shown previously defines the shape of an addresses map.
Map> addresses = personDocFromDb.getMap("addresses", EnhancedType.of(String.class), addressMapEnhancedType);
addresses.keySet().forEach(k -> logger.info(addresses.get(k).toString()));
// {zipCode=00002, city=Any Town, street=123 Any Street, state=ME}
// Alternatively, work with AttributeValue types checking along the way for deeply nested attributes.
Map addressesMap = personDocFromDb.getMapOfUnknownType("addresses");
addressesMap.keySet().forEach((String k) -> {
logger.info("Looking at data for [{}] address", k);
// Looking at data for [home] address
AttributeValue value = addressesMap.get(k);
AttributeValue cityValue = value.m().get("city");
if (cityValue != null) {
logger.info(cityValue.s());
// Any Town
}
});
List phoneNumbers = personDocFromDb.getListOfUnknownType("phoneNumbers");
phoneNumbers.forEach((AttributeValue av) -> {
if (av.hasM()) {
AttributeValue type = av.m().get("type");
if (type.s() != null) {
logger.info("Type of phone: {}", type.s());
// Type of phone: Home
// Type of phone: Work
}
}
});
String jsonPerson = personDocFromDb.toJson();
logger.info(jsonPerson);
// {"firstName":"Shirley","lastName":"Rodriguez","addresses":{"home":{"zipCode":"00002","city":"Any Town","street":"123 Any Street","state":"ME"}},"hobbies":["Theater","Golf"],
// "id":50,"nullAttribute":null,"age":53,"phoneNumbers":[{"number":"555-0140","type":"Home"},{"number":"555-0155","type":"Work"}]}
```
`EnhancedDocument`les instances peuvent être utilisées avec n'importe quelle méthode `[DynamoDbTable](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html)` ou [DynamoDbEnhancedClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.html)à la place de classes de données mappées.
# Accédez aux attributs de document améliorés sous forme d'objets personnalisés
En plus de fournir une API pour lire et écrire des attributs avec des structures sans schéma, l'API Enhanced Document vous permet de convertir des attributs depuis et vers des instances de classes personnalisées.
L'API de document améliorée utilise `AttributeConverterProvider` les valeurs s et `AttributeConverter` s affichées dans la section de [conversion des attributs de contrôle](ddb-en-client-adv-features-conversion.md) dans le cadre de l'API client améliorée DynamoDB.
Dans l'exemple suivant, nous utilisons a `CustomAttributeConverterProvider` avec sa `AddressConverter` classe imbriquée pour convertir `Address` des objets.
Cet exemple montre que vous pouvez mélanger des données provenant de classes et des données provenant de structures créées selon les besoins. Cet exemple montre également que les classes personnalisées peuvent être utilisées à n'importe quel niveau d'une structure imbriquée. Les `Address` objets de cet exemple sont des valeurs utilisées dans une carte.
```
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'}
```
## Code de la `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;
}
}
}
```
## classe `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;
}
}
```
## Méthode d'assistance qui fournit des adresses
La méthode d'assistance suivante fournit la carte qui utilise des `Address` instances personnalisées pour les valeurs plutôt que des `Map` instances génériques pour les valeurs.
```
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);
}
```
# Utiliser et `EnhancedDocument` sans DynamoDB
Bien que vous utilisiez généralement une instance d'un `EnhancedDocument` pour lire et écrire des éléments DynamoDB de type document, elle peut également être utilisée indépendamment de DynamoDB.
Vous pouvez `EnhancedDocuments` les utiliser pour leur capacité à convertir des chaînes JSON ou des objets personnalisés en cartes de bas niveau, `AttributeValues` comme indiqué dans l'exemple suivant.
```
public static void conversionWithoutDynamoDbExample() {
Address address = new Address();
address.setCity("my city");
address.setState("my state");
address.setStreet("my street");
address.setZipCode("00000");
// Build an EnhancedDocument instance for its conversion functionality alone.
EnhancedDocument addressEnhancedDoc = EnhancedDocument.builder()
// Important: You must specify attribute converter providers when you build an EnhancedDocument instance not used with a DynamoDB table.
.attributeConverterProviders(new CustomAttributeConverterProvider(), DefaultAttributeConverterProvider.create())
.put("addressDoc", address, Address.class)
.build();
// Convert address to a low-level item representation.
final Map addressAsAttributeMap = addressEnhancedDoc.getMapOfUnknownType("addressDoc");
logger.info("addressAsAttributeMap: {}", addressAsAttributeMap.toString());
// Convert address to a JSON string.
String addressAsJsonString = addressEnhancedDoc.getJson("addressDoc");
logger.info("addressAsJsonString: {}", addressAsJsonString);
// Convert addressEnhancedDoc back to an Address instance.
Address addressConverted = addressEnhancedDoc.get("addressDoc", Address.class);
logger.info("addressConverted: {}", addressConverted.toString());
}
/* Console output:
addressAsAttributeMap: {zipCode=AttributeValue(S=00000), state=AttributeValue(S=my state), street=AttributeValue(S=my street), city=AttributeValue(S=my city)}
addressAsJsonString: {"zipCode":"00000","state":"my state","street":"my street","city":"my city"}
addressConverted: Address{street='my street', city='my city', state='my state', zipCode='00000'}
*/
```
**Note**
Lorsque vous utilisez un document amélioré indépendant d'une table DynamoDB, assurez-vous de définir explicitement les fournisseurs de convertisseurs d'attributs dans le générateur.
En revanche, le schéma de table de documents fournit les fournisseurs de conversion lorsqu'un document amélioré est utilisé avec une table DynamoDB.
# Utiliser des extensions pour personnaliser les opérations du client DynamoDB Enhanced
L'API DynamoDB Enhanced Client prend en charge les extensions de plug-in qui fournissent des fonctionnalités allant au-delà des opérations de mappage. Les extensions utilisent deux méthodes hook pour modifier les données lors des opérations de lecture et d'écriture :
+ `beforeWrite()`- Modifie une opération d'écriture avant qu'elle ne se produise
+ `afterRead()`- Modifie les résultats d'une opération de lecture après qu'elle se soit produite
Certaines opérations (telles que les mises à jour d'éléments) effectuent à la fois une écriture puis une lecture. Les deux méthodes hook sont donc appelées.
## Comment les extensions sont chargées
Les extensions sont chargées dans l'ordre que vous spécifiez dans le générateur de clients amélioré. L'ordre de chargement peut être important car une extension peut agir sur des valeurs transformées par une extension précédente.
Par défaut, le client amélioré charge deux extensions :
+ `[VersionedRecordExtension](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/extensions/VersionedRecordExtension.html)`- Assure un verrouillage optimiste
+ `[AtomicCounterExtension](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/extensions/AtomicCounterExtension.html)`- Incrémente automatiquement les attributs du compteur
Vous pouvez modifier le comportement par défaut à l'aide du générateur de clients amélioré et charger n'importe quelle extension. Vous pouvez également n'en spécifier aucune si vous ne souhaitez pas utiliser les extensions par défaut.
**Important**
Si vous chargez vos propres extensions, le client amélioré ne charge aucune extension par défaut. Si vous souhaitez obtenir le comportement fourni par l'une ou l'autre des extensions par défaut, vous devez l'ajouter explicitement à la liste des extensions.
L'exemple suivant montre comment charger une extension personnalisée nommée d'`verifyChecksumExtension`après le`VersionedRecordExtension`. Le n'`AtomicCounterExtension`est pas chargé dans cet exemple.
```
DynamoDbEnhancedClientExtension versionedRecordExtension = VersionedRecordExtension.builder().build();
DynamoDbEnhancedClient enhancedClient =
DynamoDbEnhancedClient.builder()
.dynamoDbClient(dynamoDbClient)
.extensions(versionedRecordExtension, verifyChecksumExtension)
.build();
```
## Détails et configuration des extensions disponibles
Les sections suivantes fournissent des informations détaillées sur chaque extension disponible dans le SDK.
### Mettez en œuvre un verrouillage optimiste avec le `VersionedRecordExtension`
L'`VersionedRecordExtension`extension permet un verrouillage optimiste en incrémentant et en suivant le numéro de version d'un élément au fur et à mesure que les éléments sont écrits dans la base de données. Une condition est ajoutée à chaque écriture qui entraîne l'échec de l'écriture si le numéro de version de l'élément persistant réel ne correspond pas à la valeur lue pour la dernière fois par l'application.
#### Configuration
Pour spécifier l'attribut à utiliser pour suivre le numéro de version de l'article, balisez un attribut numérique dans le schéma du tableau.
L'extrait suivant indique que l'`version`attribut doit contenir le numéro de version de l'article.
```
@DynamoDbVersionAttribute
public Integer getVersion() {...};
public void setVersion(Integer version) {...};
```
L'approche équivalente du schéma de table statique est illustrée dans l'extrait suivant.
```
.addAttribute(Integer.class, a -> a.name("version")
.getter(Customer::getVersion)
.setter(Customer::setVersion)
// Apply the 'version' tag to the attribute.
.tags(VersionedRecordExtension.AttributeTags.versionAttribute())
```
#### Comment ça marche
Le verrouillage optimiste avec le `VersionedRecordExtension` a l'impact suivant sur ces derniers `DynamoDbEnhancedClient` et sur `DynamoDbTable` les méthodes :
**`putItem`**
Une valeur de version initiale de 0 est attribuée aux nouveaux éléments. Cela peut être configuré avec`@DynamoDbVersionAttribute(startAt = X)`.
**`updateItem`**
Si vous récupérez un élément, mettez à jour une ou plusieurs de ses propriétés et tentez d'enregistrer les modifications, l'opération n'aboutit que si le numéro de version côté client et côté serveur correspondent.
En cas de succès, le numéro de version est automatiquement incrémenté de 1. Cela peut être configuré avec`@DynamoDbVersionAttribute(incrementBy = X)`.
**`deleteItem`**
L'`DynamoDbVersionAttribute`annotation n'a aucun effet. Vous devez ajouter une expression de condition manuellement lorsque vous supprimez un élément.
L'exemple suivant ajoute une expression conditionnelle pour garantir que l'élément supprimé est bien celui qui a été lu. Dans l'exemple suivant, `recordVersion` l'attribut du bean est annoté avec`@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`: Cette méthode a le même comportement que`putItem`.
+ `addUpdateItem`: Cette méthode a le même comportement que`updateItem`.
+ `addDeleteItem`: Cette méthode a le même comportement que`deleteItem`.
**`batchWriteItem`**
+ `addPutItem`: Cette méthode a le même comportement que`putItem`.
+ `addDeleteItem`: Cette méthode a le même comportement que`deleteItem`.
**Note**
Les tables globales DynamoDB utilisent [une réconciliation « le dernier rédacteur gagne » entre les](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/V2globaltables_HowItWorks.html#V2globaltables_HowItWorks.consistency-modes) mises à jour simultanées, DynamoDB faisant de son mieux pour déterminer le dernier rédacteur. Si vous utilisez des tables globales, cette règle du « dernier rédacteur gagne » signifie que les stratégies de verrouillage risquent de ne pas fonctionner comme prévu, car toutes les répliques finiront par converger en fonction de la dernière écriture déterminée par DynamoDB.
#### Comment désactiver
Pour désactiver le verrouillage optimiste, n'utilisez pas l'`@DynamoDbVersionAttribute`annotation.
### Implémentez des compteurs avec le `AtomicCounterExtension`
L'`AtomicCounterExtension`extension incrémente un attribut numérique balisé chaque fois qu'un enregistrement est écrit dans la base de données. Vous pouvez spécifier des valeurs de départ et d'incrémentation. Si aucune valeur n'est spécifiée, la valeur de départ est définie sur 0 et la valeur de l'attribut augmente de 1.
#### Configuration
Pour spécifier quel attribut est un compteur, balisez un attribut de type `Long` dans le schéma du tableau.
L'extrait suivant montre l'utilisation des valeurs de début et d'incrément par défaut pour l'attribut. `counter`
```
@DynamoDbAtomicCounter
public Long getCounter() {...};
public void setCounter(Long counter) {...};
```
L'approche du schéma de table statique est illustrée dans l'extrait suivant. L'extension du compteur atomique utilise une valeur de départ de 10 et augmente la valeur de 5 à chaque fois que l'enregistrement est écrit.
```
.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))
```
### Ajoutez des horodatages avec le `AutoGeneratedTimestampRecordExtension`
L'`AutoGeneratedTimestampRecordExtension`extension met automatiquement à jour les attributs de type balisés `[Instant](https://docs.oracle.com/javase/8/docs/api/java/time/Instant.html)` avec un horodatage actuel chaque fois que l'élément est écrit avec succès dans la base de données. Cette extension n'est pas chargée par défaut.
#### Configuration
Pour spécifier l'attribut à mettre à jour avec l'horodatage actuel, balisez-le dans le `Instant` schéma de la table.
L'`lastUpdate`attribut est la cible du comportement de l'extension dans l'extrait suivant. Notez l'exigence selon laquelle l'attribut doit être un `Instant` type.
```
@DynamoDbAutoGeneratedTimestampAttribute
public Instant getLastUpdate() {...}
public void setLastUpdate(Instant lastUpdate) {...}
```
L'approche équivalente du schéma de table statique est illustrée dans l'extrait suivant.
```
.addAttribute(Instant.class, a -> a.name("lastUpdate")
.getter(Customer::getLastUpdate)
.setter(Customer::setLastUpdate)
// Applying the 'autoGeneratedTimestamp' tag to the attribute.
.tags(AutoGeneratedTimestampRecordExtension.AttributeTags.autoGeneratedTimestampAttribute())
```
### Générez un UUID avec le AutoGeneratedUuidExtension
L'`AutoGeneratedUuidExtension`extension génère un UUID (identifiant unique universel) unique pour un attribut lorsqu'un nouvel enregistrement est écrit dans la base de données. Utilise la méthode Java JDK [UUID.randomUUID ()](https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html#randomUUID--) et s'applique aux attributs de type. `java.lang.String` Cette extension n'est pas chargée par défaut.
#### Configuration
L'`uniqueId`attribut est la cible du comportement de l'extension dans l'extrait suivant.
```
@AutoGeneratedUuidExtension
public String getUniqueId() {...}
public void setUniqueId(String uniqueId) {...}
```
L'approche équivalente du schéma de table statique est illustrée dans l'extrait suivant.
```
.addAttribute(String.class, a -> a.name("uniqueId")
.getter(Customer::getUniqueId)
.setter(Customer::setUniqueId)
// Applying the 'autoGeneratedUuid' tag to the attribute.
.tags(AutoGeneratedUuidExtension.AttributeTags.autoGeneratedUuidAttribute())
```
Si vous souhaitez que l'extension renseigne l'UUID uniquement pour les `putItem` méthodes et non pour les `updateItem` méthodes, ajoutez l'annotation du [comportement de mise à jour](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/mapper/UpdateBehavior.html) comme indiqué dans l'extrait suivant.
```
@AutoGeneratedUuidExtension
@DynamoDbUpdateBehavior(UpdateBehavior.WRITE_IF_NOT_EXISTS)
public String getUniqueId() {...}
public void setUniqueId(String uniqueId) {...}
```
Si vous utilisez l'approche du schéma de table statique, utilisez le code équivalent suivant.
```
.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))
```
# Exemple d'extension personnalisée
Vous pouvez créer des extensions personnalisées en implémentant l'`DynamoDbEnhancedClientExtension`interface. La classe d'extension personnalisée suivante montre une `beforeWrite()` méthode qui utilise une expression de mise à jour pour définir un `registrationDate` attribut si l'élément de la base de données n'en possède pas déjà un.
```
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();
}
}
```
# Utiliser l'API client améliorée DynamoDB de manière asynchrone
Si votre application nécessite des appels asynchrones non bloquants à DynamoDB, vous pouvez utiliser le. [DynamoDbEnhancedAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.html) Elle est similaire à l'implémentation synchrone, mais avec les principales différences suivantes :
1. Lorsque vous créez le`DynamoDbEnhancedAsyncClient`, vous devez fournir la version asynchrone du client standard`DynamoDbAsyncClient`, comme indiqué dans l'extrait de code suivant.
```
DynamoDbEnhancedAsyncClient enhancedClient =
DynamoDbEnhancedAsyncClient.builder()
.dynamoDbClient(dynamoDbAsyncClient)
.build();
```
1. Les méthodes qui renvoient un seul objet de données renvoient une partie `CompletableFuture` du résultat au lieu du seul résultat. Votre application peut ensuite effectuer d'autres travaux sans avoir à bloquer le résultat. L'extrait suivant montre la méthode asynchrone`getItem()`.
```
CompletableFuture result = customerDynamoDbTable.getItem(customer);
// Perform other work here.
return result.join(); // Now block and wait for the result.
```
1. Les méthodes qui renvoient des listes de résultats paginées renvoient un [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)au lieu d'un [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)que le synchrone `DynamoDbEnhanceClient` renvoie pour les mêmes méthodes. Votre application peut ensuite abonner un gestionnaire à cet éditeur pour traiter les résultats de manière asynchrone sans avoir à les bloquer.
```
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.
```
Pour un exemple plus complet d'utilisation du`SdkPublisher API`, consultez [l'exemple présenté](ddb-en-client-use-multirecord.md#ddb-en-client-use-multirecord-scan-async) dans la section de ce guide consacrée à la `scan()` méthode asynchrone.
# Annotations de classes de données
Le tableau suivant répertorie les annotations qui peuvent être utilisées sur les classes de données et fournit des liens vers des informations et des exemples contenus dans ce guide. Le tableau est trié par ordre alphabétique croissant par nom d'annotation.
**Annotations de classes de données utilisées dans ce guide**
| Nom de l'annotation | L'annotation s'applique à 1 | Ce qu'il fait | Où cela est indiqué dans ce guide |
| --- | --- | --- | --- |
| DynamoDbAtomicCounter | attribut 2 | Incrémente un attribut numérique balisé chaque fois qu'un enregistrement est écrit dans la base de données. | [Présentation et discussion.](ddb-en-client-extensions.md#ddb-en-client-extensions-ACE) |
| DynamoDbAttribute | attribute | Définit ou renomme une propriété de bean mappée à un attribut de table DynamoDB. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbAutoGeneratedTimestampAttribute | attribute | Met à jour un attribut balisé avec un horodatage actuel chaque fois que l'élément est correctement écrit dans la base de données | [Présentation et discussion](ddb-en-client-extensions.md#ddb-en-client-extensions-AGTE). |
| DynamoDbAutoGeneratedUuid | attribute | Générez un UUID (identifiant unique universel) unique pour un attribut lorsqu'un nouvel enregistrement est écrit dans la base de données. | [Présentation et discussion.](ddb-en-client-extensions.md#ddb-en-client-extensions-AGUE) |
| DynamoDbBean | class | Marque une classe de données comme mappable à un schéma de table. | Première utilisation dans la [classe Customer](ddb-en-client-gs-tableschema.md#ddb-en-client-gs-tableschema-anno-bean-cust) dans la section Commencer. Plusieurs utilisations apparaissent dans le guide. |
| DynamoDbConvertedBy | attribute | Associe une personnalisation AttributeConverter à l'attribut annoté. | [Discussion initiale et exemple.](ddb-en-client-adv-features-conversion.md#ddb-en-client-adv-features-conversion-single) |
| DynamoDbFlatten | attribute | Aplatit tous les attributs d'une classe de données DynamoDB distincte et les ajoute en tant qu'attributs de premier niveau à l'enregistrement lu et écrit dans la base de données. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbIgnore | attribute | Il en résulte que l'attribut reste non mappé. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbIgnoreNulls | attribute | Empêche l'enregistrement des attributs nuls des DynamoDb objets imbriqués. | [Discussion et exemples.](ddb-en-client-adv-features-ignore-null.md) |
| DynamoDbImmutable | class | Marque une classe de données immuable comme mappable à un schéma de table. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbPartitionKey | attribute | Marque un attribut comme clé de partition principale (clé de hachage) de la DynamoDb table. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbPreserveEmptyObject | attribute | Spécifie que si aucune donnée n'est présente pour l'objet mappé à l'attribut annoté, l'objet doit être initialisé avec tous les champs nuls. | [Discussion et exemples.](ddb-en-client-adv-features-empty.md) |
| DynamoDbSecondaryPartitionKey | attribute | Marque un attribut comme clé de partition pour un index secondaire global. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbSecondarySortKey | attribute | Marque un attribut comme clé de tri facultative pour un index secondaire global ou local. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbSortKey | attribute | Marque un attribut comme clé de tri primaire facultative (clé de plage). | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbUpdateBehavior | attribute | Spécifie le comportement lorsque cet attribut est mis à jour dans le cadre d'une opération de « mise à jour » telle que UpdateItem. | [Introduction et exemple.](ddb-en-client-adv-features-upd-behavior.md) |
| DynamoDbVersionAttribute | attribute | Incrémente le numéro de version d'un article. | [Présentation et discussion.](ddb-en-client-extensions.md#ddb-en-client-extensions-VRE) |
1 Vous pouvez appliquer des annotations au niveau de l'attribut au getter ou au setter, mais pas aux deux. Ce guide montre les annotations sur les getters.
2 Le terme `property` est normalement utilisé pour une valeur encapsulée dans une classe de JavaBean données. Toutefois, ce guide utilise ce terme à la `attribute` place, par souci de cohérence avec la terminologie utilisée par DynamoDB.