Modifications apportées au APIs mappage/document DynamoDB de la version 1 à la version 2

Cette rubrique décrit les modifications apportées au niveau élevé SDK de Java APIs pour Amazon DynamoDB entre les versions 1.x (v1) et (v2). AWS SDK for Java 2.x Nous abordons d'abord le object-to-table mappage, API puis discutons du document API permettant de travailler avec des documents de JSON style.

Changements de haut niveau

Les noms du client de mappage dans chaque bibliothèque diffèrent dans les versions 1 et 2 :

• v1 - D ynamoDBMapper

• v2 - Client DynamoDB amélioré

Vous interagissez avec les deux bibliothèques de la même manière : vous instanciez un mappeur/client, puis vous fournissez un code Java POJO pour lire et écrire ces éléments dans APIs les tables DynamoDB. Les deux bibliothèques proposent également des annotations pour la classe de POJO afin de déterminer comment le client gère lePOJO.

Les différences notables lorsque vous passez à la version v2 incluent :

• Les versions V2 et v1 utilisent des noms de méthode différents pour les opérations DynamoDB de bas niveau. Par exemple :

  v1	v2
  charge	getItem
  enregistrer	putItem
  batchLoad	batchGetItem

• La V2 propose plusieurs méthodes pour définir des schémas de tables et les POJOs mapper à des tables. Vous pouvez choisir d'utiliser des annotations ou un schéma généré à partir du code à l'aide d'un générateur. La V2 propose également des versions mutables et immuables des schémas.

• Avec la v2, vous créez spécifiquement le schéma de table comme l'une des premières étapes, tandis qu'en v1, le schéma de table est déduit de la classe annotée selon les besoins.

• La version V2 inclut le APIclient Document dans le client amélioréAPI, tandis que la version 1 utilise un client distinct API.

• Tous APIs sont disponibles en versions synchrone et asynchrone dans la v2.

Consultez la section de mappage DynamoDB de ce guide pour obtenir des informations plus détaillées sur le client amélioré v2.

Importer des dépendances

v1	v2
<dependencyManagement> <dependencies> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-java-sdk-bom</artifactId> <version>1.X.X</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-java-sdk-dynamodb</artifactId> </dependency> </dependencies>	<dependencyManagement> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>bom</artifactId> <version>2.X.X*</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>dynamodb-enhanced</artifactId> </dependency> </dependencies>

^* Dernière version.

Dans la version 1, une seule dépendance inclut à la fois le API DynamoDB de bas niveau et le API mappage/document, tandis que dans la version 2, vous utilisez la dépendance d'artefact pour accéder dynamodb-enhanced au mappage/document. API Le dynamodb-enhanced module contient une dépendance transitive vis-à-vis du module de bas niveau. dynamodb

APImodifications

Création d'un client

Cas d’utilisation	v1	v2
Instanciation normale	AmazonDynamoDB standardClient = AmazonDynamoDBClientBuilder.standard() .withCredentials(credentialsProvider) .withRegion(Regions.US_EAST_1) .build(); DynamoDBMapper mapper = new DynamoDBMapper(standardClient);	DynamoDbClient standardClient = DynamoDbClient.builder() .credentialsProvider(ProfileCredentialsProvider.create()) .region(Region.US_EAST_1) .build(); DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() .dynamoDbClient(standardClient) .build();
Instanciation minimale	AmazonDynamoDB standardClient = AmazonDynamoDBClientBuilder.standard(); DynamoDBMapper mapper = new DynamoDBMapper(standardClient);	DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.create();
Avec transformateur d'attributs *	DynamoDBMapper mapper = new DynamoDBMapper(standardClient, attributeTransformerInstance);	DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() .dynamoDbClient(standardClient) .extensions(extensionAInstance, extensionBInstance) .build();

^{* Les} extensions de la v2 correspondent approximativement aux transformateurs d'attributs de la v1. La Utiliser des extensions section contient plus d'informations sur les extensions de la version 2.

