From 93099049d921a308e977b60ece6c4ccd7bc8c7d4 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 12 Mar 2025 10:33:46 -0400 Subject: [PATCH 1/2] get started merge --- snooty.toml | 1 - source/get-started.txt | 275 +++++++++++++++++- .../create-a-connection-string.txt | 59 ---- source/get-started/create-a-deployment.txt | 30 -- source/get-started/download-and-install.txt | 96 ------ source/get-started/next-steps.txt | 17 -- source/get-started/run-sample-query.txt | 85 ------ .../get-started/quickstart-troubleshoot.rst | 2 +- 8 files changed, 268 insertions(+), 297 deletions(-) delete mode 100644 source/get-started/create-a-connection-string.txt delete mode 100644 source/get-started/create-a-deployment.txt delete mode 100644 source/get-started/download-and-install.txt delete mode 100644 source/get-started/next-steps.txt delete mode 100644 source/get-started/run-sample-query.txt diff --git a/snooty.toml b/snooty.toml index d9cc772..9d13885 100644 --- a/snooty.toml +++ b/snooty.toml @@ -9,7 +9,6 @@ intersphinx = [ toc_landing_pages = [ "/write-operations", - "/get-started", "/read", "/connect", "/indexes", diff --git a/source/get-started.txt b/source/get-started.txt index c11e763..5142130 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -18,14 +18,6 @@ Get Started with the Kotlin Sync Driver :description: Learn how to create an app to connect to MongoDB deployment by using the Kotlin Sync driver. :keywords: quick start, tutorial, basics -.. toctree:: - - Download & Install - Create a Deployment - Create a Connection String - Run a Sample Query - Next Steps - Overview -------- @@ -43,3 +35,270 @@ MongoDB Atlas and interact with data. 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 <>`. + +.. _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. + +.. _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. + +.. _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. + +To connect to an instance or deployment not hosted on Atlas, see the :ref:`kotlin-sync-connection-targets` guide. + +.. 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. + +.. _kotlin-sync-connect-to-mongodb: +.. _kotlin-sync-run-sample-query: + +Run a Sample Query +------------------ + +.. 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. + +.. 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. + +.. _kotlin-sync-get-started-next-steps: + +Next Steps +---------- + +Congratulations on completing the tutorial! + +.. include:: /includes/get-started/quickstart-troubleshoot.rst + +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. + +- Learn how to perform write operations in the :ref:`` section. diff --git a/source/get-started/create-a-connection-string.txt b/source/get-started/create-a-connection-string.txt deleted file mode 100644 index 47392bc..0000000 --- a/source/get-started/create-a-connection-string.txt +++ /dev/null @@ -1,59 +0,0 @@ -.. _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. - -To connect to an instance or deployment not hosted on Atlas, see the :ref:`kotlin-sync-connection-targets` guide. - -.. 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 diff --git a/source/get-started/create-a-deployment.txt b/source/get-started/create-a-deployment.txt deleted file mode 100644 index 974cdd8..0000000 --- a/source/get-started/create-a-deployment.txt +++ /dev/null @@ -1,30 +0,0 @@ -.. _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 - diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt deleted file mode 100644 index 52c3ff2..0000000 --- a/source/get-started/download-and-install.txt +++ /dev/null @@ -1,96 +0,0 @@ -.. _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 the Driver Bill of Materials - - .. _kotlin-sync-get-started-install-bom: - - .. sharedinclude:: dbx/jvm/bom.rst - - .. replacement:: gradle-filename - - ``build.gradle.kts`` - - .. 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 - - Because you installed the BOM, you can omit a version in the - {+driver-short+} dependency entry. The version you specify in the - BOM determines the dependency versions to install. - - 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 diff --git a/source/get-started/next-steps.txt b/source/get-started/next-steps.txt deleted file mode 100644 index fc8f66c..0000000 --- a/source/get-started/next-steps.txt +++ /dev/null @@ -1,17 +0,0 @@ -.. _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. - -- Learn how to perform write operations in the :ref:`` section. diff --git a/source/get-started/run-sample-query.txt b/source/get-started/run-sample-query.txt deleted file mode 100644 index 2a45e5f..0000000 --- a/source/get-started/run-sample-query.txt +++ /dev/null @@ -1,85 +0,0 @@ -.. _kotlin-sync-connect-to-mongodb: -.. _kotlin-sync-run-sample-query: - -================== -Run a Sample Query -================== - -.. 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 - -.. 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/includes/get-started/quickstart-troubleshoot.rst b/source/includes/get-started/quickstart-troubleshoot.rst index 9403907..f1e77d7 100644 --- a/source/includes/get-started/quickstart-troubleshoot.rst +++ b/source/includes/get-started/quickstart-troubleshoot.rst @@ -1,6 +1,6 @@ .. note:: - If you run into issues on this step, ask for help in the + If you run into issues in this tutorial, 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 From 6ed5fa3fbed35a9de5c5a227213c7042f646cf90 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 16 Apr 2025 14:06:00 -0400 Subject: [PATCH 2/2] bom --- source/get-started.txt | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/source/get-started.txt b/source/get-started.txt index 5142130..a54c0c1 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -41,7 +41,7 @@ programming language, see the :driver:`list of official MongoDB drivers <>`. Download and Install -------------------- -This guide demonstrates how to create a project and add the +This section demonstrates how to create a project and add the {+driver-short+} dependencies by using `Gradle `__ or `Maven `__. @@ -71,6 +71,16 @@ or `Maven `__. <{+kotlin-docs+}/docs/jvm-get-started.html>`__ in the {+language+} language documentation. + .. step:: Add the Driver Bill of Materials + + .. _kotlin-sync-get-started-install-bom: + + .. sharedinclude:: dbx/jvm/bom.rst + + .. replacement:: gradle-filename + + ``build.gradle.kts`` + .. step:: Add MongoDB as a Dependency If you are using Gradle to manage your @@ -84,6 +94,10 @@ or `Maven `__. .. include:: /includes/kotlin-sync-driver-maven-versioned.rst + Because you installed the BOM, you can omit a version in the + {+driver-short+} dependency entry. The version you specify in the + BOM determines the dependency versions to install. + 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. @@ -111,8 +125,7 @@ or `Maven `__. project by running the dependency manager and refreshing the project in your IDE. -.. To learn more about these packages, see -.. :ref:`kotlin-sync-serialization`. + 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.