Codecs

Visão geral

Neste guia, você pode aprender sobre Codecs e classes de suporte que lidam com a codificação e decodificação de objetos Kotlin de e para dados BSON. A abstração do Codec permite mapear qualquer tipo Kotlin para um tipo BSON correspondente. Você pode usar esse recurso para mapear seus objetos de domínio diretamente de e para o BSON, em vez de usar classes como Document ou BsonDocument.

Você pode aprender a especificar a lógica de codificação e decodificação personalizada usando a Codec abstração e exibir implementações de exemplo nas seções a seguir:

• Codec

• CodecRegistry

• CodecProvider

• Exemplo de codec personalizado

Codec

A interface do Codec contém métodos abstratos para serializar e desserializar objetos Kotlin para dados BSON. Você pode definir a lógica de conversão personalizada em sua implementação desta interface.

Para implementar a interface do Codec, substitua os métodos abstratos encode(), decode() e getEncoderClass().

enum class PowerStatus {
    ON,
    OFF
}

class PowerStatusCodec : Codec<PowerStatus> {
    override fun encode(
        writer: BsonWriter, value: PowerStatus, encoderContext: EncoderContext
    ) = writer.writeBoolean(value == PowerStatus.ON)
    override fun decode(
        reader: BsonReader, decoderContext: DecoderContext)
    : PowerStatus {
        return when (reader.readBoolean()) {
            true -> PowerStatus.ON
            false -> PowerStatus.OFF
        }
    }
    override fun getEncoderClass(): Class<PowerStatus> = PowerStatus::class.java
}

CodecRegistry

Um CodecRegistry é uma coleção imutável de instâncias do Codec que codificam e decodificam classes Kotlin . Você pode usar qualquer um dos seguintes métodos de fábrica estática de classe CodecRegistries para construir uma CodecRegistry a partir das instâncias Codec contidas nos tipos associados:

• fromCodecs(): Cria um registro a partir de instâncias de Codec

• fromProviders(): Cria um registro a partir de instâncias de CodecProvider

• fromRegistries(): Cria um registro a partir de instâncias de CodecRegistry

O seguinte código mostra como construir um CodecRegistry utilizando o método fromCodecs() :

val codecRegistry = CodecRegistries
    .fromCodecs(IntegerCodec(), PowerStatusCodec())

O exemplo anterior atribui ao CodecRegistry as seguintes implementações do Codec :

• IntegerCodec: Codec que converte Integers. Faz parte do pacote BSON.

• PowerStatusCodec: Exemplo Codec da seção anterior que converte valores de enumeração do Kotlin em booleanos BSON.

Você pode recuperar as instâncias Codec da instância CodecRegistry usando o código a seguir:

val powerStatusCodec = codecRegistry.get(PowerStatus::class.java)
val integerCodec = codecRegistry.get(Integer::class.java)

Se você tentar recuperar uma instância do Codec para uma classe que não está registrada, o método do codecRegistry.get() gerará uma exceção do CodecConfigurationException .

Para obter mais informações sobre as classes e interfaces nesta seção, consulte a seguinte Documentação da API:

• CodecRegistries

• Codec inteiro

CodecProvider

Um CodecProvider é uma interface que contém métodos abstratos para criar instâncias do Codec e atribuí-las a instâncias do CodecRegistry . Semelhante à interface CodecRegistry , a biblioteca BSON usa as instâncias do Codec recuperadas pelo método CodecProvider.get() para converter entre Kotlin e tipos de dados BSON.

No entanto, nos casos em que você adicionar uma classe que contém campos que exigem objetos Codec correspondentes, certifique-se de instanciar os objetos Codec para os campos da classe antes de instanciar o Codec para a classe inteira. Você pode utilizar o parâmetro CodecRegistry no método CodecProvider.get() para passar qualquer uma das instâncias do Codec em que o Codec confia.

Para visualizar um exemplo executável que demonstra operações de leitura e escrita utilizando classes Codec , consulte a seção Exemplo de codec personalizado deste guia.

val newRegistry = CodecRegistries.fromRegistries(
    CodecRegistries.fromCodecs(MyEnumCodec()),
    MongoClientSettings.getCodecRegistry()
)

val bsonTypeClassMap = BsonTypeClassMap()
val clazz = bsonTypeClassMap[BsonType.ARRAY]
println("Kotlin class name: " + clazz.name)

Kotlin class name: java.util.List

val replacements = mutableMapOf<BsonType, Class<*>>(BsonType.ARRAY to MutableSet::class.java)
val bsonTypeClassMap = BsonTypeClassMap(replacements)
val clazz = bsonTypeClassMap[BsonType.ARRAY]
println("Class name: " + clazz.name)

