Codifica 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 te permite mapear cualquier tipo de Kotlin a un tipo BSON correspondiente. Puedes utilizar esta funcionalidad para mapear objetos de dominio directamente hacia y desde BSON, en lugar de utilizar clases como Document o BsonDocument.

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

• Códec

• CodecRegistry

• CodecProvider

• Ejemplo de Codec 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, sobreescribe 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
}

CodecRegistry

Un CodecRegistry es una colección inmutable de instancias Codec que codifican y decodifican clases de Kotlin. Se puede utilizar cualquier método de fábrica estático de la clase CodecRegistries para construir un CodecRegistry a partir de las instancias Codec contenidas en los tipos asociados:

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

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

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

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 de Codec de la instancia de 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:

• CodecRegistries

• IntegerCodec

CodecProvider

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

Sin embargo, en los casos en los que agregues una clase que contenga campos que requieran objetos Codec correspondientes, asegúrate de instanciar los objetos Codec para los campos de la clase antes de instanciar el Codec para toda la clase. Puedes usar el parámetro CodecRegistry en el método CodecProvider.get() para pasar cualquiera de las instancias Codec de las que depende el 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 Codec 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 que requieren cada uno un Codec correspondiente para gestionar 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:

• Almacene instancias de Monolight en MongoDB

• Recuperar documentos de MongoDB como instancias de Monolight

El siguiente código asigna el MonolightCodecProvider a la instancia MongoCollection pasándolo al método withCodecRegistry(). La clase de ejemplo también inserta y recupera datos utilizando 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()

• fromRegistries()