# 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 itemsToGet = new ArrayList(); ForumItem forumItem = new ForumItem(); forumItem.setForumName("Amazon DynamoDB"); itemsToGet.add(forumItem); ThreadItem threadItem = new ThreadItem(); threadItem.setForumName("Amazon DynamoDB"); threadItem.setSubject("Amazon DynamoDB thread 1 message text"); itemsToGet.add(threadItem); Map> items = mapper.batchLoad(itemsToGet); ``` ## batchDelete Elimina objetos de 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 eliminan dos elementos (libros) de la tabla `ProductCatalog`. ``` Book book1 = mapper.load(Book.class, 901); Book book2 = mapper.load(Book.class, 902); mapper.batchDelete(Arrays.asList(book1, book2)); ``` ## batchWrite Guarda o elimina 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 ni admite el control de versiones (colocaciones o eliminaciones condicionales). En el siguiente código Java se escribe un nuevo elemento en la tabla `Forum`, se escribe un nuevo elemento en la tabla `Thread` y se elimina un elemento de la tabla `ProductCatalog`. ``` // Create a Forum item to save Forum forumItem = new Forum(); forumItem.setName("Test BatchWrite Forum"); // Create a Thread item to save Thread threadItem = new Thread(); threadItem.setForumName("AmazonDynamoDB"); threadItem.setSubject("My sample question"); // Load a ProductCatalog item to delete Book book3 = mapper.load(Book.class, 903); List objectsToWrite = Arrays.asList(forumItem, threadItem); List objectsToDelete = Arrays.asList(book3); mapper.batchWrite(objectsToWrite, objectsToDelete); ``` ## transactionWrite Guarda o elimina objetos en una o varias tablas mediante una llamada al método `AmazonDynamoDB.transactWriteItems`. Para ver una lista de excepciones específicas de la transacción, consulte [Errores de TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html#API_TransactWriteItems_Errors). Para obtener más información sobre las transacciones de DynamoDB y las garantías proporcionadas de atomicidad, coherencia, aislamiento y durabilidad (ACID), consulte [Amazon DynamoDB Transactions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transactions.html). **nota** Este método no admite lo siguiente: [DynamoDBMapperConfig.SaveBehavior](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.OptionalConfig.html). El siguiente código Java escribe un nuevo elemento en cada una de las tablas `Forum` y `Thread` de un modo transaccional. ``` Thread s3ForumThread = new Thread(); s3ForumThread.setForumName("S3 Forum"); s3ForumThread.setSubject("Sample Subject 1"); s3ForumThread.setMessage("Sample Question 1"); Forum s3Forum = new Forum(); s3Forum.setName("S3 Forum"); s3Forum.setCategory("Amazon Web Services"); s3Forum.setThreads(1); TransactionWriteRequest transactionWriteRequest = new TransactionWriteRequest(); transactionWriteRequest.addPut(s3Forum); transactionWriteRequest.addPut(s3ForumThread); mapper.transactionWrite(transactionWriteRequest); ``` ## transactionLoad Carga objetos de una o varias tablas mediante una llamada al método `AmazonDynamoDB.transactGetItems`. Para ver una lista de excepciones específicas de transacciones, consulte [Errores de TransactGetItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html#API_TransactGetItems_Errors). Para obtener más información sobre las transacciones de DynamoDB y las garantías proporcionadas de atomicidad, coherencia, aislamiento y durabilidad (ACID), consulte [Amazon DynamoDB Transactions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transactions.html). El siguiente código Java carga un elemento en cada una de las tablas `Forum` y `Thread` de un modo transaccional. ``` Forum dynamodbForum = new Forum(); dynamodbForum.setName("DynamoDB Forum"); Thread dynamodbForumThread = new Thread(); dynamodbForumThread.setForumName("DynamoDB Forum"); TransactionLoadRequest transactionLoadRequest = new TransactionLoadRequest(); transactionLoadRequest.addLoad(dynamodbForum); transactionLoadRequest.addLoad(dynamodbForumThread); mapper.transactionLoad(transactionLoadRequest); ``` ## count Evalúa la expresión de examen especificada y devuelve el recuento de elementos coincidentes. No se devuelven datos de elementos. ## generateCreateTableRequest Analiza una clase de objeto Java estándar (POJO) que representa una tabla de DynamoDB y devuelve una solicitud de `CreateTableRequest` para esa tabla. ## createS3Link Crea un enlace a un objeto en Amazon S3. Debe especificar un nombre de bucket y un nombre de clave para identificar el objeto en el bucket de forma exclusiva. Para usar `createS3Link`, la clase de mapeador debe definir métodos getter y setter. Esto se ilustra en el siguiente ejemplo de código con la adición de un nuevo atributo y de métodos getter/setter a la clase `CatalogItem`. ``` @DynamoDBTable(tableName="ProductCatalog") public class CatalogItem { ... public S3Link productImage; .... @DynamoDBAttribute(attributeName = "ProductImage") public S3Link getProductImage() { return productImage; } public void setProductImage(S3Link productImage) { this.productImage = productImage; } ... } ``` En el siguiente código Java se define un nuevo elemento para escribirlo en la tabla `Product`. El elemento incluye un enlace a la imagen de un producto; los datos de la imagen se cargan en Amazon S3. ``` CatalogItem item = new CatalogItem(); item.setId(150); item.setTitle("Book 150 Title"); String amzn-s3-demo-bucket = "amzn-s3-demo-bucket"; String myS3Key = "productImages/book_150_cover.jpg"; item.setProductImage(mapper.createS3Link(amzn-s3-demo-bucket, myS3Key)); item.getProductImage().uploadFrom(new File("/file/path/book_150_cover.jpg")); mapper.save(item); ``` La clase `S3Link` proporciona muchos métodos más para manipular objetos en Amazon S3. Para obtener más información, consulte los javadocs en [Class `S3Link`](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/S3Link.html). ## getS3ClientCache Devuelve el objeto `S3ClientCache` subyacente para obtener acceso a Amazon S3. Un objeto `S3ClientCache` es un mapa inteligente para objetos `AmazonS3Client`. Si tiene varios clientes, `S3ClientCache` puede ayudarle a organizarlos por región de AWS y a crear nuevos clientes de Amazon S3 en diferido.