Serialización de Kotlin

Tipos admitidos

El controlador de Kotlin admite:

• Todos los tipos de Kotlin que son compatibles con la biblioteca de serialización de Kotlin

• Todas las BSON typesdisponibles

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)

Ejemplo de serializador personalizado

Puedes crear un serializador personalizado para gestionar la representación de tus datos en BSON. El controlador Kotlin utiliza la interfaz KSerializer del paquete kotlinx.serialization para implementar serializadores personalizados. Puedes 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.toEpochMilliseconds()))
            else -> throw SerializationException("Instant is not supported by ${encoder::class}")
        }
    }
    override fun deserialize(decoder: Decoder): Instant {
        return when (decoder) {
            is BsonDecoder -> Instant.fromEpochMilliseconds(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, consulte la siguiente documentación de API:

• KSerializador

• Instantáneo

• BsonEncoder

• BsonDecoder

Ejemplo de Codec Personalizado

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

import org.bson.codecs.configuration.CodecRegistries
import org.bson.codecs.kotlinx.BsonConfiguration
import org.bson.codecs.kotlinx.KotlinSerializerCodec

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 después, puedes dirigir al controlador para que serialice los nombres de los campos de 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:

import org.bson.codecs.kotlinx.BsonConfiguration
import org.bson.codecs.kotlinx.BsonNamingStrategy

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, consulte la siguiente documentación de 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")
collection.withDocumentClass<Teacher>()
    .find(Filters.exists("department"))
    .first().also { println(it) }
collection.withDocumentClass<Student>()
    .find(Filters.exists("grade"))
    .first().also { println(it) }
println("\nRetrieving by using Person interface")
val resultsFlow = collection.withDocumentClass<Person>().find()
resultsFlow.collect { println(it) }
println("\nRetrieving as Document type")
val resultsDocFlow = collection.withDocumentClass<Document>().find()
resultsDocFlow.collect { println(it) }

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",
}