Établir le mappage vers la table/l'index DynamoDB

Dans la version 1, vous spécifiez le nom d'une table DynamoDB par le biais d'une annotation de bean. Dans la version 2, une méthode d'usine produit une instance de DynamoDbTable qui représente la table DynamoDB distante. table() Le premier paramètre de la table() méthode est le nom de la table DynamoDB.

Cas d’utilisation	v1	v2
Mappez la POJO classe Java à la table DynamoDB	@DynamoDBTable(tableName ="Customer") public class Customer { ... }	DynamoDbTable<Customer> customerTable = enhancedClient.table("Customer", TableSchema.fromBean(Customer.class));
Mapper vers un index secondaire DynamoDB	Définissez une POJO classe qui représente l'index. Annotez la classe @DynamoDBTable en fournissant le nom de la table contenant l'index. Annotez les propriétés avec @DynamoDBIndexHashKey et éventuellement@DynamoDBIndexRangeKey. Créez une expression de requête. Requête utilisant une référence à la POJO classe qui représente l'index. Par exemple mapper.query(IdEmailIndex.class, queryExpression) où IdEmailIndex est la classe de mappage de l'index. La section du Guide du développeur DynamoDB qui décrit la méthode query v1 présente un exemple complet.	Annotez les attributs d'une POJO classe avec @DynamoDbSecondaryPartitionKey (pour a GSI) et @DynamoDbSecondarySortKey (pour et GSI ou LSI). Par exemple, @DynamoDbSecondarySortKey(indexNames = "IdEmailIndex") public String getEmail() { return this.email; } Récupérez une référence à l'index. Par exemple, DynamoDbIndex<Customer> customerIndex = customerTable.index("IdEmailIndex"); Interrogez l'index. La Utiliser des indices secondaires section de ce guide fournit plus d'informations.

Opérations de table

Cette section décrit les opérations APIs qui diffèrent entre la v1 et la v2 pour la plupart des cas d'utilisation standard.

Dans la version 2, toutes les opérations impliquant une seule table sont appelées sur l'DynamoDbTableinstance, et non sur le client amélioré. Le client amélioré contient des méthodes qui peuvent cibler plusieurs tables.

Dans le tableau intitulé Opérations de table ci-dessous, une POJO instance est désignée sous le nom item ou en tant que type spécifique tel quecustomer1. Pour les exemples de la version 2, les instances nommées table sont le résultat d'un appel précédent enhancedClient.table() qui renvoie une référence à l'DynamoDbTableinstance.

Notez que la plupart des opérations v2 peuvent être appelées avec un modèle de consommation fluide même lorsqu'elles ne sont pas affichées. Par exemple,

Customer customer = table.getItem(r → r.key(key));
  or
Customer customer = table.getItem(r → r.key(k -> k.partitionValue("id").sortValue("email"))) 

Pour les opérations v1, le tableau contient certains des formulaires couramment utilisés, mais pas tous les formulaires surchargés. Par exemple, la load() méthode présente les surcharges suivantes :

mapper.load(Customer.class, hashKey)
mapper.load(Customer.class, hashKey, rangeKey)
mapper.load(Customer.class, hashKey, config)
mapper.load(Customer.class, hashKey, rangeKey, config)
mapper.load(item)
mapper.load(item, config)

Le tableau présente les formulaires les plus couramment utilisés :

mapper.load(item)
mapper.load(item, config)

Opérations de table

