Serialización de datos

Tipos admitidos

El controlador Kotlin Sync admite los siguientes tipos:

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

• Todo BSON types

Clases anotadas de consulta

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 en busca de documentos que tengan 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 consulta 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 al nombre del campo especificado en la anotación @SerialName.

Ejemplo de serializador personalizado

Puedes crear un serializador personalizado para gestionar la representación de tus datos en BSON. El controlador de sincronización de Kotlin utiliza la interfaz KSerializer de la biblioteca 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 KSerializer personalizada 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 serializador personalizado 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:

• KSerializer en la documentación de Kotlin

• Instantáneo en la documentación de Kotlin

• BsonEncoder

• BsonDecoder

Ejemplo de códec 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 la estrategia de nombres de casos de serpiente

Al usar el paquete bson-kotlinx v5.4 o posterior, puede indicar al controlador que serialice los nombres de los campos de clase de datos escritos en CamelCase a SnakeCase en MongoDB. El siguiente ejemplo muestra cómo crear y registrar un códec personalizado para convertir los nombres de los campos de clase de datos a SnakeCase mediante 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, consulte la siguiente documentación de API:

• Códec serializador de Kotlin

• KotlinSerializerCodec.create()

• Configuración de Bson

• Estrategia de nombres de Bson

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 biblioteca de Kotlin que ofrece un alto nivel de control sobre la serialización de los valores de fecha y hora. Para usarla, añada la dependencia kotlinx-datetime a la lista de dependencias de su proyecto.

Seleccione una 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 biblioteca, consulte el repositorio kotlinx-datetime en GitHub.

Ejemplo de clase de datos con fechas y horas

Después de agregar la dependencia de la biblioteca, puede implementar serializadores de la biblioteca kotlinx-datetime que asignan los valores de los campos de 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 controlador serializa el valor como una cadena.

• date:El controlador utiliza el serializador kotlinx-datetime porque el campo tiene la anotación @Contextual. Los valores LocalDate 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",
}