serialización de datos

Tipos admitidos

El controlador de sincronización de Kotlin es compatible con los siguientes tipos:

• Todos los tipos de Kotlin que son compatibles con la librería kotlinx.serialization

• Todo BSON types

query Clases Anotadas

Puede consultar clases de datos anotadas mediante la clase Filtros del mongodb-driver-kotlin-extensions paquete. Esta clase permite crear filtros de consulta para nombres de campo anotados con la @SerialName anotación.

El siguiente ejemplo consulta la colección orders para los documentos que tienen un valor de campo brand de "Sherwin-Williams":

val queryFilter = eq(PaintOrder::manufacturer, "Sherwin-Williams")
val results = collection.find(queryFilter).toList()

El código anterior crea un filtro de query que hace referencia a la propiedad PaintOrder::manufacturer pero consulta el campo BSON brand. El controlador convierte automáticamente el nombre de la propiedad de la clase de datos en el nombre del campo especificado en la anotación @SerialName.

Ejemplo de serializador personalizado

Puede crear un serializador personalizado para gestionar cómo se representa su información en BSON. El controlador Kotlin Sync utiliza la interfaz KSerializer de la librería kotlinx.serialization para implementar serializadores personalizados. Puede especificar el serializador personalizado como parámetro de la anotación @Serializable para un campo específico.

El siguiente ejemplo muestra cómo crear una instancia personalizada de KSerializer para convertir un kotlin.time.Instant en un BsonDateTime:

object InstantAsBsonDateTime : KSerializer<Instant> {
    override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("InstantAsBsonDateTime", PrimitiveKind.LONG)
    override fun serialize(encoder: Encoder, value: Instant) {
        when (encoder) {
            is BsonEncoder -> encoder.encodeBsonValue(BsonDateTime(value.toEpochMilli()))
            else -> throw SerializationException("Instant is not supported by ${encoder::class}")
        }
    }
    override fun deserialize(decoder: Decoder): Instant {
        return when (decoder) {
            is BsonDecoder -> Instant.ofEpochMilli(decoder.decodeBsonValue().asDateTime().value)
            else -> throw SerializationException("Instant is not supported by ${decoder::class}")
        }
    }
}

El siguiente código muestra la clase de datos PaintOrder en la que el campo orderDate tiene una anotación que especifica la clase de serialización personalizada definida en el código anterior:

@Serializable
data class PaintOrder(
    val color: String,
    val qty: Int,
    @Serializable(with = InstantAsBsonDateTime::class)
    val orderDate: Instant,
)

Para obtener más información sobre los métodos y clases mencionados en esta sección, consulta la siguiente documentación de la API:

• KSerializer en la documentación de Kotlin

• Instantánea en la documentación de Kotlin

• BsonEncoder

• BsonDecoder

Ejemplo de Codec Personalizado

El siguiente ejemplo muestra cómo crear un códec utilizando el KotlinSerializerCodec.create() método y luego configurarlo para no codificar valores predeterminados:

val myCustomCodec = KotlinSerializerCodec.create<PaintOrder>(
    bsonConfiguration = BsonConfiguration(encodeDefaults = false)
)
val registry = CodecRegistries.fromRegistries(
    CodecRegistries.fromCodecs(myCustomCodec), collection.codecRegistry
)

Implementar una estrategia de denominación en snake case

Al usar el paquete bson-kotlinx v5.4 o posteriormente, puede indicar al controlador que serialice los nombres de los campos de la clase de datos escritos en camel case a snake case en MongoDB. El siguiente ejemplo muestra cómo crear y registrar un códec personalizado para convertir los nombres de los campos de la clase de datos a snake case al establecer el parámetro bsonNamingStrategy en un códec:

val myCustomCodec = KotlinSerializerCodec.create<PaintOrder>(
    bsonConfiguration = BsonConfiguration(bsonNamingStrategy = BsonNamingStrategy.SNAKE_CASE)
)
val registry = CodecRegistries.fromRegistries(
    CodecRegistries.fromCodecs(myCustomCodec), collection.codecRegistry
)

Para obtener más información sobre los métodos y clases mencionados en esta sección, consulta la siguiente documentación de la API:

• KotlinSerializerCodec

• KotlinSerializerCodec.create()

• Configuración de Bson

• BsonNamingStrategy

Ejemplo de Clases de Datos Polimórficos