Cas d’utilisation	v1	Fonctionnement DynamoDB	v2
Écrire un code Java POJO dans une table DynamoDB	mapper.save(item) mapper.save(item, config) mapper.save(item, saveExpression, config) Dans la version 1, DynamoDBMapperConfig.SaveBehavior les annotations déterminent la méthode DynamoDB de bas niveau qui sera appelée. En général, UpdateItem est appelé sauf lors de l'utilisation de SaveBehavior.CLOBBER etSaveBehavior.PUT. Les clés générées automatiquement constituent un cas d'utilisation particulier, et parfois les deux PutItem UpdateItem sont utilisées.	PutItem, UpdateItem	table.putItem(putItemRequest) table.putItem(item) table.putItemWithResponse(item) //Returns metadata. updateItem(updateItemRequest) table.updateItem(item) table.updateItemWithResponse(item) //Returns metadata.
Lire un élément d'une table DynamoDB vers un Java POJO	mapper.load(item) mapper.load(item, config)	GetItem	table.getItem(getItemRequest) table.getItem(item) table.getItem(key) table.getItemWithResponse(key) //Returns POJO with metadata.
Supprimer un élément d'une table DynamoDB	mapper.delete(item, deleteExpression, config)	DeleteItem	table.deleteItem(deleteItemRequest) table.deleteItem(item) table.deleteItem(key)
Interrogez une table DynamoDB ou un index secondaire et renvoyez une liste paginée	mapper.query(Customer.class, queryExpression) mapper.query(Customer.class, queryExpression, mapperConfig)	Query	table.query(queryRequest) table.query(queryConditional) Utiliser le renvoi PageIterable.stream() (chargement différé) pour les réponses synchronisées et PagePublisher.subscribe() pour les réponses asynchrones
Interrogez une table DynamoDB ou un index secondaire et renvoyez une liste	mapper.queryPage(Customer.class, queryExpression) mapper.queryPage(Customer.class, queryExpression, mapperConfig)	Query	table.query(queryRequest) table.query(queryConditional) Utiliser le renvoi PageIterable.items() (chargement différé) pour les réponses synchronisées et PagePublisher.items.subscribe() pour les réponses asynchrones
Scanner une table DynamoDB ou un index secondaire et renvoyer une liste paginée	mapper.scan(Customer.class, scanExpression) mapper.scan(Customer.class, scanExpression, mapperConfig)	Scan	table.scan() table.scan(scanRequest) Utiliser le renvoi PageIterable.stream() (chargement différé) pour les réponses synchronisées et PagePublisher.subscribe() pour les réponses asynchrones
Scanner une table DynamoDB ou un index secondaire et renvoyer une liste	mapper.scanPage(Customer.class, scanExpression) mapper.scanPage(Customer.class, scanExpression, mapperConfig)	Scan	table.scan() table.scan(scanRequest) Utiliser le renvoi PageIterable.items() (chargement différé) pour les réponses synchronisées et PagePublisher.items.subscribe() pour les réponses asynchrones
Lire plusieurs éléments de plusieurs tables dans un lot	mapper.batchLoad(Arrays.asList(customer1, customer2, book1)) mapper.batchLoad(itemsToGet) // itemsToGet: Map<Class<?>, List<KeyPair>>	BatchGetItem	enhancedClient.batchGetItem(batchGetItemRequest) enhancedClient.batchGetItem(r -> r.readBatches( ReadBatch.builder(Record1.class) .mappedTableResource(mappedTable1) .addGetItem(i -> i.key(k -> k.partitionValue(0))) .build(), ReadBatch.builder(Record2.class) .mappedTableResource(mappedTable2) .addGetItem(i -> i.key(k -> k.partitionValue(0))) .build())) // Iterate over pages with lazy loading or over all items from the same table.
Écrire plusieurs éléments dans plusieurs tables par lot	mapper.batchSave(Arrays.asList(customer1, customer2, book1))	BatchWriteItem	enhancedClient.batchWriteItem(batchWriteItemRequest) enhancedClient.batchWriteItem(r -> r.writeBatches( WriteBatch.builder(Record1.class) .mappedTableResource(mappedTable1) .addPutItem(item1) .build(), WriteBatch.builder(Record2.class) .mappedTableResource(mappedTable2) .addPutItem(item2) .build()))
Supprimer plusieurs éléments de plusieurs tables par lot	mapper.batchDelete(Arrays.asList(customer1, customer2, book1))	BatchWriteItem	enhancedClient.batchWriteItem(r -> r.writeBatches( WriteBatch.builder(Record1.class) .mappedTableResource(mappedTable1) .addDeleteItem(item1key) .build(), WriteBatch.builder(Record2.class) .mappedTableResource(mappedTable2) .addDeleteItem(item2key) .build()))
Écrivez/supprimez plusieurs éléments dans un lot	mapper.batchWrite(Arrays.asList(customer1, book1), Arrays.asList(customer2))	BatchWriteItem	enhancedClient.batchWriteItem(r -> r.writeBatches( WriteBatch.builder(Record1.class) .mappedTableResource(mappedTable1) .addPutItem(item1) .build(), WriteBatch.builder(Record2.class) .mappedTableResource(mappedTable2) .addDeleteItem(item2key) .build()))
Réaliser une écriture transactionnelle	mapper.transactionWrite(transactionWriteRequest)	TransactWriteItems	enhancedClient.transactWriteItems(transasctWriteItemsRequest)
Réaliser une lecture transactionnelle	mapper.transactionLoad(transactionLoadRequest)	TransactGetItems	enhancedClient.transactGetItems(transactGetItemsRequest)
Obtenir le nombre d'éléments correspondants d'un scan ou d'une requête	mapper.count(Customer.class, queryExpression) mapper.count(Customer.class, scanExpression)	Query, Scan avec Select.COUNT	Non pris en charge
Créez une table dans DynamoDB correspondant à la classe POJO	mapper.generateCreateTableRequest(Customer.class) L'instruction précédente génère une demande de création de table de bas niveau ; les utilisateurs doivent appeler createTable le client DynamoDB.	CreateTable	table.createTable(createTableRequest) table.createTable(r -> r.provisionedThroughput(getDefaultProvisionedThroughput()) .globalSecondaryIndices( EnhancedGlobalSecondaryIndex.builder() .indexName("gsi_1") .projection(p -> p.projectionType(ProjectionType.ALL)) .provisionedThroughput(getDefaultProvisionedThroughput()) .build()));
Effectuer un scan parallèle dans DynamoDB	mapper.parallelScan(Customer.class, scanExpression, numTotalSegments)	Scanavec Segment et TotalSegments paramètres	Les utilisateurs sont tenus de gérer les threads de travail et d'appeler scan pour chaque segment : table.scan(r -> r.segment(0).totalSegments(5))
Intégrez Amazon S3 à DynamoDB pour stocker des liens S3 intelligents	mapper.createS3Link(bucket, key) mapper.getS3ClientCache()	-	Non pris en charge car il associe Amazon S3 et DynamoDB.

