From e331367bdcd83580b51cc0ef32d8fff89e6b9dec Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 19 Sep 2024 13:02:59 -0400 Subject: [PATCH 1/4] DOCSP-41865: datetime serializers --- source/whats-new.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/source/whats-new.txt b/source/whats-new.txt index c0b3c0f9..314a93cd 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -26,7 +26,8 @@ Learn what's new in: What's New in 5.2 ----------------- -New features of the 4.11 driver release include: +The 5.2 driver release includes the following new features, +improvements, and fixes: .. sharedinclude:: dbx/jvm/v5.2-wn-items.rst @@ -34,6 +35,10 @@ New features of the 4.11 driver release include: :ref:`kotlin-search-indexes` in the Indexes guide +- Adds support for serializers from the ``kotlinx-datetime`` library + that let you map to BSON as the expected types. To learn more, see the + :ref:`fundamentals-kotlin-serialization` guide. + .. _kotlin-coroutine-version-5.1.3: What's New in 5.1.3 From 97cf99045719d0245dd10aa8cdba4e2a6a65c6dc Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 20 Sep 2024 14:11:25 -0400 Subject: [PATCH 2/4] DOCSP-41865: datetime serializers --- .../test/kotlin/KotlinXSerializationTest.kt | 30 ++++++- snooty.toml | 1 + ...izationTest.snippet.datetime-data-class.kt | 6 ++ ...lizationTest.snippet.datetime-insertone.kt | 9 +++ .../data-formats/serialization.txt | 81 +++++++++++++++++++ source/whats-new.txt | 5 +- 6 files changed, 129 insertions(+), 3 deletions(-) create mode 100644 source/examples/generated/KotlinXSerializationTest.snippet.datetime-data-class.kt create mode 100644 source/examples/generated/KotlinXSerializationTest.snippet.datetime-insertone.kt diff --git a/examples/src/test/kotlin/KotlinXSerializationTest.kt b/examples/src/test/kotlin/KotlinXSerializationTest.kt index 2eb8e421..5839be6e 100644 --- a/examples/src/test/kotlin/KotlinXSerializationTest.kt +++ b/examples/src/test/kotlin/KotlinXSerializationTest.kt @@ -204,7 +204,6 @@ internal class KotlinXSerializationTest { val department: String, ) : Person // :snippet-end: - @Test fun polymorphicSerializationTest() = runBlocking { @@ -242,5 +241,34 @@ internal class KotlinXSerializationTest { collection.drop() } + // :snippet-start: datetime-data-class + @Serializable + data class Appointment( + val name: String, + @Contextual val date: LocalDate, + val time: LocalTime, + ) + // :snippet-end: + + @Test + fun dateTimeSerializationTest() = runBlocking { + + // :snippet-start: datetime-insertone + val collection = database.getCollection("appointments") + + val apptDoc = Appointment( + "Daria Smith", + LocalDate(2024, 10, 15), + LocalTime(hour = 11, minute = 30) + ) + + collection.insertOne(apptDoc) + // :snippet-end: + + assertEquals(apptDoc.name, "Daria Smith") + + collection.drop() + } + } diff --git a/snooty.toml b/snooty.toml index 6a9cc40c..333c144d 100644 --- a/snooty.toml +++ b/snooty.toml @@ -35,3 +35,4 @@ zstdVersion = "com.github.luben:zstd-jni:1.5.5-2" logbackVersion = "1.2.11" log4j2Version = "2.17.1" serializationVersion = "1.5.1" +kotlinx-dt-version = "0.6.1" diff --git a/source/examples/generated/KotlinXSerializationTest.snippet.datetime-data-class.kt b/source/examples/generated/KotlinXSerializationTest.snippet.datetime-data-class.kt new file mode 100644 index 00000000..0c9fe4ce --- /dev/null +++ b/source/examples/generated/KotlinXSerializationTest.snippet.datetime-data-class.kt @@ -0,0 +1,6 @@ +@Serializable +data class Appointment( + val name: String, + @Contextual val date: LocalDate, + val time: LocalTime, +) diff --git a/source/examples/generated/KotlinXSerializationTest.snippet.datetime-insertone.kt b/source/examples/generated/KotlinXSerializationTest.snippet.datetime-insertone.kt new file mode 100644 index 00000000..09b08c27 --- /dev/null +++ b/source/examples/generated/KotlinXSerializationTest.snippet.datetime-insertone.kt @@ -0,0 +1,9 @@ +val collection = database.getCollection("appointments") + +val apptDoc = Appointment( + "Daria Smith", + LocalDate(2024, 10, 15), + LocalTime(hour = 11, minute = 30) +) + +collection.insertOne(apptDoc) diff --git a/source/fundamentals/data-formats/serialization.txt b/source/fundamentals/data-formats/serialization.txt index d9147c13..9ae6feac 100644 --- a/source/fundamentals/data-formats/serialization.txt +++ b/source/fundamentals/data-formats/serialization.txt @@ -301,3 +301,84 @@ deserializes them accordingly. Retrieving as Document type Document{{_id=..., _t=Teacher, name=Vivian Lee, department=History}} Document{{_id=..., _t=Student, name=Kate Parker, grade=10}} + +.. _kotlin-datetime-serialization: + +Serialize Dates and Times +------------------------- + +In this section, you can learn about using {+language+} serialization to +work with date and time types. + +kotlinx-datetime Library +~~~~~~~~~~~~~~~~~~~~~~~~ + +``kotlinx-datetime`` is a {+language} library that allows +you to work with dates and times. If you want a high level of control +over how your date and time values are serialized, you can add the +dependency to your project's dependency list. + +Select from the following tabs to see how to add the ``kotlinx-datetime`` +dependency to your project by using the :guilabel:`Gradle` and +:guilabel:`Maven` package managers: + +.. tabs:: + + .. tab:: + :tabid: Gradle + + .. code-block:: kotlin + :caption: build.gradle.kts + + implementation("org.jetbrains.kotlinx:kotlinx-datetime:{+kotlinx-dt-version+}") + + .. tab:: + :tabid: Maven + + .. code-block:: kotlin + :caption: pom.xml + + + org.jetbrains.kotlinx + kotlinx-datetime-jvm + {+kotlinx-dt-version+} + + +To learn more about this library, see the :github:`kotlinx-datetime repository +` on GitHub. + +Example Data Class with Dates and Times +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After you add the library dependency, you can implement serializers from +the ``kotlinx-datetime`` library that map your data class field values +to the expected types in BSON. + +The following ``Appointment`` data class has the ``@Serializable`` +annotation and the ``@Contextual`` annotation on the ``date`` field +to use the ``kotlinx-datetime`` serializer for ``LocalDate`` values. +Values of the ``time`` field are stored as strings, because the driver +does not use a serializer without the ``@Contextual`` annotation: + +.. literalinclude:: /examples/generated/KotlinXSerializationTest.snippet.datetime-data-class.kt + :language: kotlin + +The following example inserts an instance of the ``Appointment`` data +class into MongoDB: + +.. literalinclude:: /examples/generated/KotlinXSerializationTest.snippet.datetime-insertone.kt + :language: kotlin + +In MongoDB, the ``LocalDate`` value is stored as a BSON date, and the +``time`` field is stored by using default serialization as a string: + +.. code-block:: json + + { + "_id": ..., + "name": "Daria Smith", + "date": { + "$date": "2024-10-15T00:00:00.000Z" + }, + "time": "11:30", + } diff --git a/source/whats-new.txt b/source/whats-new.txt index 314a93cd..98933ac0 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -36,8 +36,9 @@ improvements, and fixes: :ref:`kotlin-search-indexes` in the Indexes guide - Adds support for serializers from the ``kotlinx-datetime`` library - that let you map to BSON as the expected types. To learn more, see the - :ref:`fundamentals-kotlin-serialization` guide. + that let you map to BSON as the expected types instead of as strings. + To learn more, see the :ref:`kotlin-datetime-serialization` section of + the Kotlin Serialization guide. .. _kotlin-coroutine-version-5.1.3: From 67bcfc4ae3e9eada073be37cad47dc6f48dca2e1 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 20 Sep 2024 15:01:30 -0400 Subject: [PATCH 3/4] fixes --- .github/workflows/check-autobuilder.yml | 13 ------------- source/fundamentals/data-formats/serialization.txt | 2 +- 2 files changed, 1 insertion(+), 14 deletions(-) delete mode 100644 .github/workflows/check-autobuilder.yml diff --git a/.github/workflows/check-autobuilder.yml b/.github/workflows/check-autobuilder.yml deleted file mode 100644 index 8495db96..00000000 --- a/.github/workflows/check-autobuilder.yml +++ /dev/null @@ -1,13 +0,0 @@ -name: Check Autobuilder for Errors - -on: - pull_request: - paths: - - "source/**" - -jobs: - check: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: cbush/snooty-autobuilder-check@main diff --git a/source/fundamentals/data-formats/serialization.txt b/source/fundamentals/data-formats/serialization.txt index 9ae6feac..b541e2e0 100644 --- a/source/fundamentals/data-formats/serialization.txt +++ b/source/fundamentals/data-formats/serialization.txt @@ -313,7 +313,7 @@ work with date and time types. kotlinx-datetime Library ~~~~~~~~~~~~~~~~~~~~~~~~ -``kotlinx-datetime`` is a {+language} library that allows +``kotlinx-datetime`` is a {+language+} library that allows you to work with dates and times. If you want a high level of control over how your date and time values are serialized, you can add the dependency to your project's dependency list. From 760109a07f72d234bf0ab366de4c15024ae9f2b4 Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 23 Sep 2024 10:18:04 -0400 Subject: [PATCH 4/4] MW PR fixes 1 --- .../data-formats/serialization.txt | 24 ++++++++++++------- source/whats-new.txt | 7 +++--- 2 files changed, 19 insertions(+), 12 deletions(-) diff --git a/source/fundamentals/data-formats/serialization.txt b/source/fundamentals/data-formats/serialization.txt index b541e2e0..f42ceae1 100644 --- a/source/fundamentals/data-formats/serialization.txt +++ b/source/fundamentals/data-formats/serialization.txt @@ -313,9 +313,9 @@ work with date and time types. kotlinx-datetime Library ~~~~~~~~~~~~~~~~~~~~~~~~ -``kotlinx-datetime`` is a {+language+} library that allows -you to work with dates and times. If you want a high level of control -over how your date and time values are serialized, you can add the +``kotlinx-datetime`` is a {+language+} library that offers +a high level of control over how your date and time values +are serialized. To use the library, add the ``kotlinx-datetime`` dependency to your project's dependency list. Select from the following tabs to see how to add the ``kotlinx-datetime`` @@ -354,11 +354,17 @@ After you add the library dependency, you can implement serializers from the ``kotlinx-datetime`` library that map your data class field values to the expected types in BSON. -The following ``Appointment`` data class has the ``@Serializable`` -annotation and the ``@Contextual`` annotation on the ``date`` field -to use the ``kotlinx-datetime`` serializer for ``LocalDate`` values. -Values of the ``time`` field are stored as strings, because the driver -does not use a serializer without the ``@Contextual`` annotation: +In the following example, the driver serializes the fields of +the ``Appointment`` data class with the following behavior: + +- ``name``: The driver serializes the value as a string. + +- ``date``: The driver uses the ``kotlinx-datetime`` serializer + because the field has the ``@Contextual`` annotation. So, + ``LocalDate`` values are serialized as BSON dates. + +- ``time``: The driver serializes the value as a string because it does + not have the ``@Contextual`` annotation. .. literalinclude:: /examples/generated/KotlinXSerializationTest.snippet.datetime-data-class.kt :language: kotlin @@ -370,7 +376,7 @@ class into MongoDB: :language: kotlin In MongoDB, the ``LocalDate`` value is stored as a BSON date, and the -``time`` field is stored by using default serialization as a string: +``time`` field is stored as a string by default serialization: .. code-block:: json diff --git a/source/whats-new.txt b/source/whats-new.txt index 98933ac0..ffad74f5 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -36,9 +36,10 @@ improvements, and fixes: :ref:`kotlin-search-indexes` in the Indexes guide - Adds support for serializers from the ``kotlinx-datetime`` library - that let you map to BSON as the expected types instead of as strings. - To learn more, see the :ref:`kotlin-datetime-serialization` section of - the Kotlin Serialization guide. + that let you map {+language+} date and time types to BSON as the + expected types instead of as strings. To learn more, see the + :ref:`kotlin-datetime-serialization` section of the {+language+} + Serialization guide. .. _kotlin-coroutine-version-5.1.3: