Kotlin 直列化

項目一覧

Overview

サポートされているタイプ
Kotlin 直列化をプロジェクトに追加する
データクラスの注釈
カスタムシリアライザーの例
シリアライザー構成をカスタマイズする
カスタム Codec の例
多形直列化
多形データクラスの例
日付と時刻を直列化
kotlinx-datetime ライブラリ
日付と時刻を含むサンプルデータクラス

Overview

Kotlin ドライバーは、 Kotlin オブジェクトを直列化および逆直列化するための kotlinx.serializationライブラリをサポートしています。

このドライバーは効率的なBsonシリアライザーを提供し、 @Serializableとしてマークされたクラスで使用して、 Kotlin オブジェクトの BSON データへの直列化を処理します。

また、デフォルトをエンコードし、null をエンコードし、クラス弁別子を定義する構成で、カスタムコーデックをサポートするためにbson-kotlinxライブラリをインストールすることもできます。

注意

Kotlin シリアル化ライブラリではなくCodecインターフェースを使用して Kotlin オブジェクトを BSON データにカスタムエンコードおよびデコードを指定する方法については、「コーデックガイド」を参照してください。

フレームワークにすでに理解している場合、または慣用的な Kotlin アプローチを使用したい場合は、 Kotlin シリアル化を選択することができます。

Kotlin ドライバーは Kotlin シリアル化Jsonライブラリで使用できますが、 JsonシリアライザーはObjectIdなどの BSON 値型を直接サポートしていません。 BSON と JSON の間の変換を処理できるカスタムシリアライザーを提供する必要があります。

サポートされているタイプ

Kotlin ドライバーは次の機能をサポートします。

Kotlin 直列化ライブラリでサポートされているすべての Kotlin 型
利用可能なすべてのBSON types

Kotlin 直列化をプロジェクトに追加する

Support for 直列化 in the Kotlin driver depends on the official Kotlin 直列化 library.

GradleとMavenパッケージマネージャーを使用してプロジェクトにシリアル化の依存関係を追加する方法を確認するには、次のタブから選択します。

Gradle を使用している場合依存関係を管理するには、次のものをbuild.gradle.kts 依存関係リストに追加します。

build. Gradle.kts

implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.6.0")
implementation("org.mongodb:bson-kotlinx:5.3.0")

Maven を使用している場合依存関係を管理するには、次のものをpom.xml 依存関係リストに追加します。

pom.xml

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-serialization-core</artifactId>
    <version>1.6.0</version>
</dependency>
<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>bson-kotlinx</artifactId>
    <version>5.3.0</version>
</dependency>

データクラスの注釈

クラスをシリアル化可能として宣言するには、 Kotlin シリアル化フレームワークからの@Serializableアノテーションで Kotlin データクラスを注釈を付けます。

データクラスは、シリアル化可能としてマークすると、コード内で通常どおり使用できます。 Kotlin ドライバーと Kotlin 直列化フレームワークは BSON の直列化と逆直列化を処理します。

この例では、次の注釈が付けられた単純なデータクラスを示しています。

@Serializable クラスをシリアル化可能なものとしてマークします。
@SerialName で、BSON ドキュメント内のプロパティとプロパティの名前を指定します。idmanufacturerこれは、シリアル化可能なクラスでサポートされていない@BsonIdと@BsonPropertyアノテーションの代わりに使用できます。
@Contextual BSON idプロパティをマークし、組み込みのObjectIdSerializerを使用します。この注釈は、BSON types を正しく直列化するのに必要です。

@Serializable
data class PaintOrder(
    @SerialName("_id") // Use instead of @BsonId
    @Contextual val id: ObjectId?,
    val color: String,
    val qty: Int,
    @SerialName("brand")
    val manufacturer: String = "Acme" // Use instead of @BsonProperty
)

注意

@Serializableデータクラスではorg.bson.codecs.pojo.annotationsパッケージの注釈は使用できません。

シリアル化可能なクラスと利用可能な注釈クラスの詳細については、公式の Kotlin 直列化を参照してください。ドキュメント。

カスタムシリアライザーの例

BSON でのデータの表現方法を処理するカスタムシリアライザーを作成できます。 Kotlin ドライバーは、 kotlinx.serializationパッケージのKSerializerインターフェースを使用してカスタムシリアライザーを実装します。特定のフィールドの@Serializableアノテーションのパラメータとしてカスタムシリアライザーを指定できます。

次の例は、カスタムKSerializerインスタンスを作成して、 kotlinx.datetime.InstantをBsonDateTimeに変換する方法を示しています。

