Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Java 1.x : Dynamo DBMapper **Note** Le kit SDK pour Java est disponible en deux versions : 1.x et 2.x. Le end-of-support for 1.x a été [annoncé](https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-aws-sdk-for-java-v1-x-on-december-31-2025/) le 12 janvier 2024. Il le sera et end-of-support doit être remis le 31 décembre 2025. Pour les nouveaux développements, nous vous recommandons vivement d’utiliser la version 2.x. AWS SDK pour Java fournit une `DynamoDBMapper` classe qui vous permet de mapper vos classes côté client aux tables Amazon DynamoDB. Pour utiliser `DynamoDBMapper`, vous définissez la relation entre éléments d’une table DynamoDB et leurs instances d’objet correspondantes dans votre code. La classe `DynamoDBMapper` vous permet d’effectuer diverses opérations de création, de lecture, de mise à jour et de suppression (opérations CRUD) sur des éléments, ainsi que d’exécuter des requêtes et analyses sur des tables. **Topics** + [Classe Dynamo DBMapper](DynamoDBMapper.Methods.md) + [Types de données pris en charge pour Dynamo DBMapper pour Java](DynamoDBMapper.DataTypes.md) + [Annotations Java pour DynamoDB](DynamoDBMapper.Annotations.md) + [Paramètres de configuration facultatifs pour Dynamo DBMapper](DynamoDBMapper.OptionalConfig.md) + [DynamoDB et verrouillage optimiste avec numéro de version](DynamoDBMapper.OptimisticLocking.md) + [Mappage des données arbitraires dans DynamoDB](DynamoDBMapper.ArbitraryDataMapping.md) + [Exemples DynamoDBMapper](DynamoDBMapper.Examples.md) **Note** La classe `DynamoDBMapper` ne vous permet pas de créer, de mettre à jour ou de supprimer des tables. Pour effectuer ces tâches, utilisez plutôt l’interface du kit SDK de bas niveau pour Java. Le kit SDK pour Java fournit un ensemble de types d’annotations qui vous permettent de mapper vos classes à des tables. Par exemple, imaginons une table `ProductCatalog` ayant `Id` en tant que clé de partition. ``` ProductCatalog(Id, ...) ``` Vous pouvez mapper une classe de votre application client à la table `ProductCatalog`, comme illustré dans le code Java suivant. Cet exemple de code définit un objet Java ancien brut (Plain Old Java Object, POJO) nommé `CatalogItem` qui utilise des annotations pour mapper des champs d’objet à des noms d’attribut 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; } } ``` Dans le code précédent, l’annotation `@DynamoDBTable` mappe la classe `CatalogItem` à la table `ProductCatalog`. Vous pouvez stocker des instances de classe individuelles en tant qu’éléments dans la table. Dans la définition de classe, l’annotation `@DynamoDBHashKey` mappe l’`Id` de propriété à la clé primaire. Par défaut, les propriétés de classe mappent avec les mêmes attributs de nom dans la table. Les propriétés `Title` et `ISBN` mappent avec les mêmes attributs de nom dans la table. L’annotation `@DynamoDBAttribute` est facultative si le nom de l’attribut DynamoDB correspond au nom de la propriété déclarée dans la classe. Si les noms diffèrent, utilisez cette annotation avec le paramètre `attributeName` pour spécifier l’attribut DynamoDB auquel cette propriété correspond. Dans l’exemple précédent, l’annotation `@DynamoDBAttribute` est ajoutée à chaque propriété afin de garantir que les noms de propriété correspondent exactement aux tables créées au cours d’une étape précédente et d’assurer la cohérence avec les noms d’attributs utilisés dans d’autres exemples de code dans ce guide. Votre définition de classe peut avoir des propriétés qui ne mappent avec aucun attribut de la table. Vous identifiez ces propriétés en ajoutant l’annotation `@DynamoDBIgnore`. Dans l’exemple précédent, la propriété `SomeProp` est marquée avec l’annotation `@DynamoDBIgnore`. Lorsque vous téléchargez une instance `CatalogItem` vers la table, votre instance `DynamoDBMapper` n’inclut pas de propriété `SomeProp`. En outre, l’outil de mappage ne retourne pas cet attribut lorsque vous récupérez un élément de la table. Une fois que vous avez défini votre classe de mappage, vous pouvez utiliser des méthodes `DynamoDBMapper` pour écrire une instance de cette classe d’un élément correspondant dans la table `Catalog`. L’exemple de code suivant illustre cette technique. ``` 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); ``` L’exemple de code suivant montre comment récupérer l’élément et accéder à certains de ses attributs : ``` 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` offre un moyen intuitif, naturel d’utiliser des données DynamoDB dans Java. Il offre aussi différentes fonctionnalités intégrées telles que le verrouillage optimiste, les transactions ACID, les valeurs de clé de tri et de clé de partition générées automatiquement et la gestion des versions d’objet. # Classe Dynamo DBMapper La classe `DynamoDBMapper` est le point d’entrée d’Amazon DynamoDB. Elle donne accès à un point de terminaison DynamoDB et vous permet d’accéder à vos données dans différentes tables. Elle vous permet également d’effectuer diverses opérations de création, de lecture, de mise à jour et de suppression (opérations CRUD) sur des éléments, ainsi que d’exécuter des requêtes et analyses sur des tables. Cette classe fournit les méthodes suivantes utiliser DynamoDB. *Pour consulter la documentation Javadoc correspondante, consultez [Dynamo DBMapper](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html) dans le manuel de référence des AWS SDK pour Java API.* **Topics** + [enregistrer](#DynamoDBMapper.Methods.save) + [charge](#DynamoDBMapper.Methods.load) + [supprimer](#DynamoDBMapper.Methods.delete) + [query](#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) + [generateCreateTableDemande](#DynamoDBMapper.Methods.generateCreateTableRequest) + [createS3Link](#DynamoDBMapper.Methods.createS3Link) + [Obtient S3 ClientCache](#DynamoDBMapper.Methods.getS3ClientCache) ## enregistrer Enregistre l’objet spécifié dans la table. L’objet que vous voulez enregistrer est le seul paramètre requis pour cette méthode. Vous pouvez fournir des paramètres de configuration facultatifs en utilisant l’objet `DynamoDBMapperConfig`. Si un élément qui a la même clé primaire n’existe pas, cette méthode crée un nouvel élément dans la table. Si un élément qui a la même clé primaire existe, elle met à jour l’élément existant. Si la clé de partition et la clé de tri sont de type String, et annotées avec `@DynamoDBAutoGeneratedKey`, alors elles reçoivent un identificateur unique universel (UUID) aléatoire en cas de défaut d’initialisation. Les champs de version qui sont annotés avec `@DynamoDBVersionAttribute` seront incrémentés d’un niveau. En outre, si un champ de version est mis à jour ou généré par une clé, l’objet adopté est mis à jour à la suite de l’opération. Par défaut, seuls les attributs correspondants aux propriétés de classes mappées sont mis à jour. Tous les attributs supplémentaires existant sur un élément ne sont pas affectés. Toutefois, si vous spécifiez `SaveBehavior.CLOBBER`, vous pouvez forcer le remplacement complet de l’élément. ``` DynamoDBMapperConfig config = DynamoDBMapperConfig.builder() .withSaveBehavior(DynamoDBMapperConfig.SaveBehavior.CLOBBER).build(); mapper.save(item, config); ``` Si vous avez activé le contrôle de version, alors les versions d’élément côté client et côté serveur doivent correspondre. Toutefois, la version n’a pas besoin de correspondre si l’option `SaveBehavior.CLOBBER` est utilisée. Pour plus d’informations sur la gestion des versions, consultez [DynamoDB et verrouillage optimiste avec numéro de version](DynamoDBMapper.OptimisticLocking.md). ## charge Récupère un élément dans une table. Vous devez fournir la clé primaire de l’élément que vous voulez récupérer. Vous pouvez fournir des paramètres de configuration facultatifs en utilisant l’objet `DynamoDBMapperConfig`. Par exemple, vous pouvez demander le cas échéant des lectures fortement cohérentes afin de garantir que cette méthode récupère uniquement les dernières valeurs d’élément comme indiqué dans l’instruction Java suivante. ``` DynamoDBMapperConfig config = DynamoDBMapperConfig.builder() .withConsistentReads(DynamoDBMapperConfig.ConsistentReads.CONSISTENT).build(); CatalogItem item = mapper.load(CatalogItem.class, item.getId(), config); ``` Par défaut, DynamoDB renvoie l’élément ayant des valeurs éventuellement cohérentes. Pour plus d’informations sur le modèle de cohérence éventuelle de DynamoDB, consultez [Cohérence en lecture DynamoDB](HowItWorks.ReadConsistency.md). ## supprimer Supprime un élément de la table. Vous devez communiquer une instance d’objet de la classe mappée. Si vous avez activé le contrôle de version, alors les versions d’élément côté client et côté serveur doivent correspondre. Toutefois, la version n’a pas besoin de correspondre si l’option `SaveBehavior.CLOBBER` est utilisée. Pour plus d’informations sur la gestion des versions, consultez [DynamoDB et verrouillage optimiste avec numéro de version](DynamoDBMapper.OptimisticLocking.md). ## query Interroge une table ou un index secondaire. Supposons que vous ayez une table, `Reply`, qui stocke des réponses de threads de forum. Chaque objet thread peut avoir zéro ou plusieurs réponses. La clé primaire de la table `Reply` se compose des champs `Id` et `ReplyDateTime`, où `Id` est la clé de partition et `ReplyDateTime` est la clé de tri de la clé primaire. ``` Reply ( Id, ReplyDateTime, ... ) ``` Supposons que vous ayez créé un mappage entre une classe `Reply` et la table `Reply` correspondante dans DynamoDB. L’exemple de code Java suivant utilise `DynamoDBMapper` pour trouver toutes les réponses au cours des deux dernières semaines pour un objet thread spécifique. **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 requête renvoie un ensemble d’objets `Reply`. Par défaut, la méthode `query` renvoie une collection « avec chargement différé ». Elle ne renvoie initialement qu’une seule page de résultats puis effectue un appel de service pour la page suivante si nécessaire. Pour obtenir tous les éléments correspondants, itérez sur la collection `latestReplies`. Notez que l’appel de la méthode `size()` sur la collection chargera chaque résultat afin de fournir un décompte précis. Cela peut entraîner la consommation d’un débit alloué élevé et, sur une très grande table, pourrait même épuiser toute la mémoire de votre JVM. Pour interroger un index, vous devez tout d’abord affecter un modèle à l’index en tant que classe d’outil de mappage. Supposons que la `Reply` table possède un index secondaire global nommé *PostedBy-Message-Index*. La clé de partition de cet index est `PostedBy`, et la clé de tri est `Message`. La définition de classe d’un élément dans l’index se présenterait comme suit : ``` @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. } ``` L’annotation `@DynamoDBTable` indique que cet index est associé à la table `Reply`. L'`@DynamoDBIndexHashKey`annotation indique la clé de partition (*PostedBy*) de l'index et `@DynamoDBIndexRangeKey` la clé de tri (*Message*) de l'index. Vous pouvez maintenant utiliser `DynamoDBMapper` pour interroger l’index, en récupérant un sous-ensemble de messages qui ont été publiés par un utilisateur particulier. Il n’est pas nécessaire de spécifier le nom de l’index si vous n’avez pas de mappages contradictoires entre les tables et les index et si les mappages sont déjà établis dans l’outil de mappage. L’outil de mappage déduit en fonction de la clé primaire et de la clé de tri. L’exemple de code suivant interroge un index secondaire global. Étant donné que les index globaux secondaires (gsi) prennent en charge des lectures cohérentes à terme, mais pas des lectures fortement cohérentes, vous devez spécifier `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 requête renvoie un ensemble d’objets `PostedByMessage`. ## queryPage Interroge une table ou un index secondaire, et renvoie une seule page de résultats correspondants. Comme avec la méthode `query`, vous devez spécifier une valeur de clé de partition et un filtre de requête qui est appliqué à l’attribut de clé de tri. Toutefois, `queryPage` renvoie uniquement la première « page » de données, c’est-à-dire la quantité de données pouvant tenir dans 1 Mo ## scan Analyse une table ou un index secondaire entiers. Vous pouvez spécifier le cas échéant un `FilterExpression` pour filtrer l’ensemble de résultats. Supposons que vous ayez une table, `Reply`, qui stocke des réponses de threads de forum. Chaque objet thread peut avoir zéro ou plusieurs réponses. La clé primaire de la table `Reply` se compose des champs `Id` et `ReplyDateTime`, où `Id` est la clé de partition et `ReplyDateTime` est la clé de tri de la clé primaire. ``` Reply ( Id, ReplyDateTime, ... ) ``` Si vous avez mappé une classe Java à la table `Reply`, vous pouvez utiliser le `DynamoDBMapper` pour analyser la table. Par exemple, le code Java suivant analyse l’ensemble de la table `Reply`, en renvoyant uniquement les réponses pour une année donnée. **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); ``` Par défaut, la méthode `scan` renvoie une collection « avec chargement différé ». Elle ne renvoie initialement qu’une seule page de résultats puis effectue un appel de service pour la page suivante si nécessaire. Pour obtenir tous les éléments correspondants, itérez sur la collection `replies`. Notez que l’appel de la méthode `size()` sur la collection chargera chaque résultat afin de fournir un décompte précis. Cela peut entraîner la consommation d’un débit alloué élevé et, sur une très grande table, pourrait même épuiser toute la mémoire de votre JVM. Pour analyser un index, vous devez tout d’abord affecter un modèle à l’index en tant que classe d’outil de mappage. Supposons que la table `Reply` a un index secondaire global nommé `PostedBy-Message-Index`. La clé de partition de cet index est `PostedBy`, et la clé de tri est `Message`. Une classe d’outil de mappage pour cet index est disponible dans la section [query](#DynamoDBMapper.Methods.query). Elle utilise les annotations `@DynamoDBIndexHashKey` et `@DynamoDBIndexRangeKey` pour spécifier la clé de partition et la clé de tri de l’index. L’exemple de code suivant présente analyse `PostedBy-Message-Index`. Il n’utilise pas un filtre d’analyse. Ainsi, tous les éléments dans l’index vous sont renvoyés. ``` DynamoDBScanExpression scanExpression = new DynamoDBScanExpression() .withIndexName("PostedBy-Message-Index") .withConsistentRead(false); List iList = mapper.scan(PostedByMessage.class, scanExpression); Iterator indexItems = iList.iterator(); ``` ## scanPage Analyse une table ou un index secondaire, et renvoie une seule page de résultats correspondants. Comme avec la méthode `scan`, vous pouvez spécifier le cas échéant un `FilterExpression` pour filtrer le jeu de résultats. Toutefois, `scanPage` renvoie uniquement la première « page » de données, c’est-à-dire la quantité de données pouvant tenir dans 1 Mo. ## parallelScan Effectue une analyse parallèle d’une table ou d’un index secondaire entiers. Vous spécifiez un certain nombre de segments logiques pour la table, avec une expression d’analyse pour filtrer les résultats. Le `parallelScan` répartit la tâche d’analyse entre plusieurs instances de travail, une pour chaque segment logique ; les instances de travail traitent les données en parallèle et renvoient les résultats. L’exemple de code Java suivant effectue une analyse parallèle sur la table `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 Enregistre des objets dans une ou plusieurs tables à l’aide d’un ou de plusieurs appels à la méthode `AmazonDynamoDB.batchWriteItem`. Cette méthode n’offre pas de garanties de transaction. Le code Java enregistre deux éléments (livres) dans la table `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 Récupère plusieurs éléments d’une ou de plusieurs tables en utilisant leurs clés primaires. Le code Java suivant récupère deux éléments dans deux tables différentes. ``` 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 Supprime des objets d’une ou de plusieurs tables à l’aide d’un ou de plusieurs appels à la méthode `AmazonDynamoDB.batchWriteItem`. Cette méthode n’offre pas de garanties de transaction. Le code Java supprime deux éléments (livres) dans la table `ProductCatalog`. ``` Book book1 = mapper.load(Book.class, 901); Book book2 = mapper.load(Book.class, 902); mapper.batchDelete(Arrays.asList(book1, book2)); ``` ## batchWrite Enregistre et supprime des objets dans une ou plusieurs des tables à l’aide d’un ou de plusieurs appels à la méthode `AmazonDynamoDB.batchWriteItem`. Cette méthode ne fournit pas des garanties de transactions et ne prend pas en charge le contrôle de version (suppressions ou insertions conditionnelles). Le code Java suivant écrit un nouvel élément dans la table `Forum`, écrit un nouvel élément dans la table `Thread` et supprime un élément de la table `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 Enregistre et supprime des objets dans une ou plusieurs des tables à l’aide d’un appel à la méthode `AmazonDynamoDB.transactWriteItems`. [Pour obtenir la liste des exceptions spécifiques aux transactions, consultez TransactWriteItems la section Erreurs.](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html#API_TransactWriteItems_Errors) Pour plus d’informations sur les transactions DynamoDB et les garanties d’atomicité, de cohérence, d’isolation et de durabilité (ACID) offertes, consultez [Transactions d’Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transactions.html). **Note** Cette méthode ne prend pas en charge : [DBMapperConfig Dynamo. SaveBehavior](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.OptionalConfig.html). Le code Java suivant écrit un nouvel élément dans chacune des tables `Forum` et `Thread`, par voie de transaction. ``` 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 Charge des objets d’une ou de plusieurs tables à l’aide d’un appel à la méthode `AmazonDynamoDB.transactGetItems`. [Pour obtenir la liste des exceptions spécifiques aux transactions, consultez TransactGetItems la section Erreurs.](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html#API_TransactGetItems_Errors) Pour plus d’informations sur les transactions DynamoDB et les garanties d’atomicité, de cohérence, d’isolation et de durabilité (ACID) offertes, consultez [Transactions d’Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transactions.html). L’extrait de code Java suivent charge un élément à partir de chacune des tables `Forum` et `Thread`, par voie de transaction. ``` 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 Évalue l’expression d’analyse spécifiée et renvoie le nombre d’éléments correspondants. Aucun élément de données n’est renvoyé. ## generateCreateTableDemande Analyse une classe POJO représentant une table DynamoDB, et renvoie une `CreateTableRequest` pour cette table. ## createS3Link Crée un lien vers un objet dans Amazon S3. Vous devez spécifier un nom de compartiment et un nom de clé identifiant l’objet de manière unique dans le compartiment. Pour utiliser `createS3Link`, votre classe d’outil de mappage doit définir des méthodes getter et setter. L'exemple de code suivant illustre cela en ajoutant un nouvel attribut et de nouvelles getter/setter méthodes à la `CatalogItem` classe. ``` @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; } ... } ``` Le code Java suivant définit un nouvel élément à écrire dans la table `Product`. L’élément inclut un lien vers une image de produit ; les données d’image sont chargées dans 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 classe `S3Link` fournit de nombreuses autres méthodes pour la manipulation d’objets dans Amazon S3. Pour plus d’informations, consultez [Javadocs pour `S3Link`](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/S3Link.html). ## Obtient S3 ClientCache Renvoie le `S3ClientCache` sous-jacent pour l’accès à Amazon S3. Un `S3ClientCache` est une carte intelligente pour des objets `AmazonS3Client`. Si vous avez plusieurs clients, cela `S3ClientCache` peut vous aider à organiser les clients par AWS région et à créer de nouveaux clients Amazon S3 à la demande. # Types de données pris en charge pour Dynamo DBMapper pour Java Cette section décrit les types de données Java primitifs, les collections et les types de données arbitraires pris en charge dans Amazon DynamoDB. Amazon DynamoDB prend en charge les types de données Java primitifs et les classes wrapper primitives suivants. + `String` + `Boolean`, `boolean` + `Byte`, `byte` + `Date` (en tant que chaîne de précision à la milliseconde [ISO\$18601](http://en.wikipedia.org/wiki/ISO_8601), passée sur UTC) + `Calendar` (en tant que chaîne de précision à la milliseconde [ISO\$18601](http://en.wikipedia.org/wiki/ISO_8601), passée sur UTC) + `Long`, `long` + `Integer`, `int` + `Double`, `double` + `Float`, `float` + `BigDecimal` + `BigInteger` **Note** Pour plus d’informations sur les règles de dénomination de DynamoDB et les différents types de données pris en charge, consultez [Types de données et règles de dénomination pris en charge dans Amazon DynamoDB](HowItWorks.NamingRulesDataTypes.md). Les valeurs binaires vides sont prises en charge par le Dynamo. DBMapper AWS SDK for Java 2.x prend en charge les valeurs String vides. Dans le AWS SDK for Java 1.x, DBMapper Dynamo prend en charge la lecture de valeurs d'attributs de chaîne vides, mais il n'écrit pas de valeurs d'attribut de chaîne vides car ces attributs sont supprimés de la demande. DynamoDB prend en charge les types de collections Java [Set](http://docs.oracle.com/javase/6/docs/api/java/util/Set.html) (ensemble), [List](http://docs.oracle.com/javase/6/docs/api/java/util/List.html) (liste) et [Map](http://docs.oracle.com/javase/6/docs/api/java/util/Map.html) (mappage). Le tableau suivant résume la manière dont ces types Java mappent aux types DynamoDB. **** | Type Java | Type DynamoDB | | --- | --- | | Tous les types de numéro | `N` (type Number) | | Chaînes | `S` (type String) | | Booléen | `BOOL` (type booléen), 0 ou 1. | | ByteBuffer | `B` (type Binary) | | Date | `S` (type String). Les valeurs Date sont stockées comme chaînes formatées ISO-8601. | | Types de collections [Set](http://docs.oracle.com/javase/6/docs/api/java/util/Set.html) | Type `SS` (string set), type `NS` (number set) ou type `BS` (binary set). | L’interface `DynamoDBTypeConverter` vous permet de mapper vos propres types de données arbitraires à un type de données que DynamoDB prend en charge en mode natif. Pour de plus amples informations, veuillez consulter [Mappage des données arbitraires dans DynamoDB](DynamoDBMapper.ArbitraryDataMapping.md). # Annotations Java pour DynamoDB Cette section décrit les annotations disponibles pour le mappage de vos classes et propriétés à des tables et attributs dans Amazon DynamoDB. Pour la documentation Javadoc correspondante, consultez [Annotation Types Summary](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/package-summary.html) dans la [Référence d’API AWS SDK pour Java](https://docs.aws.amazon.com/sdk-for-java/latest/reference/). **Note** Dans les annotations suivantes, seules `DynamoDBTable` et `DynamoDBHashKey` sont obligatoires. **Topics** + [Dynamo DBAttribute](#DynamoDBMapper.Annotations.DynamoDBAttribute) + [Dynamo DBAuto GeneratedKey](#DynamoDBMapper.Annotations.DynamoDBAutoGeneratedKey) + [Dynamo DBAuto GeneratedTimestamp](#DynamoDBMapper.Annotations.DynamoDBAutoGeneratedTimestamp) + [Dynamo DBDocument](#DynamoDBMapper.Annotations.DynamoDBDocument) + [Clé Dynamo DBHash](#DynamoDBMapper.Annotations.DynamoDBHashKey) + [Dynamo DBIgnore](#DynamoDBMapper.Annotations.DynamoDBIgnore) + [Dynamo DBIndex HashKey](#DynamoDBMapper.Annotations.DynamoDBIndexHashKey) + [Dynamo DBIndex RangeKey](#DynamoDBMapper.Annotations.DynamoDBIndexRangeKey) + [Clé Dynamo DBRange](#DynamoDBMapper.Annotations.DynamoDBRangeKey) + [Dynamo DBTable](#DynamoDBMapper.Annotations.DynamoDBTable) + [Dynamo convertie DBType](#DynamoDBMapper.Annotations.DynamoDBTypeConverted) + [Dynamo DBTyped](#DynamoDBMapper.Annotations.DynamoDBTyped) + [Attribut Dynamo DBVersion](#DynamoDBMapper.Annotations.DynamoDBVersionAttribute) ## Dynamo DBAttribute Mappe une propriété avec un attribut de table. Par défaut, chaque propriété de classe mappe un attribut d’élément avec le même nom. Toutefois, si les noms ne sont pas les mêmes, vous pouvez utiliser cette annotation pour mapper une propriété avec l’attribut. Dans l’extrait Java suivant, l’`DynamoDBAttribute` mappe la propriété `BookAuthors` avec le nom d’attribut `Authors` de la table. ``` @DynamoDBAttribute(attributeName = "Authors") public List getBookAuthors() { return BookAuthors; } public void setBookAuthors(List BookAuthors) { this.BookAuthors = BookAuthors; } ``` Le `DynamoDBMapper` utilise `Authors` en tant que nom d’attribut lors de l’enregistrement de l’objet vers la table. ## Dynamo DBAuto GeneratedKey Marque une propriété de clé de tri ou de clé de partition comme étant générée automatiquement. `DynamoDBMapper` génère un [UUID](http://docs.oracle.com/javase/6/docs/api/java/util/UUID.html) aléatoire lors de l’enregistrement de ces attributs. Seules les propriétés String peuvent être marquées en tant que clés générées automatiquement. L’exemple suivant illustre l’utilisation clés générées automatiquement. ``` @DynamoDBTable(tableName="AutoGeneratedKeysExample") public class AutoGeneratedKeys { private String id; private String payload; @DynamoDBHashKey(attributeName = "Id") @DynamoDBAutoGeneratedKey public String getId() { return id; } public void setId(String id) { this.id = id; } @DynamoDBAttribute(attributeName="payload") public String getPayload() { return this.payload; } public void setPayload(String payload) { this.payload = payload; } public static void saveItem() { AutoGeneratedKeys obj = new AutoGeneratedKeys(); obj.setPayload("abc123"); // id field is null at this point DynamoDBMapper mapper = new DynamoDBMapper(dynamoDBClient); mapper.save(obj); System.out.println("Object was saved with id " + obj.getId()); } } ``` ## Dynamo DBAuto GeneratedTimestamp Génère automatiquement un horodatage. ``` @DynamoDBAutoGeneratedTimestamp(strategy=DynamoDBAutoGenerateStrategy.ALWAYS) public Date getLastUpdatedDate() { return lastUpdatedDate; } public void setLastUpdatedDate(Date lastUpdatedDate) { this.lastUpdatedDate = lastUpdatedDate; } ``` (Facultatif) La stratégie de génération automatique peut être définie en fournissant un attribut de stratégie. La valeur par défaut est `ALWAYS`. ## Dynamo DBDocument Indique qu’une classe peut être sérialisée sous forme de document Amazon DynamoDB. Par exemple, supposons que vous voulez mapper un document JSON à un attribut DynamoDB de type Map (`M`). L’exemple de code suivant définit un élément contenant un attribut imbriqué de type de Map. ``` public class ProductCatalogItem { private Integer id; //partition key private Pictures pictures; /* ...other attributes omitted... */ @DynamoDBHashKey(attributeName="Id") public Integer getId() { return id;} public void setId(Integer id) {this.id = id;} @DynamoDBAttribute(attributeName="Pictures") public Pictures getPictures() { return pictures;} public void setPictures(Pictures pictures) {this.pictures = pictures;} // Additional properties go here. @DynamoDBDocument public static class Pictures { private String frontView; private String rearView; private String sideView; @DynamoDBAttribute(attributeName = "FrontView") public String getFrontView() { return frontView; } public void setFrontView(String frontView) { this.frontView = frontView; } @DynamoDBAttribute(attributeName = "RearView") public String getRearView() { return rearView; } public void setRearView(String rearView) { this.rearView = rearView; } @DynamoDBAttribute(attributeName = "SideView") public String getSideView() { return sideView; } public void setSideView(String sideView) { this.sideView = sideView; } } } ``` Vous pouvez alors enregistrer un nouvel élément `ProductCatalog` avec `Pictures`, comme illustré dans l’exemple suivant. ``` ProductCatalogItem item = new ProductCatalogItem(); Pictures pix = new Pictures(); pix.setFrontView("http://example.com/products/123_front.jpg"); pix.setRearView("http://example.com/products/123_rear.jpg"); pix.setSideView("http://example.com/products/123_left_side.jpg"); item.setPictures(pix); item.setId(123); mapper.save(item); ``` L’élément `ProductCatalog` qui en résulte se présente comme suit (au format JSON) : ``` { "Id" : 123 "Pictures" : { "SideView" : "http://example.com/products/123_left_side.jpg", "RearView" : "http://example.com/products/123_rear.jpg", "FrontView" : "http://example.com/products/123_front.jpg" } } ``` ## Clé Dynamo DBHash Mappe une propriété de classe avec la clé de partition de la table. La propriété doit être un des types binaire, numéro ou chaîne scalaire. La propriété ne peut pas être de type collection. Supposons que vous ayez une table, `ProductCatalog`, qui a un `Id` en tant que clé primaire. Le code Java suivant définit une classe `CatalogItem` et mappe sa propriété `Id` à la clé primaire de la table `ProductCatalog` à l’aide de la balise `@DynamoDBHashKey`. ``` @DynamoDBTable(tableName="ProductCatalog") public class CatalogItem { private Integer Id; @DynamoDBHashKey(attributeName="Id") public Integer getId() { return Id; } public void setId(Integer Id) { this.Id = Id; } // Additional properties go here. } ``` ## Dynamo DBIgnore Indique à l’instance `DynamoDBMapper` que la propriété associée doit être ignorée. Lors de l’enregistrement de données dans la table, `DynamoDBMapper` ne sauvegarde pas cette propriété dans la table. S’applique à la méthode getter ou au champ de classe pour une propriété non modélisée. Si l’annotation est appliquée directement au champ de classe, les méthodes getter et setter correspondantes doivent être déclarées dans la même classe. ## Dynamo DBIndex HashKey Mappe une propriété de classe à la clé de partition d’un index secondaire global. La propriété doit être un des types binaire, numéro ou chaîne scalaire. La propriété ne peut pas être de type collection. Utilisez cette annotation si vous devez interroger (`Query`) un index secondaire global. Vous devez spécifier le nom d’index (`globalSecondaryIndexName`). Si le nom de la propriété de classe est différent de la clé de partition d’index, vous devez également spécifier le nom de cet attribut d’index (`attributeName`). ## Dynamo DBIndex RangeKey Mappe une propriété de classe à la clé de tri d’un index secondaire global ou local. La propriété doit être un des types binaire, numéro ou chaîne scalaire. La propriété ne peut pas être de type collection. Utilisez cette annotation si vous devez interroger (`Query`) un index secondaire local ou global, et souhaitez affiner vos résultats à l’aide de la clé de tri d’index. Vous devez spécifier le nom d’index (soit `globalSecondaryIndexName`, soit `localSecondaryIndexName`). Si le nom de la propriété de classe est différent de la clé de tri d’index, vous devez également spécifier le nom de cet attribut d’index (`attributeName`). ## Clé Dynamo DBRange Mappe une propriété de classe avec la clé de tri de la table. La propriété doit être un des types binaire, numéro ou chaîne scalaire. Elle ne peut pas être de type collection. Si la clé primaire est composite (clé de partition et clé de tri), vous pouvez utiliser cette balise pour mapper votre champ de classe avec la clé de tri. Par exemple, supposons que vous ayez une table `Reply` qui stocke les réponses pour les threads de forum. Chaque thread peut avoir plusieurs réponses. Ainsi, la clé primaire de cette table est à la fois `ThreadId` et `ReplyDateTime`. La clé de partition est `ThreadId` et la clé de tri est `ReplyDateTime`. L’extrait de code Java suivant définit une classe `Reply` et la mappe à la table `Reply`. Il utilise les deux balises, `@DynamoDBHashKey` et `@DynamoDBRangeKey`, pour identifier les propriétés de classe qui sont mappées avec la clé primaire. ``` @DynamoDBTable(tableName="Reply") public class Reply { private Integer id; private String replyDateTime; @DynamoDBHashKey(attributeName="Id") public Integer getId() { return id; } public void setId(Integer id) { this.id = id; } @DynamoDBRangeKey(attributeName="ReplyDateTime") public String getReplyDateTime() { return replyDateTime; } public void setReplyDateTime(String replyDateTime) { this.replyDateTime = replyDateTime; } // Additional properties go here. } ``` ## Dynamo DBTable Identifie la table cible dans DynamoDB. Par exemple, l’extrait de code Java suivant définit une classe `Developer` et la mappe à la table `People` dans DynamoDB. ``` @DynamoDBTable(tableName="People") public class Developer { ...} ``` L’annotation `@DynamoDBTable` peut être héritée. Toute nouvelle classe qui hérite de la classe `Developer` se mappe également à la table `People`. Par exemple, supposons que vous génériez une classe `Lead` qui hérite de la classe `Developer`. Étant donné que vous avez mappé la classe `Developer` à la table `People`, les objets de la classe `Lead` sont également stockés dans la même table. La `@DynamoDBTable` peut également être remplacée. Toute nouvelle classe qui hérite de la classe `Developer` par défaut se mappe à la même table `People`. Toutefois, vous pouvez substituer ce mappage par défaut. Par exemple, si vous créez une classe qui hérite de la classe `Developer`, vous pouvez explicitement la mapper à une autre table en ajoutant l’annotation `@DynamoDBTable` comme illustré dans l’extrait de code Java suivant. ``` @DynamoDBTable(tableName="Managers") public class Manager extends Developer { ...} ``` ## Dynamo convertie DBType Une annotation permettant d’indiquer qu’une propriété utilise un convertisseur personnalisé. Peut être indiquée sur une annotation définie par l’utilisateur afin de transmettre des propriétés à `DynamoDBTypeConverter`. L’interface `DynamoDBTypeConverter` vous permet de mapper vos propres types de données arbitraires à un type de données que DynamoDB prend en charge en mode natif. Pour de plus amples informations, veuillez consulter [Mappage des données arbitraires dans DynamoDB](DynamoDBMapper.ArbitraryDataMapping.md). ## Dynamo DBTyped Une annotation permettant de remplacer la liaison du type d’attribut standard. Les types standard ne nécessitent pas l’annotation si la liaison d’attribut par défaut est appliquée pour ce type. ## Attribut Dynamo DBVersion Identifie une propriété de classe pour stocker un numéro de version de verrouillage optimiste. `DynamoDBMapper` affecte un numéro de version à cette propriété lorsqu’il enregistre un nouvel élément et l’augmente chaque fois que vous mettez à jour l’élément. Seuls les types scalaires de numéros sont pris en charge. Pour plus d’informations sur les types de données, consultez [Types de données](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes), Pour plus d’informations sur la gestion des versions, consultez [DynamoDB et verrouillage optimiste avec numéro de version](DynamoDBMapper.OptimisticLocking.md). # Paramètres de configuration facultatifs pour Dynamo DBMapper Lorsque vous créez une instance de `DynamoDBMapper`, elle a certains comportements par défaut ; vous pouvez remplacer ces valeurs par défaut en utilisant la classe `DynamoDBMapperConfig`. L’extrait de code suivant crée un `DynamoDBMapper` avec des paramètres personnalisés : ``` AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build(); DynamoDBMapperConfig mapperConfig = DynamoDBMapperConfig.builder() .withSaveBehavior(DynamoDBMapperConfig.SaveBehavior.CLOBBER) .withConsistentReads(DynamoDBMapperConfig.ConsistentReads.CONSISTENT) .withTableNameOverride(null) .withPaginationLoadingStrategy(DynamoDBMapperConfig.PaginationLoadingStrategy.EAGER_LOADING) .build(); DynamoDBMapper mapper = new DynamoDBMapper(client, mapperConfig); ``` Pour plus d'informations, consultez [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapperConfig.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapperConfig.html) dans le manuel de [référence de l'AWS SDK pour Java API](https://docs.aws.amazon.com/sdk-for-java/latest/reference/). Vous pouvez utiliser les arguments suivants pour une instance de `DynamoDBMapperConfig` : + Une valeur d’énumération `DynamoDBMapperConfig.ConsistentReads` : + `EVENTUAL` – L’instance du mappeur utilise une demande de lecture éventuellement cohérente. + `CONSISTENT` – L’instance du mappeur utilise une demande de lecture fortement cohérente. Vous pouvez utiliser ce paramètre facultatif avec des opérations `load`, `query` ou `scan`. Les lectures fortement cohérentes ont des implications pour les performances et la facturation. Pour plus d’informations, consultez la [page détaillée du produit](https://aws.amazon.com/dynamodb). Si vous ne spécifiez pas un paramètre de cohérence de lecture pour votre instance d’outil de mappage, la valeur par défaut est `EVENTUAL`. **Note** Cette valeur est appliquée dans les `batch load` opérations `query``querypage`,`load`, et de la Dynamo. DBMapper + Valeur d’énumération `DynamoDBMapperConfig.PaginationLoadingStrategy` – Contrôle la façon dont l’instance de mappeur traite une liste paginée de données, telle que les résultats d’une opération `query` ou `scan` : + `LAZY_LOADING` – L’instance de mappeur charge les données quand cela est possible, et conserve tous les résultats chargés en mémoire. + `EAGER_LOADING` – L’instance de mappeur charge les données dès que la liste est initialisée. + `ITERATION_ONLY` – Vous ne pouvez utiliser qu’un itérateur pour lire la liste. Pendant l’itération, la liste efface tous les résultats précédents avant de charger la page suivante, pour que la liste conserve en mémoire au maximum une page des résultats chargés. Cela signifie également que la liste ne peut être itérée qu’à une seule reprise. Cette stratégie est recommandée lors de la gestion d’éléments importants, afin de réduire les frais généraux de mémoire. Si vous ne spécifiez pas une stratégie de chargement de pagination pour votre instance d’outil de mappage, la valeur par défaut est `LAZY_LOADING`. + Une valeur d’énumération `DynamoDBMapperConfig.SaveBehavior` - Spécifie comment l’instance d’outil de mappage devrait traiter les attributs lors des opérations d’enregistrement : + `UPDATE` – Lors d’une opération d’enregistrement, tous les attributs modélisés sont mis à jour, et les attributs non modélisés ne sont pas affectés. Les types de numéros primitifs (octets, int, long) sont définis sur 0. Les types d’objets sont définis sur null. + `CLOBBER` – Efface et remplace tous les attributs, y compris non modélisés, lors d’une opération d’enregistrement. Pour cela, il faut supprimer l’élément et le recréer. Les contraintes de champ avec version sont également ignorées. Si vous ne spécifiez pas le comportement de sauvegarde pour votre instance d’outil de mappage, la valeur par défaut est `UPDATE`. **Note** Les opérations DBMapper transactionnelles Dynamo ne prennent pas en charge `DynamoDBMapperConfig.SaveBehavior` l'énumération. + Objet `DynamoDBMapperConfig.TableNameOverride` – Indique à l’instance de mappeur d’ignorer le nom de table spécifié par l’annotation `DynamoDBTable` d’une classe, et d’utiliser plutôt un autre nom de table que vous fournissez. Cela est utile lors du partitionnement de vos données dans plusieurs tables au moment de l’exécution. Vous pouvez remplacer l’objet de configuration par défaut pour `DynamoDBMapper` par opération, en fonction des besoins. # DynamoDB et verrouillage optimiste avec numéro de version Le *verrouillage optimiste* est une politique visant à garantir que l’élément côté client que vous mettez à jour (ou supprimez) est identique à l’élément dans Amazon DynamoDB. Si vous utilisez cette stratégie, les écritures de votre base de données ne peuvent pas être remplacées par les écritures d’autres, et vice versa. Avec le verrouillage optimiste, chaque élément possède un attribut qui agit comme un numéro de version. Si vous récupérez un élément à partir d’une table, l’application enregistre le numéro de version de cet élément. Vous pouvez mettre à jour l’élément, mais uniquement si le numéro de version sur le côté serveur n’a pas changé. Si les versions ne correspondent pas, cela signifie que quelqu’un d’autre a modifié cet élément avant vous. La tentative de mise à jour échoue car vous possédez une version obsolète de l’élément. Si cela se produit, essayez à nouveau en récupérant l’élément, puis en tentant de le mettre à jour. Le verrouillage optimiste vous empêche de remplacer accidentellement les modifications effectuées par les autres. Il empêche également que vos modifications soient remplacées. Bien que vous puissiez mettre en œuvre votre propre stratégie de verrouillage optimiste, AWS SDK pour Java elle fournit l'`@DynamoDBVersionAttribute`annotation. Dans la classe de mappage pour votre table, vous indiquez une propriété pour stocker le numéro de version et vous la marquez à l’aide de cette annotation. Lorsque vous enregistrez un objet, l’élément correspondant dans la table DynamoDB aura un attribut qui stocke le numéro de version. Le `DynamoDBMapper` attribue un numéro de version lors de l’enregistrement initial de l’objet, et il augmente automatiquement le numéro de version chaque fois que vous mettez à jour l’élément. Vos demandes de mise à jour ou de suppression aboutissent uniquement si la version d’objet côté client correspond au numéro de version de l’élément correspondant dans la table DynamoDB. `ConditionalCheckFailedException` est émis si : + Vous utilisez le verrouillage optimiste avec `@DynamoDBVersionAttribute` et la valeur de version sur le serveur est différente de la valeur côté client. + Vous spécifiez vos propres contraintes conditionnelles tout en enregistrant des données à l’aide de `DynamoDBMapper` avec `DynamoDBSaveExpression` et ces contraintes ont échoué. **Note** Les tables globales DynamoDB utilisent un rapprochement « last writer wins » (dernière version valide) entre des mises à jour concomitantes. Si vous utilisez des tables globales, la stratégie « last writer wins » (dernière version valide) s’applique. Dans ce cas, la stratégie de verrouillage ne fonctionne pas comme prévu. Les opérations d’écriture transactionnelle `DynamoDBMapper` ne prennent pas en charge les expressions d’annotation et de condition `@DynamoDBVersionAttribute` sur le même objet. Si un objet dans une écriture transactionnelle est annoté avec une expression `@DynamoDBVersionAttribute` conditionnelle et possède également une expression conditionnelle, une SdkClientException sera émise. Par exemple, le code Java suivant définit une classe `CatalogItem` qui possède plusieurs propriétés. La propriété `Version` est balisée avec l’annotation `@DynamoDBVersionAttribute`. **Example** ``` @DynamoDBTable(tableName="ProductCatalog") public class CatalogItem { private Integer id; private String title; private String ISBN; private Set bookAuthors; private String someProp; private Long version; @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;} @DynamoDBVersionAttribute public Long getVersion() { return version; } public void setVersion(Long version) { this.version = version;} } ``` Vous pouvez appliquer l’annotation `@DynamoDBVersionAttribute` aux types Nullable proposés par les classes de wrappers primitifs qui fournissent un type Nullable, par exemple `Long` et `Integer`. Le verrouillage optimiste a l’impact suivant sur ces méthodes `DynamoDBMapper` : + `save` – Pour un nouvel élément, le `DynamoDBMapper` attribue un numéro de version initial 1. Si vous récupérez un élément, que vous mettez à jour une ou plusieurs de ses propriétés et que vous tentez d’enregistrer les modifications, l’opération de sauvegarde n’aboutit que si les numéros de version côté client et côté serveur correspondent. Le `DynamoDBMapper` augmente le numéro de version automatiquement. + `delete` – La méthode `delete` prend un objet en tant que paramètre, et le `DynamoDBMapper` effectue une vérification de version avant de supprimer l’élément. Le contrôle de version peut être désactivé si `DynamoDBMapperConfig.SaveBehavior.CLOBBER` est spécifié dans la demande. L’implémentation interne de verrouillage optimiste au sein de `DynamoDBMapper` utilise la prise en charge de suppression et de mise à jour conditionnelles fournies par DynamoDB. + `transactionWrite` — + `Put` – Pour un nouvel élément, le `DynamoDBMapper` attribue un numéro de version initial 1. Si vous récupérez un élément, que vous mettez à jour une ou plusieurs de ses propriétés et que vous tentez d’enregistrer les modifications, l’opération « Put » n’aboutit que si les numéros de version côté client et côté serveur correspondent. Le `DynamoDBMapper` augmente le numéro de version automatiquement. + `Update` – Pour un nouvel élément, le `DynamoDBMapper` attribue un numéro de version initial 1. Si vous récupérez un élément, que vous mettez à jour une ou plusieurs de ses propriétés et que vous tentez d’enregistrer les modifications, l’opération de mise à jour n’aboutit que si les numéros de version côté client et côté serveur correspondent. Le `DynamoDBMapper` augmente le numéro de version automatiquement. + `Delete` – Le `DynamoDBMapper` effectue une vérification de version avant de supprimer l’élément. L’opération de suppression n’aboutit que si les numéros de version côté client et côté serveur correspondent. + `ConditionCheck` – L’annotation `@DynamoDBVersionAttribute` n’est pas prise en charge pour les opérations `ConditionCheck`. Un SdkClientException sera lancé lorsqu'un `ConditionCheck` élément est annoté avec`@DynamoDBVersionAttribute`. ## Désactivation du verrouillage optimiste Pour désactiver le verrouillage optimiste, vous pouvez changer la valeur d’énumération `DynamoDBMapperConfig.SaveBehavior` de `UPDATE` à `CLOBBER`. Vous pouvez le faire en créant une instance `DynamoDBMapperConfig` qui ignore la vérification de version et utilise cette instance pour toutes vos demandes. Pour plus d’informations sur les paramètres `DynamoDBMapperConfig.SaveBehavior` et autres paramètres facultatifs `DynamoDBMapper`, consultez [Paramètres de configuration facultatifs pour Dynamo DBMapper](DynamoDBMapper.OptionalConfig.md). Vous pouvez également définir le comportement de verrouillage pour une opération spécifique uniquement. Par exemple, l’extrait de Java suivant utilise le `DynamoDBMapper` pour enregistrer un élément de catalogue. Il spécifie `DynamoDBMapperConfig.SaveBehavior` en ajoutant le paramètre `DynamoDBMapperConfig` facultatif à la méthode `save`. **Note** La méthode TransactionWrite ne prend pas en charge Dynamo Config. DBMapper SaveBehaviorconfiguration. La désactivation du verrouillage optimiste pour transactionWrite n’est pas prise en charge. **Example** ``` DynamoDBMapper mapper = new DynamoDBMapper(client); // Load a catalog item. CatalogItem item = mapper.load(CatalogItem.class, 101); item.setTitle("This is a new title for the item"); ... // Save the item. mapper.save(item, new DynamoDBMapperConfig( DynamoDBMapperConfig.SaveBehavior.CLOBBER)); ``` # Mappage des données arbitraires dans DynamoDB En plus des types Java pris en charge (voir [Types de données pris en charge pour Dynamo DBMapper pour Java](DynamoDBMapper.DataTypes.md)), vous pouvez utiliser des types dans votre application pour lesquels il n’y a pas de mappage direct aux types Amazon DynamoDB. Pour mapper ces types, vous devez fournir une implémentation qui convertit votre type complexe en un type pris en charge par DynamoDB et inversement, et annoter la méthode accesseur de type complexe en utilisant l’annotation `@DynamoDBTypeConverted`. Le code de convertisseur transforme les données lorsque des objets sont enregistrés ou chargés. Il est également utilisé pour toutes les opérations qui utilisent des types complexes. Notez que, lors de la comparaison de données pendant des opérations d’interrogation et d’analyse, les comparaisons sont faites par rapport aux données stockées dans DynamoDB. Par exemple, envisagez la classe `CatalogItem` suivante qui définit une propriété, `Dimension`, qui est de `DimensionType`. Cette propriété stocke les dimensions de l’élément, telles que la hauteur, la largeur et l’épaisseur. Supposons que vous décidez de stocker ces dimensions d’élément sous la forme d’une chaîne (par exemple, 8.5x11x.05) dans DynamoDB. L’exemple suivant fournit un code de convertisseur qui convertit l’objet `DimensionType` en une chaîne et une chaîne en `DimensionType`. **Note** Cet exemple de code part du principe que vous avez déjà chargé des données dans DynamoDB pour votre compte en suivant les instructions de la section [Création de tables et chargement de données pour des exemples de code dans DynamoDB](SampleData.md). Pour step-by-step obtenir des instructions relatives à l'exécution de l'exemple suivant, reportez-vous à[Exemples de code Java](CodeSamples.Java.md). **Example** ``` public class DynamoDBMapperExample { static AmazonDynamoDB client; public static void main(String[] args) throws IOException { // Set the AWS region you want to access. Regions usWest2 = Regions.US_WEST_2; client = AmazonDynamoDBClientBuilder.standard().withRegion(usWest2).build(); DimensionType dimType = new DimensionType(); dimType.setHeight("8.00"); dimType.setLength("11.0"); dimType.setThickness("1.0"); Book book = new Book(); book.setId(502); book.setTitle("Book 502"); book.setISBN("555-5555555555"); book.setBookAuthors(new HashSet(Arrays.asList("Author1", "Author2"))); book.setDimensions(dimType); DynamoDBMapper mapper = new DynamoDBMapper(client); mapper.save(book); Book bookRetrieved = mapper.load(Book.class, 502); System.out.println("Book info: " + "\n" + bookRetrieved); bookRetrieved.getDimensions().setHeight("9.0"); bookRetrieved.getDimensions().setLength("12.0"); bookRetrieved.getDimensions().setThickness("2.0"); mapper.save(bookRetrieved); bookRetrieved = mapper.load(Book.class, 502); System.out.println("Updated book info: " + "\n" + bookRetrieved); } @DynamoDBTable(tableName = "ProductCatalog") public static class Book { private int id; private String title; private String ISBN; private Set bookAuthors; private DimensionType dimensionType; // Partition key @DynamoDBHashKey(attributeName = "Id") public int getId() { return id; } public void setId(int 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; } @DynamoDBTypeConverted(converter = DimensionTypeConverter.class) @DynamoDBAttribute(attributeName = "Dimensions") public DimensionType getDimensions() { return dimensionType; } @DynamoDBAttribute(attributeName = "Dimensions") public void setDimensions(DimensionType dimensionType) { this.dimensionType = dimensionType; } @Override public String toString() { return "Book [ISBN=" + ISBN + ", bookAuthors=" + bookAuthors + ", dimensionType= " + dimensionType.getHeight() + " X " + dimensionType.getLength() + " X " + dimensionType.getThickness() + ", Id=" + id + ", Title=" + title + "]"; } } static public class DimensionType { private String length; private String height; private String thickness; public String getLength() { return length; } public void setLength(String length) { this.length = length; } public String getHeight() { return height; } public void setHeight(String height) { this.height = height; } public String getThickness() { return thickness; } public void setThickness(String thickness) { this.thickness = thickness; } } // Converts the complex type DimensionType to a string and vice-versa. static public class DimensionTypeConverter implements DynamoDBTypeConverter { @Override public String convert(DimensionType object) { DimensionType itemDimensions = (DimensionType) object; String dimension = null; try { if (itemDimensions != null) { dimension = String.format("%s x %s x %s", itemDimensions.getLength(), itemDimensions.getHeight(), itemDimensions.getThickness()); } } catch (Exception e) { e.printStackTrace(); } return dimension; } @Override public DimensionType unconvert(String s) { DimensionType itemDimension = new DimensionType(); try { if (s != null && s.length() != 0) { String[] data = s.split("x"); itemDimension.setLength(data[0].trim()); itemDimension.setHeight(data[1].trim()); itemDimension.setThickness(data[2].trim()); } } catch (Exception e) { e.printStackTrace(); } return itemDimension; } } } ``` # Exemples DynamoDBMapper Le kit AWS SDK fournit une classe `DynamoDBMapper` qui vous permet de mapper vos classes côté client à des tables DynamoDB. Pour utiliser `DynamoDBMapper`, vous définissez la relation entre éléments d’une table DynamoDB et leurs instances d’objet correspondantes dans votre code. La classe `DynamoDBMapper` vous permet d’effectuer diverses opérations de création, de lecture, de mise à jour et de suppression (opérations CRUD) sur des éléments, ainsi que d’exécuter des requêtes et analyses sur des tables. Pour en savoir plus sur l’utilisation de `DynamoDBMapper`, consultez [DynamoDB Examples Using the AWS SDK for Java ](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/examples-dynamodb.html) dans le *Guide du développeur AWS SDK for Java 1.x*.