Codificar datos con códecs de tipo

Overview

En esta guía, puede aprender sobre los códecs y las clases de soporte que manejan la codificación y decodificación de objetos Kotlin hacia y desde datos BSON. Codec La abstracción permite mapear cualquier tipo de Kotlin a su tipo BSON correspondiente. Puede usar esta función para mapear los objetos de su dominio directamente hacia y desde BSON en lugar de usar clases como Document o BsonDocument.

Puede aprender a especificar la lógica de codificación y decodificación personalizada utilizando la abstracción Codec y ver implementaciones de ejemplo en las siguientes secciones:

• Códec

• Registro de códecs

• Proveedor de códecs

• Ejemplo de códec personalizado

Códec

La interfaz Codec contiene métodos abstractos para serializar y deserializar objetos Kotlin a datos BSON. Puedes definir una lógica de conversión personalizada en tu implementación de esta interfaz.

Para implementar la interfaz Codec, anule los métodos abstractos encode(), decode() y 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
}

Registro de códecs

Un CodecRegistry es una colección inmutable de instancias Codec que codifican y decodifican clases Kotlin. Puede usar cualquiera de los siguientes métodos de fábrica estáticos de clase CodecRegistries para construir un CodecRegistry a partir de las instancias Codec contenidas en los tipos asociados:

• fromCodecs():Crea un registro a partir de Codec instancias

• fromProviders():Crea un registro a partir de CodecProvider instancias

• fromRegistries():Crea un registro a partir de CodecRegistry instancias

El siguiente código muestra cómo construir un CodecRegistry utilizando el método fromCodecs():

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

El ejemplo anterior asigna a CodecRegistry las siguientes implementaciones Codec:

• IntegerCodec: Codec que convierte Integers. Forma parte del paquete BSON.

• PowerStatusCodec:Muestra Codec de la sección anterior que convierte valores de enumeración de Kotlin en booleanos BSON.

Puede recuperar las instancias Codec de la instancia CodecRegistry utilizando el siguiente código:

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

Si intenta recuperar una instancia Codec para una clase que no está registrada, el método codecRegistry.get() genera una excepción CodecConfigurationException.

Para obtener más información sobre las clases e interfaces de esta sección, consulte la siguiente documentación de API:

• Registros de códecs

• Códec de enteros

Proveedor de códecs

Una interfaz CodecProvider contiene métodos abstractos para crear instancias Codec y asignarlas a instancias CodecRegistry. Al igual que la interfaz CodecRegistry, la biblioteca BSON utiliza las instancias Codec recuperadas por el método CodecProvider.get() para convertir entre los tipos de datos Kotlin y BSON.

Sin embargo, si agrega una clase que contiene campos que requieren objetos Codec correspondientes, asegúrese de instanciar los objetos Codec para los campos de la clase antes de instanciar los objetos Codec para toda la clase. Puede usar el parámetro CodecRegistry en el método CodecProvider.get() para pasar cualquiera de las instancias Codec de las que depende el objeto Codec.

Para ver un ejemplo ejecutable que demuestre operaciones de lectura y escritura utilizando Codec clases, consulte la sección Ejemplo de códec personalizado de esta guía.

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

Ejemplo de códec personalizado

Esta sección muestra cómo implementar las interfaces Codec y CodecProvider para definir la lógica de codificación y decodificación de una clase Kotlin personalizada. También muestra cómo especificar y usar sus implementaciones personalizadas para realizar operaciones de lectura y escritura.

El siguiente código define la clase de datos de muestra Monolight:

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

Esta clase contiene los siguientes campos, cada uno de los cuales requiere un Codec correspondiente para manejar la codificación y decodificación:

• powerStatus: Describe si la luz del dispositivo está "ON" o "OFF". Para este campo, use la PowerStatusCodec que convierte los valores de la enumeración PowerStatus en booleanos BSON.

• colorTemperatureDescribe el color de la luz del dispositivo en kelvins como un valor Int. Para este campo, utilice el valor IntegerCodec proporcionado en la biblioteca BSON.

El siguiente código muestra cómo implementar un Codec para la clase Monolight. El constructor espera una instancia de CodecRegistry, de la cual recupera las instancias Codec necesarias para codificar y decodificar los campos de la clase:

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 garantizar que las instancias Codec de los campos estén disponibles para la clase Monolight, implemente un CodecProvider personalizado como se muestra en el siguiente ejemplo de código:

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

Después de definir la lógica de conversión, puedes realizar las siguientes acciones:

• Almacenar instancias de Monolight en MongoDB

• Recuperar documentos de MongoDB como instancias de Monolight

El siguiente código asigna MonolightCodecProvider a la instancia MongoCollection pasándola al método withCodecRegistry(). La clase de ejemplo también inserta y recupera datos mediante la clase 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 obtener más información sobre los métodos y clases mencionados en esta sección, consulte la siguiente documentación de API:

• conCodecRegistry()

• deRegistries()