From 26b875ae568cfafb3fb55827c6556560ad70dbc4 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 20 Mar 2025 12:18:50 -0400 Subject: [PATCH 1/9] DOCSP-35923: csot page --- .../connection/specify-connection-options.txt | 4 +- .../connection-options.txt | 8 + .../specify-connection-options/csot.txt | 295 ++++++++++++++++++ .../mongoclientsettings.txt | 6 +- source/crud/read-operations/cursor.txt | 12 +- source/crud/transactions.txt | 6 + source/includes/connect/CSOT.java | 110 +++++++ source/versioning/whats-new.txt | 4 + 8 files changed, 439 insertions(+), 6 deletions(-) create mode 100644 source/connection/specify-connection-options/csot.txt create mode 100644 source/includes/connect/CSOT.java diff --git a/source/connection/specify-connection-options.txt b/source/connection/specify-connection-options.txt index c9b63fdbc..2c71a6c25 100644 --- a/source/connection/specify-connection-options.txt +++ b/source/connection/specify-connection-options.txt @@ -9,6 +9,7 @@ Specify Connection Options MongoClient Settings Connection URI Options Stable API + Timeout Setting Network Compression JNDI Datasource AWS Lambda @@ -25,7 +26,8 @@ Specify Connection Options - :ref:`MongoClient Settings ` - :ref:`Connection URI Options ` - :ref:`Stable API ` +- :ref:`Limit Server Execution Time ` - :ref:`Network Compression ` - :ref:`JNDI Datasource ` - `AWS Lambda `__ -- :ref:`Connection Security Options ` \ No newline at end of file +- :ref:`Connection Security Options ` diff --git a/source/connection/specify-connection-options/connection-options.txt b/source/connection/specify-connection-options/connection-options.txt index 2c2d0e862..2548f07da 100644 --- a/source/connection/specify-connection-options/connection-options.txt +++ b/source/connection/specify-connection-options/connection-options.txt @@ -103,6 +103,14 @@ parameters of the connection URI to specify the behavior of the client. | **Default**: ``false`` + * - **timeoutMS** + - integer + - Specifies the time limit, in milliseconds, for the full execution + of an operation. This option sets a client-level operations + timeout that replaces the functionality of the ``maxTimeMS`` and + ``maxCommitTimeMS`` options. To learn more, see the :ref:`java-csot` + guide. + * - **connectTimeoutMS** - integer - Specifies the maximum amount of time, in milliseconds, the Java diff --git a/source/connection/specify-connection-options/csot.txt b/source/connection/specify-connection-options/csot.txt new file mode 100644 index 000000000..4b5f2e60e --- /dev/null +++ b/source/connection/specify-connection-options/csot.txt @@ -0,0 +1,295 @@ +.. _java-csot: + +=========================== +Limit Server Execution Time +=========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: error, blocking, thread, task, code example + +Overview +-------- + +When you use the {+driver-short+} to perform a server operation, you can also +limit the amount of time in which the server can finish the operation. To do so, +specify a **client-side operation timeout (CSOT)**. The timeout applies to all +steps needed to complete the operation, including server selection, connection +checkout, and server-side execution. When the timeout expires, the +{+driver-short+} raises a timeout exception. + +.. note:: Experimental Feature + + The CSOT feature is experimental and might change in future driver + releases. + +timeoutMS Option +---------------- + +To specify a timeout when connecting to a MongoDB deployment, set the +``timeoutMS`` connection option to the timeout length in milliseconds. You can +set the ``timeoutMS`` option in the following ways: + +- Using the ``timeout()`` method from the + ``MongoClientSettings.Builder`` class +- Setting the ``timeoutMS`` parameter in your connection string + +Select from the following :guilabel:`MongoClientSettings` and +:guilabel:`Connection String` tabs to view how to set a client-level +timeout of 5 seconds by using each method: + +.. tabs:: + + .. tab:: MongoClientSettings + :tabid: mongoclientsettings + + .. literalinclude:: /includes/connect/CSOT.java + :language: java + :start-after: start-mongoclientsettings + :end-before: end-mongoclientsettings + :dedent: + :emphasize-lines: 3 + + .. tab:: Connection String + :tabid: connection-string + + .. literalinclude:: /includes/connect/CSOT.java + :language: java + :start-after: start-string + :end-before: end-string + +Behavior +~~~~~~~~ + +The following table describes the timeout behavior corresponding to the +accepted values for ``timeoutMS``: + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Value + - Behavior + + * - Positive value + - Sets the timeout to use for operation completion. + + * - ``0`` + - Sets an infinite timeout. + + * - ``null`` + - | Defers the timeout behavior to the following settings: + | + | - :manual:`waitQueueTimeoutMS ` + | - :manual:`socketTimeoutMS ` + | - :manual:`wTimeoutMS ` + | - :manual:`maxTimeMS ` *(deprecated)* + | - `maxCommitTimeMS <{+core-api+}/com/mongodb/TransactionOptions.Builder.html#maxCommitTime(java.lang.Long,java.util.concurrent.TimeUnit)>`__ *(deprecated)* + | + | When the CSOT feature is no longer experimental, all the + preceding options will be deprecated. + +If you specify the ``timeoutMS`` option, the driver automatically applies the +specified timeout for each server operation. The following code example specifies +a timeout of 5 seconds at the client level, and then calls the +``MongoCollection.insertOne()`` method: + +.. literalinclude:: /includes/connect/CSOT.java + :language: java + :start-after: start-operation-timeout + :end-before: end-operation-timeout + :dedent: + +Timeout Inheritance +~~~~~~~~~~~~~~~~~~~ + +When you specify the ``timeoutMS`` option, the driver applies the timeout +according to the same inheritance behaviors as the other {+driver-short+} options. +The following table describes how the timeout value is inherited at each level: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Level + - Inheritance Description + + * - Operation + - Takes the highest precedence and will override ``timeoutMS`` + options set at any other level. + + * - Transaction + - Takes precedence over ``timeoutMS`` set at the session, + collection, database, or client level. + + * - Session + - Applies to all transactions and operations within + that session, unless the option is overridden by options set at those levels. + + * - Database + - Applies to all sessions and operations within that + database, unless the option is overridden by options set at those levels. + + * - Collection + - Applies to all sessions and operations on that + collection, unless the option is overridden by options set at those levels. + + * - Client + - Applies to all databases, collections, sessions, transactions, and + operations within that client that do not otherwise specify + ``timeoutMS``. + +For more information on overrides and specific options, see the following +:ref:`java-csot-overrides` section. + +.. _java-csot-overrides: + +Overrides +--------- + +The {+driver-short+} supports various levels of configuration to control the +behavior and performance of database operations. + +You can specify a ``timeoutMS`` option at the operation level to override the +client-level configuration for a specific operation. This allows you to +customize timeouts based on the needs of individual queries. + +The following example demonstrates how an collection-level timeout +configuration can override a client-level timeout configuration: + +.. literalinclude:: /includes/connect/CSOT.java + :language: java + :start-after: start-override + :end-before: end-override + :dedent: + :emphasize-lines: 10 + +.. _java-csot-txn: + +Transactions +~~~~~~~~~~~~ + +When you create a new `ClientSession +<{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html>`__ +instance to implement a transaction, use +the ``defaultTimeout()`` method when building a ``ClientSessionOptions`` +instance. You can use this option to specify the timeout to apply for +the following methods: + +- `commitTransaction() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#commitTransaction()>`__ +- `abortTransaction() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#abortTransaction()>`__ +- `withTransaction() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#withTransaction(com.mongodb.client.TransactionBody)>`__ +- `close() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/session/ClientSession.html#close()>`__ + +If you do not specify the ``defaultTimeout``, the driver uses the timeout +value set on the parent ``MongoClient``. + +You can also set a transaction-level timeout by using the ``timeout()`` +method when building a ``TransactionOptions`` instance. Setting this +option applies a timeout to all operations performed in the scope of the +transaction. + +To learn more about transactions, see the :ref:`java-fundamentals-transactions` guide. + +Client Encryption +~~~~~~~~~~~~~~~~~ + +When you use Client-Side Field Level Encryption (CSFLE), the driver uses the +``timeoutMS`` option to limit the time allowed for encryption and decryption +operations. You can set a timeout option for your ``ClientEncryption`` +instance by using the ``timeout()`` method when building a +``ClientEncryptionSettings`` instance. + +If you specify the timeout when you construct a +``ClientEncryption`` instance, it controls the lifetime of all operations +performed on that instance. If you do not provide a timeout when +instantiating ``ClientEncryption``, the instance +inherits the timeout setting from the ``MongoClient`` used in the +``ClientEncryption`` constructor. + +If you set ``timeoutMS`` on both the client and directly in +``ClientEncryption``, the value provided to ``ClientEncryption`` takes +precedence. + +.. _java-csot-cursor: + +Cursors +------- + +Cursors offer configurable timeout settings when using the CSOT feature. You can +adjust cursor handling by configuring either the cursor lifetime or cursor +iteration mode. To configure the timeout mode, use the ``timeoutMode()`` +method when performing any operation that returns an ``Iterable``. + +For operations that create cursors, the timeout setting can either cap the +lifetime of the cursor or be applied separately to the original +operation and all subsequent calls. + +.. note:: Inherited Timeout + + Setting a cursor timeout mode requires that you set a timeout either + in the ``MongoClientSettings``, on ``MongoDatabase``, or on + ``MongoCollection``. + +To learn more about cursors, see the :ref:`java-fundamentals-cursor` guide. + +Cursor Lifetime Mode +~~~~~~~~~~~~~~~~~~~~ + +The cursor lifetime mode uses the timeout setting to limit the entire lifetime of a +cursor. In this mode, the initialization of the cursor and all subsequent calls +to the cursor methods must complete within the limit specified by the +timeout option. All documents must be returned within this limit. +Otherwise, the cursor's lifetime expires and a timeout error occurs. + +When you close a cursor by calling the ``close()`` method, the +timeout resets for the ``killCursors`` command to ensure server-side resources are +cleaned up. + +The following example shows how to set a cursor timeout to ensure that +the cursor is initialized and all documents are retrieved within the +inherited timeout: + +.. literalinclude:: /includes/connect/CSOT.java + :language: java + :start-after: start-cursor-lifetime + :end-before: end-cursor-lifetime + :dedent: + :emphasize-lines: 3 + +Cursor Iteration Mode +~~~~~~~~~~~~~~~~~~~~~ + +The cursor iteration mode sets the timeout to limit each call to +the ``next()``, ``hasNext()``, and ``tryNext()`` methods. The timeout refreshes +after each call completes. This is the default mode for all tailable cursors, +such as the tailable cursors returned by the ``find()`` method on capped +collections or change streams. + +The following code example iterates over documents in the ``db.people`` collection +by using a cursor with the ``ITERATION`` timeout mode, and then retrieves +and prints the ``name`` field value for each document: + +.. literalinclude:: /includes/connect/CSOT.java + :language: java + :start-after: start-cursor-iteration + :end-before: end-cursor-iteration + :dedent: + :emphasize-lines: 3 + +API Documentation +----------------- + +To learn more about using timeouts with the {+driver-short+}, see the following +API documentation: + + diff --git a/source/connection/specify-connection-options/mongoclientsettings.txt b/source/connection/specify-connection-options/mongoclientsettings.txt index f6be3284c..49c5e48c0 100644 --- a/source/connection/specify-connection-options/mongoclientsettings.txt +++ b/source/connection/specify-connection-options/mongoclientsettings.txt @@ -142,6 +142,10 @@ connection behavior: - Sets the :ref:`server API ` to use when sending commands to the server. + * - ``timeout()`` + - Sets the time limit for the full execution of an operation. To + learn more, see the :ref:`java-csot` guide. + * - ``transportSettings()`` - Sets `TransportSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/connection/TransportSettings.html>`__. @@ -598,4 +602,4 @@ to MongoDB: :end-before: end SslSettings :language: java :emphasize-lines: 3-4 - :dedent: \ No newline at end of file + :dedent: diff --git a/source/crud/read-operations/cursor.txt b/source/crud/read-operations/cursor.txt index 9dae11158..7145942ad 100644 --- a/source/crud/read-operations/cursor.txt +++ b/source/crud/read-operations/cursor.txt @@ -4,8 +4,6 @@ Access Data From a Cursor ========================= - - .. contents:: On this page :local: :backlinks: none @@ -15,8 +13,8 @@ Access Data From a Cursor Overview -------- -In this guide, you can learn how to access data using a **cursor** with the -MongoDB Java driver. +In this guide, you can learn how to access data using a **cursor** in +the {+driver-short+}. A cursor is a mechanism that allows an application to iterate over database results while only holding a subset of them in memory at a given time. The @@ -38,6 +36,12 @@ The ``find()`` method creates and returns an instance of a matched by your search criteria and to further specify which documents to see by setting parameters through methods. +.. tip:: Cursor Timeout + + You can set a timeout to limit the amount of time it takes to + retrieve data from a cursor. To learn more, see the + :ref:`java-csot-cursor` section of the Limit Server Execution Time guide. + Terminal Methods ---------------- diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index f9c533412..3ace38639 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -125,6 +125,12 @@ A ``ClientSession`` also has methods to retrieve session properties and modify m session properties. View the :ref:`API documentation ` to learn more about these methods. +.. tip:: Transaction Timeout + + You can set a timeout to limit the amount of time it takes operations + to complete in your transactions. To learn more, see the + :ref:`java-csot-txn` section of the Limit Server Execution Time guide. + Example ------- diff --git a/source/includes/connect/CSOT.java b/source/includes/connect/CSOT.java new file mode 100644 index 000000000..ed78ecae8 --- /dev/null +++ b/source/includes/connect/CSOT.java @@ -0,0 +1,110 @@ +package org.example; + +import static com.mongodb.client.model.Filters.eq; +import static com.mongodb.client.model.Filters.gte; +import static java.util.concurrent.TimeUnit.SECONDS; + +import com.mongodb.ConnectionString; +import com.mongodb.MongoClientSettings; +import com.mongodb.client.*; +import com.mongodb.client.cursor.TimeoutMode; +import com.mongodb.client.model.InsertOneOptions; +import com.mongodb.client.result.InsertOneResult; +import org.bson.Document; + + +public class csot { + + public static void main(String[] args) { + MongoClient mongoClient = new csot().mongoClientSettings(); + } + + private MongoClient mongoClientSettings(){ + // start-mongoclientsettings + MongoClientSettings settings = MongoClientSettings.builder() + .applyConnectionString(new ConnectionString("")) + .timeout(5L, SECONDS) + .build(); + + MongoClient mongoClient = MongoClients.create(settings); + // end-mongoclientsettings + + return mongoClient; + } + + private MongoClient connectionString(){ + // start-string + String uri = "/?timeoutMS=5000"; + MongoClient mongoClient = MongoClients.create(uri); + // end-string + + return mongoClient; + } + + private void operationTimeout(){ + // start-operation-timeout + MongoClientSettings settings = MongoClientSettings.builder() + .applyConnectionString(new ConnectionString("")) + .timeout(5L, SECONDS) + .build(); + + try (MongoClient mongoClient = MongoClients.create(settings)) { + MongoDatabase database = mongoClient.getDatabase("db"); + MongoCollection collection = database.getCollection("people"); + + InsertOneResult result = collection.insertOne(new Document("name", "Francine Loews")); + System.out.println("Inserted a document with ID: " + result.getInsertedId()); + } + // end-operation-timeout + } + + private void overrideTimeout(){ + // start-override + MongoClientSettings settings = MongoClientSettings.builder() + .applyConnectionString(new ConnectionString("")) + .timeout(5L, SECONDS) + .build(); + + try (MongoClient mongoClient = MongoClients.create(settings)) { + MongoDatabase database = mongoClient.getDatabase("db"); + MongoCollection collection = database + .getCollection("people") + .withTimeout(10L, SECONDS); + + // ... perform operations on MongoCollection + } + // end-override + } + + private void cursorTimeout(){ + MongoClientSettings settings = MongoClientSettings.builder() + .applyConnectionString(new ConnectionString("")) + .timeout(5L, SECONDS) + .build(); + + try (MongoClient mongoClient = MongoClients.create(settings)) { + MongoCollection collection = mongoClient + .getDatabase("db") + .getCollection("people"); + + // start-cursor-lifetime + FindIterable cursorWithLifetimeTimeout = collection + .find(gte("age", 40)) + .timeoutMode(TimeoutMode.CURSOR_LIFETIME); + // end-cursor-lifetime + + // start-cursor-iteration + try (MongoCursor cursorWithIterationTimeout = collection + .find(gte("age", 40)) + .timeoutMode(TimeoutMode.ITERATION) + .cursor() + ) { + while (cursorWithIterationTimeout.hasNext()) { + System.out.println(cursorWithIterationTimeout.next().toJson()); + } + } + // end-cursor-iteration + } + + } +} diff --git a/source/versioning/whats-new.txt b/source/versioning/whats-new.txt index 7af6dc3f2..b2e0b3151 100644 --- a/source/versioning/whats-new.txt +++ b/source/versioning/whats-new.txt @@ -120,6 +120,10 @@ and features: .. sharedinclude:: dbx/jvm/v5.2-wn-items.rst + .. replacement:: csot-link + + the :ref:`java-csot` guide + .. replacement:: avs-index-link :ref:`java-search-indexes` in the Indexes guide From 5a7d56bba552b412f989538f55b846766443b4df Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 20 Mar 2025 12:19:53 -0400 Subject: [PATCH 2/9] small fix --- source/connection/specify-connection-options.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connection/specify-connection-options.txt b/source/connection/specify-connection-options.txt index 2c71a6c25..a00ce9ea4 100644 --- a/source/connection/specify-connection-options.txt +++ b/source/connection/specify-connection-options.txt @@ -9,7 +9,7 @@ Specify Connection Options MongoClient Settings Connection URI Options Stable API - Timeout Setting + Timeout Setting Network Compression JNDI Datasource AWS Lambda From f941168bad4caf6663c0656dc0a1183e6e74c195 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 20 Mar 2025 13:16:18 -0400 Subject: [PATCH 3/9] api docs + fixes --- .../specify-connection-options/csot.txt | 26 ++++++++++++------- .../specify-connection-options/stable-api.txt | 3 --- source/includes/connect/CSOT.java | 3 +-- 3 files changed, 18 insertions(+), 14 deletions(-) diff --git a/source/connection/specify-connection-options/csot.txt b/source/connection/specify-connection-options/csot.txt index 4b5f2e60e..96f54b53c 100644 --- a/source/connection/specify-connection-options/csot.txt +++ b/source/connection/specify-connection-options/csot.txt @@ -66,6 +66,7 @@ timeout of 5 seconds by using each method: :language: java :start-after: start-string :end-before: end-string + :dedent: Behavior ~~~~~~~~ @@ -75,7 +76,7 @@ accepted values for ``timeoutMS``: .. list-table:: :header-rows: 1 - :widths: 35 65 + :widths: 25 75 * - Value - Behavior @@ -90,10 +91,10 @@ accepted values for ``timeoutMS``: - | Defers the timeout behavior to the following settings: | | - :manual:`waitQueueTimeoutMS ` - | - :manual:`socketTimeoutMS ` - | - :manual:`wTimeoutMS ` - | - :manual:`maxTimeMS ` *(deprecated)* - | - `maxCommitTimeMS <{+core-api+}/com/mongodb/TransactionOptions.Builder.html#maxCommitTime(java.lang.Long,java.util.concurrent.TimeUnit)>`__ *(deprecated)* + - :manual:`socketTimeoutMS ` + - :manual:`wTimeoutMS ` + - :manual:`maxTimeMS ` *(deprecated)* + - `maxCommitTimeMS <{+core-api+}/com/mongodb/TransactionOptions.Builder.html#maxCommitTime(java.lang.Long,java.util.concurrent.TimeUnit)>`__ *(deprecated)* | | When the CSOT feature is no longer experimental, all the preceding options will be deprecated. @@ -159,9 +160,9 @@ Overrides The {+driver-short+} supports various levels of configuration to control the behavior and performance of database operations. -You can specify a ``timeoutMS`` option at the operation level to override the -client-level configuration for a specific operation. This allows you to -customize timeouts based on the needs of individual queries. +You can specify a ``timeoutMS`` option at a lower level to override the +client-level configuration. This allows you to customize timeouts based +on the needs of individual operations. The following example demonstrates how an collection-level timeout configuration can override a client-level timeout configuration: @@ -292,4 +293,11 @@ API Documentation To learn more about using timeouts with the {+driver-short+}, see the following API documentation: - +- `MongoClientSettings <{+core-api+}/com/mongodb/MongoClientSettings.html>`__ +- `MongoClientSettings.Builder.timeout() <{+core-api+}/com/mongodb/MongoClientSettings.Builder.html#timeout(long,java.util.concurrent.TimeUnit)>`__ +- `MongoCollection.withTimeout() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#withTimeout(long,java.util.concurrent.TimeUnit)>`__ +- `ClientSessionOptions.Builder.defaultTimeout() <{+core-api+}/com/mongodb/ClientSessionOptions.Builder.html#defaultTimeout(long,java.util.concurrent.TimeUnit)>`__ +- `TransactionOptions.Builder.timeout() <{+core-api+}/com/mongodb/TransactionOptions.Builder.html#timeout(java.lang.Long,java.util.concurrent.TimeUnit)>`__ +- `ClientEncryptionSettings.Builder.timeout() <{+core-api+}/com/mongodb/ClientEncryptionSettings.Builder.html#timeout(long,java.util.concurrent.TimeUnit)>`__ +- `FindIterable.timeoutMode() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/FindIterable.html#timeoutMode(com.mongodb.client.cursor.TimeoutMode)>`__ +- `TimeoutMode <{+core-api+}/com/mongodb/client/cursor/TimeoutMode.html>`__ diff --git a/source/connection/specify-connection-options/stable-api.txt b/source/connection/specify-connection-options/stable-api.txt index f536c5eff..c5b61a9bc 100644 --- a/source/connection/specify-connection-options/stable-api.txt +++ b/source/connection/specify-connection-options/stable-api.txt @@ -5,8 +5,6 @@ {+stable-api+} ============== - - .. contents:: On this page :local: :backlinks: none @@ -145,4 +143,3 @@ API Documentation: - `strict() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ServerApi.Builder.html#strict(boolean)>`__ - `deprecationErrors() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ServerApi.Builder.html#>`__ - diff --git a/source/includes/connect/CSOT.java b/source/includes/connect/CSOT.java index ed78ecae8..84a075c89 100644 --- a/source/includes/connect/CSOT.java +++ b/source/includes/connect/CSOT.java @@ -52,8 +52,7 @@ private void operationTimeout(){ MongoDatabase database = mongoClient.getDatabase("db"); MongoCollection collection = database.getCollection("people"); - InsertOneResult result = collection.insertOne(new Document("name", "Francine Loews")); - System.out.println("Inserted a document with ID: " + result.getInsertedId()); + collection.insertOne(new Document("name", "Francine Loews")); } // end-operation-timeout } From 739a254c6b5322d331bc4592c69e896e7d1fe183 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 20 Mar 2025 14:08:36 -0400 Subject: [PATCH 4/9] txn code examples --- .../specify-connection-options/csot.txt | 19 ++++++++++-- source/includes/connect/CSOT.java | 31 +++++++++++++++++++ 2 files changed, 48 insertions(+), 2 deletions(-) diff --git a/source/connection/specify-connection-options/csot.txt b/source/connection/specify-connection-options/csot.txt index 96f54b53c..dafa19325 100644 --- a/source/connection/specify-connection-options/csot.txt +++ b/source/connection/specify-connection-options/csot.txt @@ -164,7 +164,7 @@ You can specify a ``timeoutMS`` option at a lower level to override the client-level configuration. This allows you to customize timeouts based on the needs of individual operations. -The following example demonstrates how an collection-level timeout +The following example demonstrates how a collection-level timeout configuration can override a client-level timeout configuration: .. literalinclude:: /includes/connect/CSOT.java @@ -191,13 +191,28 @@ the following methods: - `withTransaction() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#withTransaction(com.mongodb.client.TransactionBody)>`__ - `close() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/session/ClientSession.html#close()>`__ +The following code demonstrates how to set the ``defaultTimeout`` when +instantiating a ``ClientSession``: + +.. literalinclude:: /includes/connect/CSOT.java + :language: java + :start-after: start-session-timeout + :end-before: end-session-timeout + :dedent: + If you do not specify the ``defaultTimeout``, the driver uses the timeout value set on the parent ``MongoClient``. You can also set a transaction-level timeout by using the ``timeout()`` method when building a ``TransactionOptions`` instance. Setting this option applies a timeout to all operations performed in the scope of the -transaction. +transaction: + +.. literalinclude:: /includes/connect/CSOT.java + :language: java + :start-after: start-txn-timeout + :end-before: end-txn-timeout + :dedent: To learn more about transactions, see the :ref:`java-fundamentals-transactions` guide. diff --git a/source/includes/connect/CSOT.java b/source/includes/connect/CSOT.java index 84a075c89..154c4fda9 100644 --- a/source/includes/connect/CSOT.java +++ b/source/includes/connect/CSOT.java @@ -4,11 +4,14 @@ import static com.mongodb.client.model.Filters.gte; import static java.util.concurrent.TimeUnit.SECONDS; +import com.mongodb.ClientSessionOptions; import com.mongodb.ConnectionString; import com.mongodb.MongoClientSettings; +import com.mongodb.TransactionOptions; import com.mongodb.client.*; import com.mongodb.client.cursor.TimeoutMode; import com.mongodb.client.model.InsertOneOptions; +import com.mongodb.client.model.bulk.ClientBulkWriteOptions; import com.mongodb.client.result.InsertOneResult; import org.bson.Document; @@ -75,6 +78,34 @@ private void overrideTimeout(){ // end-override } + private void txnTimeout(){ + MongoClientSettings settings = MongoClientSettings.builder() + .applyConnectionString(new ConnectionString("")) + .build(); + + try (MongoClient mongoClient = MongoClients.create(settings)) { + MongoCollection collection = mongoClient + .getDatabase("db") + .getCollection("people"); + + // start-session-timeout + ClientSessionOptions opts = ClientSessionOptions.builder() + .defaultTimeout(5L, SECONDS) + .build(); + + ClientSession session = mongoClient.startSession(opts); + // ... perform operations on ClientSession + // end-session-timeout + + // start-txn-timeout + TransactionOptions txnOptions = TransactionOptions.builder() + .timeout(5L, SECONDS) + .build(); + // end-txn-timeout + } + + } + private void cursorTimeout(){ MongoClientSettings settings = MongoClientSettings.builder() .applyConnectionString(new ConnectionString("")) From 721aca46e6d72555e45e71eed2a4b9d01aab7865 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 20 Mar 2025 16:45:44 -0400 Subject: [PATCH 5/9] deprecations --- source/connection/connection-pools.txt | 8 ++--- .../connection-options.txt | 34 +++++++++++++------ .../specify-connection-options/csot.txt | 7 ++-- source/crud/compound-operations.txt | 3 -- .../CompoundOperatorsIndividualExamples.java | 9 +++-- 5 files changed, 34 insertions(+), 27 deletions(-) diff --git a/source/connection/connection-pools.txt b/source/connection/connection-pools.txt index 26e18b75c..89c4e1dec 100644 --- a/source/connection/connection-pools.txt +++ b/source/connection/connection-pools.txt @@ -93,8 +93,7 @@ see the corresponding syntax: - 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``. + connections wait up for the amount of time set by ``timeoutMS``. *Default:* ``100`` @@ -106,11 +105,12 @@ see the corresponding syntax: *Default*: ``0`` - * - ``waitQueueTimeoutMS`` + * - ``waitQueueTimeoutMS`` *(deprecated)* - 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. + is no limit. Set the :ref:`client-level timeout ` to + replace the functionality of this deprecated option. *Default*: ``120000`` (120 seconds) diff --git a/source/connection/specify-connection-options/connection-options.txt b/source/connection/specify-connection-options/connection-options.txt index 2548f07da..0ceb3e5db 100644 --- a/source/connection/specify-connection-options/connection-options.txt +++ b/source/connection/specify-connection-options/connection-options.txt @@ -31,10 +31,12 @@ parameters of the connection URI to specify the behavior of the client. | **Default**: ``100`` - * - **waitQueueTimeoutMS** + * - **waitQueueTimeoutMS** *(deprecated)* - integer - Specifies the maximum amount of time, in milliseconds that a - thread can wait for a connection to become available. + thread can wait for a connection to become available. Set the + :ref:`client-level timeout ` to replace the + functionality of this deprecated option. | **Default**: ``120000`` (120 seconds) @@ -105,11 +107,18 @@ parameters of the connection URI to specify the behavior of the client. * - **timeoutMS** - integer - - Specifies the time limit, in milliseconds, for the full execution - of an operation. This option sets a client-level operations - timeout that replaces the functionality of the ``maxTimeMS`` and - ``maxCommitTimeMS`` options. To learn more, see the :ref:`java-csot` - guide. + - | Specifies the time limit, in milliseconds, for the full execution + of an operation. This option sets a client-level operations + timeout that replaces the functionality of the following + deprecated options: + | + | - ``waitQueueTimeoutMS`` + - ``socketTimeoutMS`` + - ``wTimeoutMS`` + - ``maxTimeMS`` + - ``maxCommitTimeMS`` + | + | To learn more, see the :ref:`java-csot` guide. * - **connectTimeoutMS** - integer @@ -120,12 +129,13 @@ parameters of the connection URI to specify the behavior of the client. | **Default**: ``10000`` (10 seconds) - * - **socketTimeoutMS** + * - **socketTimeoutMS** *(deprecated)* - integer - Specifies the maximum amount of time, in milliseconds, the Java driver will wait to send or receive a request before timing out. A value of ``0`` instructs the driver to never time out while waiting - to send or receive a request. + to send or receive a request. Set the :ref:`client-level timeout + ` to replace the functionality of this deprecated option. | **Default**: ``0`` @@ -162,12 +172,14 @@ parameters of the connection URI to specify the behavior of the client. | **Default**: ``1`` - * - **wtimeoutMS** + * - **wtimeoutMS** *(deprecated)* - integer - Specifies a time limit, in milliseconds, for the write concern. For more information, see the server documentation for the :manual:`wtimeoutMS option `. - A value of ``0`` instructs the driver to never time out write operations. + A value of ``0`` instructs the driver to never time out write operations. Set the + :ref:`client-level timeout ` to replace the + functionality of this deprecated option. | **Default**: ``0`` diff --git a/source/connection/specify-connection-options/csot.txt b/source/connection/specify-connection-options/csot.txt index dafa19325..c887e19a4 100644 --- a/source/connection/specify-connection-options/csot.txt +++ b/source/connection/specify-connection-options/csot.txt @@ -93,11 +93,10 @@ accepted values for ``timeoutMS``: | - :manual:`waitQueueTimeoutMS ` - :manual:`socketTimeoutMS ` - :manual:`wTimeoutMS ` - - :manual:`maxTimeMS ` *(deprecated)* - - `maxCommitTimeMS <{+core-api+}/com/mongodb/TransactionOptions.Builder.html#maxCommitTime(java.lang.Long,java.util.concurrent.TimeUnit)>`__ *(deprecated)* + - :manual:`maxTimeMS ` + - `maxCommitTimeMS <{+core-api+}/com/mongodb/TransactionOptions.Builder.html#maxCommitTime(java.lang.Long,java.util.concurrent.TimeUnit)>`__ | - | When the CSOT feature is no longer experimental, all the - preceding options will be deprecated. + | These settings are deprecated and are ignored if you set ``timeoutMS``. If you specify the ``timeoutMS`` option, the driver automatically applies the specified timeout for each server operation. The following code example specifies diff --git a/source/crud/compound-operations.txt b/source/crud/compound-operations.txt index 1894761e2..de7a2ef6b 100644 --- a/source/crud/compound-operations.txt +++ b/source/crud/compound-operations.txt @@ -83,9 +83,6 @@ following options: - Exclude the ``_id`` field from the found document with a projection. - Specify an upsert, which inserts the document specified by the query filter if no documents match the query. -- Set a maximum execution time of 5 seconds for this operation on the MongoDB - instance. If the operation takes longer, the ``findOneAndUpdate()`` method - will throw a ``MongoExecutionTimeoutException``. .. literalinclude:: /includes/fundamentals/code-snippets/CompoundOperatorsIndividualExamples.java :language: java diff --git a/source/includes/fundamentals/code-snippets/CompoundOperatorsIndividualExamples.java b/source/includes/fundamentals/code-snippets/CompoundOperatorsIndividualExamples.java index 3102c5120..f2a95c5ec 100644 --- a/source/includes/fundamentals/code-snippets/CompoundOperatorsIndividualExamples.java +++ b/source/includes/fundamentals/code-snippets/CompoundOperatorsIndividualExamples.java @@ -66,11 +66,10 @@ private void findOneAndUpdateExample() { // Creates an update document to set the value of "food" to "pizza" Bson update = Updates.set("food", "pizza"); - // Defines options that specify projected fields, permit an upsert and limit execution time - FindOneAndUpdateOptions options = new FindOneAndUpdateOptions(). - projection(projection). - upsert(true). - maxTime(5, TimeUnit.SECONDS); + // Defines options that specify projected fields and permit upserts + FindOneAndUpdateOptions options = new FindOneAndUpdateOptions() + .projection(projection) + .upsert(true); // Updates the first matching document with the content of the update document, applying the specified options Document result = collection.findOneAndUpdate(filter, update, options); From a1c2f154d5262f45c380f0cdc45b8e89c345c0d5 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 20 Mar 2025 16:56:42 -0400 Subject: [PATCH 6/9] list fix --- .../connection-options.txt | 14 +++++++------- .../specify-connection-options/csot.txt | 16 ++++++++-------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/source/connection/specify-connection-options/connection-options.txt b/source/connection/specify-connection-options/connection-options.txt index 0ceb3e5db..7a65d8072 100644 --- a/source/connection/specify-connection-options/connection-options.txt +++ b/source/connection/specify-connection-options/connection-options.txt @@ -111,13 +111,13 @@ parameters of the connection URI to specify the behavior of the client. of an operation. This option sets a client-level operations timeout that replaces the functionality of the following deprecated options: - | - | - ``waitQueueTimeoutMS`` - - ``socketTimeoutMS`` - - ``wTimeoutMS`` - - ``maxTimeMS`` - - ``maxCommitTimeMS`` - | + + - ``waitQueueTimeoutMS`` + - ``socketTimeoutMS`` + - ``wTimeoutMS`` + - ``maxTimeMS`` + - ``maxCommitTimeMS`` + | To learn more, see the :ref:`java-csot` guide. * - **connectTimeoutMS** diff --git a/source/connection/specify-connection-options/csot.txt b/source/connection/specify-connection-options/csot.txt index c887e19a4..703dee044 100644 --- a/source/connection/specify-connection-options/csot.txt +++ b/source/connection/specify-connection-options/csot.txt @@ -87,15 +87,15 @@ accepted values for ``timeoutMS``: * - ``0`` - Sets an infinite timeout. - * - ``null`` + * - ``null`` or unset - | Defers the timeout behavior to the following settings: - | - | - :manual:`waitQueueTimeoutMS ` - - :manual:`socketTimeoutMS ` - - :manual:`wTimeoutMS ` - - :manual:`maxTimeMS ` - - `maxCommitTimeMS <{+core-api+}/com/mongodb/TransactionOptions.Builder.html#maxCommitTime(java.lang.Long,java.util.concurrent.TimeUnit)>`__ - | + + - :manual:`waitQueueTimeoutMS ` + - :manual:`socketTimeoutMS ` + - :manual:`wTimeoutMS ` + - :manual:`maxTimeMS ` + - `maxCommitTimeMS <{+core-api+}/com/mongodb/TransactionOptions.Builder.html#maxCommitTime(java.lang.Long,java.util.concurrent.TimeUnit)>`__ + | These settings are deprecated and are ignored if you set ``timeoutMS``. If you specify the ``timeoutMS`` option, the driver automatically applies the From 9f5742d910db94c8b10209bb9668e77e3672dd8e Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 20 Mar 2025 16:57:49 -0400 Subject: [PATCH 7/9] fix --- source/connection/connection-pools.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connection/connection-pools.txt b/source/connection/connection-pools.txt index 89c4e1dec..040403b9e 100644 --- a/source/connection/connection-pools.txt +++ b/source/connection/connection-pools.txt @@ -93,7 +93,7 @@ see the corresponding syntax: - Maximum number of connections opened in the pool. When the connection pool reaches the maximum number of connections, new - connections wait up for the amount of time set by ``timeoutMS``. + connections wait for up to the amount of time set by ``timeoutMS``. *Default:* ``100`` From 4c4e2355be3c05f430f90640ddf24175da3151a3 Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 24 Mar 2025 14:10:56 -0400 Subject: [PATCH 8/9] MW + MK PR fixes --- .../connection/specify-connection-options.txt | 2 +- .../connection-pools.txt | 18 +++-- .../specify-connection-options/csot.txt | 76 ++++++++++--------- source/crud/query-documents/cursor.txt | 8 +- source/crud/transactions.txt | 2 +- .../connect/{CSOT.java => CsotExample.java} | 2 +- 6 files changed, 59 insertions(+), 49 deletions(-) rename source/includes/connect/{CSOT.java => CsotExample.java} (99%) diff --git a/source/connection/specify-connection-options.txt b/source/connection/specify-connection-options.txt index 9c8a6d205..e793af476 100644 --- a/source/connection/specify-connection-options.txt +++ b/source/connection/specify-connection-options.txt @@ -22,7 +22,7 @@ Specify Connection Options .. toctree:: Stable API - Single Timeout Setting + Limit Execution Time Connection Pools Cluster Settings Server Settings diff --git a/source/connection/specify-connection-options/connection-pools.txt b/source/connection/specify-connection-options/connection-pools.txt index 767641b2b..33f289c0c 100644 --- a/source/connection/specify-connection-options/connection-pools.txt +++ b/source/connection/specify-connection-options/connection-pools.txt @@ -87,9 +87,12 @@ see the corresponding syntax: * - ``maxPoolSize`` - - Maximum number of connections opened in the pool. When the - connection pool reaches the maximum number of connections, new - connections wait for up to the amount of time set by ``timeoutMS``. + - Maximum number of connections opened in the pool. If an + operation needs a new connection while the connection pool has + ``maxPoolSize`` connections open, the new + operation waits for a new connection to open. To limit this + waiting time, use the single timeout setting. To learn more, + see the :ref:`java-csot` guide. *Default:* ``100`` @@ -103,10 +106,13 @@ see the corresponding syntax: * - ``waitQueueTimeoutMS`` *(deprecated)* - - Maximum wait time in milliseconds that an operation can wait for + - This option is deprecated. You can configure this timeout by + setting the the :ref:`client-level timeout ` + instead. + + 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. Set the :ref:`client-level timeout ` to - replace the functionality of this deprecated option. + is no limit. *Default*: ``120000`` (120 seconds) diff --git a/source/connection/specify-connection-options/csot.txt b/source/connection/specify-connection-options/csot.txt index 703dee044..9a1df2449 100644 --- a/source/connection/specify-connection-options/csot.txt +++ b/source/connection/specify-connection-options/csot.txt @@ -39,20 +39,20 @@ To specify a timeout when connecting to a MongoDB deployment, set the ``timeoutMS`` connection option to the timeout length in milliseconds. You can set the ``timeoutMS`` option in the following ways: -- Using the ``timeout()`` method from the +- Calling the ``timeout()`` method from the ``MongoClientSettings.Builder`` class - Setting the ``timeoutMS`` parameter in your connection string -Select from the following :guilabel:`MongoClientSettings` and -:guilabel:`Connection String` tabs to view how to set a client-level -timeout of 5 seconds by using each method: +The following code examples set a client-level timeout of ``5`` seconds. +Select the :guilabel:`MongoClientSettings` or :guilabel:`Connection +String` tab to see the corresponding code. .. tabs:: .. tab:: MongoClientSettings :tabid: mongoclientsettings - .. literalinclude:: /includes/connect/CSOT.java + .. literalinclude:: /includes/connect/CsotExample.java :language: java :start-after: start-mongoclientsettings :end-before: end-mongoclientsettings @@ -62,14 +62,14 @@ timeout of 5 seconds by using each method: .. tab:: Connection String :tabid: connection-string - .. literalinclude:: /includes/connect/CSOT.java + .. literalinclude:: /includes/connect/CsotExample.java :language: java :start-after: start-string :end-before: end-string :dedent: -Behavior -~~~~~~~~ +Accepted Timeout Values +~~~~~~~~~~~~~~~~~~~~~~~ The following table describes the timeout behavior corresponding to the accepted values for ``timeoutMS``: @@ -81,11 +81,11 @@ accepted values for ``timeoutMS``: * - Value - Behavior - * - Positive value + * - Positive integer - Sets the timeout to use for operation completion. * - ``0`` - - Sets an infinite timeout. + - Specifies that operations never time out. * - ``null`` or unset - | Defers the timeout behavior to the following settings: @@ -99,11 +99,11 @@ accepted values for ``timeoutMS``: | These settings are deprecated and are ignored if you set ``timeoutMS``. If you specify the ``timeoutMS`` option, the driver automatically applies the -specified timeout for each server operation. The following code example specifies -a timeout of 5 seconds at the client level, and then calls the +specified timeout to each server operation. The following code example specifies +a timeout of ``5`` seconds at the client level, and then calls the ``MongoCollection.insertOne()`` method: -.. literalinclude:: /includes/connect/CSOT.java +.. literalinclude:: /includes/connect/CsotExample.java :language: java :start-after: start-operation-timeout :end-before: end-operation-timeout @@ -124,24 +124,27 @@ The following table describes how the timeout value is inherited at each level: - Inheritance Description * - Operation - - Takes the highest precedence and will override ``timeoutMS`` - options set at any other level. + - Takes the highest precedence and overrides the timeout + options that you set at any other level. * - Transaction - - Takes precedence over ``timeoutMS`` set at the session, + - Takes precedence over the timeout value that you set at the session, collection, database, or client level. * - Session - Applies to all transactions and operations within - that session, unless the option is overridden by options set at those levels. + that session, unless you set a different timeout value at those + levels. * - Database - Applies to all sessions and operations within that - database, unless the option is overridden by options set at those levels. + database, unless you set a different timeout value at those + levels. * - Collection - Applies to all sessions and operations on that - collection, unless the option is overridden by options set at those levels. + collection, unless you set a different timeout value at those + levels. * - Client - Applies to all databases, collections, sessions, transactions, and @@ -159,14 +162,15 @@ Overrides The {+driver-short+} supports various levels of configuration to control the behavior and performance of database operations. -You can specify a ``timeoutMS`` option at a lower level to override the -client-level configuration. This allows you to customize timeouts based -on the needs of individual operations. +You can specify a ``timeoutMS`` option at a more specific level to override the +client-level configuration. The table in the preceding section describes +the levels at which you can specify a timeout setting. This allows you +to customize timeouts based on the needs of individual operations. The following example demonstrates how a collection-level timeout configuration can override a client-level timeout configuration: -.. literalinclude:: /includes/connect/CSOT.java +.. literalinclude:: /includes/connect/CsotExample.java :language: java :start-after: start-override :end-before: end-override @@ -182,7 +186,7 @@ When you create a new `ClientSession <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html>`__ instance to implement a transaction, use the ``defaultTimeout()`` method when building a ``ClientSessionOptions`` -instance. You can use this option to specify the timeout to apply for +instance. You can use this option to specify the timeout for the following methods: - `commitTransaction() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#commitTransaction()>`__ @@ -193,7 +197,7 @@ the following methods: The following code demonstrates how to set the ``defaultTimeout`` when instantiating a ``ClientSession``: -.. literalinclude:: /includes/connect/CSOT.java +.. literalinclude:: /includes/connect/CsotExample.java :language: java :start-after: start-session-timeout :end-before: end-session-timeout @@ -202,12 +206,12 @@ instantiating a ``ClientSession``: If you do not specify the ``defaultTimeout``, the driver uses the timeout value set on the parent ``MongoClient``. -You can also set a transaction-level timeout by using the ``timeout()`` +You can also set a transaction-level timeout by calling the ``timeout()`` method when building a ``TransactionOptions`` instance. Setting this option applies a timeout to all operations performed in the scope of the transaction: -.. literalinclude:: /includes/connect/CSOT.java +.. literalinclude:: /includes/connect/CsotExample.java :language: java :start-after: start-txn-timeout :end-before: end-txn-timeout @@ -221,17 +225,17 @@ Client Encryption When you use Client-Side Field Level Encryption (CSFLE), the driver uses the ``timeoutMS`` option to limit the time allowed for encryption and decryption operations. You can set a timeout option for your ``ClientEncryption`` -instance by using the ``timeout()`` method when building a +instance by calling the ``timeout()`` method when building a ``ClientEncryptionSettings`` instance. If you specify the timeout when you construct a -``ClientEncryption`` instance, it controls the lifetime of all operations +``ClientEncryption`` instance, the timeout controls the lifetime of all operations performed on that instance. If you do not provide a timeout when instantiating ``ClientEncryption``, the instance inherits the timeout setting from the ``MongoClient`` used in the ``ClientEncryption`` constructor. -If you set ``timeoutMS`` on both the client and directly in +If you set ``timeoutMS`` both on the client and directly in ``ClientEncryption``, the value provided to ``ClientEncryption`` takes precedence. @@ -261,10 +265,10 @@ Cursor Lifetime Mode ~~~~~~~~~~~~~~~~~~~~ The cursor lifetime mode uses the timeout setting to limit the entire lifetime of a -cursor. In this mode, the initialization of the cursor and all subsequent calls -to the cursor methods must complete within the limit specified by the -timeout option. All documents must be returned within this limit. -Otherwise, the cursor's lifetime expires and a timeout error occurs. +cursor. In this mode, your application must initialize the cursor, complete +all calls to the cursor methods, and return all documents within the specified +time limit. Otherwise, the cursor's lifetime expires and the driver +raises a timeout error. When you close a cursor by calling the ``close()`` method, the timeout resets for the ``killCursors`` command to ensure server-side resources are @@ -274,7 +278,7 @@ The following example shows how to set a cursor timeout to ensure that the cursor is initialized and all documents are retrieved within the inherited timeout: -.. literalinclude:: /includes/connect/CSOT.java +.. literalinclude:: /includes/connect/CsotExample.java :language: java :start-after: start-cursor-lifetime :end-before: end-cursor-lifetime @@ -294,7 +298,7 @@ The following code example iterates over documents in the ``db.people`` collecti by using a cursor with the ``ITERATION`` timeout mode, and then retrieves and prints the ``name`` field value for each document: -.. literalinclude:: /includes/connect/CSOT.java +.. literalinclude:: /includes/connect/CsotExample.java :language: java :start-after: start-cursor-iteration :end-before: end-cursor-iteration diff --git a/source/crud/query-documents/cursor.txt b/source/crud/query-documents/cursor.txt index 7145942ad..d645e279e 100644 --- a/source/crud/query-documents/cursor.txt +++ b/source/crud/query-documents/cursor.txt @@ -13,7 +13,7 @@ Access Data From a Cursor Overview -------- -In this guide, you can learn how to access data using a **cursor** in +In this guide, you can learn how to access data by using a **cursor** in the {+driver-short+}. A cursor is a mechanism that allows an application to iterate over database @@ -38,9 +38,9 @@ to see by setting parameters through methods. .. tip:: Cursor Timeout - You can set a timeout to limit the amount of time it takes to - retrieve data from a cursor. To learn more, see the - :ref:`java-csot-cursor` section of the Limit Server Execution Time guide. + You can set a timeout on your cursor to return query results. + To learn more, see the :ref:`java-csot-cursor` section of the Limit + Server Execution Time guide. Terminal Methods ---------------- diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 04b137f7d..ca885b737 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -127,7 +127,7 @@ documentation ` to learn more about these methods. .. tip:: Transaction Timeout - You can set a timeout to limit the amount of time it takes operations + You can set a limit on amount of time that operations can take to complete in your transactions. To learn more, see the :ref:`java-csot-txn` section of the Limit Server Execution Time guide. diff --git a/source/includes/connect/CSOT.java b/source/includes/connect/CsotExample.java similarity index 99% rename from source/includes/connect/CSOT.java rename to source/includes/connect/CsotExample.java index 154c4fda9..c3a4a44a4 100644 --- a/source/includes/connect/CSOT.java +++ b/source/includes/connect/CsotExample.java @@ -16,7 +16,7 @@ import org.bson.Document; -public class csot { +public class CsotExample { public static void main(String[] args) { MongoClient mongoClient = new csot().mongoClientSettings(); From d9e0b19d626f7d2c22b5073a77cece3ab2d8acaa Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 26 Mar 2025 17:21:58 -0400 Subject: [PATCH 9/9] MK tech review 2 --- .../specify-connection-options/csot.txt | 10 +++--- source/crud/transactions.txt | 2 +- source/includes/connect/CsotExample.java | 32 ++++++++----------- .../code-snippets/Transaction.java | 4 +-- 4 files changed, 22 insertions(+), 26 deletions(-) diff --git a/source/connection/specify-connection-options/csot.txt b/source/connection/specify-connection-options/csot.txt index 9a1df2449..bd5ce2626 100644 --- a/source/connection/specify-connection-options/csot.txt +++ b/source/connection/specify-connection-options/csot.txt @@ -43,7 +43,7 @@ set the ``timeoutMS`` option in the following ways: ``MongoClientSettings.Builder`` class - Setting the ``timeoutMS`` parameter in your connection string -The following code examples set a client-level timeout of ``5`` seconds. +The following code examples set a client-level timeout of ``200`` milliseconds. Select the :guilabel:`MongoClientSettings` or :guilabel:`Connection String` tab to see the corresponding code. @@ -100,7 +100,7 @@ accepted values for ``timeoutMS``: If you specify the ``timeoutMS`` option, the driver automatically applies the specified timeout to each server operation. The following code example specifies -a timeout of ``5`` seconds at the client level, and then calls the +a timeout of ``200`` milliseconds at the client level, and then calls the ``MongoCollection.insertOne()`` method: .. literalinclude:: /includes/connect/CsotExample.java @@ -177,7 +177,7 @@ configuration can override a client-level timeout configuration: :dedent: :emphasize-lines: 10 -.. _java-csot-txn: +.. _java-csot-transaction: Transactions ~~~~~~~~~~~~ @@ -213,8 +213,8 @@ transaction: .. literalinclude:: /includes/connect/CsotExample.java :language: java - :start-after: start-txn-timeout - :end-before: end-txn-timeout + :start-after: start-transaction-timeout + :end-before: end-transaction-timeout :dedent: To learn more about transactions, see the :ref:`java-fundamentals-transactions` guide. diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index ca885b737..c8bc721e8 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -129,7 +129,7 @@ documentation ` to learn more about these methods. You can set a limit on amount of time that operations can take to complete in your transactions. To learn more, see the - :ref:`java-csot-txn` section of the Limit Server Execution Time guide. + :ref:`java-csot-transaction` section of the Limit Server Execution Time guide. Example ------- diff --git a/source/includes/connect/CsotExample.java b/source/includes/connect/CsotExample.java index c3a4a44a4..f8c775fcc 100644 --- a/source/includes/connect/CsotExample.java +++ b/source/includes/connect/CsotExample.java @@ -1,8 +1,7 @@ package org.example; -import static com.mongodb.client.model.Filters.eq; import static com.mongodb.client.model.Filters.gte; -import static java.util.concurrent.TimeUnit.SECONDS; +import static java.util.concurrent.TimeUnit.MILLISECONDS; import com.mongodb.ClientSessionOptions; import com.mongodb.ConnectionString; @@ -10,23 +9,20 @@ import com.mongodb.TransactionOptions; import com.mongodb.client.*; import com.mongodb.client.cursor.TimeoutMode; -import com.mongodb.client.model.InsertOneOptions; -import com.mongodb.client.model.bulk.ClientBulkWriteOptions; -import com.mongodb.client.result.InsertOneResult; import org.bson.Document; public class CsotExample { public static void main(String[] args) { - MongoClient mongoClient = new csot().mongoClientSettings(); + MongoClient mongoClient = new CsotExample().mongoClientSettings(); } private MongoClient mongoClientSettings(){ // start-mongoclientsettings MongoClientSettings settings = MongoClientSettings.builder() .applyConnectionString(new ConnectionString("")) - .timeout(5L, SECONDS) + .timeout(200L, MILLISECONDS) .build(); MongoClient mongoClient = MongoClients.create(settings); @@ -37,7 +33,7 @@ private MongoClient mongoClientSettings(){ private MongoClient connectionString(){ // start-string - String uri = "/?timeoutMS=5000"; + String uri = "/?timeoutMS=200"; MongoClient mongoClient = MongoClients.create(uri); // end-string @@ -48,7 +44,7 @@ private void operationTimeout(){ // start-operation-timeout MongoClientSettings settings = MongoClientSettings.builder() .applyConnectionString(new ConnectionString("")) - .timeout(5L, SECONDS) + .timeout(200L, MILLISECONDS) .build(); try (MongoClient mongoClient = MongoClients.create(settings)) { @@ -64,21 +60,21 @@ private void overrideTimeout(){ // start-override MongoClientSettings settings = MongoClientSettings.builder() .applyConnectionString(new ConnectionString("")) - .timeout(5L, SECONDS) + .timeout(200L, MILLISECONDS) .build(); try (MongoClient mongoClient = MongoClients.create(settings)) { MongoDatabase database = mongoClient.getDatabase("db"); MongoCollection collection = database .getCollection("people") - .withTimeout(10L, SECONDS); + .withTimeout(300L, MILLISECONDS); // ... perform operations on MongoCollection } // end-override } - private void txnTimeout(){ + private void transactionTimeout(){ MongoClientSettings settings = MongoClientSettings.builder() .applyConnectionString(new ConnectionString("")) .build(); @@ -90,18 +86,18 @@ private void txnTimeout(){ // start-session-timeout ClientSessionOptions opts = ClientSessionOptions.builder() - .defaultTimeout(5L, SECONDS) + .defaultTimeout(200L, MILLISECONDS) .build(); ClientSession session = mongoClient.startSession(opts); // ... perform operations on ClientSession // end-session-timeout - // start-txn-timeout - TransactionOptions txnOptions = TransactionOptions.builder() - .timeout(5L, SECONDS) + // start-transaction-timeout + TransactionOptions transactionOptions = TransactionOptions.builder() + .timeout(200L, MILLISECONDS) .build(); - // end-txn-timeout + // end-transaction-timeout } } @@ -109,7 +105,7 @@ private void txnTimeout(){ private void cursorTimeout(){ MongoClientSettings settings = MongoClientSettings.builder() .applyConnectionString(new ConnectionString("")) - .timeout(5L, SECONDS) + .timeout(200L, MILLISECONDS) .build(); try (MongoClient mongoClient = MongoClients.create(settings)) { diff --git a/source/includes/fundamentals/code-snippets/Transaction.java b/source/includes/fundamentals/code-snippets/Transaction.java index 1756b41dd..0cd75b0da 100644 --- a/source/includes/fundamentals/code-snippets/Transaction.java +++ b/source/includes/fundamentals/code-snippets/Transaction.java @@ -18,7 +18,7 @@ public static void main(String[] args) { MongoCollection collection = database.getCollection("books"); // Sets transaction options - TransactionOptions txnOptions = TransactionOptions.builder() + TransactionOptions transactionOptions = TransactionOptions.builder() .writeConcern(WriteConcern.MAJORITY) .build(); @@ -32,7 +32,7 @@ public static void main(String[] args) { new Document("title", "Song of Solomon").append("author", "Toni Morrison") )); return null; // Return value as expected by the lambda - }, txnOptions); + }, transactionOptions); } } catch (Exception e) { e.printStackTrace();