Serialização Kotlin

Visão geral

O driver do Kotlin suporta a biblioteca kotlinx.serialization para serializar e desserializar objetos do Kotlin.

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

Você também pode instalar a biblioteca do bson-kotlinx para suportar códigos personalizados com configurações para codificar padrões, codificar nulos e definir discriminadores de classe.

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

Adicionar serialização de Kotlin ao seu projeto

Support for serialização in the Kotlin driver depends on the official Kotlin serialização library.

Selecione uma das abas abaixo para ver como adicionar as dependências de serialização ao seu projeto usando os gerenciadores de pacotes Gradle e Maven:

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

<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.1</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 da estrutura de serialização do Kotlin.

Você pode utilizar suas classes de dados em seu código normalmente após marcá-las como serializáveis. O driver do Kotlin e a estrutura de serialização do Kotlin gereciam a serialização e desserialização do BSON.

Este exemplo mostra uma classe de dados simples anotada com o seguinte:

• @Serializable para marcar a classe como serializável.

• @SerialName para especificar o nome das propriedades id e manufacturer no documento BSON. Pode ser usado no lugar das anotações do @BsonId e @BsonProperty, que não são compatíveis com classes serializáveis.

• @Contextual para marcar a propriedade BSON id para utilizar o ObjectIdSerializer embutido. Esta anotação é necessária para que os tipos BSON sejam serializados 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 = "Acme" // Use instead of @BsonProperty
)

Para mais informações sobre classes serializáveis e classes de anotação disponíveis, consulte a documentação Serialização oficial de Kotlin.

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

@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 utilizar a classe KotlinSerializerCodec do pacote org.bson.codecs.kotlinx para criar um codec para suas classes de dados do @Serializable e personalizar o que é armazenado.

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

Para criar um codec personalizado, instale a dependência do bson-kotlinx no seu projeto. Selecione uma das abas abaixo para ver como adicionar a dependência ao seu projeto usando os gerenciadores de pacotes Gradle e Maven:

implementation("org.mongodb:bson-kotlinx:5.2.1")

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>bson-kotlinx</artifactId>
    <version>5.2.1</version>
</dependency>

Em seguida, você pode definir seu codec usando o método KotlinSerializerCodec.create() e adicioná-lo ao registro.

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
)

Serialização polimórfica

O driver Kotlin 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")
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}}

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