serialização de dados

Tipos suportados

O driver do Kotlin Sync é compatível com os seguintes tipos:

• Todos os tipos de Kotlin suportados pela biblioteca kotlinx.serialization

• Todos os BSON types

Classes anotadas de query

Você pode fazer query de classes de dados anotadas usando a classe Filters do pacote mongodb-driver-kotlin-extensions. Esta classe permite a você criar filtros de query em nomes de campo anotados com a anotação @SerialName.

O exemplo a seguir faz uma query da collection orders para documentos que tenham um valor de campo brand de "Sherwin-Williams":

val queryFilter = eq(PaintOrder::manufacturer, "Sherwin-Williams")val results = collection.find(queryFilter).toList()

O código anterior cria um filtro de query que faz referência à propriedade PaintOrder::manufacturer, mas que query o campo BSON brand. O driver converte automaticamente o nome da propriedade da classe de dados para o nome do campo especificado na anotação @SerialName.

Exemplo de serializador personalizado

Você pode criar um serializador personalizado para lidar com como seus dados são representados no BSON. O driver Kotlin Sync usa a interface KSerializer da biblioteca kotlinx.serialization para implementar serializadores personalizados. Você pode especificar o serializador customizado como parâmetro para a anotação @Serializable para um campo específico.

O exemplo abaixo mostra como criar uma instância personalizada do KSerializer para converter um kotlin.time.Instant para um 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}")        }    }}

O código abaixo mostra a classe de dados PaintOrder na qual o campo orderDate tem uma anotação que especifica a classe de serializador personalizado definida no código anterior:

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

Para saber mais sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

• KSerializer na documentação do Kotlin

• Instant na documentação do Kotlin

• BsonEncoder

• BsonDecoder

Exemplo de codec personalizado

O exemplo seguinte mostra como criar um codec utilizando o método KotlinSerializerCodec.create() e, em seguida, configurá-lo para não codificar padrões:

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

Implementar estratégia de nomenclatura de caso de cobra

Ao usar o pacote bson-kotlinx v5.4 ou posterior, você pode direcionar o driver para serializar os nomes dos campos de classe de dados escritos em camel case para snake case no MongoDB. O exemplo a seguir mostra como criar e registrar um codec personalizado para converter nomes de campo de classe de dados em caso de cobra configurando o parâmetro bsonNamingStrategy em um codec:

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

Para saber mais sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

• KotlinSerializerCodec

• KotlinSerializerCodec.create()

• BsonConfiguration

• Estratégia de nomeação BSON

Exemplo de classes de dados polimórficos

O exemplo seguinte cria uma interface e duas classes de dados que herdam esta interface. Nas classes de dados, o campo id é marcado com as anotações descritas na seção Anotar Classes de Dados :

@Serializablesealed interface Person {    val name: String}
@Serializabledata class Student(    @Contextual    @SerialName("_id")    val id: ObjectId,    override val name: String,    val grade: Int,) : Person
@Serializabledata class Teacher(    @Contextual    @SerialName("_id")    val id: ObjectId,    override val name: String,    val department: String,) : Person

Em seguida, você pode executar operações com classes de dados como de costume. O exemplo a seguir parametriza a coleção com a interface Person e, em seguida, executa operações com as classes polimórficas Teacher e Student. Ao recuperar documentos, o driver detecta automaticamente o tipo com base no valor do discriminador e os desserializa adequadamente.

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 classesTeacher(id=..., name=Vivian Lee, department=History)Student(id=..., name=Kate Parker, grade=10)
Retrieving by using Person interfaceTeacher(id=..., name=Vivian Lee, department=History)Student(id=..., name=Kate Parker, grade=10)
Retrieving as Document typeDocument{{_id=..., _t=Teacher, name=Vivian Lee, department=History}}Document{{_id=..., _t=Student, name=Kate Parker, grade=10}}

Biblioteca kotlinx-datetime

kotlinx-datetime é uma biblioteca Kotlin que oferece um alto nível de controle sobre como seus valores de data e hora são serializados. Para utilizar a biblioteca, adicione a dependência kotlinx-datetime à lista de dependência do seu projeto.

Selecione a partir das seguintes guias para ver como adicionar a dependência do kotlinx-datetime ao seu projeto utilizando os gerenciadores de pacote Gradle e 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 saber mais sobre essa biblioteca, consulte o repositório kotlinx-datetime no Github.

Classe de dados de exemplo com datas e horários

Após adicionar a dependência da biblioteca, você pode implementar serializadores da biblioteca do kotlinx-datetime que mapeiam seus valores de campo de classe de dados para os tipos esperados no BSON.

Neste exemplo, o driver serializa os campos da classe de dados Appointment com o seguinte comportamento:

• name: o driver serializa o valor como uma string.

• date: o driver utiliza o serializador kotlinx-datetime porque o campo tem a anotação @Contextual . LocalDate valores são serializados como datas BSON.

• time: o driver serializa o valor como uma string porque ele não tem a anotação @Contextual . Este é o comportamento de serialização padrão para valores LocalTime .

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

O exemplo seguinte insere uma instância da classe de dados Appointment na coleção appointments :

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

No MongoDB, o valor LocalDate é armazenado como uma data BSON e o campo time é armazenado como uma string por serialização padrão:

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