Skip to content

Commit 4ddb4d8

Browse files
rustagirrustagir
committed
Merge branch 'master' of github.com:mongodb/docs-kotlin-sync into DOCSP-41130-bulk
2 parents 0f02d52 + 9283b2e commit 4ddb4d8

25 files changed

+984
-68
lines changed

‎snooty.toml

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,13 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
77
]
88

99
toc_landing_pages = [
10+
"/write-operations",
1011
"/get-started",
1112
"/read",
1213
"/connect",
1314
"/indexes",
1415
"work-with-indexes",
16+
"/data-formats"
1517
]
1618

1719
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
@@ -26,5 +28,6 @@ version = "v{+version-number+}"
2628
mdb-server = "MongoDB Server"
2729
stable-api = "Stable API"
2830
api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync"
31+
java-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}"
32+
core-api = "{+java-api+}/apidocs/mongodb-driver-core/"
2933
kotlin-docs = "https://kotlinlang.org"
30-
core-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-core"

‎source/connect.txt

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,17 +18,18 @@ Connect to MongoDB
1818
:description: Learn how to use the Kotlin Sync driver to connect to MongoDB.
1919
:keywords: client, ssl, tls, localhost
2020

21-
.. .. toctree::
22-
.. :titlesonly:
23-
.. :maxdepth: 1
21+
.. toctree::
22+
:titlesonly:
23+
:maxdepth: 1
24+
25+
/connect/stable-api
2426
..
2527
.. /connect/mongoclient
2628
.. /connect/connection-targets
2729
.. /connect/connection-options
2830
.. /connect/tls
2931
.. /connect/network-compression
3032
.. /connect/server-selection
31-
.. /connect/stable-api
3233
.. /connect/csot
3334

3435
Overview