object InstantAsBsonDateTime : KSerializer<Instant> {
    override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("InstantAsBsonDateTime", PrimitiveKind.LONG)
    override fun serialize(encoder: Encoder, value: Instant) {
        when (encoder) {
            is BsonEncoder -> encoder.encodeBsonValue(BsonDateTime(value.toEpochMilliseconds()))
            else -> throw SerializationException("Instant is not supported by ${encoder::class}")
        }
    }
    override fun deserialize(decoder: Decoder): Instant {
        return when (decoder) {
            is BsonDecoder -> Instant.fromEpochMilliseconds(decoder.decodeBsonValue().asDateTime().value)
            else -> throw SerializationException("Instant is not supported by ${decoder::class}")
        }
    }
}

次のコードは、 orderDateフィールドが、前のコードで定義されたカスタムシリアライザークラスを指定する注釈を持つPaintOrderデータクラスを示しています。

@Serializable
data class PaintOrder(
    val color: String,
    val qty: Int,
    @Serializable(with = InstantAsBsonDateTime::class)
    val orderDate: Instant,
)

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

シリアライザー構成をカスタマイズする

org.bson.codecs.kotlinxパッケージのKotlinSerializerCodecクラスを使用して、 @Serializableデータクラスのコーデックを作成し、保存する内容をカスタマイズできます。

BsonConfigurationクラスを使用して、デフォルトをエンコードするか、null をエンコードするか、クラス弁別子を定義するかなどの構成を定義します。

カスタムコーデックを作成するには、プロジェクトにbson-kotlinx依存関係をインストールします。 GradleとMavenパッケージマネージャーを使用してプロジェクトに依存関係を追加する方法を確認するには、次のタブからを選択します。

Gradle を使用している場合依存関係を管理するには、次のものをbuild.gradle.kts 依存関係リストに追加します。

build. Gradle.kts

implementation("org.mongodb:bson-kotlinx:5.3.0")

Maven を使用している場合依存関係を管理するには、次のものをpom.xml 依存関係リストに追加します。

pom.xml

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>bson-kotlinx</artifactId>
    <version>5.3.0</version>
</dependency>

注意

bson-kotlin 依存関係

オプションで、デフォルトのコーデックレジストリを使用してbson-kotlin依存関係をインストールすることもできます。この依存関係はリフレクションとコーデックレジストリを使用して Kotlin データクラスをサポートしていますが、 BsonDiscriminator 、 BsonExtraElements 、 BsonConstructorなどの特定の POJO 注釈はサポートしていません。詳細については、 bson-kotlin API ドキュメントを参照してください。

一般的に、コーデック構成には高速なbson-kotlinxライブラリをインストールして使用することをお勧めします。

次に、 KotlinSerializerCodec.create() メソッドを使用してコーデックを定義できますメソッドを使用して、それをレジストリに追加します。

カスタム Codec の例

次の例は、 KotlinSerializerCodec.create()メソッドを使用してコーデックを作成し、デフォルトをエンコードしないように構成する方法を示しています。

import org.bson.codecs.configuration.CodecRegistries
import org.bson.codecs.kotlinx.BsonConfiguration
import org.bson.codecs.kotlinx.KotlinSerializerCodec

val myCustomCodec = KotlinSerializerCodec.create<PaintOrder>(
    bsonConfiguration = BsonConfiguration(encodeDefaults = false)
)
val registry = CodecRegistries.fromRegistries(
    CodecRegistries.fromCodecs(myCustomCodec), collection.codecRegistry
)

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

多形直列化

Kotlin ドライバーは、多形クラスの直列化と逆直列化をネイティブでサポートしています。シード処理されたインターフェースと、そのインターフェースを継承するデータクラスを@Serializableアノテーションでマークすると、ドライバーはKSerializer実装を使用して BSON との間で型の変換を処理します。

多形データクラスのインスタンスを MongoDB に挿入すると、ドライバーは弁別子フィールドであるフィールド_tを追加します。このフィールドの値は、データクラス名です。

多形データクラスの例

次の例では、インターフェースと、そのインターフェースを継承する 2 つのデータクラスを作成します。データクラスでは、 idフィールドは、「データクラスの注釈」セクションで説明されている注釈でマークされます。

@Serializable
sealed interface Person {
    val name: String
}
@Serializable
data class Student(
    @Contextual
    @SerialName("_id")
    val id: ObjectId,
    override val name: String,
    val grade: Int,
) : Person
@Serializable
data class Teacher(
    @Contextual
    @SerialName("_id")
    val id: ObjectId,
    override val name: String,
    val department: String,
) : Person

