Skip to content

Commit eaa2386

Browse files
rustagirrustagir
authored
DOCSP-41115: get started (#7)
* DOCSP-41115: get started * wip * wip * wip * wip * wip * wip * MM PR fixes 1 * MM PR fixes 2 * delete qs file * fix sc + link
1 parent 7ce8c73 commit eaa2386

18 files changed

+438
-14
lines changed

‎snooty.toml

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

99
toc_landing_pages = [
10+
"/get-started",
1011
"/read",
1112
"/connect",
1213
"/indexes",
@@ -20,9 +21,10 @@ driver-long = "MongoDB Kotlin Sync Driver"
2021
driver-short = "Kotlin Sync driver"
2122
language = "Kotlin"
2223
version-number = "5.1"
24+
full-version = "{+version-number+}.2"
2325
version = "v{+version-number+}"
24-
patch-version-number = "{+version-number+}.0"
2526
mdb-server = "MongoDB Server"
2627
stable-api = "Stable API"
2728
api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync"
29+
kotlin-docs = "https://kotlinlang.org"
2830
core-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-core/"

‎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/

‎source/get-started/connect-to-mongodb.txt

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
.. _kotlin-sync-connect-to-mongodb:
2+
3+
==================
4+
Connect to MongoDB
5+
==================
6+
7+
.. procedure::
8+
:style: connected
9+
10+
.. step:: Create the Application File
11+
12+
Create a file called ``DemoDataClassExample.kt`` in your project.
13+
14+
Copy the following sample code into the file and replace the value of
15+
the ``<connection URI string>`` placeholder with your MongoDB
16+
Atlas connection string that you saved in the preceding step.
17+
18+
.. literalinclude:: /includes/get-started/DemoDataClassExample.kt
19+
:language: kotlin
20+
:caption: DemoDataClassExample.kt
21+
22+
.. note::
23+
24+
This example uses a {+language+} data class to model MongoDB data.
25+
26+
.. step:: Run the Application
27+
28+
When you run the application, it prints the details
29+
of a movie document that matches the query, as shown in the
30+
following output:
31+
32+
.. code-block:: none
33+
:copyable: false
34+
35+
Movie(title=Before Sunrise, year=1995, directors=[Richard Linklater])
36+
37+
If you don't see any output or receive an error, check whether you
38+
included the proper connection string in your application. Also, confirm
39+
that you successfully loaded the sample dataset into your MongoDB Atlas cluster.
40+
41+
After completing this step, you have a working application that uses
42+
the {+driver-short+} to connect to your MongoDB cluster, run a query on the
43+
sample data, and print out the result.
44+
45+
.. step:: Use the Document Class to Model Data (Alternative)
46+
47+
The preceding step demonstrates how to run a query on a sample
48+
collection to retrieve data by using a {+language+} data class. This section
49+
shows how to use the `Document <https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/bson/org/bson/Document.html>`__
50+
class to store and retrieve data from MongoDB.
51+
52+
In a file called ``DemoDocumentExample.kt``, paste the following sample
53+
code to run a query on your sample dataset in MongoDB Atlas. Replace the
54+
value of the ``<connection URI string>`` placeholder with your
55+
MongoDB Atlas connection string:
56+
57+
.. literalinclude:: /includes/get-started/DemoDocumentExample.kt
58+
:caption: DemoDocumentExample.kt
59+
:language: kotlin
60+
61+
When you run the application, it prints the details
62+
of a movie document that matches the query, as shown in the
63+
following output:
64+
65+
.. code-block:: none
66+
:copyable: false
67+
68+
Document{{_id=..., plot=A young man and woman ..., genres=[Drama, Romance], ...}}
69+
70+
If you don't see any output or receive an error, check whether you
71+
included the proper connection string in your application. Also, confirm
72+
that you successfully loaded the sample dataset into your MongoDB
73+
Atlas cluster.
74+
75+
After you complete these steps, you have a working application that
76+
uses the driver to connect to your MongoDB deployment, runs a query on
77+
the sample data, and prints out the result.
78+
79+
.. include:: /includes/get-started/quickstart-troubleshoot.rst
80+
81+
.. button:: Next Steps
82+
:uri: /get-started/next-steps/
83+
84+
.. TODO add after output .. tip:: Data Classes
85+
..
86+
.. To learn more about using data classes to store and retrieve data,
87+
.. see the :ref:`fundamentals-data-classes` guide.

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

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
.. _kotlin-sync-get-started-connection-string:
2+
3+
==========================
4+
Create a Connection String
5+
==========================
6+
7+
You can connect to your MongoDB deployment by providing a
8+
**connection URI**, also called a *connection string*, which
9+
instructs the driver on how to connect to a MongoDB deployment
10+
and how to behave while connected.
11+
12+
The connection string includes the hostname or IP address and
13+
port of your deployment, the authentication mechanism, user credentials
14+
when applicable, and connection options.
15+
16+
.. TODO To connect to an instance or deployment not hosted on Atlas, see
17+
.. :ref:`kotlin-sync-connection-targets`.
18+
19+
.. procedure::
20+
:style: connected
21+
22+
.. step:: Find your MongoDB Atlas Connection String
23+
24+
To retrieve your connection string for the deployment that
25+
you created in the :ref:`previous step <kotlin-sync-get-started-create-deployment>`,
26+
log into your Atlas account, navigate to the
27+
:guilabel:`Database` section, then click the :guilabel:`Connect` button
28+
for your new deployment.
29+
30+
.. figure:: /includes/figures/atlas_connection_select_cluster.png
31+
:alt: The connect button in the clusters section of the Atlas UI
32+
33+
Proceed to the :guilabel:`Connect your application` section, then select
34+
**{+language+}** from the :guilabel:`Driver` selection menu.
35+
36+
Select the :guilabel:`Password (SCRAM)` authentication mechanism.
37+
38+
Deselect the :guilabel:`Include full driver code example` option to view
39+
only the connection string.
40+
41+
.. step:: Copy your Connection String
42+
43+
Click the button on the right of the connection string to copy it to
44+
your clipboard as shown in the following screenshot:
45+
46+
.. figure:: /includes/figures/atlas_connection_copy_string_kotlin.png
47+
:alt: The connection string copy button in the Atlas UI
48+
49+
.. step:: Update the Placeholders
50+
51+
Paste this connection string into a file in your preferred text editor
52+
and replace the ``<username>`` and ``<password>`` placeholders with
53+
your database user's username and password.
54+
55+
Save this file to a safe location to use in the next step.
56+
57+
After completing these steps, you have a connection string that
58+
contains your database username and password.
59+
60+
.. include:: /includes/get-started/quickstart-troubleshoot.rst
61+
62+
.. button:: Next: Connect to MongoDB
63+
:uri: /get-started/connect-to-mongodb/

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

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
.. _kotlin-sync-get-started-create-deployment:
2+
3+
===========================
4+
Create a MongoDB Deployment
5+
===========================
6+
7+
You can create a free tier MongoDB deployment on MongoDB Atlas
8+
to store and manage your data. MongoDB Atlas hosts and manages
9+
your MongoDB database in the cloud.
10+
11+
.. procedure::
12+
:style: connected
13+
14+
.. step:: Create a Free MongoDB deployment on Atlas
15+
16+
Complete the :atlas:`Get Started with Atlas </getting-started>`
17+
guide to set up a new Atlas account and load sample data into a new free
18+
tier MongoDB deployment.
19+
20+
.. step:: Save your Credentials
21+
22+
After you create your database user, save the user's
23+
username and password to a safe location for use in an upcoming step.
24+
25+
After you complete these steps, you have a new free tier MongoDB
26+
deployment on Atlas, database user credentials, and sample data loaded
27+
in your database.
28+
29+
.. include:: /includes/get-started/quickstart-troubleshoot.rst
30+
31+
.. button:: Next: Create a Connection String
32+
:uri: /get-started/create-a-connection-string/

‎source/get-started/download-and-install.txt

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
.. _kotlin-sync-download-install:
2+
3+
====================
4+
Download and Install
5+
====================
6+
7+
This guide demonstrates how to create a project and add the
8+
{+driver-short+} dependencies by using `Gradle <https://gradle.org/>`__
9+
or `Maven <https://maven.apache.org/>`__.
10+
11+
.. procedure::
12+
:style: connected
13+
14+
.. step:: Create a {+language+} Project
15+
16+
First, make sure that your system has {+language+} installed and
17+
running on JDK 1.8 or later.
18+
19+
We recommend that you use an integrated development
20+
environment (IDE) such as IntelliJ IDEA or Eclipse IDE to
21+
configure Gradle or Maven to build and run your project.
22+
23+
.. tip::
24+
25+
If you are not using an IDE, see the
26+
`Creating New Gradle Builds
27+
<https://guides.gradle.org/creating-new-gradle-builds/>`__ guide
28+
or the `Building Maven
29+
<https://maven.apache.org/guides/development/guide-building-maven.html>`__ guide
30+
for more information on how to set up your project.
31+
32+
For more information on getting started with
33+
{+language+} and creating your first project, see `Get started with Kotlin/JVM
34+
<{+kotlin-docs+}/docs/jvm-get-started.html>`__ in the {+language+}
35+
language documentation.
36+
37+
.. step:: Add MongoDB as a Dependency
38+
39+
If you are using Gradle to manage your
40+
packages, add the following entry to your ``build.gradle.kts``
41+
dependencies list:
42+
43+
.. include:: /includes/kotlin-sync-driver-gradle-versioned.rst
44+
45+
If you are using Maven to manage your
46+
packages, add the following entry to your ``pom.xml`` dependencies list:
47+
48+
.. include:: /includes/kotlin-sync-driver-maven-versioned.rst
49+
50+
After you configure your dependencies, ensure that they are
51+
available to your project by running the dependency manager and
52+
refreshing the project in your IDE.
53+
54+
.. step:: Add Serialization Library Dependencies
55+
56+
To enable the driver to convert between {+language+} objects and BSON, the
57+
data format for documents in MongoDB, you must also add one or both of the
58+
following serialization packages to your application:
59+
60+
- ``bson-kotlinx`` *(Recommended)*
61+
- ``bson-kotlin``
62+
63+
If you are using Gradle to manage your packages, add one of the following
64+
entries to your ``build.gradle.kts`` dependencies list:
65+
66+
.. include:: /includes/serialization-libs-gradle-versioned.rst
67+
68+
If you are using Maven to manage your packages, add one of the following
69+
entries to your ``pom.xml`` dependencies list:
70+
71+
.. include:: /includes/serialization-libs-maven-versioned.rst
72+
73+
After you configure your dependencies, ensure that they are available to your
74+
project by running the dependency manager and refreshing the
75+
project in your IDE.
76+
77+
.. To learn more about these packages, see
78+
.. :ref:`kotlin-sync-serialization`.
79+
80+
After you complete these steps, you have a new project directory
81+
and the driver dependencies installed.
82+
83+
.. include:: /includes/get-started/quickstart-troubleshoot.rst
84+
85+
.. button:: Next: Create a MongoDB Deployment
86+
:uri: /get-started/create-a-deployment/

‎source/get-started/next-steps.txt

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
.. _kotlin-sync-get-started-next-steps:
2+
3+
==========
4+
Next Steps
5+
==========
6+
7+
Congratulations on completing the tutorial!
8+
9+
In this tutorial, you created a {+language+} application that
10+
connects to a MongoDB deployment hosted on MongoDB Atlas
11+
and retrieves a document that matches a query.
12+
13+
Learn more about the {+driver-short+} from the following resources:
14+
15+
- Learn how to perform read operations in the :ref:`<kotlin-sync-read>` section.
16+
17+
.. TODO - Learn how to perform write operations in the :ref:`<kotlin-sync-write>` section.

‎source/includes/figures/atlas_connection_copy_string_kotlin.png

206 KB
Loading

‎source/includes/figures/atlas_connection_select_cluster.png

34.6 KB
Loading

‎source/includes/get-started/DemoDataClassExample.kt

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import com.mongodb.client.model.Filters.eq
2+
import com.mongodb.kotlin.client.MongoClient
3+
4+
// Create data class to represent a MongoDB document
5+
data class Movie(val title: String, val year: Int, val directors: List<String>)
6+
7+
fun main() {
8+
// Replace the placeholder with your MongoDB deployment's connection string
9+
val uri = "<connection URI string>"
10+
11+
val mongoClient = MongoClient.create(uri)
12+
val database = mongoClient.getDatabase("sample_mflix")
13+
val collection = database.getCollection<Movie>("movies")
14+
15+
// Find a document with the specified title
16+
val doc = collection.find(eq(Movie::title.name, "Before Sunrise")).firstOrNull()
17+
18+
if (doc != null) {
19+
// Print the matching document
20+
println(doc)
21+
} else {
22+
println("No matching documents found.")
23+
}
24+
}

0 commit comments

Comments
 (0)