diff --git a/snooty.toml b/snooty.toml index f9e67736..5eed4e15 100644 --- a/snooty.toml +++ b/snooty.toml @@ -7,6 +7,7 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv", ] toc_landing_pages = [ + "/get-started", "/read", "/connect", "/indexes", @@ -20,9 +21,10 @@ driver-long = "MongoDB Kotlin Sync Driver" driver-short = "Kotlin Sync driver" language = "Kotlin" version-number = "5.1" +full-version = "{+version-number+}.2" version = "v{+version-number+}" -patch-version-number = "{+version-number+}.0" mdb-server = "MongoDB Server" stable-api = "Stable API" api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync" +kotlin-docs = "https://kotlinlang.org" core-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-core/" diff --git a/source/get-started.txt b/source/get-started.txt new file mode 100644 index 00000000..16cd76a0 --- /dev/null +++ b/source/get-started.txt @@ -0,0 +1,48 @@ +.. _kotlin-sync-get-started: + +======================================= +Get Started with the Kotlin Sync Driver +======================================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :description: Learn how to create an app to connect to MongoDB deployment by using the Kotlin Sync driver. + :keywords: quick start, tutorial, basics + +.. toctree:: + + /get-started/download-and-install/ + /get-started/create-a-deployment/ + /get-started/create-a-connection-string/ + /get-started/connect-to-mongodb/ + /get-started/next-steps/ + +Overview +-------- + +You can use the {+driver-short+} to connect to and communicate with +MongoDB. This guide shows you how to create an application that uses +the {+driver-short+} to connect to a MongoDB cluster hosted on +MongoDB Atlas and interact with data. + +.. tip:: + + MongoDB Atlas is a fully managed cloud database service that hosts your MongoDB + deployments. You can create your own free (no credit card required) MongoDB Atlas + deployment by following the steps in this guide. + +Follow this guide to connect a sample {+language+} application to a MongoDB Atlas +deployment. If you prefer to connect to MongoDB using a different driver or +programming language, see the :driver:`list of official MongoDB drivers <>`. + +.. button:: Next: Download and Install + :uri: /get-started/download-and-install/ diff --git a/source/get-started/connect-to-mongodb.txt b/source/get-started/connect-to-mongodb.txt new file mode 100644 index 00000000..984694a0 --- /dev/null +++ b/source/get-started/connect-to-mongodb.txt @@ -0,0 +1,87 @@ +.. _kotlin-sync-connect-to-mongodb: + +================== +Connect to MongoDB +================== + +.. procedure:: + :style: connected + + .. step:: Create the Application File + + Create a file called ``DemoDataClassExample.kt`` in your project. + + Copy the following sample code into the file and replace the value of + the ```` placeholder with your MongoDB + Atlas connection string that you saved in the preceding step. + + .. literalinclude:: /includes/get-started/DemoDataClassExample.kt + :language: kotlin + :caption: DemoDataClassExample.kt + + .. note:: + + This example uses a {+language+} data class to model MongoDB data. + + .. step:: Run the Application + + When you run the application, it prints the details + of a movie document that matches the query, as shown in the + following output: + + .. code-block:: none + :copyable: false + + Movie(title=Before Sunrise, year=1995, directors=[Richard Linklater]) + + If you don't see any output or receive an error, check whether you + included the proper connection string in your application. Also, confirm + that you successfully loaded the sample dataset into your MongoDB Atlas cluster. + + After completing this step, you have a working application that uses + the {+driver-short+} to connect to your MongoDB cluster, run a query on the + sample data, and print out the result. + + .. step:: Use the Document Class to Model Data (Alternative) + + The preceding step demonstrates how to run a query on a sample + collection to retrieve data by using a {+language+} data class. This section + shows how to use the `Document `__ + class to store and retrieve data from MongoDB. + + In a file called ``DemoDocumentExample.kt``, paste the following sample + code to run a query on your sample dataset in MongoDB Atlas. Replace the + value of the ```` placeholder with your + MongoDB Atlas connection string: + + .. literalinclude:: /includes/get-started/DemoDocumentExample.kt + :caption: DemoDocumentExample.kt + :language: kotlin + + When you run the application, it prints the details + of a movie document that matches the query, as shown in the + following output: + + .. code-block:: none + :copyable: false + + Document{{_id=..., plot=A young man and woman ..., genres=[Drama, Romance], ...}} + + If you don't see any output or receive an error, check whether you + included the proper connection string in your application. Also, confirm + that you successfully loaded the sample dataset into your MongoDB + Atlas cluster. + +After you complete these steps, you have a working application that +uses the driver to connect to your MongoDB deployment, runs a query on +the sample data, and prints out the result. + +.. include:: /includes/get-started/quickstart-troubleshoot.rst + +.. button:: Next Steps + :uri: /get-started/next-steps/ + +.. TODO add after output .. tip:: Data Classes +.. +.. To learn more about using data classes to store and retrieve data, +.. see the :ref:`fundamentals-data-classes` guide. \ No newline at end of file diff --git a/source/get-started/create-a-connection-string.txt b/source/get-started/create-a-connection-string.txt new file mode 100644 index 00000000..0218bf57 --- /dev/null +++ b/source/get-started/create-a-connection-string.txt @@ -0,0 +1,63 @@ +.. _kotlin-sync-get-started-connection-string: + +========================== +Create a Connection String +========================== + +You can connect to your MongoDB deployment by providing a +**connection URI**, also called a *connection string*, which +instructs the driver on how to connect to a MongoDB deployment +and how to behave while connected. + +The connection string includes the hostname or IP address and +port of your deployment, the authentication mechanism, user credentials +when applicable, and connection options. + +.. TODO To connect to an instance or deployment not hosted on Atlas, see +.. :ref:`kotlin-sync-connection-targets`. + +.. procedure:: + :style: connected + + .. step:: Find your MongoDB Atlas Connection String + + To retrieve your connection string for the deployment that + you created in the :ref:`previous step `, + log into your Atlas account, navigate to the + :guilabel:`Database` section, then click the :guilabel:`Connect` button + for your new deployment. + + .. figure:: /includes/figures/atlas_connection_select_cluster.png + :alt: The connect button in the clusters section of the Atlas UI + + Proceed to the :guilabel:`Connect your application` section, then select + **{+language+}** from the :guilabel:`Driver` selection menu. + + Select the :guilabel:`Password (SCRAM)` authentication mechanism. + + Deselect the :guilabel:`Include full driver code example` option to view + only the connection string. + + .. step:: Copy your Connection String + + Click the button on the right of the connection string to copy it to + your clipboard as shown in the following screenshot: + + .. figure:: /includes/figures/atlas_connection_copy_string_kotlin.png + :alt: The connection string copy button in the Atlas UI + + .. step:: Update the Placeholders + + Paste this connection string into a file in your preferred text editor + and replace the ```` and ```` placeholders with + your database user's username and password. + + Save this file to a safe location to use in the next step. + +After completing these steps, you have a connection string that +contains your database username and password. + +.. include:: /includes/get-started/quickstart-troubleshoot.rst + +.. button:: Next: Connect to MongoDB + :uri: /get-started/connect-to-mongodb/ \ No newline at end of file diff --git a/source/get-started/create-a-deployment.txt b/source/get-started/create-a-deployment.txt new file mode 100644 index 00000000..2f67f10e --- /dev/null +++ b/source/get-started/create-a-deployment.txt @@ -0,0 +1,32 @@ +.. _kotlin-sync-get-started-create-deployment: + +=========================== +Create a MongoDB Deployment +=========================== + +You can create a free tier MongoDB deployment on MongoDB Atlas +to store and manage your data. MongoDB Atlas hosts and manages +your MongoDB database in the cloud. + +.. procedure:: + :style: connected + + .. step:: Create a Free MongoDB deployment on Atlas + + Complete the :atlas:`Get Started with Atlas ` + guide to set up a new Atlas account and load sample data into a new free + tier MongoDB deployment. + + .. step:: Save your Credentials + + After you create your database user, save the user's + username and password to a safe location for use in an upcoming step. + +After you complete these steps, you have a new free tier MongoDB +deployment on Atlas, database user credentials, and sample data loaded +in your database. + +.. include:: /includes/get-started/quickstart-troubleshoot.rst + +.. button:: Next: Create a Connection String + :uri: /get-started/create-a-connection-string/ diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt new file mode 100644 index 00000000..0163f3c2 --- /dev/null +++ b/source/get-started/download-and-install.txt @@ -0,0 +1,86 @@ +.. _kotlin-sync-download-install: + +==================== +Download and Install +==================== + +This guide demonstrates how to create a project and add the +{+driver-short+} dependencies by using `Gradle `__ +or `Maven `__. + +.. procedure:: + :style: connected + + .. step:: Create a {+language+} Project + + First, make sure that your system has {+language+} installed and + running on JDK 1.8 or later. + + We recommend that you use an integrated development + environment (IDE) such as IntelliJ IDEA or Eclipse IDE to + configure Gradle or Maven to build and run your project. + + .. tip:: + + If you are not using an IDE, see the + `Creating New Gradle Builds + `__ guide + or the `Building Maven + `__ guide + for more information on how to set up your project. + + For more information on getting started with + {+language+} and creating your first project, see `Get started with Kotlin/JVM + <{+kotlin-docs+}/docs/jvm-get-started.html>`__ in the {+language+} + language documentation. + + .. step:: Add MongoDB as a Dependency + + If you are using Gradle to manage your + packages, add the following entry to your ``build.gradle.kts`` + dependencies list: + + .. include:: /includes/kotlin-sync-driver-gradle-versioned.rst + + If you are using Maven to manage your + packages, add the following entry to your ``pom.xml`` dependencies list: + + .. include:: /includes/kotlin-sync-driver-maven-versioned.rst + + After you configure your dependencies, ensure that they are + available to your project by running the dependency manager and + refreshing the project in your IDE. + + .. step:: Add Serialization Library Dependencies + + To enable the driver to convert between {+language+} objects and BSON, the + data format for documents in MongoDB, you must also add one or both of the + following serialization packages to your application: + + - ``bson-kotlinx`` *(Recommended)* + - ``bson-kotlin`` + + If you are using Gradle to manage your packages, add one of the following + entries to your ``build.gradle.kts`` dependencies list: + + .. include:: /includes/serialization-libs-gradle-versioned.rst + + If you are using Maven to manage your packages, add one of the following + entries to your ``pom.xml`` dependencies list: + + .. include:: /includes/serialization-libs-maven-versioned.rst + + After you configure your dependencies, ensure that they are available to your + project by running the dependency manager and refreshing the + project in your IDE. + +.. To learn more about these packages, see +.. :ref:`kotlin-sync-serialization`. + +After you complete these steps, you have a new project directory +and the driver dependencies installed. + +.. include:: /includes/get-started/quickstart-troubleshoot.rst + +.. button:: Next: Create a MongoDB Deployment + :uri: /get-started/create-a-deployment/ diff --git a/source/get-started/next-steps.txt b/source/get-started/next-steps.txt new file mode 100644 index 00000000..a75f0572 --- /dev/null +++ b/source/get-started/next-steps.txt @@ -0,0 +1,17 @@ +.. _kotlin-sync-get-started-next-steps: + +========== +Next Steps +========== + +Congratulations on completing the tutorial! + +In this tutorial, you created a {+language+} application that +connects to a MongoDB deployment hosted on MongoDB Atlas +and retrieves a document that matches a query. + +Learn more about the {+driver-short+} from the following resources: + +- Learn how to perform read operations in the :ref:`` section. + +.. TODO - Learn how to perform write operations in the :ref:`` section. diff --git a/source/includes/figures/atlas_connection_copy_string_kotlin.png b/source/includes/figures/atlas_connection_copy_string_kotlin.png new file mode 100644 index 00000000..24d4dd0d Binary files /dev/null and b/source/includes/figures/atlas_connection_copy_string_kotlin.png differ diff --git a/source/includes/figures/atlas_connection_select_cluster.png b/source/includes/figures/atlas_connection_select_cluster.png new file mode 100644 index 00000000..52d827d6 Binary files /dev/null and b/source/includes/figures/atlas_connection_select_cluster.png differ diff --git a/source/includes/get-started/DemoDataClassExample.kt b/source/includes/get-started/DemoDataClassExample.kt new file mode 100644 index 00000000..52a1247c --- /dev/null +++ b/source/includes/get-started/DemoDataClassExample.kt @@ -0,0 +1,24 @@ +import com.mongodb.client.model.Filters.eq +import com.mongodb.kotlin.client.MongoClient + +// Create data class to represent a MongoDB document +data class Movie(val title: String, val year: Int, val directors: List) + +fun main() { + // Replace the placeholder with your MongoDB deployment's connection string + val uri = "" + + val mongoClient = MongoClient.create(uri) + val database = mongoClient.getDatabase("sample_mflix") + val collection = database.getCollection("movies") + + // Find a document with the specified title + val doc = collection.find(eq(Movie::title.name, "Before Sunrise")).firstOrNull() + + if (doc != null) { + // Print the matching document + println(doc) + } else { + println("No matching documents found.") + } +} \ No newline at end of file diff --git a/source/includes/get-started/DemoDocumentExample.kt b/source/includes/get-started/DemoDocumentExample.kt new file mode 100644 index 00000000..452ceabd --- /dev/null +++ b/source/includes/get-started/DemoDocumentExample.kt @@ -0,0 +1,23 @@ +import com.mongodb.client.model.Filters.eq +import com.mongodb.kotlin.client.MongoClient +import org.bson.Document + +fun main() { + // Replace the placeholder with your MongoDB deployment's connection string + val uri = "" + + val mongoClient = MongoClient.create(uri) + val database = mongoClient.getDatabase("sample_mflix") + val collection = database.getCollection("movies") + + // Find a document with the specified title + val doc = collection.find(eq("title", "Before Sunrise")).firstOrNull() + + if (doc != null) { + // Print the matching document + println(doc) + } else { + println("No matching documents found.") + } +} + diff --git a/source/includes/get-started/quickstart-troubleshoot.rst b/source/includes/get-started/quickstart-troubleshoot.rst new file mode 100644 index 00000000..9403907b --- /dev/null +++ b/source/includes/get-started/quickstart-troubleshoot.rst @@ -0,0 +1,6 @@ +.. note:: + + If you run into issues on this step, ask for help in the + :community-forum:`MongoDB Community Forums ` + or submit feedback by using the :guilabel:`Rate this page` + tab on the right or bottom right side of this page. \ No newline at end of file diff --git a/source/includes/kotlin-sync-driver-gradle-versioned.rst b/source/includes/kotlin-sync-driver-gradle-versioned.rst new file mode 100644 index 00000000..be0a3f6f --- /dev/null +++ b/source/includes/kotlin-sync-driver-gradle-versioned.rst @@ -0,0 +1,7 @@ +.. code-block:: kotlin + :caption: build.gradle.kts + :copyable: true + + dependencies { + implementation("org.mongodb:mongodb-driver-kotlin-sync:{+full-version+}") + } \ No newline at end of file diff --git a/source/includes/kotlin-sync-driver-maven-versioned.rst b/source/includes/kotlin-sync-driver-maven-versioned.rst new file mode 100644 index 00000000..8b8d58f5 --- /dev/null +++ b/source/includes/kotlin-sync-driver-maven-versioned.rst @@ -0,0 +1,11 @@ +.. code-block:: xml + :caption: pom.xml + :copyable: true + + + + org.mongodb + mongodb-driver-kotlin-sync + {+full-version+} + + \ No newline at end of file diff --git a/source/includes/serialization-libs-gradle-versioned.rst b/source/includes/serialization-libs-gradle-versioned.rst new file mode 100644 index 00000000..ac994c76 --- /dev/null +++ b/source/includes/serialization-libs-gradle-versioned.rst @@ -0,0 +1,8 @@ +.. code-block:: kotlin + :caption: build.gradle.kts + :copyable: true + + implementation("org.mongodb:bson-kotlinx:{+full-version+}") + // OR + implementation("org.mongodb:bson-kotlin:{+full-version+}") + \ No newline at end of file diff --git a/source/includes/serialization-libs-maven-versioned.rst b/source/includes/serialization-libs-maven-versioned.rst new file mode 100644 index 00000000..16ba6eb6 --- /dev/null +++ b/source/includes/serialization-libs-maven-versioned.rst @@ -0,0 +1,16 @@ +.. code-block:: xml + :caption: pom.xml + :copyable: true + + + org.mongodb + bson-kotlinx + {+full-version+} + + + + org.mongodb + bson-kotlin + {+full-version+} + + \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index c89afcbf..bccb9ebd 100644 --- a/source/index.txt +++ b/source/index.txt @@ -13,6 +13,7 @@ .. toctree:: + Get Started /connect /write-operations /read @@ -28,13 +29,13 @@ Introduction ------------ Welcome to the documentation site for the {+driver-long+}, the official -MongoDB driver for synchronous Kotlin applications. Download the driver by using +MongoDB driver for synchronous {+language+} applications. Download the driver by using `Maven `__ or `Gradle `__, or set up a runnable project by following our Quick Start guide. -.. tip:: Other Kotlin Platforms for MongoDB +.. tip:: Other {+language+} Platforms for MongoDB - If your Kotlin application requires asynchronous processing, use the + If your {+language+} application requires asynchronous processing, use the :driver:`Coroutine Driver `, which uses coroutines for server-side applications. @@ -42,11 +43,11 @@ runnable project by following our Quick Start guide. application, you can use the :realm:`MongoDB Atlas Device Kotlin SDK ` to implement Device Sync and to manage your Realm data. -Quick Start +Get Started ----------- -Learn how to establish a connection to MongoDB Atlas and begin -working with data in the :ref:`Quick Start ` section. +Learn how to install the driver, establish a connection to MongoDB, and begin +working with data in the :ref:`kotlin-sync-get-started` tutorial. Connect to MongoDB ------------------ diff --git a/source/quick-start.txt b/source/quick-start.txt deleted file mode 100644 index 7a5d8666..00000000 --- a/source/quick-start.txt +++ /dev/null @@ -1,7 +0,0 @@ -.. _kotlin-sync-quick-start: - -=========== -Quick Start -=========== - -.. TODO \ No newline at end of file