Codificar dados com codecs de tipo

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.

O seguinte código mostra como implementar um Codec para a classe Monolight . O construtor espera uma instância de CodecRegistry da qual ele recupera as instâncias de Codec necessárias para codificar e decodificar os campos de classe :

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()