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.

# Génération d'un schéma à partir d'annotations
<a name="ddb-mapper-anno-schema-gen"></a>

****  
**DynamoDB Mapper est une version préliminaire pour les développeurs. Les fonctionnalités ne sont pas complètes et sont susceptibles d'être modifiées.**

Le mappeur DynamoDB repose sur des schémas qui définissent le mappage entre vos classes Kotlin et les éléments DynamoDB. Vos classes Kotlin peuvent piloter la création de schémas en utilisant le plugin Gradle générateur de schémas. 

## Appliquer le plugin
<a name="ddb-mapper-anno-schema-gen-plugin"></a>

Pour commencer à générer des schémas de code pour vos classes, appliquez le plugin dans le script de compilation de votre application et ajoutez une dépendance au module d'annotations. L'extrait de script Gradle suivant montre la configuration nécessaire à la génération de code. 

(Vous pouvez accéder au *X.Y.Z* lien pour voir la dernière version disponible.)

```
// build.gradle.kts
val sdkVersion: String = [https://github.com/awslabs/aws-sdk-kotlin/releases/latest](https://github.com/awslabs/aws-sdk-kotlin/releases/latest) 

plugins {
    id("aws.sdk.kotlin.hll.dynamodbmapper.schema.generator") version "$sdkVersion-beta" // For the Developer Preview, use the beta version of the latest SDK.
}

dependencies {
    implementation("aws.sdk.kotlin:dynamodb-mapper:$sdkVersion-beta")
    implementation("aws.sdk.kotlin:dynamodb-mapper-annotations:$sdkVersion-beta")
}
```

## Configuration du plug-in
<a name="ddb-mapper-anno-schema-gen-conf-plugin"></a>

Le plugin propose un certain nombre d'options de configuration que vous pouvez appliquer en utilisant l'extension du `dynamoDbMapper { ... }` plugin dans votre script de compilation : 


| Option | Description de l'option | Valeurs | 
| --- | --- | --- | 
| generateBuilderClasses |  Contrôle si des classes de générateur de style DSL seront générées pour les classes annotées avec `@DynamoDbItem`  |  `WHEN_REQUIRED`(par défaut) : les classes Builder ne seront pas générées pour les classes composées uniquement de membres mutables publics et ayant un constructeur zéro-arg `ALWAYS`: les classes Builder seront toujours générées  | 
| visibility | Contrôle la visibilité des classes générées |  `PUBLIC` (par défaut) `INTERNAL`  | 
| destinationPackage | Spécifie le nom du package pour les classes générées |  `RELATIVE`(par défaut) : les classes de schéma seront générées dans un sous-package relatif à votre classe annotée. Par défaut, le sous-package est nommé`dynamodbmapper.generatedschemas`, et cela est configurable en passant un paramètre de chaîne `ABSOLUTE`: Les classes de schéma seront générées dans un package absolu relatif à la racine de votre application. Par défaut, le package est nommé`aws.sdk.kotlin.hll.dynamodbmapper.generatedschemas`, et cela est configurable en passant un paramètre de chaîne.  | 
| generateGetTableExtension |  Contrôle si une méthode d'`DynamoDbMapper.get${CLASS_NAME}Table`extension sera générée  |  `true` (par défaut) `false`  | 

**Example Exemple de configuration d'un plugin de génération de code**  
L'exemple suivant configure le package de destination et la visibilité du schéma généré :  

```
// build.gradle.kts

import aws.sdk.kotlin.hll.dynamodbmapper.codegen.annotations.DestinationPackage
import aws.sdk.kotlin.hll.dynamodbmapper.codegen.annotations.Visibility
import aws.smithy.kotlin.runtime.ExperimentalApi

@OptIn(ExperimentalApi::class)
dynamoDbMapper {
    destinationPackage = DestinationPackage.RELATIVE("my.configured.package")
    visibility = Visibility.INTERNAL
}
```

## Annoter les classes
<a name="ddb-mapper-anno-schema-gen-annotate"></a>

Le générateur de schéma recherche des annotations de classe afin de déterminer les classes pour lesquelles générer des schémas. Pour choisir de générer des schémas, annotez vos classes avec. `@[DynamoDbItem](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/index.html)` Vous devez également annoter une propriété de classe qui sert de clé de partition à l'élément avec l'`@[DynamoDbPartitionKey](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-partition-key/index.html)`annotation.

La définition de classe suivante indique les annotations minimales requises pour la génération du schéma :

**Example**  

```
@DynamoDbItem
data class Employee(
    @DynamoDbPartitionKey
    val id: Int,
    
    val name: String,
    val role: String,
)
```

### Annotations de classe
<a name="ddb-mapper-anno-schema-gen-class-annos"></a>

