DOCSP-47777: Rework get started

snooty.toml

@@ -7,7 +7,7 @@ intersphinx = [
 ]
 
 toc_landing_pages = [
-    "/getting-started",
+    "/get-started",
     "/connection",
     "/crud",
     "/crud/builders",

source/get-started.txt

@@ -0,0 +1,51 @@
+.. _java-get-started:
+
+================================
+Get Started with the Java Driver
+================================
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :description: Learn how to create an app to connect to MongoDB deployment by using the {+driver-short+}.
+   :keywords: quick start, tutorial, basics
+
+.. toctree::
+
+   Download & Install </get-started/download-and-install/>
+   Create a Deployment </get-started/create-deployment/>
+   Create a Connection String </get-started/connection-string/>
+   Connect to MongoDB </get-started/connect-to-mongodb/>
+   Next Steps </get-started/next-steps/>
+   Databases & Collections </get-started/databases-collections/>
+
+Overview
+--------
+
+The {+driver-short+} is a synchronous API that you can use to interact with MongoDB
+from your Java application. 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 query data in your cluster.
+
+.. tip:: 
+
+   :atlas:`MongoDB Atlas </getting-started/>` 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 tutorial to connect a sample Java application to a MongoDB Atlas
+deployment. The tutorial includes the following sections:
+
+- :ref:`java-get-started-download-and-install`: Learn how to install
+  the {+driver-short+}.
+- :ref:`java-get-started-create-deployment`: Learn how to create
+  a free MongoDB deployment on Atlas.
+- :ref:`java-get-started-connection-string`: Learn how to retrieve
+  your Atlas deployment's connection string.
+- :ref:`java-connect-to-mongodb`: Learn how to create an application
+  that connects to MongoDB and queries data stored in your deployment.
+
+If you prefer to connect to MongoDB using a different driver or
+programming language, see our :driver:`list of official drivers <>`.

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

@@ -0,0 +1,52 @@
+.. _java-connect-to-mongodb:
+
+==================
+Connect to MongoDB
+==================
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: test connection, runnable, code example
+
+After retrieving the connection string for your MongoDB Atlas deployment,
+you can connect to the deployment from your Java application and query
+the Atlas sample datasets.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Create your Java application file
+
+      In your project's base package directory, create a file called
+      ``QuickStart.java``. Copy and paste the following code into this file,
+      which queries the ``movies`` collection in the ``sample_mflix`` database:
+
+      .. literalinclude:: /includes/get-started/code-snippets/QuickStart.java
+         :start-after: begin QuickStart
+         :end-before: end QuickStart
+         :language: java
+         :dedent:
+
+   .. step:: Assign the connection string
+
+      Replace the ``<connection string uri>`` placeholder with the connection string
+      that you copied from the :ref:`java-get-started-connection-string` step of this
+      guide.
+
+   .. step:: Run your Java application
+
+      Run your application in your IDE or your shell. Your output
+      contains details about the retrieved movie document:
+
+      .. include:: /includes/get-started/query-output.rst
+
+      .. include:: /includes/get-started/jdk-tls-issue.rst
+
+After you complete these steps, you have a Java application that
+connects to your MongoDB deployment, runs a query on the sample
+data, and returns a matching document.
+
+.. include:: /includes/get-started/quickstart-troubleshoot.rst

source/get-started/connection-string.txt

@@ -0,0 +1,53 @@
+.. _java-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.
+
+.. 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 <java-get-started-create-deployment>`,
+      log into your Atlas account and navigate to the
+      :guilabel:`Clusters` section. Click the :guilabel:`Connect` button
+      for your new deployment, as shown in the following screenshot:
+
+      .. figure:: /includes/figures/atlas_connection_connect_cluster.png
+         :alt: The connect button in the clusters section of the Atlas UI
+
+      Then, proceed to the :guilabel:`Connect your application` section. Select
+      "Java" from the :guilabel:`Driver` selection menu and the version
+      that best matches the version you installed from the :guilabel:`Version`
+      selection menu.
+
+   .. 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_uri_java.png
+         :alt: The connection string copy button in the Atlas UI
+
+   .. step:: Edit your connection string placeholders
+
+      Paste your connection string into a file in your preferred text editor
+      and save this file to a safe location for later use. In your connection
+      string, replace the ``<db_username>`` and ``<db_password>`` placeholders with
+      your database user's username and password.
+
+After completing these steps, you have a connection string that
+contains your database username and password.
+
+.. include:: /includes/get-started/quickstart-troubleshoot.rst

source/get-started/create-deployment.txt

@@ -0,0 +1,28 @@
+.. _java-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 </getting-started?tck=docs_driver_java>`
+      guide to set up a new Atlas account and a free tier MongoDB deployment.
+      Ensure that you **load sample data** and **add your IP address** to the IP access
+      list.
+
+   .. step:: Save your credentials
+
+      After you create your database user, save that 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.

source/getting-started/databases-collections.txt → source/get-started/databases-collections.txt

@@ -1,3 +1,5 @@
+.. _java-db-coll:
+
 =========================
 Databases and Collections
 =========================

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

@@ -0,0 +1,61 @@
+.. _java-get-started-download-and-install:
+
+====================
+Download and Install
+====================
+
+Complete the following steps to install the {+driver-short+} and
+its dependencies in your development environment.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Install the driver dependencies
+
+      Before you begin this tutorial, ensure that you install
+      the following dependencies:
+
+      - `JDK <https://www.oracle.com/java/technologies/javase-downloads.html>`__ 
+        version 8 or later 
+      - Integrated development environment (IDE), such as `IntelliJ IDEA <https://www.jetbrains.com/idea/download/>`__
+        or `Eclipse <https://www.eclipse.org/downloads/packages/>`__
+
+      .. note::
+
+         This tutorial shows how to install the {+driver-short+} by using
+         Maven or Gradle in an IDE. If you do not use an IDE, visit `Building Maven
+         <https://maven.apache.org/guides/development/guide-building-maven.html>`__
+         or `Creating New Gradle Builds <https://guides.gradle.org/creating-new-gradle-builds/>`__
+         to learn how to set up your project.
+
+   .. step:: Install the {+driver-short+}
+
+      In your IDE, create a new `Maven <https://maven.apache.org/>`__ or `Gradle <https://gradle.org/>`__
+      project. If you use Maven, add the following code to your ``pom.xml`` dependencies list:
+
+      .. code-block:: xml
+
+         <dependencies>
+             <dependency>
+                 <groupId>org.mongodb</groupId>
+                 <artifactId>mongodb-driver-sync</artifactId>
+                 <version>{+full-version+}</version>
+             </dependency>
+         </dependencies>
+
+      If you use Gradle, add the following code to your ``build.gradle`` dependencies list:
+
+      .. code-block:: groovy
+
+         dependencies {
+           implementation 'org.mongodb:mongodb-driver-sync:{+full-version+}'
+         }
+
+      After you configure your dependencies, ensure they are available to your
+      project by running your dependency manager and refreshing
+      the project in your IDE.
+
+After you complete these steps, you have a new project 
+and the driver dependencies installed.
+
+.. include:: /includes/get-started/quickstart-troubleshoot.rst

source/get-started/next-steps.txt

@@ -0,0 +1,18 @@
+.. _java-get-started-next-steps:
+
+==========
+Next Steps
+==========
+
+Congratulations on completing the tutorial!
+
+In this tutorial, you created a {+driver-short+} application that
+connects to a MongoDB deployment hosted on MongoDB Atlas
+and retrieves a document that matches a query. 
+
+For more information about interacting with MongoDB databases and collections,
+visit the :ref:`java-db-coll` guide. You can also learn more about the
+{+driver-short+} from the following resources:
+
+- Learn how to perform read operations in the :ref:`<java-read-operations>` section.
+- Learn how to perform write operations in the :ref:`<java-write-operations>` section.