‎source/connect/stable-api.txt

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
.. _kotlin-sync-stable-api:
2+
3+
==============
4+
{+stable-api+}
5+
==============
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: compatible, backwards, upgrade
19+
20+
.. note::
21+
22+
The {+stable-api+} feature requires {+mdb-server+} 5.0 or later.
23+
24+
Overview
25+
--------
26+
27+
In this guide, you can learn how to specify **{+stable-api+}** compatibility when
28+
connecting to a MongoDB deployment.
29+
30+
The {+stable-api+} feature forces the server to run operations with behaviors compatible
31+
with the API version you specify. When you update either your driver or server,
32+
the API version changes, which can change the way these operations behave.
33+
Using the {+stable-api+} ensures consistent responses from the server and
34+
provides long-term API stability for your application.
35+
36+
The following sections describe how you can enable and customize {+stable-api+} for
37+
your MongoDB client. For more information about the {+stable-api+}, including a list of
38+
the commands it supports, see :manual:`Stable API </reference/stable-api/>` in the
39+
{+mdb-server+} manual.
40+
41+
Enable the {+stable-api+}
42+
-------------------------
43+
44+
To enable the {+stable-api+}, perform the following steps:
45+
46+
1. Construct a ``ServerApi`` object and specify a {+stable-api+} version. You must use
47+
a {+stable-api+} version defined in the ``ServerApiVersion`` enum.
48+
#. Construct a ``MongoClientSettings`` object using the ``MongoClientSettings.Builder`` class.
49+
#. Instantiate a ``MongoClient`` using the ``MongoClient.create()`` method and
50+
pass your ``MongoClientSettings`` instance as a parameter.
51+
52+
The following code example shows how to specify {+stable-api+} version 1:
53+
54+
.. literalinclude:: /includes/connect/stable-api.kt
55+
:start-after: start-enable-stable-api
56+
:end-before: end-enable-stable-api
57+
:language: kotlin
58+
:copyable:
59+
:dedent:
60+
61+
Once you create a ``MongoClient`` instance with
62+
a specified API version, all commands you run with the client use the specified
63+
version. If you must run commands using more than one version of the
64+
{+stable-api+}, create a new ``MongoClient``.
65+
66+
.. _stable-api-options:
67+
68+
Configure the {+stable-api+}
69+
----------------------------
70+
71+
The following table describes the parameters of the ``ServerApi`` class. You can use these
72+
parameters to customize the behavior of the {+stable-api+}.
73+
74+
.. list-table::
75+
:header-rows: 1
76+
:stub-columns: 1
77+
:widths: 25,75
78+
79+
* - Option Name
80+
- Description
81+
82+
* - strict
83+
- | **Optional**. When ``True``, if you call a command that isn't part of
84+
the declared API version, the driver raises an exception.
85+
|
86+
| Default: **False**
87+
88+
* - deprecationErrors
89+
- | **Optional**. When ``True``, if you call a command that is deprecated in the
90+
declared API version, the driver raises an exception.
91+
|
92+
| Default: **False**
93+
94+
The following code example shows how you can set the two options on an instance of ``ServerApi``
95+
by chaining methods on the ``ServerApi.Builder``:
96+
97+
.. literalinclude:: /includes/connect/stable-api-options.kt
98+
:start-after: start-stable-api-options
99+
:end-before: end-stable-api-options
100+
:language: kotlin
101+
:copyable:
102+
:dedent:
103+
104+
Troubleshooting
105+
---------------
106+
107+
Unrecognized field 'apiVersion' on server
108+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
109+
110+
The {+driver-short+} raises this exception if you specify an API version and connect to a
111+
MongoDB server that doesn't support the {+stable-api+}. Ensure you're connecting to a
112+
deployment running {+mdb-server+} v5.0 or later.
113+
114+
Provided apiStrict:true, but the command count is not in API Version
115+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
116+
117+
The {+driver-short+} raises this exception if your ``MongoClient`` runs an operation that
118+
isn't in the {+stable-api+} version you specified. To avoid this error, use an alternative
119+
operation supported by the specified {+stable-api+} version, or set the ``strict``
120+
option to ``False`` when constructing your ``ServerApi`` object.
121+
122+
API Documentation
123+
-----------------
124+
125+
For more information about using the {+stable-api+} with {+driver-short+}, see the
126+
following API documentation:
127+
128+
- `ServerApi <{+core-api+}com/mongodb/ServerApi.html>`__
129+
- `ServerApi.Builder <{+core-api+}com/mongodb/ServerApi.Builder.html>`__
130+
- `ServerApiVersion <{+core-api+}com/mongodb/ServerApiVersion.html>`__
131+
- `ServerAddress <{+core-api+}com/mongodb/ServerAddress.html>`__
132+
- `MongoClientSettings <{+core-api+}com/mongodb/MongoClientSettings.html>`__
133+
- `MongoClientSettings.Builder <{+core-api+}com/mongodb/MongoClientSettings.Builder.html>`__
134+
- `MongoClient <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__
135+
- `MongoClient.create() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/-factory/create.html>`__

‎source/data-formats.txt

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
.. _kotlin-sync-data-formats:
2+
3+
========================
4+
Specialized Data Formats
5+
========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: bson, data, class, date, time
19+
20+
.. toctree::
21+
:titlesonly:
22+
:maxdepth: 1
23+
24+
/data-formats/bson
25+
/data-formats/time-series
26+
27+
.. TODO: /data-formats/data-class
28+
.. TODO: /data-formats/extended-json
29+
30+
Overview
31+
--------
32+
33+
You can use several types of specialized document data formats in your {+driver-short+}
34+
application. To learn how to work with these data formats, see the following
35+
sections:
36+
37+
- Learn how to work with the BSON data format in the :ref:`kotlin-sync-bson` guide.
38+
- Learn how to store and interact with time series data in the :ref:`kotlin-sync-time-series` guide.
39+
40+
.. TODO: Uncomment these as pages get built
41+
.. - Learn how to store and retrieve data using {+language+} data classes in the :ref:`data-classes` guide.
42+
.. - Learn how to use the Extended JSON format in the :ref:`kotlin-sync-extended-json` guide.

‎source/data-formats/bson.txt

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
.. _kotlin-sync-bson:
2+
3+
====
4+
BSON
5+
====
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
In this guide, you can learn about the BSON data format, how MongoDB
17+
uses BSON to organize and store data, and how to install the BSON library independently of
18+
the {+driver-short+}.
19+
20+
BSON Data Format
21+
----------------
22+
23+
**BSON**, or Binary JSON, is the data format that MongoDB uses to organize
24+
and store data. This data format includes all JSON data structure types and
25+
adds support for types including dates, differently-sized integers (32-bit and 64-bit),
26+
ObjectIds, and binary data. For a complete list of supported types, see the
27+
:manual:`BSON Types </reference/bson-types>` in the {+mdb-server+} documentation.
28+
29+
BSON is not human-readable, but you can use the
30+
:ref:`BSON library <install-bson-library>` to convert it to the human-readable JSON
31+
representation. You can read more about the relationship between these
32+
formats in the :website:`JSON and BSON </json-and-bson>` guide on the MongoDB website.
33+
34+
MongoDB and BSON
35+
----------------
36+
37+
You can work with BSON data in your {+driver-short+} application by using one of the
38+
following object types that implements the `BSON interface <{+java-api+}/apidocs/bson/org/bson/conversions/Bson.html>`__:
39+
40+
- `Document <{+java-api+}/apidocs/bson/org/bson/Document.html>`__ (BSON library package)
41+
- `BsonDocument <{+java-api+}/apidocs/bson/org/bson/BsonDocument.html>`__ (BSON library package)
42+
- `RawBsonDocument <{+java-api+}/apidocs/bson/org/bson/RawBsonDocument.html>`__ (BSON library package)
43+
- `JsonObject <{+java-api+}/apidocs/bson/org/bson/json/JsonObject.html>`__ (BSON library package)
44+
45+
.. _install-bson-library:
46+
47+
Install the BSON Library
48+
------------------------
49+
50+
These instructions detail how to add the BSON library as a dependency to
51+
your project.
52+
53+
.. note::
54+
55+
If you have already added the {+driver-short+} as a dependency to your
56+
project, then you can skip this step. This is because the BSON library is already
57+
included as a required dependency of the driver.
58+
59+
.. TODO: For instructions on how to add the
60+
.. MongoDB Kotlin driver as a dependency to your project, see the
61+
.. :ref:`driver installation <kotlin-sync-download-install>` section of our Get Started
62+
.. guide.
63+
64+
We recommend that you use the `Maven <https://maven.apache.org/>`__ or
65+
`Gradle <https://gradle.org/>`__ build automation tool to manage your {+language+}
66+
project's dependencies. The following instructions detail the dependency declarations for
67+
both Maven and Gradle:
68+
69+
.. tabs::
70+
71+
.. tab:: Maven
72+
:tabid: maven-dependencies
73+
74+
The following snippet shows the dependency declaration in the
75+
``dependencies`` section of your ``pom.xml`` file.
76+
77+
.. include:: /includes/data-formats/bson-maven-versioned.rst
78+
79+
.. tab:: Gradle
80+
:tabid: gradle-dependencies
81+
82+
The following snippet shows the dependency declaration in the
83+
``dependencies`` object in your ``build.gradle`` file.
84+
85+
.. include:: /includes/data-formats/bson-gradle-versioned.rst
86+
87+
If you are not using either of the preceding tools, then you can include the BSON dependency
88+
in your project by downloading the JAR file directly from the
89+
`sonatype repository <https://repo1.maven.org/maven2/org/mongodb/bson/>`__.

0 commit comments

Comments
 (0)