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/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..c6194c05 100644 --- a/source/fundamentals/data-formats/serialization.txt +++ b/source/fundamentals/data-formats/serialization.txt @@ -301,3 +301,91 @@ 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 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`` +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. + +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. ``LocalDate`` + values are serialized as BSON dates. + +- ``time``: The driver serializes the value as a string because it does + not have the ``@Contextual`` annotation. This is the default + serialization behavior for ``LocalTime`` values. + +.. 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 as a string by default serialization: + +.. 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 f0fc50bc..714607e5 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,12 @@ 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 {+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. + - Supports serialization of `JsonElement <{+kotlin-docs+}/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/>`__ values. To work with the ``JsonElement`` type, you must add the