Classes et propriétés de cartes

Dans les versions 1 et 2, vous mappez des classes à des tables à l'aide d'annotations de style haricot. La V2 propose également d'autres moyens de définir des schémas pour des cas d'utilisation spécifiques, tels que l'utilisation de classes immuables.

Annotations sur les haricots

Le tableau suivant montre les annotations de bean équivalentes pour un cas d'utilisation spécifique qui sont utilisées dans les versions 1 et 2. Un scénario Customer de classe est utilisé pour illustrer les paramètres.

Les annotations, ainsi que les classes et les énumérations, de la version 2 suivent la convention Camel Case et utilisent « », et non « DynamoDB ». DynamoDb

Cas d’utilisation	v1	v2
Associer une classe à une table	@DynamoDBTable (tableName ="CustomerTable")	@DynamoDbBean @DynamoDbBean(converterProviders = {...}) Le nom de la table est défini lors de l'appel de la DynamoDbEDnhancedClient#table() méthode.
Désigner un membre de classe comme attribut de table	@DynamoDBAttribute(attributeName = "customerName")	@DynamoDbAttribute("customerName")
Désigner un membre de classe comme clé de hachage ou de partition	@DynamoDBHashKey	@DynamoDbPartitionKey
Désigner un membre de classe à l'aide d'une clé de rangement/de tri	@DynamoDBHashKey	@DynamoDbSortKey
Désigner un membre de classe comme clé de hachage ou de partition d'index secondaire	@DynamoDBIndexHashKey	@DynamoDbSecondaryPartitionKey
Désigner un membre de classe comme plage d'index secondaire/clé de tri	@DynamoDBIndexRangeKey	@DynamoDbSecondarySortKey
Ignorer ce membre de classe lors du mappage vers une table	@DynamoDBIgnore	@DynamoDbIgnore
Désigner un membre de classe comme attribut UUID clé généré automatiquement	@DynamoDBAutoGeneratedKey	@DynamoDbAutoGeneratedUuid L'extension qui fournit cela n'est pas chargée par défaut ; vous devez ajouter l'extension au générateur de clients.
Désigner un membre de classe comme attribut d'horodatage généré automatiquement	@DynamoDBAutoGeneratedTimestamp	@DynamoDbAutoGeneratedTimestampAttribute L'extension qui fournit cela n'est pas chargée par défaut ; vous devez ajouter l'extension au générateur de clients.
Désigner un membre de classe comme attribut de version auto-incrémenté	@DynamoDBVersionAttribute	@DynamoDbVersionAttribute L'extension qui fournit cela est chargée automatiquement.
Désigner un membre de la classe comme nécessitant une conversion personnalisée	@DynamoDBTypeConverted	@DynamoDbConvertedBy
Désignez un membre de classe à stocker sous un autre type d'attribut	@DynamoDBTyped(<DynamoDBAttributeType>)	Pas d'équivalent
Désignez une classe qui peut être sérialisée dans un document DynamoDB JSON (document de style) ou un sous-document DynamoDB	@DynamoDBDocument	Aucune annotation équivalente directe. Utilisez le document amélioréAPI.

