Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

# Generar un esquema a partir de anotaciones
<a name="ddb-mapper-anno-schema-gen"></a>

****  
**DynamoDB Mapper es una versión preliminar para desarrolladores. No incluye todas las funciones y está sujeta a cambios.**

DynamoDB Mapper se basa en esquemas que definen el mapeo entre las clases de Kotlin y los elementos de DynamoDB. Las clases de Kotlin pueden impulsar la creación de esquemas mediante el complemento generador de esquemas de Gradle. 

## Aplica el complemento
<a name="ddb-mapper-anno-schema-gen-plugin"></a>

Para empezar a generar código para tus clases, aplica el complemento en el script de compilación de la aplicación y añade una dependencia en el módulo de anotaciones. El siguiente fragmento de script de Gradle muestra la configuración necesaria para la generación de código. 

(Puedes navegar hasta el *X.Y.Z* enlace para ver la última versión 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")
}
```

## Configuración del complemento
<a name="ddb-mapper-anno-schema-gen-conf-plugin"></a>

El complemento ofrece una serie de opciones de configuración que puedes aplicar mediante la extensión del `dynamoDbMapper { ... }` complemento en tu script de compilación: 


| Opción | Descripción de la opción | Valores | 
| --- | --- | --- | 
| generateBuilderClasses |  Controla si se generarán clases de creación de estilo DSL para las clases anotadas con `@DynamoDbItem`  |  `WHEN_REQUIRED`(predeterminado): las clases de construcción no se generarán para las clases que consten únicamente de miembros mutables públicos y que tengan un constructor sin argumentos `ALWAYS`: Las clases de Builder siempre se generarán  | 
| visibility | Controla la visibilidad de las clases generadas |  `PUBLIC` (predeterminado) `INTERNAL`  | 
| destinationPackage | Especifica el nombre del paquete de las clases generadas |  `RELATIVE`(predeterminado): las clases de esquema se generarán en un subpaquete relativo a la clase anotada. De forma predeterminada, el subpaquete recibe un nombre`dynamodbmapper.generatedschemas`, que se puede configurar pasando un parámetro de cadena `ABSOLUTE`: Las clases de esquema se generarán en un paquete absoluto relativo a la raíz de la aplicación. De forma predeterminada, el paquete recibe un nombre`aws.sdk.kotlin.hll.dynamodbmapper.generatedschemas`, que se puede configurar pasando un parámetro de cadena.  | 
| generateGetTableExtension |  Controla si se generará un método de `DynamoDbMapper.get${CLASS_NAME}Table` extensión  |  `true` (predeterminado) `false`  | 

**Example Ejemplo de configuración de un complemento de generación de código**  
El siguiente ejemplo configura el paquete de destino y la visibilidad del esquema generado:  

```
// 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
}
```

## Anota las clases
<a name="ddb-mapper-anno-schema-gen-annotate"></a>

El generador de esquemas busca anotaciones de clases para determinar para qué clases generar esquemas. Para optar por la generación de esquemas, anota tus clases con ellas. `@[DynamoDbItem](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/index.html)` También debes anotar con la anotación una propiedad de clase que sirva como clave de partición del elemento. `@[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)`

La siguiente definición de clase muestra las anotaciones mínimas necesarias para la generación del esquema:

**Example**  

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

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

Las siguientes anotaciones se aplican a las clases para controlar la generación del esquema:
+ `@DynamoDbItem`: Especifica que class/interface describe un tipo de elemento de una tabla. Todas las propiedades públicas de este tipo se asignarán a atributos a menos que se ignoren de forma explícita. Cuando esté presente, se generará un esquema para esta clase.
  + `converterName`: Un parámetro opcional que indica que se debe usar un esquema personalizado en lugar del creado por el complemento generador de esquemas. Este es el nombre completo de la `ItemConverter` clase personalizada. [Defina un conversor de artículos personalizado](#ddb-mapper-anno-schema-custom)En la sección se muestra un ejemplo de creación y uso de un esquema personalizado.

### Anotaciones de propiedades
<a name="ddb-mapper-anno-schema-gen-prop-annos"></a>

Puede aplicar las siguientes anotaciones a las propiedades de la clase para controlar la generación del esquema:
+ `@[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)`: Especifica la clave de partición del elemento.
+ `@[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)`: especifica una clave de clasificación opcional para el elemento.
+ `@[DynamoDbIgnore](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-ignore/index.html)`: especifica que DynamoDB Mapper no debe convertir esta propiedad de clase en to/from un atributo de elemento.
+ `@[DynamoDbAttribute](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-attribute/index.html)`: Especifica un nombre de atributo personalizado opcional para esta propiedad de clase.

## Defina un conversor de artículos personalizado
<a name="ddb-mapper-anno-schema-custom"></a>

En algunos casos, es posible que desees definir un conversor de artículos personalizado para tu clase. Una razón para ello sería si tu clase usa un tipo que no es compatible con el complemento generador de esquemas. Usamos la siguiente versión de la `Employee` clase como ejemplo:

```
import kotlin.uuid.Uuid

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

La `Employee` clase ahora usa un `kotlin.uuid.Uuid` tipo, que actualmente no es compatible con el generador de esquemas. La generación del esquema falla y se produce un error:`Unsupported attribute type TypeRef(pkg=kotlin.uuid, shortName=Uuid, genericArgs=[], nullable=false)`. Este error indica que el complemento no puede generar un convertidor de elementos para esta clase. Por lo tanto, necesitamos escribir el nuestro.

Para ello, implementamos una `[ItemConverter](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.items/-item-converter/index.html)` para la clase y, a continuación, modificamos la anotación de la `@DynamoDbItem` clase especificando el nombre completo del nuevo conversor de elementos.

En primer lugar, implementamos a `[ValueConverter](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.values/-value-converter/index.html)` para la `kotlin.uuid.Uuid` clase:

```
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())
}
```

Luego, implementamos una `ItemConverter` para nuestra `Employee` clase. `ItemConverter`Utiliza este nuevo conversor de valores en el descriptor de atributos de «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
        )
    ),
)
```

Ahora que hemos definido el conversor de artículos, podemos aplicarlo a nuestra clase. Actualizamos la `@[DynamoDbItem](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/index.html)` anotación para hacer referencia al conversor de artículos proporcionando el nombre completo de la clase, tal y como se muestra a continuación:

```
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
)
```

Por último, podemos empezar a usar la clase con DynamoDB Mapper.