Skip to content

Commit 7e440af

Browse files
lindseymoorelindseymoore
committed
merge
2 parents 3f88511 + 6bb165f commit 7e440af

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+1794
-71
lines changed

‎snooty.toml

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

99
toc_landing_pages = [
10+
"/get-started",
1011
"/read",
12+
"/connect",
1113
"/indexes",
1214
"/connect",
1315
"work-with-indexes",
16+
"/data-formats"
1417
]
1518

1619
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
@@ -20,9 +23,15 @@ driver-long = "MongoDB Kotlin Sync Driver"
2023
driver-short = "Kotlin Sync driver"
2124
language = "Kotlin"
2225
version-number = "5.1"
26+
full-version = "{+version-number+}.2"
2327
version = "v{+version-number+}"
24-
patch-version-number = "{+version-number+}.0"
2528
mdb-server = "MongoDB Server"
2629
stable-api = "Stable API"
2730
api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync"
28-
core-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-core/com/mongodb"
31+
<<<<<<< HEAD
32+
core-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-core/com/mongodb"
33+
=======
34+
java-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}"
35+
core-api = "{+java-api+}/apidocs/mongodb-driver-core/"
36+
kotlin-docs = "https://kotlinlang.org"
37+
>>>>>>> refs/remotes/upstream/master

‎source/connect.txt

Lines changed: 169 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,178 @@ Connect to MongoDB
1313
.. facet::
1414
:name: genre
1515
:values: reference
16-
16+
1717
.. meta::
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/mongoclient
26+
.. /connect/connection-targets
27+
.. /connect/connection-options
28+
.. /connect/tls
29+
.. /connect/network-compression
30+
.. /connect/server-selection
31+
.. /connect/stable-api
32+
.. /connect/csot
33+
34+
Overview
35+
--------
36+
37+
This page contains code examples that show how to use the
38+
{+driver-short+} to connect your application to MongoDB by specifying
39+
various settings.
40+
41+
.. .. tip::
42+
..
43+
.. To learn more about the connection options on this page, see the link
44+
.. provided in each section.
45+
46+
To use a connection example from this page, copy the code example into the
47+
:ref:`sample application <kotlin-sync-connect-sample>` or your own application.
48+
Be sure to replace all placeholders in the code examples, such as
49+
``<hostname>``, with the relevant values for your MongoDB deployment.
50+
51+
.. _kotlin-sync-connect-sample:
52+
53+
.. include:: /includes/usage-examples/sample-app-intro.rst
54+
55+
.. literalinclude:: /includes/usage-examples/connect-sample-app.kt
56+
:language: kotlin
57+
:copyable: true
58+
:linenos:
59+
:emphasize-lines: 6-8
60+
61+
Connection
62+
----------
63+
64+
The following sections describe how to connect to different targets,
65+
such as a local instance of MongoDB or a cloud-hosted instance on Atlas.
66+
67+
Local Deployment
68+
~~~~~~~~~~~~~~~~
69+
70+
The following code shows the connection string to connect to a local
71+
instance of MongoDB:
72+
73+
.. code-block:: kotlin
74+
75+
val uri = "mongodb://localhost:27017/"
76+
val mongoClient = MongoClient.create(uri)
77+
78+
Atlas
79+
~~~~~
80+
81+
The following code shows the connection string to connect to a
82+
deployment hosted on Atlas:
83+
84+
.. code-block:: kotlin
85+
86+
val uri = "mongodb+srv://<username>:<password>@<hostname/port>/?<options>"
87+
val mongoClient = MongoClient.create(uri)
88+
89+
Replica Set
90+
~~~~~~~~~~~
91+
92+
The following code shows the connection string to connect to a
93+
replica set:
94+
95+
.. code-block:: kotlin
96+
97+
val uri = "mongodb://<replica set member>:<port>/?replicaSet=<replica set name>"
98+
val mongoClient = MongoClient.create(uri)
99+
100+
Transport Layer Security (TLS)
101+
------------------------------
102+
103+
The following sections describe how to connect to MongoDB
104+
while enabling the TLS protocol.
105+
106+
Enable TLS
107+
~~~~~~~~~~
108+
109+
The following tabs demonstrate how to enable TLS on a connection:
110+
111+
.. include:: /includes/connect/tls-tabs.rst
112+
113+
.. To learn more about enabling TLS, see :ref:`kotlin-sync-enable-tls` in
114+
.. the TLS configuration guide.
115+
116+
Disable Hostname Verification
117+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
118+
119+
The following tabs demonstrate how to disable hostname verification when
120+
connecting by using TLS:
121+
122+
.. include:: /includes/connect/disable-host-verification-tabs.rst
123+
124+
.. To learn more about disabling hostname verification, see :ref:`kotlin-sync-insecure-tls` in
125+
.. the TLS configuration guide.
126+
127+
Network Compression
128+
-------------------
129+
130+
The following sections describe how to connect to MongoDB
131+
while specifying network compression algorithms.
132+
133+
Compression Algorithms
134+
~~~~~~~~~~~~~~~~~~~~~~
135+
136+
The following tabs demonstrate how to specify all available compressors
137+
while connecting to MongoDB:
138+
139+
.. include:: /includes/connect/compression-tabs.rst
140+
141+
.. To learn more about specifying compression algorithms, see
142+
.. :ref:`kotlin-sync-enable-compression` in the Network Compression guide.
143+
144+
zlib Compression Level
145+
~~~~~~~~~~~~~~~~~~~~~~
146+
147+
The following tabs demonstrate how to specify a compression level for
148+
the ``zlib`` compressor:
149+
150+
.. include:: /includes/connect/zlib-level-tabs.rst
151+
152+
.. To learn more about setting the zlib compression level, see
153+
.. :ref:`kotlin-sync-enable-compression` in the Network Compression guide.
154+
155+
Server Selection
156+
----------------
157+
158+
The following code shows a connection string that specifies a server
159+
selection function:
160+
161+
.. code-block:: kotlin
162+
163+
val client = MongoClient.create("mongodb://<username>:<password>@<hostname>:<port>",
164+
server_selector=<selector function>)
165+
166+
.. To learn more about customizing server selection, see
167+
.. :ref:`kotlin-sync-server-selection`.
168+
169+
{+stable-api+}
170+
--------------
171+
172+
The following code shows how to specify Stable API settings within a
173+
``MongoClientSettings`` instance:
174+
175+
.. code-block:: kotlin
176+
177+
val serverApi = ServerApi.builder()
178+
.version(ServerApiVersion.V1)
179+
.build()
180+
181+
val uri = "<connection string>"
182+
183+
val settings = MongoClientSettings.builder()
184+
.applyConnectionString(ConnectionString(uri))
185+
.serverApi(serverApi)
186+
.build()
24187