Annotations supplémentaires V2

Cas d’utilisation	v1	v2
Désignez un membre de classe à ne pas stocker en tant qu'NULLattribut si la valeur Java est nulle	N/A	@DynamoDbIgnoreNulls
Désignez un membre de classe comme un objet vide si tous les attributs sont nuls	N/A	@DynamoDbPreserveEmptyObject
Désigner une action de mise à jour spéciale pour un membre du groupe	N/A	@DynamoDbUpdateBehavior
Désigner une classe immuable	N/A	@DynamoDbImmutable
Désigner un membre de classe comme attribut de compteur auto-incrémenté	N/A	@DynamoDbAtomicCounter L'extension qui fournit cette fonctionnalité est chargée automatiquement.

Configuration

Dans la version 1, vous contrôlez généralement des comportements spécifiques en utilisant une instance deDynamoDBMapperConfig. Vous pouvez fournir l'objet de configuration lorsque vous créez le mappeur ou lorsque vous faites une demande. Dans la version 2, la configuration est spécifique à l'objet de demande pour l'opération.

Cas d’utilisation	v1	Par défaut dans la version 1	v2
	DynamoDBMapperConfig.builder()
Stratégie de nouvelle tentative de chargement par lots	.withBatchLoadRetryStrategy(batchLoadRetryStrategy)	réessayer les articles ayant échoué
Stratégie de nouvelles tentatives d'écriture par lots	.withBatchWriteRetryStrategy(batchWriteRetryStrategy)	réessayer les articles ayant échoué
Lectures cohérentes	.withConsistentReads(CONSISTENT)	EVENTUAL	Par défaut, les lectures cohérentes ont la valeur false pour les opérations de lecture. Remplacez par .consistentRead(true) sur l'objet de la requête.
Schéma de conversion avec des ensembles de marshallers/unmarshallers	.withConversionSchema(conversionSchema) Les implémentations statiques offrent une rétrocompatibilité avec les anciennes versions.	V2_COMPATIBLE	Non applicable. Il s'agit d'une fonctionnalité héritée qui fait référence à la façon dont les premières versions de DynamoDB (v1) stockaient les types de données. Ce comportement ne sera pas conservé dans le client amélioré. Un exemple de comportement dans DynamoDB v1 consiste à stocker les booléens sous forme de nombre plutôt que sous forme de booléen.
Noms des tables	.withObjectTableNameResolver() .withTableNameOverride() .withTableNameResolver() Les implémentations statiques offrent une rétrocompatibilité avec les anciennes versions	utiliser une annotation ou deviner à partir de la classe	Le nom de la table est défini lors de l'appel de la DynamoDbEDnhancedClient#table() méthode.
Stratégie de chargement de pagination	.withPaginationLoadingStrategy(strategy) Les options sont les suivantes : LAZY _ LOADINGEAGER_LOADING, ou ITERATION_ONLY	LAZY_LOADING	L'itération uniquement est la valeur par défaut. Les autres options v1 ne sont pas prises en charge.
Demander la collecte de métriques	.withRequestMetricCollector(collector)	null	metricPublisher()À utiliser ClientOverrideConfiguration lors de la création du client DynamoDB standard.
Enregistrer le comportement	.withSaveBehavior(SaveBehavior.CLOBBER) Les options sont UPDATECLOBBER,PUT,APPEND_SET, ouUPDATE_SKIP_NULL_ATTRIBUTES.	UPDATE	Dans la v2, vous appelez putItem() ou updateItem() explicitement. CLOBBER or PUT: L'action correspondante dans la version 2 est l'appelputItem(). Il n'existe aucune CLOBBER configuration spécifique. UPDATE: Correspond à updateItem() UPDATE_SKIP_NULL_ATTRIBUTES: Correspond àupdateItem(). Contrôlez le comportement des mises à jour à l'aide du paramètre de demande ignoreNulls et de l'DynamoDbUpdateBehaviorannotation/de la balise. APPEND_SET: Non pris en charge
Type : usine de convertisseurs	.withTypeConverterFactory(typeConverterFactory)	convertisseurs de type standard	Fixez le haricot en utilisant @DynamoDbBean(converterProviders = {ConverterProvider.class, DefaultAttributeConverterProvider.class})

