diff --git a/source/connection.txt b/source/connection.txt index d34dc63f2..92a7feda6 100644 --- a/source/connection.txt +++ b/source/connection.txt @@ -10,6 +10,7 @@ Connection Guide Connection Options MongoClient Settings Stable API + Connection Pools Network Compression JNDI Datasource Connection Troubleshooting diff --git a/source/connection/connection-pools.txt b/source/connection/connection-pools.txt new file mode 100644 index 000000000..26e18b75c --- /dev/null +++ b/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://:/?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 ` + 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:`` guide. + +Additional Information +---------------------- + +For more information on using a connection pool, see the +:manual:`Connection Pool ` +documentation in the Server manual. diff --git a/source/includes/fundamentals/code-snippets/ConnectionPool.java b/source/includes/fundamentals/code-snippets/ConnectionPool.java new file mode 100644 index 000000000..f3b7b817e --- /dev/null +++ b/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("")) + .applyToConnectionPoolSettings(builder -> + builder.maxSize(50)) + .build()); + //end MongoSettings + mongoClient.listDatabaseNames().forEach(n -> System.out.println(n)); + mongoClient.close(); + } finally { + System.out.print("---------------------------------------"); + } + } + +} diff --git a/source/includes/fundamentals/code-snippets/mcs.java b/source/includes/fundamentals/code-snippets/MCSettings.java similarity index 98% rename from source/includes/fundamentals/code-snippets/mcs.java rename to source/includes/fundamentals/code-snippets/MCSettings.java index 23a424cfb..c38717be8 100644 --- a/source/includes/fundamentals/code-snippets/mcs.java +++ b/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("")) .applyToConnectionPoolSettings(builder -> builder.maxWaitTime(10, SECONDS) - .maxSize(200) + .maxSize(200)) .build()); //end ConnectionPoolSettings mongoClient.listDatabaseNames().forEach(n -> System.out.println(n));