Kotlin class name: java.util.Set

Exemplo de codec personalizado

Esta seção demonstra como você pode implementar interfaces do Codec e CodecProvider para definir a lógica de codificação e decodificação de uma classe Kotlin personalizada. Ele mostra como você pode especificar e usar suas implementações personalizadas para realizar operações de leitura e escrita.

O seguinte código define a classe de dados de amostra Monolight:

data class Monolight(
    var powerStatus: PowerStatus = PowerStatus.OFF,
    var colorTemperature: Int? = null
) { 
    override fun toString():
        String = "Monolight { powerStatus: $powerStatus, colorTemperature: $colorTemperature }"
}

Esta classe contém os seguintes campos que cada um exige um Codec correspondente para lidar com a codificação e decodificação:

• powerStatus: descreve se a luz do dispositivo é "ON" ou "OFF". Para este campo, use o PowerStatusCodec que converte os valores de enumeração do PowerStatus para booleanos BSON.

• colorTemperature: descreve a cor da luz do dispositivo em celvins como um valor Int . Para este campo, utilize o IntegerCodec fornecido na biblioteca BSON.

The following code shows how to implement a Codec for the Monolight class. The constructor expects an instance of CodecRegistry from which it retrieves the Codec instances needed to encode and decode the class fields:

class MonolightCodec(registry: CodecRegistry) : Codec<Monolight> {
    private val powerStatusCodec: Codec<PowerStatus>
    private val integerCodec: Codec<Int>
    init {
        powerStatusCodec = registry[PowerStatus::class.java]
        integerCodec = IntegerCodec()
    }
    override fun encode(writer: BsonWriter, value: Monolight, encoderContext: EncoderContext) {
        writer.writeStartDocument()
        writer.writeName("powerStatus")
        powerStatusCodec.encode(writer, value.powerStatus, encoderContext)
        writer.writeName("colorTemperature")
        integerCodec.encode(writer, value.colorTemperature, encoderContext)
        writer.writeEndDocument()
    }
    override fun decode(reader: BsonReader, decoderContext: DecoderContext): Monolight {
        val monolight = Monolight()
        reader.readStartDocument()
        while (reader.readBsonType() != BsonType.END_OF_DOCUMENT) {
            when (reader.readName()) {
                "powerStatus" -> monolight.powerStatus =
                    powerStatusCodec.decode(reader, decoderContext)
                "colorTemperature" -> monolight.colorTemperature =
                    integerCodec.decode(reader, decoderContext)
                "_id" -> reader.readObjectId()
            }
        }
        reader.readEndDocument()
        return monolight
    }
    override fun getEncoderClass(): Class<Monolight> = Monolight::class.java
}

Para garantir que as instâncias Codec dos campos estejam disponíveis para a classe Monolight , implemente um CodecProvider personalizado conforme mostrado no exemplo de código a seguir :

class MonolightCodecProvider : CodecProvider {
    @Suppress("UNCHECKED_CAST")
    override fun <T> get(clazz: Class<T>, registry: CodecRegistry): Codec<T>? {
        return if (clazz == Monolight::class.java) {
            MonolightCodec(registry) as Codec<T>
        } else null // Return null when not a provider for the requested class
    }
}

Após definir a lógica de conversão, você pode executar as seguintes ações:

• Armazenar instâncias de Monolight no MongoDB

• Recuperar documentos do MongoDB como instâncias de Monolight

O código a seguir atribui o MonolightCodecProvider à instância MongoCollection passando-o para o método withCodecRegistry() . A classe de exemplo também insere e recupera dados utilizando a classe Monolight :

    val mongoClient = MongoClient.create(uri)
    val codecRegistry = CodecRegistries.fromRegistries(
        CodecRegistries.fromCodecs(IntegerCodec(), PowerStatusCodec()),
        CodecRegistries.fromProviders(MonolightCodecProvider()),
        MongoClientSettings.getDefaultCodecRegistry()
    )
    val database = mongoClient.getDatabase("codec_test")
    val collection = database.getCollection<Monolight>("monolights")
        .withCodecRegistry(codecRegistry)
    // Insert instances of Monolight
    val monolights = listOf(
        Monolight(PowerStatus.ON, 5200),
        Monolight(PowerStatus.OFF, 3000)
    )
    collection.insertMany(monolights)
    // Retrieve instances of Monolight
    val results =  collection.find()
    results.forEach { l ->
        println(l)
    }

Monolight { powerStatus: ON, colorTemperature: 5200 }
Monolight { powerStatus: OFF, colorTemperature: 3000 }

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

• withCodecRegistry()

• fromRegistries()