Classe DynamoDBMapper - Amazon DynamoDB
enregistrer charge supprimerqueryqueryPagescanscanPageparallelScanbatchSavebatchLoadbatchDeletebatchWritetransactionWritetransactionLoadcountgenerateCreateTableDemandecreateS3LinkObtient S3 ClientCache

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.

Classe DynamoDBMapper

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 la documentation Javadoc correspondante, consultez DynamoDBMapper dans la Référence d'API AWS SDK for Java .

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 Verrouillage optimiste avec numéro de version.

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.

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 Verrouillage optimiste avec numéro de version.

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.

Exemple 
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<String, AttributeValue> eav = new HashMap<String, AttributeValue>();
eav.put(":v1", new AttributeValue().withS(partitionKey));
eav.put(":v2",new AttributeValue().withS(twoWeeksAgoStr.toString()));

DynamoDBQueryExpression<Reply> queryExpression = new DynamoDBQueryExpression<Reply>()
    .withKeyConditionExpression("Id = :v1 and ReplyDateTime > :v2")
    .withExpressionAttributeValues(eav);

List<Reply> 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'@DynamoDBIndexHashKeyannotation 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<String, AttributeValue> eav = new HashMap<String, AttributeValue>();
eav.put(":v1",  new AttributeValue().withS("User A"));
eav.put(":v2",  new AttributeValue().withS("DynamoDB"));

DynamoDBQueryExpression<PostedByMessage> queryExpression = new DynamoDBQueryExpression<PostedByMessage>()
    .withIndexName("PostedBy-Message-Index")
    .withConsistentRead(false)
    .withKeyConditionExpression("PostedBy = :v1 and begins_with(Message, :v2)")
    .withExpressionAttributeValues(eav);

List<PostedByMessage> 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.

Exemple 
HashMap<String, AttributeValue> eav = new HashMap<String, AttributeValue>();
eav.put(":v1", new AttributeValue().withS("2015"));

DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
    .withFilterExpression("begins_with(ReplyDateTime,:v1)")
    .withExpressionAttributeValues(eav);

List<Reply> 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. 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<PostedByMessage> iList =  mapper.scan(PostedByMessage.class, scanExpression);
    Iterator<PostedByMessage> 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<String, AttributeValue> eav = new HashMap<String, AttributeValue>();
eav.put(":n", new AttributeValue().withN("100"));

DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
    .withFilterExpression("Price <= :n")
    .withExpressionAttributeValues(eav);

List<Product> scanResult = mapper.parallelScan(Product.class, scanExpression, numberOfThreads);

Pour un exemple de code Java illustrant l'utilisation de parallelScan, consultez Opérations de requête et d'analyse de DynamoDBMapper.

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<Object> itemsToGet = new ArrayList<Object>();

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<String, List<Object>> 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<Object> objectsToWrite = Arrays.asList(forumItem, threadItem);
List<Book> 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.

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.

Note

Cette méthode ne prend pas en charge :

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.

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.

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.

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 des méthodes getter/setter à la classe 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;
    }

...
}

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 myS3Bucket = "myS3bucket";
String myS3Key = "productImages/book_150_cover.jpg";
item.setProductImage(mapper.createS3Link(myS3Bucket, 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.

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.