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();
```
O exemplo anterior do esquema estático usa as seguintes classes de dados:
#### Classes de dados
------
#### [ 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;
}
```
------
Você pode usar o padrão do construtor para nivelar quantas classes elegíveis forem necessárias.
## Implicações para outro código
Quando você usa o atributo `@DynamoDbFlatten` (ou método `flatten()` do construtor), o item no DynamoDB contém um atributo para cada atributo do objeto composto. Isso também inclui os atributos do objeto de composição.
Por outro lado, se você anotar uma classe de dados com uma classe composta e não usar `@DynamoDbFlatten`, o item será salvo com o objeto composto como um único atributo.
Por exemplo, compare a classe `Customer` mostrada no [exemplo de nivelamento com composição](#ddb-en-client-adv-features-flatmap-comp-anno) com e sem nivelamento do atributo `record`. Você pode visualizar a diferença com JSON conforme mostrado na tabela a seguir.
****
| Com nivelamento | Sem nivelamento |
| --- | --- |
| 3 atributos | 2 atributos |
| {
"id": "1",
"createdDate": "today",
"name": "my name"
} | {
"id": "1",
"record": {
"createdDate": "today",
"name": "my name"
}
} |
A diferença se torna importante se você tiver outro código acessando a tabela do DynamoDB que espera encontrar certos atributos.
# Trabalhar com atributos que são beans, mapas, listas e conjuntos
Uma definição de bean, como a classe `Person` mostrada abaixo, pode definir propriedades (ou atributos) que se referem a tipos com atributos adicionais. Por exemplo, na classe `Person`, `mainAddress` é uma propriedade que se refere a um bean `Address` que define atributos de valor adicionais. `addresses` refere-se a um mapa Java, cujos elementos se referem a beans `Address`. Esses tipos complexos podem ser considerados contêineres de atributos simples que você usa como valor de dados no contexto do DynamoDB.
O DynamoDB se refere às propriedades de valor de elementos aninhados, como mapas, listas ou beans, como *atributos aninhados*. O [Guia do desenvolvedor do Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes) se refere à forma salva de um mapa, lista ou bean Java como um *tipo de documento*. Os atributos simples que você usa como valor de dados em Java são chamados de *tipos escalares* no DynamoDB. Conjuntos, que contêm vários elementos escalares do mesmo tipo e chamados de *tipos de conjuntos*.
É importante saber que a API do Cliente Aprimorado do DynamoDB converte uma propriedade que é bean em um tipo de documento de mapa do DynamoDB quando é salva.
## 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 + '\'' +
'}';
}
}
```
## Salvar tipos complexos
### Usar classes de dados anotadas
Salve atributos aninhados para classes personalizadas simplesmente fazendo anotações neles. A classe `Address` e a classe `PhoneNumber` mostradas anteriormente são anotadas somente com a anotação `@DynamoDbBean`. Quando a API do Cliente Aprimorado do DynamoDB cria o esquema de tabela para a classe `Person` com o seguinte trecho, a API descobre o uso das classes `Address` e `PhoneNumber` e cria os mapeamentos correspondentes para funcionar com o DynamoDB.
```
TableSchema personTableSchema = TableSchema.fromBean(Person.class);
```
### Usar esquemas abstratos com compiladores
A abordagem alternativa é usar compiladores de esquemas de tabelas estáticas para cada classe de bean aninhada, conforme mostrado no código a seguir.
Os esquemas de tabela das classes `Address` e `PhoneNumber` são abstratos, uma vez que não podem ser usados com uma tabela do DynamoDB. Isso ocorre porque eles não têm definições para a chave primária. No entanto, eles são usados como esquemas aninhados no esquema de tabela da classe `Person`.
Depois de comentar as linhas 1 e 2 na definição de `PERSON_TABLE_SCHEMA`, você vê o código que usa os esquemas de tabela abstrata. O uso de `documentOf` no método `EnhanceType.documentOf(...)` não indica que o método retorne um tipo `EnhancedDocument` da API de documento aprimorado. O método `documentOf(...)` nesse contexto retorna um objeto que sabe como mapear seu argumento de classe de e para os atributos da tabela do DynamoDB usando o argumento do esquema da tabela.
#### Código de esquema estático
```
// 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();
```
## Atributos de projeto de tipos complexos
Para os métodos `query()` e `scan()`, você pode especificar quais atributos você deseja que sejam retornados nos resultados usando chamadas de método como `addNestedAttributeToProject()` e `attributesToProject()`. A API do Cliente Aprimorado do DynamoDB converte os parâmetros de chamada do método Java em [expressões de projeção](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html) antes do envio da solicitação.
O exemplo a seguir preenche a tabela `Person` com dois itens e, em seguida, executa três operações de verificação.
A primeira verificação acessa todos os itens da tabela para comparar os resultados com as outras operações de verificação.
A segunda verificação usa o método do construtor [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)) para retornar somente o valor do atributo `street`.
A terceira operação de varredura usa o método do construtor [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...)) para retornar os dados do atributo de primeiro nível, `hobbies`. O tipo do atributo de `hobbies` é uma lista. Para acessar itens individuais da lista, execute uma operação `get()` na lista.
```
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
```
**nota**
Se o método `attributesToProject()` seguir qualquer outro método do construtor que adiciona atributos que você deseja projetar, a lista de nomes de atributos fornecida ao `attributesToProject()` substitui todos os outros nomes de atributos.
Uma verificação realizada com a instância `ScanEnhancedRequest` no trecho a seguir retorna somente dados de hobby.
```
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]}
```
O trecho de código a seguir usa o método `attributesToProject()` primeiro. Essa ordenação preserva todos os outros atributos obrigatórios.
```
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]}
```
## Usar tipos complexos em expressões
É possível usar tipos complexos em expressões, como expressões de filtro e expressões condicionais, usando operadores de desreferenciamento para navegar pela estrutura do tipo complexo. Para objetos e mapas, use `. (dot)` e para elementos da lista use `[n]` (colchetes ao redor do número de sequência do elemento). Não é possível se referir a elementos individuais de um conjunto, mas você pode usar a [função `contains`](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions).
O exemplo a seguir mostra duas expressões de filtro usadas em operações de varredura. As expressões de filtro especificam as condições de correspondência dos itens que você deseja nos resultados. O exemplo usa as classes `Person`, `Address` e `PhoneNumber` mostradas anteriormente.
```
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étodo auxiliar que preenche a tabela
```
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);
}
```
### Representação JSON de itens no banco de dados
```
{
"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"
}
]
}
```
## Atualizar itens que contêm tipos complexos
Para atualizar um item que contém tipos complexos, você tem duas abordagens básicas:
+ Abordagem 1: primeiro recupere o item (usando `getItem`), atualize o objeto e, depois, chame `DynamoDbTable#updateItem`.
+ Abordagem 2: não recupere o item, mas construa uma nova instância, defina as propriedades que você deseja atualizar e envie a instância para `DynamoDbTable#updateItem` definindo o valor apropriado 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). Essa abordagem não exige que você busque o item antes de atualizá-lo.
Os exemplos mostrados nesta seção usam as classes `Person`, `Address` e `PhoneNumber` mostradas anteriormente.
### Abordagem de atualização 1: recuperar e, depois, atualizar
Ao usar essa abordagem, você garante que nenhum dado seja perdido na atualização. A API do Cliente Aprimorado do DynamoDB recria o bean com os atributos do item salvo no DynamoDB, incluindo valores de tipos complexos. Depois, você precisa usar os getters e setters para atualizar o bean. A desvantagem dessa abordagem é o custo em que você incorre ao recuperar o item primeiro.
O exemplo a seguir demonstra que nenhum dado será perdido se você recuperar o item antes de atualizá-lo.
```
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;
}
```
### Abordagem de atualização 2: use uma enumeração `IgnoreNullsMode` sem recuperar o item primeiro
Para atualizar um item no DynamoDB, é possível fornecer um novo objeto que tenha somente as propriedades que você deseja atualizar e deixar os outros valores como nulos. Com essa abordagem, você precisa estar ciente de como os valores nulos no objeto são tratados pelo SDK e como controlar o comportamento.
Para especificar quais propriedades de valor nulo você deseja que o SDK ignore, forneça uma enumeração `IgnoreNullsMode` ao criar o [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). Como exemplo do uso de um dos valores enumerados, o trecho a seguir usa o modo `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"
}
}
*/
```
O Guia do desenvolvedor do Amazon DynamoDB contém mais informações sobre [expressões de atualização](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html).
#### Descrições das opções `IgnoreNullsMode`
+ `IgnoreNullsMode.SCALAR_ONLY`: use essa configuração para atualizar atributos escalares em qualquer nível. O SDK cria uma declaração de atualização que envia somente atributos escalares não nulos para o DynamoDB. O SDK ignora os atributos escalares de valor nulo de um bean ou mapa, mantendo o valor salvo no DynamoDB.
Quando você atualiza um atributo escalar de map ou bean, o mapa já deve existir no DynamoDB. Se adicionar um mapa ou um bean ao objeto que ainda não existe para o objeto no DynamoDB, você receberá uma `DynamoDbException` com a mensagem *O caminho do documento fornecido na expressão de atualização é inválido para atualização*. Você deve usar o modo `MAPS_ONLY` para adicionar um bean ou um mapa ao DynamoDB antes de atualizar qualquer um de seus atributos.
+ `IgnoreNullsMode.MAPS_ONLY`: use essa configuração para adicionar ou substituir propriedades que são um bean ou um mapa. O SDK substitui ou adiciona qualquer mapa ou bean fornecido no objeto. Todos os beans ou mapas que são nulos no objeto são ignorados, mantendo o mapa que existe no DynamoDB.
+ `IgnoreNullsMode.DEFAULT`: com essa configuração, o SDK nunca ignora valores nulos. Os atributos escalares em qualquer nível que sejam nulos são atualizados para nulos. O SDK atualiza qualquer bean, mapa, lista ou propriedade de conjunto com valor nulo no objeto para nulo no DynamoDB. Quando você usa esse modo, ou não informa nenhum modo, já que ele é o padrão, é recomendável recuperar o item antes. Isso evita que valores existentes no DynamoDB sejam substituídos por nulo devido aos valores nulos presentes no objeto usado para a atualização, a menos que a sua intenção seja realmente definir esses valores como nulos.
Em todos os modos, se você fornecer um objeto `updateItem` que tenha uma lista ou conjunto não nulo, a lista ou o conjunto será salvo no DynamoDB.
#### Por que os modos?
Quando você fornece um objeto com um bean ou um mapa para o `updateItem` método, o SDK não sabe se deve usar os valores das propriedades no bean (ou os valores de entrada no mapa) para atualizar o item ou se o todo bean/map deve substituir o que foi salvo no DynamoDB.
Trabalhando com nosso exemplo anterior, que mostra primeiro a recuperação do item, vamos tentar atualizar o atributo `city` de `mainAddress` sem a recuperação.
```
/* 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'.
*/
```
Os dois exemplos a seguir mostram os usos dos valores `MAPS_ONLY` e `SCALAR_ONLY` enumerados. `MAPS_ONLY` adiciona um mapa e `SCALAR_ONLY` atualiza um mapa.
##### Exemplo 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.
}
```
Consulte na tabela a seguir quais valores nulos são ignorados em cada modo. Muitas vezes, você pode trabalhar com `SCALAR_ONLY` e `MAPS_ONLY`, exceto quando trabalha com beans ou mapas.
**Quais propriedades de valor nulo no objeto enviado para `updateItem` o SDK ignora em cada modo?**
| Tipo de propriedade | no modo SCALAR\$1ONLY | no modo MAPS\$1ONLY | no modo DEFAULT |
| --- | --- | --- | --- |
| Escalar superior | Sim | Sim | Não |
| Bean ou mapa | Sim | Sim | Não |
| Valor escalar de uma entrada de bean ou mapa | Sim1 | Número2 | Não |
| Listar ou definir | Sim | Sim | Não |
1Isso pressupõe que o mapa já exista no DynamoDB. Qualquer valor escalar, seja nulo ou não, do bean ou mapa que você fornece no objeto para atualização exige que exista um caminho para o valor no DynamoDB. O SDK constrói um caminho para o atributo usando o operador de desreferenciação `. (dot)` antes de enviar a solicitação.
2Como você usa o modo `MAPS_ONLY` para substituir totalmente ou adicionar um bean ou mapa, todos os valores nulos no bean ou no mapa são retidos no mapa salvo no DynamoDB.
# Preservar objetos vazios com `@DynamoDbPreserveEmptyObject`
Se você salvar um bean no Amazon DynamoDB com objetos vazios e quiser que o SDK recrie os objetos vazios após a recuperação, anote o getter do bean interno com `@DynamoDbPreserveEmptyObject`.
Para ilustrar como a anotação funciona, o exemplo de código usa os dois beans a seguir.
## Exemplos de beans
A classe de dados a seguir contém dois campos `InnerBean`. O método getter, `getInnerBeanWithoutAnno()`, não é anotado com `@DynamoDbPreserveEmptyObject`. O método `getInnerBeanWithAnno()` é anotado.
```
@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();
}
}
```
As instâncias da classe `InnerBean` a seguir são campos de `MyBean` e são inicializadas como objetos vazios no código de exemplo.
```
@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 + '\'' +
'}';
}
}
```
O exemplo de código a seguir salva um objeto `MyBean` com beans internos inicializados no DynamoDB e, em seguida, recupera o item. A saída registrada mostra que o `innerBeanWithoutAnno` não foi inicializado, mas `innerBeanWithAnno` foi criado.
```
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;
}
```
## Esquema estático alternativo
Você pode usar a seguinte versão `StaticTableSchema` dos esquemas de tabela no lugar das anotações nos 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();
}
```
# Evitar salvar atributos nulos de objetos aninhados
Você pode ignorar atributos nulos de objetos aninhados ao salvar um objeto de classe de dados no DynamoDB aplicando a anotação `@DynamoDbIgnoreNulls`. Por outro lado, atributos de nível superior com valores nulos nunca são salvos no banco de dados.
Para ilustrar como a anotação funciona, o exemplo de código usa os dois beans a seguir.
## Exemplos de beans
A classe de dados a seguir contém dois campos `InnerBean`. O método getter, `getInnerBeanWithoutAnno()`, não é anotado. O método `getInnerBeanWithIgnoreNullsAnno()` é anotado com `@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();
}
}
```
As instâncias da classe `InnerBean` a seguir são campos de `MyBean` e são usadas no código de exemplo a seguir.
```
@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();
}
}
```
O exemplo de código a seguir cria um objeto `InnerBean` e define somente um de seus dois atributos com um valor.
```
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);
}
```
Para visualizar os dados de nível baixo enviados ao DynamoDB, o código registra o mapa de atributos antes de salvar o objeto `MyBean`.
A saída registrada mostra que `innerBeanWithIgnoreNullsAnno` gera um atributo,
```
innerBeanWithIgnoreNullsAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200)})
```
A instância `innerBeanWithoutAnno` gera dois atributos. Um atributo tem um valor de 200 e o outro é um atributo de valor nulo.
```
innerBeanWithoutAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200), innerBeanFieldString=AttributeValue(NUL=true)})
```
## Representação JSON do mapa de atributo
A representação JSON a seguir facilita a visualização dos dados salvos no DynamoDB.
```
{
"id": {
"S": "1"
},
"innerBeanWithIgnoreNullsAnno": {
"M": {
"innerBeanFieldInteger": {
"N": "200"
}
}
},
"innerBeanWithoutAnno": {
"M": {
"innerBeanFieldInteger": {
"N": "200"
},
"innerBeanFieldString": {
"NULL": true
}
}
}
}
```
## Esquema estático alternativo
Você pode usar a seguinte versão `StaticTableSchema` dos esquemas de tabela nas anotações da classe de dados no local.
```
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();
}
```
# Trabalhar com documentos JSON com a API de documentos aprimorados do DynamoDB
A [API de documentos aprimorada](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/package-summary.html) para foi AWS SDK for Java 2.x projetada para funcionar com dados orientados a documentos que não têm um esquema fixo. No entanto, ela também permite que você use classes personalizadas para mapear atributos individuais.
A API de documentos aprimorada é a sucessora da [API de documentos](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/DynamoDB.html) da AWS SDK para Java v1.x.
**Contents**
+ [Começar a usar a API de documentos aprimorados](ddb-en-client-doc-api-steps.md)
+ [Criar um `DocumentTableSchema` e uma `DynamoDbTable`](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema)
+ [Criar documentos aprimorados](ddb-en-client-doc-api-steps-create-ed.md)
+ [Criar a partir de uma cadeia de caracteres JSON](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromJson)
+ [Criar a partir de elementos individuais](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts)
+ [Executar operações de CRUD](ddb-en-client-doc-api-steps-use.md)
+ [Acessar atributos do documento aprimorado como objetos personalizados](ddb-en-client-doc-api-convert.md)
+ [Usar um `EnhancedDocument` sem o DynamoDB](ddb-en-client-doc-api-standalone.md)
# Começar a usar a API de documentos aprimorados
A API de Documento Aprimorado exige as mesmas [dependências](ddb-en-client-getting-started.md#ddb-en-client-gs-dep) necessárias para a API do Cliente Aprimorado do DynamoDB. Ela também requer uma [instância `DynamoDbEnhancedClient`](ddb-en-client-getting-started-dynamodbTable.md#ddb-en-client-getting-started-dynamodbTable-eclient), conforme mostrado no início deste tópico.
Como a API de documentos aprimorada foi lançada com a versão 2.20.3 do AWS SDK for Java 2.x, você precisa dessa versão ou superior.
## Criar um `DocumentTableSchema` e uma `DynamoDbTable`
Para invocar comandos em uma tabela do DynamoDB usando a Enhanced Document API, associe a tabela a um objeto de recurso < > do lado do [DynamoDbTablecliente EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html).
O método `table()` do cliente aprimorado cria uma instância `DynamoDbTable` e exige parâmetros para o nome da tabela do DynamoDB e uma `DocumentTableSchema`.
O construtor de um [DocumentTableSchema](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/DocumentTableSchema.html)requer uma chave de índice primária e um ou mais provedores de conversão de atributos. O método `AttributeConverterProvider.defaultProvider()` fornece conversores para [tipos padrão](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/internal/converter/attribute/package-summary.html). Ele deve ser especificado mesmo se você fornecer um provedor de conversão de atributos personalizado. Você pode adicionar uma chave de índice secundária opcional ao construtor.
O trecho de código a seguir mostra o código que gera a representação do lado do cliente de uma tabela `person` do DynamoDB que armazena objetos `EnhancedDocument` sem esquema.
```
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.
```
Veja a seguir a representação JSON de um objeto `person` usado em toda esta seção.
### Objeto 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"
}
]
}
```
# Criar documentos aprimorados
Um `[EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html)` representa um objeto do tipo documento que tem uma estrutura complexa com atributos aninhados. Um `EnhancedDocument` requer atributos de nível superior que correspondam aos atributos da chave primária especificados para o `DocumentTableSchema`. O conteúdo restante é arbitrário e pode consistir em atributos de nível superior e também em atributos profundamente aninhados.
Você cria uma instância `EnhancedDocument` usando um construtor que fornece várias maneiras de adicionar elementos.
## Criar a partir de uma cadeia de caracteres JSON
Com uma cadeia de caracteres JSON, você pode criar um `EnhancedDocument` com uma chamada do método. O trecho a seguir cria um `EnhancedDocument` a partir de uma cadeia de caracteres JSON retornada pelo método auxiliar `jsonPerson()`. O método `jsonPerson()` retorna a versão da cadeia de caracteres JSON do [objeto person](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema-obj) mostrado anteriormente.
```
EnhancedDocument document =
EnhancedDocument.builder()
.json( jsonPerson() )
.build());
```
## Criar a partir de elementos individuais
Como alternativa, você pode criar uma instância `EnhancedDocument` a partir de componentes individuais usando métodos seguros de tipo do construtor.
O exemplo a seguir cria um documento aprimorado `person` semelhante ao documento aprimorado criado a partir da cadeia de caracteres JSON no exemplo anterior.
```
/* 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étodos auxiliares
```
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"));
}
```
# Executar operações de CRUD
Depois que definir uma instância `EnhancedDocument`, você poderá salvá-la em uma tabela do DynamoDB. O trecho de código a seguir usa o [personDocument](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts) que foi criado a partir de elementos individuais.
```
documentDynamoDbTable.putItem(personDocument);
```
Depois de ler uma instância de documento aprimorado a partir do DynamoDB, você pode extrair os valores dos atributos individuais usando getters, conforme mostrado no trecho de código a seguir, que acessam os dados salvos do `personDocument`. Como alternativa, você pode extrair o conteúdo completo em uma cadeia de caracteres JSON, conforme mostrado na última parte do código de exemplo.
```
// 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`as instâncias podem ser usadas com qualquer método de `[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)no lugar de classes de dados mapeadas.
# Acessar atributos do documento aprimorado como objetos personalizados
Além de fornecer uma API para ler e gravar atributos com estruturas sem esquemas, a API de Documento Aprimorado permite converter atributos de e para instâncias de classes personalizadas.
A API de Documento Aprimorado usa `AttributeConverterProvider`s e `AttributeConverter`s que foram mostrados na seção de [conversão de atributos de controle](ddb-en-client-adv-features-conversion.md) como parte da API do Cliente Aprimorado do DynamoDB.
No exemplo a seguir, usamos um `CustomAttributeConverterProvider` com sua classe `AddressConverter` aninhada para converter objetos `Address`.
Este exemplo mostra que você pode misturar dados de classes e também dados de estruturas que são criadas conforme necessário. Esse exemplo também mostra que classes personalizadas podem ser usadas em qualquer nível de uma estrutura aninhada. Os objetos `Address` neste exemplo são valores usados em um mapa.
```
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'}
```
## Código `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étodo auxiliar que fornece endereços
O método auxiliar a seguir fornece o mapa que usa instâncias `Address` personalizadas para valores em vez de instâncias `Map` genéricas para valores.
```
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);
}
```
# Usar um `EnhancedDocument` sem o DynamoDB
Embora você geralmente use uma instância de um `EnhancedDocument` para ler e gravar itens do tipo documento do DynamoDB, ela também pode ser usada independentemente do DynamoDB.
Você pode usar `EnhancedDocuments` pela sua capacidade de converter desde cadeias de caracteres JSON ou objetos personalizados a mapas de nível baixo de `AttributeValues`, conforme mostrado no exemplo a seguir.
```
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'}
*/
```
**nota**
Ao usar um documento aprimorado independente de uma tabela do DynamoDB, defina explicitamente os provedores de conversão de atributos no construtor.
Por outro lado, o esquema da tabela de documentos fornece os provedores de conversão quando um documento aprimorado é usado com uma tabela do DynamoDB.
# Usar extensões para personalizar as operações do Cliente Aprimorado do DynamoDB
A API do Cliente Aprimorado do DynamoDB fornece suporte a extensões de complemento que fornecem funcionalidades além das operações de mapeamento. As extensões usam dois métodos de hook para modificar dados durante as operações de leitura e gravação:
+ `beforeWrite()`: modifica uma operação de gravação antes que ela aconteça
+ `afterRead()`: modifica os resultados de uma operação de leitura depois que ela acontece
Algumas operações (como atualizações de itens) realizam uma gravação e depois uma leitura, então os dois métodos de hook são chamados.
## Como as extensões são carregadas
As extensões são carregadas na ordem em que você especifica no compilador do cliente aprimorado. A ordem de carregamento pode ser importante porque uma extensão pode atuar em valores que foram transformados por uma extensão anterior.
Por padrão, o cliente aprimorado carrega duas extensões:
+ `[VersionedRecordExtension](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/extensions/VersionedRecordExtension.html)`: proporciona um bloqueio positivo
+ `[AtomicCounterExtension](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/extensions/AtomicCounterExtension.html)`: incrementa automaticamente os atributos do contador
Você pode substituir o comportamento padrão com o compilador de cliente aprimorado e carregar qualquer extensão. Você também pode especificar nenhuma se não quiser as extensões padrão.
**Importante**
Se você carregar suas próprias extensões, o cliente aprimorado não carregará nenhuma extensão padrão. Se você quiser o comportamento fornecido por uma extensão padrão, precisará adicioná-la explicitamente à lista de extensões.
O exemplo a seguir mostra como carregar uma extensão personalizada chamada `verifyChecksumExtension` depois de `VersionedRecordExtension`. A `AtomicCounterExtension` não está carregada neste exemplo.
```
DynamoDbEnhancedClientExtension versionedRecordExtension = VersionedRecordExtension.builder().build();
DynamoDbEnhancedClient enhancedClient =
DynamoDbEnhancedClient.builder()
.dynamoDbClient(dynamoDbClient)
.extensions(versionedRecordExtension, verifyChecksumExtension)
.build();
```
## Detalhes e configuração da extensão disponível
As seções a seguir fornecem informações detalhadas sobre cada extensão disponível no SDK.
### Implementar um bloqueio positivo com o `VersionedRecordExtension`
A extensão `VersionedRecordExtension` fornece bloqueio positivo incrementando e rastreando um número de versão do item à medida que os itens são gravados no banco de dados. É adicionada uma condição a cada operação de gravação que faz com que ela falhe caso o número de versão do item armazenado não corresponda ao valor que a aplicação leu por último.
#### Configuração
Para especificar qual atributo usar para rastrear o número da versão do item, marque um atributo numérico no esquema da tabela.
O trecho a seguir especifica que o atributo `version` deve conter o número da versão do item.
```
@DynamoDbVersionAttribute
public Integer getVersion() {...};
public void setVersion(Integer version) {...};
```
A abordagem equivalente do esquema de tabela estática é mostrada no trecho a seguir.
```
.addAttribute(Integer.class, a -> a.name("version")
.getter(Customer::getVersion)
.setter(Customer::setVersion)
// Apply the 'version' tag to the attribute.
.tags(VersionedRecordExtension.AttributeTags.versionAttribute())
```
#### Como funciona
O bloqueio positivo com a `VersionedRecordExtension` tem o seguinte impacto sobre estes métodos `DynamoDbEnhancedClient` e `DynamoDbTable`:
**`putItem`**
Novos itens recebem um valor de versão inicial de 0. Isso pode ser configurado com `@DynamoDbVersionAttribute(startAt = X)`.
**`updateItem`**
Se você recuperar um item, atualizar uma ou mais das suas propriedades e tentar salvar as alterações, a operação será bem-sucedida somente se o número de versão no lado do cliente e no lado do servidor corresponder.
Se for bem-sucedida, o número da versão é incrementado automaticamente em 1. Isso pode ser configurado com `@DynamoDbVersionAttribute(incrementBy = X)`.
**`deleteItem`**
A anotação `DynamoDbVersionAttribute` não tem efeito. Você deve adicionar uma expressão de condição manualmente ao excluir um item.
O exemplo a seguir adiciona uma expressão condicional para garantir que o item excluído seja o que foi lido. No exemplo a seguir, `recordVersion` é o atributo do bean anotado com `@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`: esse método tem o mesmo comportamento de `putItem`.
+ `addUpdateItem`: esse método tem o mesmo comportamento de `updateItem`.
+ `addDeleteItem`: esse método tem o mesmo comportamento de `deleteItem`.
**`batchWriteItem`**
+ `addPutItem`: esse método tem o mesmo comportamento de `putItem`.
+ `addDeleteItem`: esse método tem o mesmo comportamento de `deleteItem`.
**nota**
As tabelas globais do DynamoDB usam uma [reconciliação do tipo “o último a gravar vence”](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/V2globaltables_HowItWorks.html#V2globaltables_HowItWorks.consistency-modes) entre as atualizações simultâneas. Com ela, o DynamoDB faz o melhor esforço para determinar o último a gravar. Se você usa tabelas globais, essa política de “o último a gravar vence” significa que as estratégias de bloqueio podem não funcionar conforme o esperado, pois todas as réplicas acabarão por convergir com base na última gravação determinada pelo DynamoDB.
#### Como desabilitar
Para desabilitar o bloqueio positivo, não use a anotação `@DynamoDbVersionAttribute`.
### Implementar contadores com a `AtomicCounterExtension`
A extensão `AtomicCounterExtension` incrementa um atributo numérico marcado sempre que um registro é gravado no banco de dados. É possível especificar valores de início e de incremento. Se nenhum valor for especificado, o valor inicial será definido como 0 e o valor do atributo será incrementado em 1.
#### Configuração
Para especificar qual atributo é um contador, marque um atributo do tipo `Long` no esquema da tabela.
O trecho a seguir mostra o uso dos valores padrão de início e de incremento para o atributo `counter`.
```
@DynamoDbAtomicCounter
public Long getCounter() {...};
public void setCounter(Long counter) {...};
```
A abordagem do esquema de tabela estática é mostrada no trecho a seguir. A extensão do contador atômico usa um valor inicial de 10 e incrementa o valor em 5 cada vez que o registro é gravado.
```
.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))
```
### Adicionar carimbos de data e hora com a `AutoGeneratedTimestampRecordExtension`
A extensão `AutoGeneratedTimestampRecordExtension` atualiza automaticamente os atributos marcados do tipo `[Instant](https://docs.oracle.com/javase/8/docs/api/java/time/Instant.html)` com um carimbo de data e hora atual sempre que o item é gravado com sucesso no banco de dados. Essa extensão não é carregada por padrão.
#### Configuração
Para especificar qual atributo atualizar com o carimbo de data/hora atual, marque o atributo `Instant` no esquema da tabela.
O atributo `lastUpdate` é o alvo do comportamento da extensão no trecho a seguir. Observe a exigência de que o atributo seja um tipo `Instant`.
```
@DynamoDbAutoGeneratedTimestampAttribute
public Instant getLastUpdate() {...}
public void setLastUpdate(Instant lastUpdate) {...}
```
A abordagem equivalente do esquema de tabela estática é mostrada no trecho a seguir.
```
.addAttribute(Instant.class, a -> a.name("lastUpdate")
.getter(Customer::getLastUpdate)
.setter(Customer::setLastUpdate)
// Applying the 'autoGeneratedTimestamp' tag to the attribute.
.tags(AutoGeneratedTimestampRecordExtension.AttributeTags.autoGeneratedTimestampAttribute())
```
### Gere um UUID com o AutoGeneratedUuidExtension
A extensão `AutoGeneratedUuidExtension` gera um UUID (Identificador Único Universal) exclusivo para um atributo quando um novo registro é gravado no banco de dados. Usa o método Java JDK [UUID.randomUUID()](https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html#randomUUID--) e se aplica aos atributos do tipo `java.lang.String`. Essa extensão não é carregada por padrão.
#### Configuração
O atributo `uniqueId` é o alvo do comportamento da extensão no trecho a seguir.
```
@AutoGeneratedUuidExtension
public String getUniqueId() {...}
public void setUniqueId(String uniqueId) {...}
```
A abordagem equivalente do esquema de tabela estática é mostrada no trecho a seguir.
```
.addAttribute(String.class, a -> a.name("uniqueId")
.getter(Customer::getUniqueId)
.setter(Customer::setUniqueId)
// Applying the 'autoGeneratedUuid' tag to the attribute.
.tags(AutoGeneratedUuidExtension.AttributeTags.autoGeneratedUuidAttribute())
```
Se quiser que a extensão preencha o UUID somente para métodos `putItem` e não para métodos `updateItem`, adicione a anotação de [comportamento de atualização](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/mapper/UpdateBehavior.html) conforme mostrado no trecho a seguir.
```
@AutoGeneratedUuidExtension
@DynamoDbUpdateBehavior(UpdateBehavior.WRITE_IF_NOT_EXISTS)
public String getUniqueId() {...}
public void setUniqueId(String uniqueId) {...}
```
Se você usar a abordagem de esquema de tabela estática, use o código equivalente a seguir.
```
.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))
```
# Exemplo de extensão personalizada
É possível criar extensões personalizadas implementando a interface `DynamoDbEnhancedClientExtension`. A classe de extensão personalizada a seguir mostra um método `beforeWrite()` que usa uma expressão de atualização para definir um atributo `registrationDate` caso o item no banco de dados ainda não tenha um.
```
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();
}
}
```
# Usar a API do cliente avançado do DynamoDB de forma assíncrona
Se seu aplicativo exigir chamadas assíncronas e sem bloqueio para o DynamoDB, você poderá usar o [DynamoDbEnhancedAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.html). Ele é semelhante à implementação síncrona, mas com as seguintes diferenças principais:
1. Ao criar o `DynamoDbEnhancedAsyncClient`, é necessário usar a versão assíncrona do cliente padrão, `DynamoDbAsyncClient`, conforme mostrado no trecho a seguir.
```
DynamoDbEnhancedAsyncClient enhancedClient =
DynamoDbEnhancedAsyncClient.builder()
.dynamoDbClient(dynamoDbAsyncClient)
.build();
```
1. Os métodos que retornam um único objeto de dados retornam um `CompletableFuture` do resultado em vez de somente o resultado. Entretanto, seu aplicativo pode fazer outro trabalho sem precisar bloquear o resultado. O trecho a seguir mostra o método `getItem()` assíncrono.
```
CompletableFuture result = customerDynamoDbTable.getItem(customer);
// Perform other work here.
return result.join(); // Now block and wait for the result.
```
1. Métodos que retornam listas paginadas de resultados retornam um [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) em vez de um [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 o `DynamoDbEnhanceClient` síncrono retorna para os mesmos métodos. Seu aplicativo pode então inscrever um manipulador nesse publicador para lidar com os resultados de forma assíncrona, sem precisar bloquear.
```
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.
```
Para obter um exemplo mais completo de como trabalhar com a `SdkPublisher API`, consulte [o exemplo](ddb-en-client-use-multirecord.md#ddb-en-client-use-multirecord-scan-async) na seção que discute o método `scan()` assíncrono deste guia.
# Anotações de classes de dados
A tabela a seguir lista as anotações que podem ser usadas em classes de dados e fornece links para informações e exemplos neste guia. A tabela é classificada em ordem alfabética crescente pelo nome da anotação.
**Anotações de classe de dados usadas neste guia**
| Nome da anotação | A anotação se aplica a1 | O que ela faz | Onde ela é mostrada neste guia |
| --- | --- | --- | --- |
| DynamoDbAtomicCounter | atributo2 | Incrementa um atributo numérico marcado sempre que um registro é gravado no banco de dados. | [Introdução e discussão.](ddb-en-client-extensions.md#ddb-en-client-extensions-ACE) |
| DynamoDbAttribute | atributo | Define ou renomeia uma propriedade de bean que é mapeada para um atributo de tabela do DynamoDB. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbAutoGeneratedTimestampAttribute | atributo | Atualiza um atributo marcado com um carimbo de data/hora atual toda vez que o item é gravado com sucesso no banco de dados | [Introdução e discussão](ddb-en-client-extensions.md#ddb-en-client-extensions-AGTE). |
| DynamoDbAutoGeneratedUuid | atributo | Gere um UUID (Identificador Único Universal) exclusivo para um atributo quando um novo registro é gravado no banco de dados. | [Introdução e discussão.](ddb-en-client-extensions.md#ddb-en-client-extensions-AGUE) |
| DynamoDbBean | classe | Marca uma classe de dados como mapeável para um esquema de tabela. | Primeiro uso na [classe Customer](ddb-en-client-gs-tableschema.md#ddb-en-client-gs-tableschema-anno-bean-cust) na seção Conceitos básicos. Vários usos aparecem no guia. |
| DynamoDbConvertedBy | atributo | Associa um AttributeConverter personalizado ao atributo anotado. | [Discussão inicial e exemplo.](ddb-en-client-adv-features-conversion.md#ddb-en-client-adv-features-conversion-single) |
| DynamoDbFlatten | atributo | Nivela todos os atributos de uma classe de dados separada do DynamoDB e os adiciona como atributos de nível superior ao registro que é lido e gravado no banco de dados. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbIgnore | atributo | Faz com que o atributo permaneça não mapeado. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbIgnoreNulls | atributo | Impede o salvamento de atributos nulos de objetos aninhados do DynamoDb. | [Discussão e exemplos.](ddb-en-client-adv-features-ignore-null.md) |
| DynamoDbImmutable | classe | Marca uma classe de dados imutável como mapeável para um esquema de tabela. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbPartitionKey | atributo | Marca um atributo como a chave de partição primária (chave de hash) da tabela do DynamoDb. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbPreserveEmptyObject | atributo | Especifica que, se nenhum dado estiver presente para o objeto mapeado para o atributo anotado, o objeto deverá ser inicializado com todos os campos nulos. | [Discussão e exemplos.](ddb-en-client-adv-features-empty.md) |
| DynamoDbSecondaryPartitionKey | atributo | Marca um atributo como uma chave de partição para um índice secundário global. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbSecondarySortKey | atributo | Marca um atributo como uma chave de classificação opcional para um índice secundário global ou local. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbSortKey | atributo | Marca um atributo como a chave de classificação primária opcional (chave de intervalo). | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbUpdateBehavior | atributo | Especifica o comportamento quando esse atributo é atualizado como parte de uma operação de atualização, como UpdateItem. | [Introdução e exemplo.](ddb-en-client-adv-features-upd-behavior.md) |
| DynamoDbVersionAttribute | atributo | Incrementa o número da versão de um item. | [Introdução e discussão.](ddb-en-client-extensions.md#ddb-en-client-extensions-VRE) |
1Você pode aplicar anotações no nível de atributo ao getter ou ao setter, mas não a ambos. Este guia mostra anotações sobre getters.
2O termo `property` normalmente é usado para um valor encapsulado em uma classe de dados JavaBean. No entanto, no lugar desse termo, este guia usa o termo `attribute`, para ser consistente com a terminologia usada pelo DynamoDB.