DOCSP-47031 Connection Pools

source/connection.txt

@@ -10,6 +10,7 @@ Connection Guide
    Connection Options </connection/connection-options>
    MongoClient Settings </connection/mongoclientsettings>
    Stable API </connection/stable-api>
+   Connection Pools </connection/connection-pools>
    Network Compression </connection/network-compression>
    JNDI Datasource </connection/jndi>
    Connection Troubleshooting </connection/connection-troubleshooting>

source/connection/connection-pools.txt

@@ -0,0 +1,139 @@
+.. _java-connection-pools:
+
+================
+Connection Pools
+================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+Overview
+--------
+
+In this guide, you can learn about how the {+driver-short+} uses connection pools to manage
+connections to a MongoDB deployment and how you can configure connection pool settings
+in your application.
+
+A connection pool is a cache of open database connections maintained by the {+driver-short+}.
+When your application requests a connection to MongoDB, the {+driver-short+} seamlessly
+gets a connection from the pool, performs operations, and returns the connection
+to the pool for reuse.
+
+Connection pools help reduce application latency and the number of times new connections
+are created by {+driver-short+}.
+
+Create a Connection Pool
+------------------------
+
+Every ``MongoClient`` instance has a built-in connection pool for each server 
+in your MongoDB topology. Connection pools open sockets on demand to support 
+concurrent MongoDB operations in your multi-threaded application.
+
+The ``maxPoolSize`` option sets the maximum size of each connection pool, which 
+defaults to 100. If the number of in-use connections to a server reaches the 
+value of ``maxPoolSize``, the next request to that server will wait until a 
+connection becomes available.
+
+Each ``MongoClient`` instance opens two more sockets per server in your MongoDB 
+topology for monitoring the server's state.
+
+Configure a Connection Pool
+---------------------------
+
+You can specify settings for your connection pool using either a connection
+string or by passing a ``MongoClientSettings`` object to the 
+``MongoClients.create()`` method.
+
+The following code creates a client with a maximum connection pool size of ``50``. 
+Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings`  tab to
+see the corresponding syntax:
+
+.. tabs::
+
+  .. tab:: Connection String
+    :tabid: uri
+
+    .. code-block:: java
+
+      ConnectionString connectionString = "mongodb://<host>:<port>/?maxPoolSize=50"
+      MongoClient mongoClient = MongoClients.create(connectionString)
+
+    The following are connection string settings you can use to configure your 
+    connection pool:
+
+    .. list-table::
+      :widths: 25,75                                                          
+      :header-rows: 1
+
+      * - Setting
+        - Description
+
+      * - ``maxConnecting``
+
+        - Maximum number of connections a pool may establish
+          concurrently.
+
+          *Default:* ``2``
+
+      * - ``maxIdleTimeMS``
+
+        - The maximum number of milliseconds that a connection can 
+          remain idle in the pool before being removed and closed.
+
+          *Default:* ``0``
+
+      * - ``maxPoolSize``
+
+        - Maximum number of connections opened in the pool. When the 
+          connection pool reaches the maximum number of connections, new 
+          connections wait up until to the value of 
+          ``waitQueueTimeoutMS``.
+
+          *Default:* ``100`` 
+
+      * - ``minPoolSize``
+
+        - Minimum number of connections opened in the pool. 
+          The value of ``minPoolSize`` must be less than 
+          the value of ``maxPoolSize``.
+
+          *Default*: ``0``
+
+      * - ``waitQueueTimeoutMS``
+
+        - Maximum wait time in milliseconds that an operation can wait for 
+          a connection to become available. A value of ``0`` means there
+          is no limit. 
+
+          *Default*: ``120000`` (120 seconds)
+
+    To learn more about connection string options, see the 
+    :ref:`Connection Options <connection-options>`
+    guide. 
+
+  .. tab:: MongoClientSettings
+     :tabid: MongoClient
+
+     .. literalinclude:: /includes/fundamentals/code-snippets/ConnectionPool.java
+        :start-after: begin MongoSettings
+        :end-before: end MongoSettings
+        :language: java
+        :dedent:
+
+     For more information on configuring you connection pool by using a 
+     ``MongoClientSettings`` object see the Connection Pool Settings section
+     of the :ref:`<specify-mongoclient-settings>` guide. 
+
+Additional Information
+----------------------
+
+For more information on using a connection pool, see the 
+:manual:`Connection Pool </administration/connection-pool-overview>`
+documentation in the Server manual. 

source/includes/fundamentals/code-snippets/ConnectionPool.java

@@ -0,0 +1,36 @@
+import static java.util.concurrent.TimeUnit.*;
+
+import com.mongodb.client.MongoClient;
+import com.mongodb.client.MongoClients;
+import com.mongodb.connection.ClusterConnectionMode;
+import com.mongodb.ConnectionString;
+import com.mongodb.MongoClientSettings;
+
+public class ConnectionPool {
+
+    public static void main(String[] args) {
+
+        System.out.println("MongoSettings:");
+        createMongoSettings();
+        System.out.println();
+
+    }
+
+       private static void createMongoSettings() {
+        try {
+            //begin MongoSettings
+            MongoClient mongoClient = MongoClients.create(
+                MongoClientSettings.builder().applyConnectionString(
+                    new ConnectionString("<your connection string>"))
+                .applyToConnectionPoolSettings(builder ->
+                    builder.maxSize(50))
+                .build());
+            //end MongoSettings
+            mongoClient.listDatabaseNames().forEach(n -> System.out.println(n));
+            mongoClient.close();
+        } finally {
+            System.out.print("---------------------------------------");
+        }
+    }
+
+}

source/includes/fundamentals/code-snippets/mcs.java → source/includes/fundamentals/code-snippets/MCSettings.java

@@ -58,7 +58,7 @@ private static void createClusterSettings() {
             MongoClient mongoClient = MongoClients.create(
                 MongoClientSettings.builder()
                 .applyToClusterSettings(builder ->
-                    builder.mode(ClusterConnectionMode.SINGLE)
+                    builder.mode(ClusterConnectionMode.SINGLE))
                 .build());
             //end ClusterSettings
             mongoClient.listDatabaseNames().forEach(n -> System.out.println(n));
@@ -109,7 +109,7 @@ private static void createConnectionPoolSettings() {
                 MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
                 .applyToConnectionPoolSettings(builder ->
                     builder.maxWaitTime(10, SECONDS)
-                    .maxSize(200)
+                    .maxSize(200))
                 .build());
             //end ConnectionPoolSettings
             mongoClient.listDatabaseNames().forEach(n -> System.out.println(n));