DOCSP-35884: custom serializer example (#148)

* DOCSP-35884: custom serializer example

* rearrange structure

* add intro to dependency tabs

* small fix

(cherry picked from commit 5015f98)

Author: rustagir

examples/build.gradle.kts

@@ -29,6 +29,7 @@ dependencies {
     implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1")
     implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.5.0")
     implementation("org.mongodb:bson-kotlinx:4.10.0-alpha1")
+    implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.4.0")
 }
 
 tasks.test {

examples/src/test/kotlin/KotlinXSerializationTest.kt

@@ -1,4 +1,5 @@
 
+import com.mongodb.client.model.Filters.eq
 import com.mongodb.kotlin.client.coroutine.MongoClient
 import config.getConfig
 import kotlinx.coroutines.flow.first
@@ -8,11 +9,22 @@ import kotlinx.serialization.Contextual
 import kotlinx.serialization.ExperimentalSerializationApi
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
+import kotlinx.datetime.*
+import kotlinx.serialization.KSerializer
+import kotlinx.serialization.SerializationException
+import kotlinx.serialization.descriptors.PrimitiveKind
+import kotlinx.serialization.descriptors.PrimitiveSerialDescriptor
+import kotlinx.serialization.descriptors.SerialDescriptor
+import kotlinx.serialization.encoding.Decoder
+import kotlinx.serialization.encoding.Encoder
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.encodeToJsonElement
+import org.bson.BsonDateTime
 import org.bson.Document
 import org.bson.codecs.configuration.CodecRegistries
 import org.bson.codecs.kotlinx.BsonConfiguration
+import org.bson.codecs.kotlinx.BsonDecoder
+import org.bson.codecs.kotlinx.BsonEncoder
 import org.bson.codecs.kotlinx.KotlinSerializerCodec
 import org.bson.codecs.kotlinx.ObjectIdSerializer
 import org.bson.types.ObjectId
@@ -22,6 +34,7 @@ import org.junit.jupiter.api.Assertions.assertFalse
 
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.TestInstance
+import java.util.Date
 
 @TestInstance(TestInstance.Lifecycle.PER_CLASS)
 internal class KotlinXSerializationTest {
@@ -118,5 +131,52 @@ internal class KotlinXSerializationTest {
         collection.drop()
     }
 
+    // :snippet-start: kserializer
+    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}")
+            }
+        }
+    }
+    // :snippet-end:
+
+    @Test
+    fun customKSerializerTest() = runBlocking {
+        // :snippet-start: kserializer-dataclass
+        @Serializable
+        data class PaintOrder(
+            val color: String,
+            val qty: Int,
+            @Serializable(with = InstantAsBsonDateTime::class)
+            val orderDate: Instant,
+        )
+        // :snippet-end:
+
+        val collection = database.getCollection<PaintOrder>("orders")
+        val paintOrder = PaintOrder("magenta", 5, Instant.parse("2024-01-15T00:00:00Z"))
+        val insertOneResult = collection.insertOne(paintOrder)
+
+        val resultsFlow = collection.withDocumentClass<Document>()
+            .find(eq(PaintOrder::color.name, "magenta"))
+            .firstOrNull()
+
+        if (resultsFlow != null) {
+            assertEquals(resultsFlow["orderDate"], Date.from(java.time.Instant.parse("2024-01-15T00:00:00Z")))
+        }
+
+        collection.drop()
+    }
+
 }
 

snooty.toml

@@ -22,7 +22,7 @@ driver-long = "MongoDB Kotlin Driver"
 version = "4.10"
 full-version = "{+version+}.1"
 mdb-server = "MongoDB server"
-kotlin-docs = "https://kotlinlang.org/docs"
+kotlin-docs = "https://kotlinlang.org"
 
 package-name-org = "mongodb-org"
 api = "https://mongodb.github.io/mongo-java-driver/{+version+}"

source/examples/generated/KotlinXSerializationTest.snippet.kserializer-dataclass.kt

@@ -0,0 +1,7 @@
+@Serializable
+data class PaintOrder(
+    val color: String,
+    val qty: Int,
+    @Serializable(with = InstantAsBsonDateTime::class)
+    val orderDate: Instant,
+)

source/examples/generated/KotlinXSerializationTest.snippet.kserializer.kt

@@ -0,0 +1,17 @@
+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}")
+        }
+    }
+}

source/fundamentals/data-formats/serialization.txt

@@ -20,7 +20,7 @@ Kotlin Serialization
 Overview
 --------
 
-The Kotlin driver supports the ``kotlinx.serialization`` library for
+The {+driver-short+} supports the ``kotlinx.serialization`` library for
 serializing and deserializing Kotlin objects. 
 
 The driver provides an efficient ``Bson`` serializer that you can use with 
@@ -41,29 +41,28 @@ defaults, encode nulls, and define class discriminators.
    You might choose Kotlin serialization if you are already familiar
    with the framework or if you prefer to use an idiomatic Kotlin approach.
 
-Although you can use the Kotlin driver with the Kotlin serialization ``Json`` 
+Although you can use the {+driver-short+} with the Kotlin serialization ``Json`` 
 library, the ``Json`` serializer does *not* directly support BSON value types such
 as ``ObjectId``. You must provide a custom serializer that can handle the 
 conversion between BSON and JSON. 
 
 Supported Types
 ~~~~~~~~~~~~~~~
 