Configuration par opération

Dans la version 1, certaines opérations, telles quequery(), sont hautement configurables via un objet « expression » soumis à l'opération. Par exemple :

DynamoDBQueryExpression<Customer> emailBwQueryExpr = new DynamoDBQueryExpression<Customer>()
    .withRangeKeyCondition("Email",
        new Condition()
            .withComparisonOperator(ComparisonOperator.BEGINS_WITH)
            .withAttributeValueList(
                new AttributeValue().withS("my")));

mapper.query(Customer.class, emailBwQueryExpr);

Dans la version 2, au lieu d'utiliser un objet de configuration, vous définissez les paramètres de l'objet de demande à l'aide d'un générateur. Par exemple :

QueryEnhancedRequest emailBw = QueryEnhancedRequest.builder()
    .queryConditional(QueryConditional
        .sortBeginsWith(kb -> kb
            .sortValue("my"))).build();

customerTable.query(emailBw);

Conditionnels

Dans la version 2, les expressions conditionnelles et filtrantes sont exprimées à l'aide d'un Expression objet qui encapsule la condition et le mappage des noms et des filtres.

Cas d’utilisation	Opérations	v1	v2
Conditions d'attribut attendues	enregistrer (), supprimer (), interroger (), scanner ()	new DynamoDBSaveExpression() .withExpected(Collections.singletonMap( "otherAttribute", new ExpectedAttributeValue(false))) .withConditionalOperator(ConditionalOperator.AND);	Obsolète ; à utiliser ConditionExpression à la place.
Expression de condition	supprimer ()	deleteExpression.setConditionExpression("zipcode = :zipcode") deleteExpression.setExpressionAttributeValues(...)	Expression conditionExpression = Expression.builder() .expression("#key = :value OR #key1 = :value1") .putExpressionName("#key", "attribute") .putExpressionName("#key1", "attribute3") .putExpressionValue(":value", AttributeValues.stringValue("wrong")) .putExpressionValue(":value1", AttributeValues.stringValue("three")) .build(); DeleteItemEnhancedRequest request = DeleteItemEnhancedRequest.builder() .conditionExpression(conditionExpression).build();
Expression de filtrage	requête (), scan ()	scanExpression .withFilterExpression("#statename = :state") .withExpressionAttributeValues(attributeValueMapBuilder.build()) .withExpressionAttributeNames(attributeNameMapBuilder.build())	Map<String, AttributeValue> values = singletonMap(":key", stringValue("value")); Expression filterExpression = Expression.builder() .expression("name = :key") .expressionValues(values) .build(); QueryEnhancedRequest request = QueryEnhancedRequest.builder() .filterExpression(filterExpression).build();
Expression de condition pour la requête	requête ()	queryExpression.withKeyConditionExpression()	QueryConditional keyEqual = QueryConditional.keyEqualTo(b -> b .partitionValue("movie01")); QueryEnhancedRequest tableQuery = QueryEnhancedRequest.builder() .queryConditional(keyEqual) .build();