Les annotations suivantes sont appliquées aux classes pour contrôler la génération de schémas :
+ `@DynamoDbItem`: Spécifie que cela class/interface décrit un type d'élément dans une table. Toutes les propriétés publiques de ce type seront mappées à des attributs à moins qu'elles ne soient explicitement ignorées. Lorsqu'il est présent, un schéma sera généré pour cette classe.
  + `converterName`: paramètre facultatif qui indique qu'un schéma personnalisé doit être utilisé plutôt que celui créé par le plugin générateur de schémas. Il s'agit du nom complet de la `ItemConverter` classe personnalisée. La [Définition d'un convertisseur d'articles personnalisé](#ddb-mapper-anno-schema-custom) section présente un exemple de création et d'utilisation d'un schéma personnalisé.

### Annotations de propriétés
<a name="ddb-mapper-anno-schema-gen-prop-annos"></a>

Vous pouvez appliquer les annotations suivantes aux propriétés de classe pour contrôler la génération du schéma :
+ `@[https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/index.html](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/index.html)`: Spécifie la clé de partition de l'élément.
+ `@[DynamoDbSortKey](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-sort-key/index.html)`: Spécifie une clé de tri facultative pour l'élément.
+ `@[DynamoDbIgnore](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-ignore/index.html)`: Spécifie que cette propriété de classe ne doit pas être convertie en to/from attribut Item par le mappeur DynamoDB.
+ `@[DynamoDbAttribute](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-attribute/index.html)`: Spécifie un nom d'attribut personnalisé facultatif pour cette propriété de classe.

## Définition d'un convertisseur d'articles personnalisé
<a name="ddb-mapper-anno-schema-custom"></a>

Dans certains cas, vous souhaiterez peut-être définir un convertisseur d'éléments personnalisé pour votre classe. Cela s'explique notamment par le fait que votre classe utilise un type qui n'est pas pris en charge par le plugin du générateur de schéma. Nous utilisons la version suivante de la `Employee` classe comme exemple :

```
import kotlin.uuid.Uuid

@DynamoDbItem
data class Employee(
    @DynamoDbPartitionKey
    var id: Int,
    
    var name: String,
    var role: String,
    var workstationId: Uuid
)
```

La `Employee` classe utilise désormais un `kotlin.uuid.Uuid` type qui n'est actuellement pas pris en charge par le générateur de schéma. La génération du schéma échoue avec une erreur :`Unsupported attribute type TypeRef(pkg=kotlin.uuid, shortName=Uuid, genericArgs=[], nullable=false)`. Cette erreur indique que le plugin ne peut pas générer de convertisseur d'éléments pour cette classe. Par conséquent, nous devons écrire les nôtres.

Pour ce faire, nous implémentons un `[ItemConverter](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.items/-item-converter/index.html)` pour la classe, puis modifions l'annotation de `@DynamoDbItem` classe en spécifiant le nom complet du nouveau convertisseur d'éléments.

Tout d'abord, nous implémentons un `[ValueConverter](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.values/-value-converter/index.html)` pour la `kotlin.uuid.Uuid` classe :

```
import aws.sdk.kotlin.hll.dynamodbmapper.values.ValueConverter
import aws.sdk.kotlin.services.dynamodb.model.AttributeValue
import kotlin.uuid.Uuid

public val UuidValueConverter = object : ValueConverter<Uuid> {
    override fun convertFrom(to: AttributeValue): Uuid = 
        Uuid.parseHex(to.asS())
        
    override fun convertTo(from: Uuid): AttributeValue = 
        AttributeValue.S(from.toHexString())
}
```

Ensuite, nous implémentons un an `ItemConverter` pour notre `Employee` classe. Il `ItemConverter` utilise ce nouveau convertisseur de valeurs dans le descripteur d'attribut pour « WorkstationID » :

```
import aws.sdk.kotlin.hll.dynamodbmapper.items.AttributeDescriptor
import aws.sdk.kotlin.hll.dynamodbmapper.items.ItemConverter
import aws.sdk.kotlin.hll.dynamodbmapper.items.SimpleItemConverter
import aws.sdk.kotlin.hll.dynamodbmapper.values.scalars.IntConverter
import aws.sdk.kotlin.hll.dynamodbmapper.values.scalars.StringConverter

public object MyEmployeeConverter : ItemConverter<Employee> by SimpleItemConverter(
    builderFactory = { Employee() },
    build = { this },
    descriptors = arrayOf(
        AttributeDescriptor(
            "id",
            Employee::id,
            Employee::id::set,
            IntConverter,
        ),
        AttributeDescriptor(
            "name",
            Employee::name,
            Employee::name::set,
            StringConverter,
        ),
        AttributeDescriptor(
            "role",
            Employee::role,
            Employee::role::set,
            StringConverter
        ),
        AttributeDescriptor(
            "workstationId",
            Employee::workstationId,
            Employee::workstationId::set,
            UuidValueConverter
        )
    ),
)
```

Maintenant que nous avons défini le convertisseur d'articles, nous pouvons l'appliquer à notre classe. Nous mettons à jour l'`@[DynamoDbItem](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/index.html)`annotation pour faire référence au convertisseur d'articles en fournissant le nom de classe complet, comme indiqué ci-dessous :

```
import kotlin.uuid.Uuid

@DynamoDbItem("my.custom.item.converter.MyEmployeeConverter")
data class Employee(
    @DynamoDbPartitionKey
    var id: Int,
    
    var name: String,
    var role: String,
    var workstationId: Uuid
)
```

Enfin, nous pouvons commencer à utiliser la classe avec DynamoDB Mapper.