mongo client settings

Author: rachel-mack

source/connection/mongoclient.txt

@@ -32,9 +32,51 @@ MongoClient
 -----------
 
 You can connect to and communicate with MongoDB using the ``MongoClient``
-class.
+class. To create a `MongoClientSettings
+<{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__ object, use the ``MongoClientSettings.builder()`` method and chain methods to specify your
+settings. After chaining them, use the ``build()`` method to create the
+``MongoClientSettings`` object.
 
-Use the ``MongoClients.create()`` method to construct a ``MongoClient``.
+To learn about the different settings you can use to control the behavior of your ``MongoClient``, see the :ref:`Specify MongoClient Settings <specify-mongoclient-settings>` guide.
+
+Example
+~~~~~~~
+
+This example demonstrates specifying a ``ConnectionString``:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java
+   :start-after: begin ConnectionString
+   :end-before: end ConnectionString
+   :language: java
+   :emphasize-lines: 3
+   :dedent:
+
+.. note:: Chain Order
+
+   Some options in the settings map to a connection string option.
+   If you specify the same options in your settings and connection
+   string, the order you chain them determines which option the driver
+   uses. The driver uses the **last** setting it reads.
+
+   For example, this snippet contains settings with the following times
+   for the driver to connect to an available socket:
+
+   - The connection string specifies within ``2 SECONDS``
+   - The :ref:`socket settings <mcs-socket-settings>` specifies within
+     ``5 SECONDS``
+
+   .. code-block:: java
+      :emphasize-lines: 2,4
+
+      MongoClient mongoClient = MongoClients.create(
+         MongoClientSettings.builder().applyConnectionString(new ConnectionString("mongodb+srv://<db_username>:<db_password>@<hostname>:<port>/<auth db>?connectTimeoutMS=2000"))
+            .applyToSocketSettings(builder ->
+            builder.connectTimeout(5L, SECONDS))
+            .build());
+
+   Since the driver reads the socket settings options last, the driver
+   expects to connect to an available socket within ``5 SECONDS`` before
+   timing out.
 
 .. important:: Reuse Your Client
 
@@ -44,10 +86,6 @@ Use the ``MongoClients.create()`` method to construct a ``MongoClient``.
    All resource usage limits, such as max connections, apply to individual
    ``MongoClient`` instances.
 
-To learn about the different settings you can use to control the
-behavior of your ``MongoClient``, see the
-:ref:`Specify MongoClient Settings <specify-mongoclient-settings>` guide.
-
 .. tip::
 
    Always call ``MongoClient.close()`` to clean up resources when an

source/connection/specify-connection-options.txt

@@ -6,8 +6,6 @@ Specify Connection Options
 
 .. toctree::
 
-   MongoClient Settings
-   </connection/specify-connection-options/mongoclientsettings>
    Stable API </connection/specify-connection-options/stable-api>
    Connection Pools </connection/specify-connection-options/connection-pools>
    Cluster Settings </connection/specify-connection-options/cluster-settings>

source/connection/specify-connection-options/cluster-settings.txt

@@ -86,6 +86,18 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available:
            your :ref:`connection URI <connection-uri>` to use this option.  
 
            **Default**: ``mongodb``
+    
+    This example connects the driver directly to a server,
+    regardless of the type of MongoDB cluster it's a part of:
+
+    .. code-block:: java
+
+      ConnectionString connectionString = "mongodb://<host>:<port>/?directConnection=true"
+      MongoClient mongoClient = MongoClients.create(connectionString)
+    
+    For more information about these parameters, see the `ConnectionString
+    <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__
+    API documentation.
 
   .. tab:: MongoClientSettings
     :tabid: MongoClient
@@ -163,7 +175,7 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available:
 
            Throws an exception if you are not using the SRV connection protocol.
 
-    This example specifies for the driver to connect directly to a server,
+    This example connects the driver directly to a server,
     regardless of the type of MongoDB cluster it's a part of:
 
     .. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java

source/connection/specify-connection-options/mongoclientsettings.txt

@@ -56,20 +56,14 @@ by specifying the algorithms in one of the following ways:
 - Use the ``compressors`` parameter in your connection string.
 - Chain the ``compressorList()`` method to the ``MongoClientSettings.builder()`` method.
 
-This example shows how to specify the Snappy, Zstandard, and Zlib compression
-algorithms. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings`
+Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings`
 tab to see the corresponding syntax:
 
 .. tabs::
 
   .. tab:: Connection String
     :tabid: uri
 
-    .. literalinclude:: /includes/connect/NetworkCompression.java
-       :start-after: start-specify-connection-string
-       :end-before: end-specify-connection-string
-       :language: java
-
     Include the following parameters in your connection string to enable compression:
 
     .. list-table:: 
@@ -98,14 +92,40 @@ tab to see the corresponding syntax:
            values compressing slower (but resulting in smaller requests). 
 
            **Default**: ``null``
+   
+    The following specifies the order in which the driver will attempt to
+    compress requests before they are sent:
+
+    .. literalinclude:: /includes/connect/NetworkCompression.java
+       :start-after: start-specify-connection-string
+       :end-before: end-specify-connection-string
+       :language: java
+    
+    For more information about these parameters, see the `ConnectionString
+    <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__
+    API documentation.
 
   .. tab:: MongoClientSettings
-     :tabid: mongoclientsettings
+    :tabid: mongoclientsettings
+
+    Chain the following methods to your ``MongoClientSettings``  constructor to modify the driver's compression behavior:
+
+    .. list-table::
+       :widths: 40 60
+       :header-rows:  1
+
+       * - Method
+         - Description
+
+       * - ``compressorList()``
+         - Sets the compressors to use for compressing messages to the server.
+
+    .. literalinclude:: /includes/connect/NetworkCompression.java
+       :start-after: start-specify-client-settings
+       :end-before: end-specify-client-settings
+       :language: java
 
-     .. literalinclude:: /includes/connect/NetworkCompression.java
-        :start-after: start-specify-client-settings
-        :end-before: end-specify-client-settings
-        :language: java
+    For more information, see the `MongoClientSettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ API documentation.
 
 .. _java-compression-dependencies:
 

source/connection/specify-connection-options/network-compression.txt

@@ -99,9 +99,6 @@ Configuring Server Settings
       * - ``addServerMonitorListener()``
         - Adds a listener for server monitor-related events.
 
-      * - ``applyConnectionString()``
-        - Uses the settings from a ``ConnectionString`` object.
-
       * - ``applySettings()``
         - Uses the server settings specified in a ``ServerSettings`` object.
 

source/connection/specify-connection-options/server-settings.txt

@@ -141,6 +141,7 @@ private static void createLoggerSettings() {
             ////begin LoggerSettings
             MongoClient mongoClient = MongoClients.create(
                 MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
+                .applicationName("<application name>")
                 .applyToLoggerSettings(builder ->
                      builder.maxDocumentLength(5_000))
                 .build());