Conversion de type

Convertisseurs par défaut

Dans la version 2, il SDK fournit un ensemble de convertisseurs par défaut pour tous les types courants. Vous pouvez modifier les convertisseurs de type à la fois au niveau global du fournisseur et pour un seul attribut. Vous trouverez une liste des convertisseurs disponibles dans la AttributeConverterAPIréférence.

Définir un convertisseur personnalisé pour un attribut

Dans la version 1, vous pouvez annoter une méthode getter @DynamoDBTypeConverted pour spécifier la classe qui effectue la conversion entre le type d'attribut Java et le type d'attribut DynamoDB. Par exemple, une CurrencyFormatConverter conversion entre un Currency type Java et une chaîne DynamoDB peut être appliquée comme indiqué dans l'extrait suivant.

@DynamoDBTypeConverted(converter = CurrencyFormatConverter.class)
public Currency getCurrency() { return currency; }

L'équivalent v2 de l'extrait précédent est illustré ci-dessous.

@DynamoDbConvertedBy(CurrencyFormatConverter.class)
public Currency getCurrency() { return currency; }

Note

Dans la version 1, vous pouvez appliquer l'annotation à l'attribut lui-même, à un type ou à une annotation définie par l'utilisateur, tandis que la version v2 prend en charge l'application de l'annotation uniquement au getter.

Ajouter un convertisseur de type, une usine ou un fournisseur

Dans la version 1, vous pouvez fournir votre propre ensemble de convertisseurs de type ou remplacer les types qui vous intéressent en ajoutant une usine de convertisseurs de type à la configuration. La fabrique de convertisseurs de types s'étendDynamoDBTypeConverterFactory, et les remplacements sont effectués en obtenant une référence à l'ensemble par défaut et en l'étendant. L'extrait suivant montre comment procéder.

DynamoDBTypeConverterFactory typeConverterFactory =
    DynamoDBTypeConverterFactory.standard().override()
        .with(String.class, CustomBoolean.class, new DynamoDBTypeConverter<String, CustomBoolean>() {
            @Override
            public String convert(CustomBoolean bool) {
                return String.valueOf(bool.getValue());
            }
            @Override
            public CustomBoolean unconvert(String string) {
                return new CustomBoolean(Boolean.valueOf(string));
            }}).build();
DynamoDBMapperConfig config =
    DynamoDBMapperConfig.builder()
        .withTypeConverterFactory(typeConverterFactory)
        .build();
DynamoDBMapper mapperWithTypeConverterFactory = new DynamoDBMapper(dynamo, config);

La V2 fournit des fonctionnalités similaires par le biais de l'@DynamoDbBeanannotation. Vous pouvez fournir une commande unique AttributeConverterProvider ou une chaîne de AttributeConverterProvider commandes. Notez que si vous fournissez votre propre chaîne de fournisseurs de convertisseurs d'attributs, vous remplacerez le fournisseur de conversion par défaut et devrez l'inclure dans la chaîne pour utiliser ses convertisseurs d'attributs.