25-
/connect/stable-api
188+
val client = MongoClient.create(settings)
26189

190+
.. To learn more about the {+stable-api+}, see :ref:`kotlin-sync-stable-api`.

‎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+
26+
.. TODO: /data-formats/data-class
27+
.. TODO: /data-formats/extended-json
28+
.. TODO: /data-formats/time-series
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:`BSON <kotlin-sync-bson>` guide.
38+
39+
.. TODO: Uncomment these as pages get built
40+
.. - Learn how to store and retrieve data using {+language+} data classes in the :ref:`data-classes` guide.
41+
.. - Learn how to use the Extended JSON format in the :ref:`kotlin-sync-extended-json` guide.
42+
.. - Learn how to store and interact with time series data in the :ref:`kotlin-sync-time-series` 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+
Document Data Format: 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/>`__.

‎source/get-started.txt

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
.. _kotlin-sync-get-started:
2+
3+
=======================================
4+
Get Started with the Kotlin Sync Driver
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: tutorial
16+
17+
.. meta::
18+
:description: Learn how to create an app to connect to MongoDB deployment by using the Kotlin Sync driver.
19+
:keywords: quick start, tutorial, basics
20+
21+
.. toctree::
22+
23+
/get-started/download-and-install/
24+
/get-started/create-a-deployment/
25+
/get-started/create-a-connection-string/
26+
/get-started/connect-to-mongodb/
27+
/get-started/next-steps/
28+
29+
Overview
30+
--------
31+
32+
You can use the {+driver-short+} to connect to and communicate with
33+
MongoDB. This guide shows you how to create an application that uses
34+
the {+driver-short+} to connect to a MongoDB cluster hosted on
35+
MongoDB Atlas and interact with data.
36+
37+
.. tip::
38+
39+
MongoDB Atlas is a fully managed cloud database service that hosts your MongoDB
40+
deployments. You can create your own free (no credit card required) MongoDB Atlas
41+
deployment by following the steps in this guide.
42+
43+
Follow this guide to connect a sample {+language+} application to a MongoDB Atlas
44+
deployment. If you prefer to connect to MongoDB using a different driver or
45+
programming language, see the :driver:`list of official MongoDB drivers <>`.
46+
47+
.. button:: Next: Download and Install
48+
:uri: /get-started/download-and-install/

0 commit comments

Comments
 (0)