El siguiente ejemplo crea una interfaz y dos clases de datos que heredan dicha interfaz. En las clases de datos, el id campo se marca con las anotaciones descritas en la sección "Anotar clases de datos":

@Serializable
sealed interface Person {
    val name: String
}
@Serializable
data class Student(
    @Contextual
    @SerialName("_id")
    val id: ObjectId,
    override val name: String,
    val grade: Int,
) : Person
@Serializable
data class Teacher(
    @Contextual
    @SerialName("_id")
    val id: ObjectId,
    override val name: String,
    val department: String,
) : Person

A continuación, puede realizar operaciones con las clases de datos de la forma habitual. El siguiente ejemplo parametriza la colección con la interfaz Person y, a continuación, realiza operaciones con las clases polimórficas Teacher y Student. Al recuperar documentos, el controlador detecta automáticamente el tipo según el valor del discriminador y los deserializa en consecuencia.

val collection = database.getCollection<Person>("school")
val teacherDoc = Teacher(ObjectId(), "Vivian Lee", "History")
val studentDoc = Student(ObjectId(), "Kate Parker", 10)
collection.insertOne(teacherDoc)
collection.insertOne(studentDoc)
println("Retrieving by using data classes")
val resultTeacher = collection.withDocumentClass<Teacher>()
    .find(Filters.exists("department"))
    .firstOrNull()
println(resultTeacher)
val resultStudent = collection.withDocumentClass<Student>()
    .find(Filters.exists("grade"))
    .firstOrNull()
println(resultStudent)
println("\nRetrieving by using Person interface")
val resultsPerson = collection.withDocumentClass<Person>().find()
resultsPerson.forEach { result ->
    println(result)
}
println("\nRetrieving as Document type")
val resultsDocument = collection.withDocumentClass<Document>().find()
resultsDocument.forEach { result ->
    println(result)
}

Retrieving by using data classes
Teacher(id=..., name=Vivian Lee, department=History)
Student(id=..., name=Kate Parker, grade=10)
Retrieving by using Person interface
Teacher(id=..., name=Vivian Lee, department=History)
Student(id=..., name=Kate Parker, grade=10)
Retrieving as Document type
Document{{_id=..., _t=Teacher, name=Vivian Lee, department=History}}
Document{{_id=..., _t=Student, name=Kate Parker, grade=10}}

Biblioteca kotlinx-datetime

kotlinx-datetime es una librería de Kotlin que ofrece un alto nivel de control sobre cómo se serializan los valores de fecha y hora. Para usar la librería, agrega la dependencia kotlinx-datetime a la lista de dependencias de tu proyecto.

Seleccione de las siguientes pestañas para ver cómo agregar la dependencia kotlinx-datetime a su Proyecto utilizando los administradores de paquetes Gradle y Maven:

implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-datetime-jvm</artifactId>
    <version>0.6.1</version>
</dependency>

Para obtener más información sobre esta librería, consulta el Repositorio kotlinx-datetime en GitHub.

Ejemplo de clase de datos con fechas y horas

Después de agregar la dependencia de la librería, puede implementar los serializadores de la librería kotlinx-datetime que asignan los valores de los campos de la clase de datos a los tipos esperados en BSON.

En este ejemplo, el driver serializa los campos de la clase de datos Appointment con el siguiente comportamiento:

• name: El driver serializa el valor como una string.

• date: El controlador utiliza el serializador kotlinx-datetime porque el campo tiene la anotación @Contextual. LocalDate valores se serializan como fechas BSON.

• time: El driver serializa el valor como una string porque no tiene la anotación @Contextual. Este es el comportamiento de serialización por defecto para los valores LocalTime.

@Serializable
data class Appointment(
    val name: String,
    @Contextual val date: LocalDate,
    val time: LocalTime,
)

El siguiente ejemplo inserta una instancia de la clase de datos Appointment en la colección appointments:

val collection = database.getCollection<Appointment>("appointments")
val apptDoc = Appointment(
    "Daria Smith",
    LocalDate(2024, 10, 15),
    LocalTime(hour = 11, minute = 30)
)
collection.insertOne(apptDoc)

En MongoDB, el valor LocalDate se almacena como una fecha BSON y el campo time se almacena como una cadena mediante la serialización predeterminada:

{
  "_id": ...,
  "name": "Daria Smith",
  "date": {
    "$date": "2024-10-15T00:00:00.000Z"
  },
  "time": "11:30",
}