Skip to content

Commit 4af1e74

Browse files
rachel-mackrachel-mack
committed
get started merge
1 parent b4ad08a commit 4af1e74

8 files changed

+268
-285
lines changed

‎snooty.toml

-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
88

99
toc_landing_pages = [
1010
"/write-operations",
11-
"/get-started",
1211
"/read",
1312
"/connect",
1413
"/indexes",

‎source/get-started.txt

+267-8
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,6 @@ Get Started with the Kotlin Sync Driver
1818
:description: Learn how to create an app to connect to MongoDB deployment by using the Kotlin Sync driver.
1919
:keywords: quick start, tutorial, basics
2020

21-
.. toctree::
22-
23-
Download & Install </get-started/download-and-install/>
24-
Create a Deployment </get-started/create-a-deployment/>
25-
Create a Connection String </get-started/create-a-connection-string/>
26-
Run a Sample Query </get-started/run-sample-query/>
27-
Next Steps </get-started/next-steps/>
28-
2921
Overview
3022
--------
3123

@@ -43,3 +35,270 @@ MongoDB Atlas and interact with data.
4335
Follow this guide to connect a sample {+language+} application to a MongoDB Atlas
4436
deployment. If you prefer to connect to MongoDB using a different driver or
4537
programming language, see the :driver:`list of official MongoDB drivers <>`.
38+
39+
.. _kotlin-sync-download-install:
40+
41+
Download and Install
42+
--------------------
43+
44+
This guide demonstrates how to create a project and add the
45+
{+driver-short+} dependencies by using `Gradle <https://gradle.org/>`__
46+
or `Maven <https://maven.apache.org/>`__.
47+
48+
.. procedure::
49+
:style: connected
50+
51+
.. step:: Create a {+language+} Project
52+
53+
First, make sure that your system has {+language+} installed and
54+
running on JDK 1.8 or later.
55+
56+
We recommend that you use an integrated development
57+
environment (IDE) such as IntelliJ IDEA or Eclipse IDE to
58+
configure Gradle or Maven to build and run your project.
59+
60+
.. tip::
61+
62+
If you are not using an IDE, see the
63+
`Creating New Gradle Builds
64+
<https://guides.gradle.org/creating-new-gradle-builds/>`__ guide
65+
or the `Building Maven
66+
<https://maven.apache.org/guides/development/guide-building-maven.html>`__ guide
67+
for more information on how to set up your project.
68+
69+
For more information on getting started with
70+
{+language+} and creating your first project, see `Get started with Kotlin/JVM
71+
<{+kotlin-docs+}/docs/jvm-get-started.html>`__ in the {+language+}
72+
language documentation.
73+
74+
.. step:: Add MongoDB as a Dependency
75+
76+
If you are using Gradle to manage your
77+
packages, add the following entry to your ``build.gradle.kts``
78+
dependencies list:
79+
80+
.. include:: /includes/kotlin-sync-driver-gradle-versioned.rst
81+
82+
If you are using Maven to manage your
83+
packages, add the following entry to your ``pom.xml`` dependencies list:
84+
85+
.. include:: /includes/kotlin-sync-driver-maven-versioned.rst
86+
87+
After you configure your dependencies, ensure that they are
88+
available to your project by running the dependency manager and
89+
refreshing the project in your IDE.
90+
91+
.. step:: Add Serialization Library Dependencies
92+
93+
To enable the driver to convert between {+language+} objects and BSON, the
94+
data format for documents in MongoDB, you must also add one or both of the
95+
following serialization packages to your application:
96+
97+
- ``bson-kotlinx`` *(Recommended)*
98+
- ``bson-kotlin``
99+
100+
If you are using Gradle to manage your packages, add one of the following
101+
entries to your ``build.gradle.kts`` dependencies list:
102+
103+
.. include:: /includes/serialization-libs-gradle-versioned.rst
104+
105+
If you are using Maven to manage your packages, add one of the following
106+
entries to your ``pom.xml`` dependencies list:
107+
108+
.. include:: /includes/serialization-libs-maven-versioned.rst
109+
110+
After you configure your dependencies, ensure that they are available to your
111+
project by running the dependency manager and refreshing the
112+
project in your IDE.
113+
114+
.. To learn more about these packages, see
115+
.. :ref:`kotlin-sync-serialization`.
116+
117+
After you complete these steps, you have a new project directory
118+
and the driver dependencies installed.
119+
120+
.. _kotlin-sync-get-started-create-deployment:
121+
122+
Create a MongoDB Deployment
123+
---------------------------
124+
125+
You can create a free tier MongoDB deployment on MongoDB Atlas
126+
to store and manage your data. MongoDB Atlas hosts and manages
127+
your MongoDB database in the cloud.
128+
129+
.. procedure::
130+
:style: connected
131+
132+
.. step:: Create a Free MongoDB deployment on Atlas
133+
134+
Complete the :atlas:`Get Started with Atlas </getting-started>`
135+
guide to set up a new Atlas account and load sample data into a new free
136+
tier MongoDB deployment.
137+
138+
.. step:: Save your Credentials
139+
140+
After you create your database user, save the user's
141+
username and password to a safe location for use in an upcoming step.
142+
143+
After you complete these steps, you have a new free tier MongoDB
144+
deployment on Atlas, database user credentials, and sample data loaded
145+
in your database.
146+
147+
.. _kotlin-sync-get-started-connection-string:
148+
149+
Create a Connection String
150+
--------------------------
151+
152+
You can connect to your MongoDB deployment by providing a
153+
**connection URI**, also called a *connection string*, which
154+
instructs the driver on how to connect to a MongoDB deployment
155+
and how to behave while connected.
156+
157+
The connection string includes the hostname or IP address and
158+
port of your deployment, the authentication mechanism, user credentials
159+
when applicable, and connection options.
160+
161+
To connect to an instance or deployment not hosted on Atlas, see the :ref:`kotlin-sync-connection-targets` guide.
162+
163+
.. procedure::
164+
:style: connected
165+
166+
.. step:: Find your MongoDB Atlas Connection String
167+
168+
To retrieve your connection string for the deployment that
169+
you created in the :ref:`previous step <kotlin-sync-get-started-create-deployment>`,
170+
log into your Atlas account, navigate to the
171+
:guilabel:`Database` section, then click the :guilabel:`Connect` button
172+
for your new deployment.
173+
174+
.. figure:: /includes/figures/atlas_connection_select_cluster.png
175+
:alt: The connect button in the clusters section of the Atlas UI
176+
177+
Proceed to the :guilabel:`Connect your application` section, then select
178+
**{+language+}** from the :guilabel:`Driver` selection menu.
179+
180+
Select the :guilabel:`Password (SCRAM)` authentication mechanism.
181+
182+
Deselect the :guilabel:`Include full driver code example` option to view
183+
only the connection string.
184+
185+
.. step:: Copy your Connection String
186+
187+
Click the button on the right of the connection string to copy it to
188+
your clipboard as shown in the following screenshot:
189+
190+
.. figure:: /includes/figures/atlas_connection_copy_string_kotlin.png
191+
:alt: The connection string copy button in the Atlas UI
192+
193+
.. step:: Update the Placeholders
194+
195+
Paste this connection string into a file in your preferred text editor
196+
and replace the ``<username>`` and ``<password>`` placeholders with
197+
your database user's username and password.
198+
199+
Save this file to a safe location to use in the next step.
200+
201+
After completing these steps, you have a connection string that
202+
contains your database username and password.
203+
204+
.. _kotlin-sync-connect-to-mongodb:
205+
.. _kotlin-sync-run-sample-query:
206+
207+
Run a Sample Query
208+
------------------
209+
210+
.. procedure::
211+
:style: connected
212+
213+
.. step:: Create the Application File
214+
215+
Create a file called ``DemoDataClassExample.kt`` in your project.
216+
217+
Copy the following sample code into the file and replace the value of
218+
the ``<connection URI string>`` placeholder with your MongoDB
219+
Atlas connection string that you saved in the preceding step.
220+
221+
.. literalinclude:: /includes/get-started/DemoDataClassExample.kt
222+
:language: kotlin
223+
:caption: DemoDataClassExample.kt
224+
225+
.. note::
226+
227+
This example uses a {+language+} data class to model MongoDB data.
228+
229+
.. step:: Run the Application
230+
231+
When you run the application, it prints the details
232+
of a movie document that matches the query, as shown in the
233+
following output:
234+
235+
.. code-block:: none
236+
:copyable: false
237+
238+
Movie(title=Before Sunrise, year=1995, directors=[Richard Linklater])
239+
240+
If you don't see any output or receive an error, check whether you
241+
included the proper connection string in your application. Also, confirm
242+
that you successfully loaded the sample dataset into your MongoDB Atlas cluster.
243+
244+
After completing this step, you have a working application that uses
245+
the {+driver-short+} to connect to your MongoDB cluster, run a query on the
246+
sample data, and print out the result.
247+
248+
.. step:: Use the Document Class to Model Data (Alternative)
249+
250+
The preceding step demonstrates how to run a query on a sample
251+
collection to retrieve data by using a {+language+} data class. This section
252+
shows how to use the `Document <https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/bson/org/bson/Document.html>`__
253+
class to store and retrieve data from MongoDB.
254+
255+
In a file called ``DemoDocumentExample.kt``, paste the following sample
256+
code to run a query on your sample dataset in MongoDB Atlas. Replace the
257+
value of the ``<connection URI string>`` placeholder with your
258+
MongoDB Atlas connection string:
259+
260+
.. literalinclude:: /includes/get-started/DemoDocumentExample.kt
261+
:caption: DemoDocumentExample.kt
262+
:language: kotlin
263+
264+
When you run the application, it prints the details
265+
of a movie document that matches the query, as shown in the
266+
following output:
267+
268+
.. code-block:: none
269+
:copyable: false
270+
271+
Document{{_id=..., plot=A young man and woman ..., genres=[Drama, Romance], ...}}
272+
273+
If you don't see any output or receive an error, check whether you
274+
included the proper connection string in your application. Also, confirm
275+
that you successfully loaded the sample dataset into your MongoDB
276+
Atlas cluster.
277+
278+
After you complete these steps, you have a working application that
279+
uses the driver to connect to your MongoDB deployment, runs a query on
280+
the sample data, and prints out the result.
281+
282+
.. TODO add after output .. tip:: Data Classes
283+
..
284+
.. To learn more about using data classes to store and retrieve data,
285+
.. see the :ref:`fundamentals-data-classes` guide.
286+
287+
.. _kotlin-sync-get-started-next-steps:
288+
289+
Next Steps
290+
----------
291+
292+
Congratulations on completing the tutorial!
293+
294+
.. include:: /includes/get-started/quickstart-troubleshoot.rst
295+
296+
In this tutorial, you created a {+language+} application that
297+
connects to a MongoDB deployment hosted on MongoDB Atlas
298+
and retrieves a document that matches a query.
299+
300+
Learn more about the {+driver-short+} from the following resources:
301+
302+
- Learn how to perform read operations in the :ref:`<kotlin-sync-read>` section.
303+
304+
- Learn how to perform write operations in the :ref:`<kotlin-sync-write>` section.

‎source/get-started/create-a-connection-string.txt

-59
This file was deleted.

‎source/get-started/create-a-deployment.txt

-30
This file was deleted.

0 commit comments

Comments
 (0)