@DynamoDbBean(converterProviders = {
   ConverterProvider1.class, 
   ConverterProvider2.class,
   DefaultAttributeConverterProvider.class})
public class Customer {
  ...
}

La section de ce guide consacrée à la conversion d'attributs contient un exemple complet pour la version 2.

Historique des documents API

Le document API permet de travailler avec des documents de JSON style en tant qu'éléments uniques dans un tableau DynamoDB. Le document v1 API a un correspondant API dans la version v2, mais au lieu d'utiliser un client distinct pour le document API comme dans la version v1, la version v2 intègre les API fonctionnalités du document dans le client amélioré DynamoDB.

Dans la version 1, la Itemclasse représente un enregistrement non structuré d'une table DynamoDB. Dans la version 2, un enregistrement non structuré est représenté par une instance de la EnhancedDocumentclasse. Notez que les clés primaires sont définies dans le schéma de table pour la version 2 et sur l'élément lui-même dans la version 1.

Le tableau ci-dessous compare les différences entre le document APIs en version v1 et en version v2.

Cas d’utilisation	v1	v2
Création d'un client de documents	AmazonDynamoDB client = ... //Create a client. DynamoDB documentClient = new DynamoDB(client);	// The v2 Document API uses the same DynamoDbEnhancedClient // that is used for mapping POJOs. DynamoDbClient standardClient = ... //Create a standard client. DynamoDbEnhancedClient enhancedClient = ... // Create an enhanced client.
Référencer un tableau	Table documentTable = docClient.documentClient("Person");	DynamoDbTable<EnhancedDocument> documentTable = enhancedClient.table("Person", TableSchema.documentSchemaBuilder() .addIndexPartitionKey(TableMetadata.primaryIndexName(),"id", AttributeValueType.S) .attributeConverterProviders(AttributeConverterProvider.defaultProvider()) .build());
Work with semi-structured data
Mettre un élément	Item item = new Item() .withPrimaryKey("id", 50) .withString("firstName", "Shirley"); PutItemOutcome outcome = documentTable.putItem(item);	EnhancedDocument personDocument = EnhancedDocument.builder() .putNumber("id", 50) .putString("firstName", "Shirley") .build(); documentTable.putItem(personDocument);
Obtenir un élément	GetItemOutcome outcome = documentTable.getItemOutcome( "id", 50); Item personDocFromDb = outcome.getItem(); String firstName = personDocFromDb.getString("firstName");	EnhancedDocument personDocFromDb = documentTable .getItem(Key.builder() .partitionValue(50) .build()); String firstName = personDocFromDb.getString("firstName");
Work with JSON items
Convertir une JSON structure pour l'utiliser avec le document API	// The 'jsonPerson' identifier is a JSON string. Item item = new Item().fromJSON(jsonPerson);	// The 'jsonPerson' identifier is a JSON string. EnhancedDocument document = EnhancedDocument.builder() .json(jsonPerson).build());
Mettre JSON	documentTable.putItem(item)	documentTable.putItem(document);
Lisez JSON	GetItemOutcome outcome = //Get item. String jsonPerson = outcome.getItem().toJSON();	String jsonPerson = documentTable.getItem(Key.builder() .partitionValue(50).build()) .fromJson();

APIréférence et guides pour le document APIs

	v1	v2
Référence API	Javadoc	Javadoc
Guide de documentation	Guide du développeur Amazon DynamoDB	Document amélioré API (ce guide)

FAQ

Q. Le verrouillage optimiste avec un numéro de version fonctionne-t-il de la même manière en v2 qu'en v1 ?

R. Le comportement est similaire, mais la version 2 n'ajoute pas automatiquement des conditions pour les opérations de suppression. Vous devez ajouter des expressions de condition manuellement si vous souhaitez contrôler le comportement de suppression.