コーデック

Overview

このガイドでは、 Kotlin オブジェクトと BSON データのエンコードとデコードを処理するCodecとサポート クラスについて学習できます。 Codec抽象化を使用すると、任意の Kotlin 型を対応する BSON 型にマップできます。 この機能を使用すると、 DocumentやBsonDocumentなどのクラスを使用する代わりに、ドメイン オブジェクトを BSON との間で直接マッピングできます。

次のセクションでは、Codec 抽象化を使用してカスタム エンコードおよびデコード ロジックを指定する方法と、実装例を確認する方法について説明します。

• コーデック

• CodecRegistry

• CodecProvider

• カスタム Codec の例

コーデック

Codecインターフェースには、 Kotlin オブジェクトを BSON データにシリアル化および逆シリアル化するための抽象メソッドが含まれています。 このインターフェースの実装では、カスタム変換ロジックを定義できます。

Codec インターフェースを実装するには、encode()、decode()、および 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

CodecRegistryは、 Kotlin クラスをエンコードおよびデコードするCodecインスタンスの不変のコレクションです。 次のCodecRegistriesクラスの静的ファクトリー メソッドのいずれかを使用して、関連付けられた型に含まれるCodecインスタンスからCodecRegistryを構築できます。

• fromCodecs(): Codecインスタンスからレジストリを作成します

• fromProviders(): CodecProviderインスタンスからレジストリを作成します

• fromRegistries(): CodecRegistryインスタンスからレジストリを作成します

次のコードは、 fromCodecs()メソッドを使用してCodecRegistryを構築する方法を示しています。

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

上記の例では、 CodecRegistryに次のCodec実装が割り当てられています。

• IntegerCodec:Codec Integersを変換するこれは、BSON パッケージの一部です。

• PowerStatusCodec: Kotlin 列挙値を BSON ブール値に変換する前のセクションのサンプルCodec 。

次のコードを使用して、 CodecRegistryインスタンスからCodecインスタンスを取得できます。

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

登録されていないクラスのCodecインスタンスを検索しようとすると、 codecRegistry.get()メソッドはCodecConfigurationException例外を発生させます。

このセクションのクラスとインターフェースの詳細については、次の API ドキュメントを参照してください。

• CodecRegistries

• IntegerCodec

CodecProvider

CodecProviderは、 Codecインスタンスを作成し、それをCodecRegistryインスタンスに割り当てる抽象メソッドを含むインターフェースです。 CodecRegistryインターフェースと同様に、BSON ライブラリはCodecProvider.get()メソッドによって検索されたCodecインスタンスを使用して、 Kotlin と BSON データ型間の変換を行います。

ただし、対応するCodecオブジェクトを必要とするフィールドを含むクラスを追加する場合は、クラス全体のCodecをインスタンス化する前に、クラスのフィールドのCodecオブジェクトをインスタンス化してください。 CodecProvider.get()メソッドのCodecRegistryパラメータを使用して、 Codecが依存するCodecインスタンスのいずれかを渡すことができます。

Codecクラスを使用した読み取りおよび書込み (write) 操作を示す実行可能な例については、このガイドの「カスタム コーデックの例」セクションを参照してください。

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

カスタム Codec の例

このセクションでは、Codec CodecProviderインターフェースと インターフェースを実装して、カスタム Kotlin クラスのエンコードおよびデコード ロジックを定義する方法を示します。カスタム実装を指定して使用し、読み取りおよび書込み操作を実行する方法を示します。

次のコードは、サンプル データ クラスMonolightを定義します。

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

このクラスには次のフィールドが含まれており、エンコードとデコードを処理するために対応するCodecがそれぞれに必要です。

• powerStatus: デバイスのライトが"ON"であるか、 "OFF"であるかを表します。 このフィールドには、 PowerStatus列挙値を BSON ブール値に変換するPowerStatusCodecを使用します。

• colorTemperature: デバイスライトの色をキロメートル単位で記述し、 Int値として記述します。 このフィールドには、BSON ライブラリで提供されているIntegerCodecを使用します。

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
}

フィールドのCodecインスタンスがMonolightクラスで使用できるようにするには、次のコード例に示すようにカスタムCodecProviderを実装します。

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

変換ロジックを定義した後、次のアクションを実行できます。

• MongoDB でMonolightのインスタンスを保存する

• 次のインスタンスとして MongoDB からドキュメントを取得: Monolight

次のコードでは、 MonolightCodecProviderをwithCodecRegistry()メソッドに渡してMongoCollectionインスタンスに割り当てます。 このサンプル クラスでは、 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 }

このセクションで説明されるメソッドとクラスの詳細については、次の API ドキュメントを参照してください。

• withCodecRegistry()

• fromRegistries()