# Java 1.x: DynamoDBMapper
**nota**
El SDK para Java tiene dos versiones: 1.x y 2.x. El 12 de enero de 2024 se [anunció](https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-aws-sdk-for-java-v1-x-on-december-31-2025/) el fin de soporte de la versión 1.x. Lo hará y está previsto que se dé por terminado el 31 de diciembre de 2025. Para nuevos desarrollos, recomendamos encarecidamente el uso de 2.x.
El AWS SDK para Java proporciona la clase `DynamoDBMapper` que permite mapear las clases del lado del cliente a las tablas de Amazon DynamoDB. Para usar `DynamoDBMapper`, se define la relación entre los elementos de una tabla de DynamoDB y sus instancias de objetos correspondientes en el código. La clase `DynamoDBMapper` permite realizar varias operaciones de creación, lectura, actualización y eliminación (CRUD, Create, Read, Update y Delete) en elementos y ejecutar consultas y análisis en tablas.
**Topics**
+ [Clase DynamoDBMapper](DynamoDBMapper.Methods.md)
+ [Tipos de datos compatibles con asignador DynamoDBMapper para Java](DynamoDBMapper.DataTypes.md)
+ [Anotaciones de Java para DynamoDB](DynamoDBMapper.Annotations.md)
+ [Ajustes de configuración opcionales para DynamoDBMapper](DynamoDBMapper.OptionalConfig.md)
+ [DynamoDB y bloqueo positivo con el número de versión](DynamoDBMapper.OptimisticLocking.md)
+ [Asignación de datos arbitrarios en DynamoDB](DynamoDBMapper.ArbitraryDataMapping.md)
+ [Ejemplos de DynamoDBMapper](DynamoDBMapper.Examples.md)
**nota**
La clase `DynamoDBMapper` no permite crear, actualizar o eliminar tablas. Para realizar estas tareas, utilice la interfaz de bajo nivel del SDK para Java en su lugar.
El SDK para Java proporciona un conjunto de tipos de anotación para que pueda mapear las clases de tablas. Por ejemplo, tomemos una tabla `ProductCatalog` cuya clave de partición es `Id`.
```
ProductCatalog(Id, ...)
```
Puede mapear una clase de la aplicación cliente a la tabla `ProductCatalog` tal y como se muestra en el siguiente código Java. En este código se define un objeto Java estándar (POJO) denominado `CatalogItem` que utiliza anotaciones para mapear campos de objetos a nombres de atributos de DynamoDB.
**Example**
```
package com.amazonaws.codesamples;
import java.util.Set;
import software.amazon.dynamodb.datamodeling.DynamoDBAttribute;
import software.amazon.dynamodb.datamodeling.DynamoDBHashKey;
import software.amazon.dynamodb.datamodeling.DynamoDBIgnore;
import software.amazon.dynamodb.datamodeling.DynamoDBTable;
@DynamoDBTable(tableName="ProductCatalog")
public class CatalogItem {
private Integer id;
private String title;
private String ISBN;
private Set bookAuthors;
private String someProp;
@DynamoDBHashKey(attributeName="Id")
public Integer getId() { return id; }
public void setId(Integer id) {this.id = id; }
@DynamoDBAttribute(attributeName="Title")
public String getTitle() {return title; }
public void setTitle(String title) { this.title = title; }
@DynamoDBAttribute(attributeName="ISBN")
public String getISBN() { return ISBN; }
public void setISBN(String ISBN) { this.ISBN = ISBN; }
@DynamoDBAttribute(attributeName="Authors")
public Set getBookAuthors() { return bookAuthors; }
public void setBookAuthors(Set bookAuthors) { this.bookAuthors = bookAuthors; }
@DynamoDBIgnore
public String getSomeProp() { return someProp; }
public void setSomeProp(String someProp) { this.someProp = someProp; }
}
```
En el código anterior, la anotación `@DynamoDBTable` mapea la clase `CatalogItem` a la tabla `ProductCatalog`. Puede almacenar instancias de clases individuales como los elementos de la tabla. En la definición de clase, la anotación `@DynamoDBHashKey` mapea la propiedad `Id` a la clave principal.
De forma predeterminada, las propiedades de la clase se mapean a los atributos de la tabla que tienen el mismo nombre. Las propiedades `Title` e `ISBN` se mapean a los atributos de la tabla que tienen el mismo nombre.
La anotación `@DynamoDBAttribute` es opcional cuando el nombre del atributo de DynamoDB coincide con el nombre de la propiedad declarada en la clase. Si son distintos, use esta anotación con el parámetro `attributeName` para especificar qué atributo de DynamoDB se corresponde con esta propiedad.
En el ejemplo anterior, la anotación `@DynamoDBAttribute` se agrega a cada propiedad para garantizar que los nombres de las propiedades coincidan exactamente con las tablas creadas en un paso anterior y para mantener la coherencia con los nombres de atributo utilizados en otros ejemplos de código de esta guía.
La definición de clase puede tener propiedades que no se mapeen a ningún atributo de la tabla. Estas propiedades se identifican agregándoles la anotación `@DynamoDBIgnore`. En el ejemplo anterior, la propiedad `SomeProp` se ha marcado con la anotación `@DynamoDBIgnore`. Al cargar una instancia de `CatalogItem` en la tabla, la instancia de `DynamoDBMapper` no incluye la propiedad `SomeProp`. Tampoco el mapeador devuelve este atributo cuando se recupera un elemento de la tabla.
Después de haber definido la clase de mapeo, puede usar métodos `DynamoDBMapper` para escribir una instancia de esa clase en un elemento correspondiente de la tabla `Catalog`. En el siguiente ejemplo de código se muestra esta técnica.
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDBMapper mapper = new DynamoDBMapper(client);
CatalogItem item = new CatalogItem();
item.setId(102);
item.setTitle("Book 102 Title");
item.setISBN("222-2222222222");
item.setBookAuthors(new HashSet(Arrays.asList("Author 1", "Author 2")));
item.setSomeProp("Test");
mapper.save(item);
```
En el siguiente ejemplo de código se muestra cómo recuperar el elemento y obtener acceso a algunos de sus atributos.
```
CatalogItem partitionKey = new CatalogItem();
partitionKey.setId(102);
DynamoDBQueryExpression queryExpression = new DynamoDBQueryExpression()
.withHashKeyValues(partitionKey);
List itemList = mapper.query(CatalogItem.class, queryExpression);
for (int i = 0; i < itemList.size(); i++) {
System.out.println(itemList.get(i).getTitle());
System.out.println(itemList.get(i).getBookAuthors());
}
```
`DynamoDBMapper` ofrece un modo natural e intuitivo de usar los datos de DynamoDB en Java. También ofrece varias características integradas, tales como el bloqueo optimista, las transacciones ACID, la generación automática de valores de claves de partición y de orden y el control de versiones de objetos.
# Clase DynamoDBMapper
La clase `DynamoDBMapper` es el punto de entrada de Amazon DynamoDB. Proporciona acceso a un punto de enlace de DynamoDB y le permite obtener acceso a sus datos en diversas tablas. También permite realizar varias operaciones de creación, lectura, actualización y eliminación (CRUD, Create, Read, Update y Delete) en elementos y ejecutar consultas y análisis en tablas. Esta clase proporciona los siguientes métodos para trabajar con DynamoDB.
Para obtener la documentación de Javadoc correspondiente, consulte [DynamoDBMapper](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html) en la *Referencia de la API de AWS SDK para Java*.
**Topics**
+ [save](#DynamoDBMapper.Methods.save)
+ [carga](#DynamoDBMapper.Methods.load)
+ [eliminar](#DynamoDBMapper.Methods.delete)
+ [consulta](#DynamoDBMapper.Methods.query)
+ [queryPage](#DynamoDBMapper.Methods.queryPage)
+ [scan](#DynamoDBMapper.Methods.scan)
+ [scanPage](#DynamoDBMapper.Methods.scanPage)
+ [parallelScan](#DynamoDBMapper.Methods.parallelScan)
+ [batchSave](#DynamoDBMapper.Methods.batchSave)
+ [batchLoad](#DynamoDBMapper.Methods.batchLoad)
+ [batchDelete](#DynamoDBMapper.Methods.batchDelete)
+ [batchWrite](#DynamoDBMapper.Methods.batchWrite)
+ [transactionWrite](#DynamoDBMapper.Methods.transactionWrite)
+ [transactionLoad](#DynamoDBMapper.Methods.transactionLoad)
+ [count](#DynamoDBMapper.Methods.count)
+ [generateCreateTableRequest](#DynamoDBMapper.Methods.generateCreateTableRequest)
+ [createS3Link](#DynamoDBMapper.Methods.createS3Link)
+ [getS3ClientCache](#DynamoDBMapper.Methods.getS3ClientCache)
## save
Guarda el objeto especificado en la tabla. El objeto que se desea guardar es el único parámetro obligatorio para este método. Puede usar el objeto `DynamoDBMapperConfig` para proporcionar parámetros de configuración opcionales.
Si no hay un elemento que tenga la misma clave principal, este método crea un nuevo elemento en la tabla. Si hay un elemento que tiene la misma clave principal, lo actualiza. Si las claves de partición y orden son de tipo String y se han anotado con `@DynamoDBAutoGeneratedKey`, se les asigna un identificador universal único (UUID) aleatorio si se deja sin inicializar. Los campos de versión que se anotan con `@DynamoDBVersionAttribute` se incrementan en una unidad. Además, si se actualiza un campo de versión o se genera una clave, el objeto que se ha pasado se actualiza como consecuencia de la operación.
De forma predeterminada, solo se actualizan los atributos correspondientes a propiedades de clases mapeadas. Ningún atributo existente adicional de un elemento se ve afectado. Sin embargo, si especifica `SaveBehavior.CLOBBER`, puede forzar que se sobrescriba el elemento completo.
```
DynamoDBMapperConfig config = DynamoDBMapperConfig.builder()
.withSaveBehavior(DynamoDBMapperConfig.SaveBehavior.CLOBBER).build();
mapper.save(item, config);
```
Si el control de versiones está habilitado, las versiones del elemento del lado del cliente y del lado del servidor deben coincidir. Sin embargo, no es preciso que coincidan las versiones si se utiliza la opción `SaveBehavior.CLOBBER`. Para obtener más información sobre el control de versiones, consulte [DynamoDB y bloqueo positivo con el número de versión](DynamoDBMapper.OptimisticLocking.md).
## carga
Recupera un elemento de una tabla. Es preciso proporcionar la clave principal del elemento que se desea recuperar. Puede usar el objeto `DynamoDBMapperConfig` para proporcionar parámetros de configuración opcionales. Por ejemplo, si lo desea puede solicitar lecturas de consistencia alta para asegurarse de que este método recupere solamente los valores más recientes de los elementos, como se muestra en la siguiente instrucción de Java.
```
DynamoDBMapperConfig config = DynamoDBMapperConfig.builder()
.withConsistentReads(DynamoDBMapperConfig.ConsistentReads.CONSISTENT).build();
CatalogItem item = mapper.load(CatalogItem.class, item.getId(), config);
```
De forma predeterminada, DynamoDB devuelve el elemento cuyos valores presentan consistencia final. Para obtener más información sobre el modelo de consistencia final de DynamoDB, consulte [Coherencia de lectura de DynamoDB](HowItWorks.ReadConsistency.md).
## eliminar
Elimina un elemento de la tabla. Debe pasar una instancia de objeto de la clase mapeada.
Si el control de versiones está habilitado, las versiones del elemento del lado del cliente y del lado del servidor deben coincidir. Sin embargo, no es preciso que coincidan las versiones si se utiliza la opción `SaveBehavior.CLOBBER`. Para obtener más información sobre el control de versiones, consulte [DynamoDB y bloqueo positivo con el número de versión](DynamoDBMapper.OptimisticLocking.md).
## consulta
Consulta una tabla o un índice secundario.
Supongamos que tenemos una tabla `Reply` en la que se almacenan respuestas de conversaciones. Para cada tema de conversación puede haber cero o más respuestas. La clave principal de la tabla `Reply` consta de los campos `Id` y `ReplyDateTime`, donde `Id` es la clave de partición y `ReplyDateTime` es la clave de orden de la clave principal.
```
Reply ( Id, ReplyDateTime, ... )
```
Supongamos que creamos un mapeo entre una clase `Reply` y la tabla `Reply` correspondiente de DynamoDB. En el siguiente código Java se usa `DynamoDBMapper` para buscar todas las respuestas de las últimas dos semanas para un tema de conversación concreto.
**Example**
```
String forumName = "&DDB;";
String forumSubject = "&DDB; Thread 1";
String partitionKey = forumName + "#" + forumSubject;
long twoWeeksAgoMilli = (new Date()).getTime() - (14L*24L*60L*60L*1000L);
Date twoWeeksAgo = new Date();
twoWeeksAgo.setTime(twoWeeksAgoMilli);
SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'");
String twoWeeksAgoStr = df.format(twoWeeksAgo);
Map eav = new HashMap();
eav.put(":v1", new AttributeValue().withS(partitionKey));
eav.put(":v2",new AttributeValue().withS(twoWeeksAgoStr.toString()));
DynamoDBQueryExpression queryExpression = new DynamoDBQueryExpression()
.withKeyConditionExpression("Id = :v1 and ReplyDateTime > :v2")
.withExpressionAttributeValues(eav);
List latestReplies = mapper.query(Reply.class, queryExpression);
```
La consulta devuelve una colección de objetos `Reply`.
De forma predeterminada, el método `query` devuelve una colección de "carga diferida". Inicialmente devuelve una sola página de resultados y, a continuación, realiza una llamada de servicio para obtener la página siguiente si es necesario. Para obtener todos los elementos coincidentes, recorra en iteración la colección `latestReplies`.
Tenga en cuenta que llamar al método `size()` en la colección cargará todos los resultados para proporcionar un recuento preciso. Esto puede provocar que se consuma una gran cantidad de rendimiento aprovisionado y en una tabla muy grande incluso podría agotar toda la memoria en su JVM.
Para consultar un índice, antes es preciso modelarlo como clase de mapeador. Supongamos que la tabla `Reply` tiene un índice secundario global denominado *PostedBy-Message-Index*. La clave de partición de este índice es `PostedBy` y la de orden, `Message`. La definición de clase de un elemento del índice tendría el siguiente aspecto:
```
@DynamoDBTable(tableName="Reply")
public class PostedByMessage {
private String postedBy;
private String message;
@DynamoDBIndexHashKey(globalSecondaryIndexName = "PostedBy-Message-Index", attributeName = "PostedBy")
public String getPostedBy() { return postedBy; }
public void setPostedBy(String postedBy) { this.postedBy = postedBy; }
@DynamoDBIndexRangeKey(globalSecondaryIndexName = "PostedBy-Message-Index", attributeName = "Message")
public String getMessage() { return message; }
public void setMessage(String message) { this.message = message; }
// Additional properties go here.
}
```
La anotación `@DynamoDBTable` indica que este índice está asociado a la tabla `Reply`. La anotación `@DynamoDBIndexHashKey` se refiere a la clave de partición (*PostedBy*) del índice y la anotación `@DynamoDBIndexRangeKey`, a su clave de ordenación (*Message*).
Ahora, puede usar `DynamoDBMapper` para consultar el índice y recuperar un subconjunto de los mensajes publicados por un usuario determinado. No necesita especificar el nombre del índice si no tiene asignaciones conflictivas entre tablas e índices y las asignaciones ya están hechas en el mapeador. El mapeador deducirá en función de la clave principal y la clave de clasificación. El siguiente código consulta el índice secundario global. Es imprescindible especificar , ya que los índices secundarios globales admiten las lecturas consistentes finales, pero no las de consistencia alta `withConsistentRead(false)`.
```
HashMap eav = new HashMap();
eav.put(":v1", new AttributeValue().withS("User A"));
eav.put(":v2", new AttributeValue().withS("DynamoDB"));
DynamoDBQueryExpression queryExpression = new DynamoDBQueryExpression()
.withIndexName("PostedBy-Message-Index")
.withConsistentRead(false)
.withKeyConditionExpression("PostedBy = :v1 and begins_with(Message, :v2)")
.withExpressionAttributeValues(eav);
List iList = mapper.query(PostedByMessage.class, queryExpression);
```
La consulta devuelve una colección de objetos `PostedByMessage`.
## queryPage
Consulta una tabla o un índice secundario y devuelve una sola página de resultados coincidentes. Al igual que con el método `query`, es preciso especificar un valor de clave de partición y un filtro de consulta que se aplica al atributo de clave de ordenación. Sin embargo, `queryPage` solamente devuelve la primera "página" de datos; es decir, la cantidad de datos que se ajusta a 1 MB
## scan
Examina una tabla o un índice secundario completos. Si lo desea, puede especificar una expresión `FilterExpression` para filtrar el conjunto de resultados.
Supongamos que tenemos una tabla `Reply` en la que se almacenan respuestas de conversaciones. Para cada tema de conversación puede haber cero o más respuestas. La clave principal de la tabla `Reply` consta de los campos `Id` y `ReplyDateTime`, donde `Id` es la clave de partición y `ReplyDateTime` es la clave de orden de la clave principal.
```
Reply ( Id, ReplyDateTime, ... )
```
Si ha mapeado una clase de Java a la tabla `Reply`, puede usar `DynamoDBMapper` para examinar la tabla. Por ejemplo, en el siguiente código Java se examina toda la tabla `Reply` y únicamente se devuelven las respuestas de un año determinado.
**Example**
```
HashMap eav = new HashMap();
eav.put(":v1", new AttributeValue().withS("2015"));
DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
.withFilterExpression("begins_with(ReplyDateTime,:v1)")
.withExpressionAttributeValues(eav);
List replies = mapper.scan(Reply.class, scanExpression);
```
De forma predeterminada, el método `scan` devuelve una colección de "carga diferida". Inicialmente devuelve una sola página de resultados y, a continuación, realiza una llamada de servicio para obtener la página siguiente si es necesario. Para obtener todos los elementos coincidentes, recorra en iteración la colección `replies`.
Tenga en cuenta que llamar al método `size()` en la colección cargará todos los resultados para proporcionar un recuento preciso. Esto puede provocar que se consuma una gran cantidad de rendimiento aprovisionado y en una tabla muy grande incluso podría agotar toda la memoria en su JVM.
Para examinar un índice, antes es preciso modelarlo como clase de mapeador. Supongamos que la tabla `Reply` tiene un índice secundario global denominado `PostedBy-Message-Index`. La clave de partición de este índice es `PostedBy` y la de orden, `Message`. En la sección [consulta](#DynamoDBMapper.Methods.query) se muestra una clase de mapeador para este índice. Usa las anotaciones `@DynamoDBIndexHashKey` y `@DynamoDBIndexRangeKey` para especificar la clave de ordenación y la de partición del índice.
En el siguiente ejemplo de código se examina `PostedBy-Message-Index`. No se utiliza ningún filtro de examen, por lo que se devuelven todos los elementos del índice.
```
DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
.withIndexName("PostedBy-Message-Index")
.withConsistentRead(false);
List iList = mapper.scan(PostedByMessage.class, scanExpression);
Iterator indexItems = iList.iterator();
```
## scanPage
Examina una tabla o un índice secundario y devuelve una sola página de resultados coincidentes. Al igual que sucede con el método `scan`, si lo desea, puede especificar una expresión `FilterExpression` para filtrar el conjunto de resultados. Sin embargo, `scanPage` solamente devuelve la primera "página" de datos, es decir, la cantidad de datos que caben en 1 MB.
## parallelScan
Realiza un examen en paralelo de una tabla o un índice secundario completos. Se especifica un número de segmentos lógicos de la tabla, junto con una expresión de examen para filtrar los resultados. `parallelScan` divide la tarea de examen entre varios procesos de trabajo, uno para cada segmento lógico. Los procesos de trabajo examinan los datos en paralelo y devuelven los resultados.
En el siguiente ejemplo de código Java se realiza un examen paralelo de la tabla `Product`.
```
int numberOfThreads = 4;
Map eav = new HashMap();
eav.put(":n", new AttributeValue().withN("100"));
DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
.withFilterExpression("Price <= :n")
.withExpressionAttributeValues(eav);
List scanResult = mapper.parallelScan(Product.class, scanExpression, numberOfThreads);
```
## batchSave
Guarda objetos en una o varias tablas mediante una o varias llamadas al método `AmazonDynamoDB.batchWriteItem`. Este método no proporciona garantías de transacción.
En el siguiente código Java se guardan dos elementos (libros) en la tabla `ProductCatalog`.
```
Book book1 = new Book();
book1.setId(901);
book1.setProductCategory("Book");
book1.setTitle("Book 901 Title");
Book book2 = new Book();
book2.setId(902);
book2.setProductCategory("Book");
book2.setTitle("Book 902 Title");
mapper.batchSave(Arrays.asList(book1, book2));
```
## batchLoad
Recupera varios elementos de una o varias tablas mediante sus claves principales.
En el siguiente código Java se recuperan dos elementos de dos tablas distintas.
```
ArrayList