DOCSP-17791: new local MongoDB connection instructions (#148)

* DOCSP-17791: new local MongoDB connection instructions

Author: Chris Cho

source/fundamentals/connection.txt

@@ -3,7 +3,7 @@ Connection Guide
 ================
 
 .. default-domain:: mongodb
-   
+
 .. toctree::
 
    /fundamentals/connection/tls
@@ -60,7 +60,7 @@ connected. The following example shows each part of the connection URI:
    :alt: Connection String parts figure
 
 In this example, for the protocol, we use ``mongodb+srv`` which specifies the
-:manual:`DNS Seedlist Connection Format </reference/connection-string/#std-label-connections-dns-seedlist>`. 
+:manual:`DNS Seedlist Connection Format </reference/connection-string/#std-label-connections-dns-seedlist>`.
 This indicates that the hostname following it corresponds to the DNS SRV record of your
 MongoDB instance or deployment. If your instance or deployment does not have a
 DNS SRV record, use ``mongodb`` to specify the :manual:`Standard Connection
@@ -88,21 +88,36 @@ options as parameters. In the following example, we set two connection options:
 ``retryWrites=true`` and ``w=majority``. For more information on connection
 options, skip to the :ref:`connection options <connection-options>` section.
 
+.. _connect-atlas-java-driver:
+
 The following code shows how you can use the sample connection URI in a client to
 connect to MongoDB.
 
 .. literalinclude:: /includes/fundamentals/code-snippets/srv.java
    :language: java
 
-.. _connect-replica-set:
+.. _java-other-ways-to-connect:
 
-Connect to ``localhost``
-~~~~~~~~~~~~~~~~~~~~~~~~
+Other Ways to Connect to MongoDB
+--------------------------------
+
+If you are connecting to a single MongoDB server instance or replica set
+that is not hosted on Atlas, see the following sections to find out how to
+connect.
+
+Connect to a MongoDB Server on Your Local Machine
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. include:: /includes/localhost-connection.rst
+.. include:: /includes/fundamentals/localhost-connection.rst
+
+To test whether you can connect to your server, replace the connection
+string in the :ref:`Connect to MongoDB Atlas <connect-atlas-java-driver>` code
+example and run it.
+
+.. _connect-replica-set:
 
 Connect to a Replica Set
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 A MongoDB replica set deployment is a group of connected instances that
 store the same set of data. This configuration of instances provides data
@@ -151,7 +166,7 @@ Select the tab corresponding to the code snippet you would like to see:
       :tabid: mongoclientsettings
 
       .. code-block:: java
-      
+
          ServerAddress seed1 = new ServerAddress("host1", 27017);
          ServerAddress seed2 = new ServerAddress("host2", 27017);
          ServerAddress seed3 = new ServerAddress("host3", 27017);
@@ -236,11 +251,11 @@ using a method in the ``MongoClientSettings.Builder`` class.
    .. tab:: MongoClientSettings
       :tabid: mongoclientsettings
 
-      To enable compression with 
-      :java-docs:`MongoClientSettings <apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`, 
+      To enable compression with
+      :java-docs:`MongoClientSettings <apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`,
       pass the
       :java-docs:`compressorList() <apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#compressorList(java.util.List)>`
-      builder method a list of 
+      builder method a list of
       :java-docs:`MongoCompressor <apidocs/mongodb-driver-core/com/mongodb/MongoCompressor.html>`
       instances. You can specify one or more compression algorithms in the list:
 
@@ -389,7 +404,7 @@ parameters of the connection URI to specify the behavior of the client.
    * - **readPreference**
      - string
      - Specifies the read preference. For more information on values, see
-       the server documentation for the 
+       the server documentation for the
        :manual:`readPreference option </reference/connection-string/#urioption.readPreference>`.
 
    * - **readPreferenceTags**
@@ -467,13 +482,13 @@ parameters of the connection URI to specify the behavior of the client.
      - string
      - Specifies the UUID representation to use for read and write
        operations. For more information, see the the driver documentation
-       for the 
+       for the
        :java-docs:`MongoClientSettings.getUuidRepresentation() method <apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html#getUuidRepresentation()>`.
 
    * - **directConnection**
      - boolean
      - Specifies that the driver must connect to the host directly.
 
-For a complete list of options, see the 
+For a complete list of options, see the
 :java-docs:`ConnectionString <apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`
 API reference page.

source/fundamentals/connection/tls.txt

@@ -53,7 +53,7 @@ using a method in the ``MongoClientSettings.Builder`` class.
       :tabid: mongoclientsettings
 
       To configure your ``MongoClient``'s TLS/SSL connection options using the
-      ``MongoClientSettings.Builder`` class, call the 
+      ``MongoClientSettings.Builder`` class, call the
       :java-docs:`applyToSslSettings() <apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#applyToSslSettings(com.mongodb.Block)>`
       method. Set the ``enabled`` property to ``true`` in the ``SslSettings.Builder``
       block to enable TLS/SSL:
@@ -84,7 +84,7 @@ the following mechanisms:
 
    We based the following sections on the documentation for Oracle JDK,
    so some parts may be inapplicable to your JDK or to the custom TLS/SSL
-   implementation you use. 
+   implementation you use.
 
 .. _tls-configure-jvm-truststore:
 
@@ -96,8 +96,8 @@ Configure the JVM Trust Store
    By default, the JRE includes many commonly used public certificates
    from signing authorities like `Let's Encrypt
    <https://letsencrypt.org/>`__. As a result, you can connect to
-   instances of :atlas:`MongoDB Atlas <>` (or any other server whose
-   certificate is signed by an authority in the JRE's default
+   instances of :atlas:`MongoDB Atlas </?jmp=docs_driver_java>` (or any other
+   server whose certificate is signed by an authority in the JRE's default
    certificate store) with TLS/SSL without configuring the trust store.
 
 The JVM trust store saves certificates that securely identify other
@@ -168,11 +168,11 @@ You can configure a client-specific trust store and key store using the
 ``init()`` method of the ``SSLContext`` class.
 
 You can find an example showing how to configure a client with an ``SSLContext``
-instance in the 
+instance in the
 :ref:`Customize TLS/SSL Configuration with an SSLContext section of this guide <tls-custom-sslContext>`.
 
 For more information on the ``SSLContext`` class, see the API
-documentation for `SSL Context <https://docs.oracle.com/en/java/javase/16/docs/api/java.base/javax/net/ssl/SSLContext.html>`__. 
+documentation for `SSL Context <https://docs.oracle.com/en/java/javase/16/docs/api/java.base/javax/net/ssl/SSLContext.html>`__.
 
 Disable Hostname Verification
 -----------------------------

source/fundamentals/indexes.txt

@@ -243,8 +243,9 @@ language as an option when creating the index.
 
 .. tip::
 
-   Text indexes differ from the more powerful :atlas:`Atlas full text search indexes </atlas-search/>`. Atlas users
-   should use Atlas search.
+   Text indexes differ from the more powerful
+   :atlas:`Atlas full text search indexes </atlas-search/?jmp=docs_driver_java>`.
+   Atlas users should use Atlas search.
 
 .. common-content-end
 
@@ -279,19 +280,19 @@ Multiple Fields
 A collection can only contain one text index. If you want to create a
 text index for multiple text fields, you need to create a compound
 index. A text search runs on all the text fields within the compound
-index. 
+index.
 
 The following snippet creates a compound text index for the ``title`` and ``genre``
 fields:
 
 .. code-block:: java
-   
+
    collection.createIndex(Indexes.compoundIndex(Indexes.text("title"), Indexes.text("genre")));
-   
+
 For more information, see the following Server Manual Entries:
 
 - :manual:`Compound Text Index Restrictions </core/index-text/#std-label-text-index-compound>`
-- :manual:`Text Indexes </core/index-text>` 
+- :manual:`Text Indexes </core/index-text>`
 
 Geospatial Indexes
 ~~~~~~~~~~~~~~~~~~
@@ -398,7 +399,7 @@ Remove an Index
 ---------------
 
 You can remove any unused index except the default unique index on the
-``_id`` field. 
+``_id`` field.
 
 The following sections show the ways to remove indexes:
 
@@ -412,7 +413,7 @@ Remove an Index Using an Index Specification Document
 Pass an **index specification document** to the ``dropIndex()`` method to
 remove an index from a collection. An index specification document is
 a ``Bson`` instance that specifies the type of index on a
-specified field. 
+specified field.
 
 The following snippet removes an ascending index on the ``title`` field
 in a collection:
@@ -425,7 +426,7 @@ in a collection:
 
    If you want to drop a text index, you must use the name of the index
    instead. See the :ref:`Remove an Index Using a Name Field
-   <name_field>` section for details. 
+   <name_field>` section for details.
 
 .. _name_field:
 
@@ -436,10 +437,10 @@ Pass the ``name`` field of the index to the ``dropIndex()`` method to
 remove an index from a collection.
 
 If you need to find the name of your index, use the ``listIndexes()``
-method to see the value of the ``name`` fields in your indexes. 
+method to see the value of the ``name`` fields in your indexes.
 
 The following snippet retrieves and prints all the indexes in a
-collection: 
+collection:
 
 .. literalinclude:: /includes/fundamentals/code-snippets/SearchText.java
    :language: java
@@ -448,25 +449,25 @@ collection:
    :end-before: end listIndex
 
 If you call ``listIndex()`` on a collection that contains a text index,
-the output might resemble the following: 
+the output might resemble the following:
 
 .. code-block:: json
    :copyable: false
 
    { "v": 2, "key": {"_id": 1}, "name": "_id_" }
-   { "v": 2, "key": {"_fts": "text", "_ftsx": 1}, "name": "title_text", "weights": {"title": 1}, 
+   { "v": 2, "key": {"_fts": "text", "_ftsx": 1}, "name": "title_text", "weights": {"title": 1},
    "default_language": "english", "language_override": "language", "textIndexVersion": 3 }
 
 This output tells us the names of the existing indexes are "_id" and
-"title_text". 
+"title_text".
 
 The following snippet removes the "title_text" index from the collection:
 
 .. code-block:: java
 
    collection.dropIndex("title_text");
 
-.. note:: 
+.. note::
 
    You cannot remove a single field from a compound text index. You must
    drop the entire index and create a new one to update the indexed
@@ -476,7 +477,7 @@ Remove an Index Using a Wildcard Character
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Starting with MongoDB 4.2, you can drop all indexes by calling the
-``dropIndexes()`` method on your collection: 
+``dropIndexes()`` method on your collection:
 
 .. code-block:: java
 

source/includes/fundamentals/localhost-connection.rst

@@ -0,0 +1,27 @@
+If you need to run a MongoDB server on your local machine for development
+purposes instead of using an Atlas cluster, you need to complete the following:
+
+1. Download the `Community <https://www.mongodb.com/try/download/community>`__
+   or `Enterprise <https://www.mongodb.com/try/download/enterprise>`__ version
+   of MongoDB Server.
+
+#. `Install and configure <https://docs.mongodb.com/manual/installation/>`__
+   MongoDB Server.
+
+#. Start the server.
+
+.. important::
+
+   Always secure your MongoDB server from malicious attacks. See our
+   :manual:`Security Checklist </administration/security-checklist/>` for a
+   list of security recommendations.
+
+After you successfully start your MongoDB server, specify your connection
+string in your driver connection code.
+
+If your MongoDB Server is running locally, you can use the connection string
+``"mongodb://localhost:<port>"`` where ``<port>`` is the port number you
+configured your server to listen for incoming connections.
+
+If you need to specify a different hostname or IP address, see our Server
+Manual entry on :manual:`Connection Strings </reference/connection-string/>`.

source/includes/localhost-connection.rst

@@ -3,9 +3,9 @@ Set up a Free Tier Cluster in Atlas
 
 After setting up your Java project dependencies, create a MongoDB cluster
 where you can store and manage your data. Complete the
-:atlas:`Get Started with Atlas </getting-started>` guide to set up a new
-Atlas account, create and launch a free tier MongoDB cluster, load datasets, and
-interact with the data.
+:atlas:`Get Started with Atlas </getting-started?jmp=docs_driver_java>` guide
+to set up a new Atlas account, create and launch a free tier MongoDB cluster,
+load datasets, and interact with the data.
 
 After completing the steps in the Atlas guide, you should have a new MongoDB
 cluster deployed in Atlas, a new database user, and sample datasets loaded
@@ -24,6 +24,10 @@ includes information on the hostname or IP address and port of your
 cluster, authentication mechanism, user credentials when applicable, and
 other connection options.
 
+If you are connecting to an instance or cluster that is not hosted by Atlas,
+see :ref:`Other Ways to Connect to MongoDB <java-other-ways-to-connect>` for
+instructions on how to format your connection string.
+
 To retrieve your connection string for the cluster and user you created in
 the previous step, log into your Atlas account and navigate to the
 **Clusters** section and click the **Connect** button for the cluster that you

source/includes/quick-start/atlas-setup.rst

@@ -96,11 +96,6 @@ After completing this step, you should have a working application that uses
 the Java driver to connect to your MongoDB cluster, run a query on the
 sample data, and print out the result.
 
-Connect to ``localhost``
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. include:: /includes/localhost-connection.rst
-
 Working with POJOs (Optional)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

source/quick-start.txt

@@ -41,10 +41,10 @@ operations. Each example provides the following information:
 How to Use the Usage Examples
 -----------------------------
 
-These examples use the :atlas:`sample datasets </sample-data>` provided by
-Atlas. You can load them into your database on the free tier of MongoDB
-Atlas by following the
-:atlas:`Get Started with Atlas Guide </getting-started/#atlas-getting-started>`
+These examples use the :atlas:`sample datasets </sample-data?jmp=docs_driver_java>`
+provided by Atlas. You can load them into your database on the free tier of
+MongoDB Atlas by following the
+:atlas:`Get Started with Atlas Guide </getting-started/#atlas-getting-started?jmp=docs_driver_java>`
 or you can
 :guides:`import the sample dataset into a local MongoDB instance
 </server/import/>`.

source/usage-examples.txt

@@ -29,7 +29,7 @@ New features of the 4.3 Java driver release include:
 - Added support for connection to
   `MongoDB Atlas Serverless Instances <https://www.mongodb.com/cloud/atlas/serverless>`__.
   For more information on setup, see our documentation on how to
-  :atlas:`Create a New Serverless Instance </tutorial/create-new-serverless-instance/>`
+  :atlas:`Create a New Serverless Instance </tutorial/create-new-serverless-instance/?jmp=docs_driver_java>`
 - Added a builder API for the ``setWindowFields`` pipeline stage to allow the use of window operators
 - Added support for setting Netty `io.netty.handler.ssl.SslContext <https://netty.io/4.1/api/io/netty/handler/ssl/SslContext.html>`__
 - Added support for snapshot reads to ``ClientSession``