その後は、データクラスを使用した操作を通常どおり実行できます。次の例では、コレクションをPersonインターフェースでパラメータ化し、多形クラスTeacherとStudentを使用して操作を実行します。ドキュメントを検索すると、ドライバーは弁別子の値に基づいて型を自動的に検出し、それに応じて逆直列化します。

val collection = database.getCollection<Person>("school")
val teacherDoc = Teacher(ObjectId(), "Vivian Lee", "History")
val studentDoc = Student(ObjectId(), "Kate Parker", 10)
collection.insertOne(teacherDoc)
collection.insertOne(studentDoc)
println("Retrieving by using data classes")
collection.withDocumentClass<Teacher>()
    .find(Filters.exists("department"))
    .first().also { println(it) }
collection.withDocumentClass<Student>()
    .find(Filters.exists("grade"))
    .first().also { println(it) }
println("\nRetrieving by using Person interface")
val resultsFlow = collection.withDocumentClass<Person>().find()
resultsFlow.collect { println(it) }
println("\nRetrieving as Document type")
val resultsDocFlow = collection.withDocumentClass<Document>().find()
resultsDocFlow.collect { println(it) }

Retrieving by using data classes
Teacher(id=..., name=Vivian Lee, department=History)
Student(id=..., name=Kate Parker, grade=10)
Retrieving by using Person interface
Teacher(id=..., name=Vivian Lee, department=History)
Student(id=..., name=Kate Parker, grade=10)
Retrieving as Document type
Document{{_id=..., _t=Teacher, name=Vivian Lee, department=History}}
Document{{_id=..., _t=Student, name=Kate Parker, grade=10}}

日付と時刻を直列化

このセクションでは、 Kotlin 直列化を使用して日付型および時刻型を操作する方法を学習できます。

kotlinx-datetime ライブラリ

kotlinx-datetime は、日付と時刻の値が直列化される方法を高レベルで制御する Kotlin ライブラリです。ライブラリを使用するには、 kotlinx-datetime依存関係をプロジェクトの依存関係リストに追加します。

次のタブから選択して、 Gradle } パッケージマネージャーとMavenパッケージマネージャーを使用してプロジェクトにkotlinx-datetime依存関係を追加する方法を確認します。

build. Gradle.kts

implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")

pom.xml

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-datetime-jvm</artifactId>
    <version>0.6.1</version>
</dependency>

このライブラリの詳細については、 kotlinx-datetime リポジトリ Githubを参照してください。 .

日付と時刻を含むサンプルデータクラス

ライブラリの依存関係を追加したら、 kotlinx-datetimeライブラリからデータクラスフィールド値を BSON で期待される型にマッピングするシリアライザーを実装できます。

この例では、ドライバーはAppointmentデータクラスのフィールドを次の動作で直列化します。

name: ドライバーは値を string として直列化します。
date: フィールドに@Contextualアノテーションがあるため、ドライバーはkotlinx-datetimeライザーを使用します。 LocalDate値は BSON 日付としてシリアル化されます。
time: @Contextual注釈がないため、ドライバーは値を string として直列化します。これは、 LocalTime値のデフォルトの直列化動作です。

@Serializable
data class Appointment(
    val name: String,
    @Contextual val date: LocalDate,
    val time: LocalTime,
)

次の例では、 Appointmentデータクラスのインスタンスをappointmentsコレクションに挿入します。

val collection = database.getCollection<Appointment>("appointments")
val apptDoc = Appointment(
    "Daria Smith",
    LocalDate(2024, 10, 15),
    LocalTime(hour = 11, minute = 30)
)
collection.insertOne(apptDoc)

MongoDB では、 LocalDate値は BSON 日付として保存され、 timeフィールドはデフォルトの直列化で string として保存されます。

{
  "_id": ...,
  "name": "Daria Smith",
  "date": {
    "$date": "2024-10-15T00:00:00.000Z"
  },
  "time": "11:30",
}

戻る

ドキュメント

コーデック

Overview

注意

サポートされているタイプ

Kotlin 直列化をプロジェクトに追加する

データクラスの注釈

注意

カスタムシリアライザーの例

シリアライザー構成をカスタマイズする

注意

bson-kotlin 依存関係

カスタム Codec の例

多形直列化

多形データ クラスの例

日付と時刻を直列化

kotlinx-datetime ライブラリ

日付と時刻を含むサンプルデータクラス

多形データクラスの例