-The Kotlin driver supports: 
+The {+driver-short+} supports: 
 
 - All Kotlin types that are supported by the Kotlin serialization library 
 - All available :manual:`BSON types </reference/bson-types>`
 
-You can implement a custom serializers to handle any other types. See the 
-`official Kotlin Documentation <https://kotlinlang.org/docs/serialization.html>`__ 
-for more information.
-
 Add Kotlin Serialization to Your Project
 ----------------------------------------
 
-The Kotlin driver serialization support depends on the official Kotlin 
-serialization library. You must add `Kotlin Serialization <https://github.com/Kotlin/kotlinx.serialization>`__ 
-to your project:
+Support for serialization in the {+driver-short+} depends on the official `Kotlin
+serialization library <https://github.com/Kotlin/kotlinx.serialization>`__.
+
+Select from the following tabs to see how to add the serialization
+dependencies to your project by using the :guilabel:`Gradle` and
+:guilabel:`Maven` package managers:
 
 .. tabs::
 
@@ -106,7 +105,7 @@ To declare a class as serializable, annotate your Kotlin data classes with the
 ``@Serializable`` annotation from the Kotlin serialization framework.
 
 You can use your data classes in your code as normal after you mark them as serializable.
-The Kotlin driver and the Kotlin serialization framework will handle the 
+The {+driver-short+} and the Kotlin serialization framework handle the 
 BSON serialization and deserialization.
 
 This example shows a simple data class annotated with the following: 
@@ -130,6 +129,38 @@ For more information on serializable classes and available annotation classes,
 see the `official Kotlin Serialization <https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/basic-serialization.md#serializable-classes>`__ 
 documentation.
 
+Custom Serializer Example
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can create a custom serializer to handle how your data is
+represented in BSON. The {+driver-short+} uses the ``KSerializer``
+interface from the ``kotlinx.serialization`` package to implement custom
+serializers. You can specify the custom serializer as the parameter to
+the ``@Serializable`` annotation for a specific field.
+
+The following example shows how to create a custom
+``KSerializer`` instance to convert a ``kotlinx.datetime.Instant`` to a
+``BsonDateTime``:
+
+.. literalinclude:: /examples/generated/KotlinXSerializationTest.snippet.kserializer.kt
+    :language: kotlin
+
+The following code shows the ``PaintOrder`` data class in which the
+``orderDate`` field has an annotation that specifies the custom
+serializer class defined in the preceding code:
+
+.. literalinclude:: /examples/generated/KotlinXSerializationTest.snippet.kserializer-dataclass.kt
+    :language: kotlin
+    :emphasize-lines: 5
+
+For more information about the methods and classes mentioned in this section,
+see the following API documentation:
+
+- `KSerializer <{+kotlin-docs+}/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-k-serializer/>`__
+- `Instant <{+kotlin-docs+}/api/kotlinx-datetime/kotlinx-datetime/kotlinx.datetime/-instant/>`__
+- `BsonEncoder <{+api+}/apidocs/bson-kotlinx/bson-kotlinx/org.bson.codecs.kotlinx/-bson-encoder/index.html>`__
+- `BsonDecoder <{+api+}/apidocs/bson-kotlinx/bson-kotlinx/org.bson.codecs.kotlinx/-bson-decoder/index.html>`__
+
 .. _kotlin-custom-codec:
 
 Customize the Serializer Configuration
@@ -142,7 +173,10 @@ customize what is stored.
 Use the ``BsonConfiguration`` class to define the configuration, 
 including whether to encode defaults, encode nulls, or define class discriminators.
 
-To create a custom codec, install the ``bson-kotlinx`` dependency to your project.
+To create a custom codec, install the ``bson-kotlinx``
+dependency to your project. Select from the following tabs to see how to
+add the dependency to your project by using the :guilabel:`Gradle` and
+:guilabel:`Maven` package managers:
 
 .. tabs::
 
@@ -189,6 +223,9 @@ Then, you can define your codec using the
 <{+api+}/apidocs/bson-kotlinx/bson-kotlinx/org.bson.codecs.kotlinx/-kotlin-serializer-codec/-companion/index.html>`__
 method and add it to the registry.
 
+Custom Codec Example
+~~~~~~~~~~~~~~~~~~~~
+
 The following example shows how to create a codec using the 
 ``KotlinSerializerCodec.create()`` method and configure it to not encode defaults:
 
@@ -203,7 +240,7 @@ The following example shows how to create a codec using the
     :language: kotlin
 
 For more information about the methods and classes mentioned in this section,
-see the following API Documentation:
+see the following API documentation:
 
 - `KotlinSerializerCodec <{+api+}/apidocs/bson-kotlinx/bson-kotlinx/org.bson.codecs.kotlinx/-kotlin-serializer-codec/index.html>`__
 - `KotlinSerializerCodec.create() <{+api+}/apidocs/bson-kotlinx/bson-kotlinx/org.bson.codecs.kotlinx/-kotlin-serializer-codec/-companion/create.html>`__

source/quick-start.txt

@@ -48,7 +48,7 @@ Install Kotlin
 
 Make sure that your system has Kotlin installed and running on JDK 1.8 or later.
 For more information on getting started with Kotlin/JVM development,
-refer to `Get started with Kotlin/JVM <{+kotlin-docs+}/jvm-get-started.html>`__
+refer to `Get started with Kotlin/JVM <{+kotlin-docs+}/docs/jvm-get-started.html>`__
 in the Kotlin language documentation.
 
 Create the Project