Serialização Kotlin

Visão geral

Você pode usar a biblioteca kotlinx.serialization ao serializar e desserializar objetos Kotlin em seu aplicação.

O driver fornece um serializador Bson eficiente que você pode usar com classes marcadas com a anotação @Serializable para lidar com a serialização de objetos Kotlin em dados BSON.

Embora você possa usar a Kotlin biblioteca de serialização Json , o Json serializador não oferece suporte direto a BSON tipos de valor , como ObjectId. Você deve fornecer um serializador personalizado que possa lidar com a conversão entre BSON e JSON.

Recomendamos instalar a biblioteca bson-kotlinx para oferecer suporte a codecs personalizados que tenham configurações para codificar padrões, nulos e definir discriminadores de classe .

Adicionar as dependências de serialização ao seu projeto

Você deve instalar a biblioteca oficial de serialização Kotlin , kotlinx.serialization, para serializar e desserializar dados em seu aplicação. Para saber mais sobre essa biblioteca, consulte o kotlinx. repositório de serialização do GitHub.

Selecione a partir das seguintes abas para ver como adicionar as dependências de serialização ao seu projeto usando Gradle ou Maven:

implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1")
implementation("org.mongodb:bson-kotlinx:5.2.0")

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-serialization-core</artifactId>
    <version>1.5.1</version>
</dependency>
<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>bson-kotlinx</artifactId>
    <version>5.2.0</version>
</dependency>

Anotar classes de dados

Para declarar uma classe como serializável, anote suas classes de dados do Kotlin com a anotação @Serializable .

Você pode usar suas classes de dados em seu código da mesma forma que usa qualquer outra classe de dados depois de marcá-las como serializáveis. O driver Kotlin Sync e a estrutura de serialização do Kotlin lidam com serialização e desserialização BSON.

Este exemplo mostra uma classe de dados de amostra com as seguintes anotações:

• @Serializable: Marca a classe como serializável.

• @SerialName: especifica o nome das propriedades id e manufacturer no documento BSON. Esta anotação pode ser utilizada no lugar das anotações do @BsonId e @BsonProperty , que não são suportadas em classes serializáveis.

• @Contextual: marca a propriedade BSON id para usar o ObjectIdSerializer. Essa anotação é necessária para que o driver serialize os BSON types corretamente.

@Serializable
data class PaintOrder(
    @SerialName("_id") // Use instead of @BsonId
    @Contextual val id: ObjectId?,
    val color: String,
    val qty: Int,
    @SerialName("brand")
    val manufacturer: String = "Grumbacher" // Use instead of @BsonProperty
)

Para saber mais sobre classes serializáveis e anotações disponíveis, consulte Classes serializáveis na kotlinx.serialization documentação da biblioteca .

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

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

Personalizar a Configuração do Serializador

Você pode usar a classe KotlinSerializerCodec do pacote org.bson.codecs.kotlinx para criar um codec para suas classes de dados do @Serializable e personalizar o que o driver armazena no MongoDB.

Use a classe BsonConfiguration para definir a configuração, que pode incluir se deseja codificar padrões, codificar nulos ou definir discriminadores de classe .

Para criar um codec personalizado, seu projeto deve ter a dependência bson-kotlinx . Consulte a seção Adicionar as dependências de serialização ao seu projeto deste guia para obter instruções de instalação.

Você pode definir seu codec usando o arquivo KotlinSerializerCodec.create() método, então você pode adicionar o codec ao registro.

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

Serialização polimórfica

O driver Kotlin Sync suporta nativamente serialização e desserialização de classes polimórficas. Quando você marca uma interface selada e classes de dados que herdam essa interface com a anotação @Serializable , o driver usa uma implementação KSerializer para lidar com a conversão de seus tipos de e para BSON.

Quando você insere uma instância de uma classe de dados polimórficos no MongoDB, o driver adiciona o campo _t, o campo discriminador. O valor deste campo é o nome da classe de dados.

@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

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

Serialize datas e horários

Nesta seção, você pode aprender sobre como usar a serialização do Kotlin para trabalhar com tipos de data e hora.

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>

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

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

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