Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCSP-28748: bson-kotlin dependency #147

Merged
merged 5 commits into from
Jan 23, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 38 additions & 14 deletions source/fundamentals/data-formats/serialization.txt
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,13 @@
Kotlin Serialization
====================

.. facet::
:name: genre
:values: reference

.. meta::
:keywords: code example, data model, conversion

.. contents:: On this page
:local:
:backlinks: none
Expand All @@ -13,23 +20,26 @@ Kotlin Serialization
Overview
--------

The Kotlin driver supports the ``kotlinx.serialization`` library for serializing
and deserializing Kotlin objects.
The Kotlin driver supports the ``kotlinx.serialization`` library for
serializing and deserializing Kotlin objects.

The driver provides an efficient ``Bson`` serializer that can can be used with
The driver provides an efficient ``Bson`` serializer that you can use with
classes marked as ``@Serializable`` to handle the serialization of Kotlin objects
to BSON data.
The ``bson-kotlinx`` library also supports :ref:`custom codecs <kotlin-custom-codec>`
with configurations to encode defaults, encode nulls, and define class
discriminators.
to BSON data.

You can also install the ``bson-kotlinx`` library to support
:ref:`custom codecs <kotlin-custom-codec>` with configurations to encode
defaults, encode nulls, and define class discriminators.

.. note::

To use the ``Codec`` interface instead of the Kotlin serialization library
to specify custom encoding and decoding of Kotlin objects to BSON data,
see the :ref:`Codecs <fundamentals-codecs>` documentation. You might choose
Kotlin serialization if you are already familiar with the framework or
you prefer to use an idiomatic Kotlin approach.
To learn how to use the ``Codec`` interface instead of the
Kotlin serialization library to specify custom encoding and decoding
of Kotlin objects to BSON data, see the :ref:`Codecs
<fundamentals-codecs>` guide.

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``
library, the ``Json`` serializer does *not* directly support BSON value types such
Expand Down Expand Up @@ -162,8 +172,22 @@ To create a custom codec, install the ``bson-kotlinx`` dependency to your projec
<version>{+full-version+}</version>
</dependency>

Then, you can define your codec using the `KotlinSerializerCodec.create() <apidocs/bson-kotlinx/bson-kotlinx/org.bson.codecs.kotlinx/-kotlin-serializer-codec/-companion/create.html>`__
method and add it to the registry.
.. note:: bson-kotlin Dependency

You can also optionally install the ``bson-kotlin`` dependency
through the default codec registry. This dependency uses reflection
and the codec registry to support Kotlin data classes, but it does
not support certain POJO annotations such as ``BsonDiscriminator``,
``BsonExtraElements``, and ``BsonConstructor``. To learn more, see
the `bson-kotlin API documentation <{+api+}/apidocs/bson-kotlin/index.html>`__.

Generally, we recommend that you install and use the faster
``bson-kotlinx`` library for codec configuration.

Then, you can define your codec using the
`KotlinSerializerCodec.create()
<{+api+}/apidocs/bson-kotlinx/bson-kotlinx/org.bson.codecs.kotlinx/-kotlin-serializer-codec/-companion/index.html>`__
method and add it to the registry.

The following example shows how to create a codec using the
``KotlinSerializerCodec.create()`` method and configure it to not encode defaults:
Expand Down
Loading