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

Puedes query las clases de datos anotados utilizando la clase Filters del paquete mongodb-driver-kotlin-extensions. Esta clase te permite crear filtros de query en nombres de campo con la anotación @SerialName.

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 cómo se representa tus datos en BSON. El driver de Kotlin utiliza la interfaz KSerializer del paquete kotlinx.serialization para implementar serializadores personalizados. Puede especificar el serializador personalizado como parámetro para la anotación @Serializable de 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, consulta la siguiente documentación de la API:

• KSerializer

• 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 que no codifique los valores por defecto:

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, consulta la siguiente documentación de la API:

• KotlinSerializerCodec

• KotlinSerializerCodec.create()

• BsonConfiguration

• BsonNamingStrategy

Ejemplo de Clases de Datos Polimórficos

El siguiente ejemplo crea una interfaz y dos clases de datos que heredan de esa interfaz. En las clases de datos, el campo id está marcado 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

Luego, puedes realizar operaciones con clases de datos como de costumbre. El siguiente ejemplo parametriza la colección con la interfaz Person, luego realiza operaciones con las clases polimorfas Teacher y Student. Cuando se recuperan documentos, el controlador detecta automáticamente el tipo en función del valor 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}}

librería 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 por serialización predeterminada:

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