Skip to content

Commit 26b875a

Browse files
rustagirrustagir
committed
DOCSP-35923: csot page
1 parent e05bf7b commit 26b875a

File tree

8 files changed

+439
-6
lines changed

8 files changed

+439
-6
lines changed

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Specify Connection Options
99
MongoClient Settings </connection/specify-connection-options/mongoclientsettings>
1010
Connection URI Options </connection/specify-connection-options/connection-options.txt>
1111
Stable API </connection/specify-connection-options/stable-api>
12+
Timeout Setting </connection/specify-connection-options/csot.txt>
1213
Network Compression </connection/specify-connection-options/network-compression>
1314
JNDI Datasource </connection/specify-connection-options/jndi>
1415
AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>
@@ -25,7 +26,8 @@ Specify Connection Options
2526
- :ref:`MongoClient Settings <mongoclientsettings>`
2627
- :ref:`Connection URI Options <connection-options>`
2728
- :ref:`Stable API <stable-api-java>`
29+
- :ref:`Limit Server Execution Time <java-csot>`
2830
- :ref:`Network Compression <network-compression>`
2931
- :ref:`JNDI Datasource <jndi>`
3032
- `AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>`__
31-
- :ref:`Connection Security Options <security-connection-settings>`
33+
- :ref:`Connection Security Options <security-connection-settings>`

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,14 @@ parameters of the connection URI to specify the behavior of the client.
103103

104104
| **Default**: ``false``
105105

106+
* - **timeoutMS**
107+
- integer
108+
- Specifies the time limit, in milliseconds, for the full execution
109+
of an operation. This option sets a client-level operations
110+
timeout that replaces the functionality of the ``maxTimeMS`` and
111+
``maxCommitTimeMS`` options. To learn more, see the :ref:`java-csot`
112+
guide.
113+
106114
* - **connectTimeoutMS**
107115
- integer
108116
- Specifies the maximum amount of time, in milliseconds, the Java

‎source/connection/specify-connection-options/csot.txt

Lines changed: 295 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,295 @@
1+
.. _java-csot:
2+
3+
===========================
4+
Limit Server Execution Time
5+
===========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: error, blocking, thread, task, code example
19+
20+
Overview
21+
--------
22+
23+
When you use the {+driver-short+} to perform a server operation, you can also
24+
limit the amount of time in which the server can finish the operation. To do so,
25+
specify a **client-side operation timeout (CSOT)**. The timeout applies to all
26+
steps needed to complete the operation, including server selection, connection
27+
checkout, and server-side execution. When the timeout expires, the
28+
{+driver-short+} raises a timeout exception.
29+
30+
.. note:: Experimental Feature
31+
32+
The CSOT feature is experimental and might change in future driver
33+
releases.
34+
35+
timeoutMS Option
36+
----------------
37+
38+
To specify a timeout when connecting to a MongoDB deployment, set the
39+
``timeoutMS`` connection option to the timeout length in milliseconds. You can
40+
set the ``timeoutMS`` option in the following ways:
41+
42+
- Using the ``timeout()`` method from the
43+
``MongoClientSettings.Builder`` class
44+
- Setting the ``timeoutMS`` parameter in your connection string
45+
46+
Select from the following :guilabel:`MongoClientSettings` and
47+
:guilabel:`Connection String` tabs to view how to set a client-level
48+
timeout of 5 seconds by using each method:
49+
50+
.. tabs::
51+
52+
.. tab:: MongoClientSettings
53+
:tabid: mongoclientsettings
54+
55+
.. literalinclude:: /includes/connect/CSOT.java
56+
:language: java
57+
:start-after: start-mongoclientsettings
58+
:end-before: end-mongoclientsettings
59+
:dedent:
60+
:emphasize-lines: 3
61+
62+
.. tab:: Connection String
63+
:tabid: connection-string
64+
65+
.. literalinclude:: /includes/connect/CSOT.java
66+
:language: java
67+
:start-after: start-string
68+
:end-before: end-string
69+
70+
Behavior
71+
~~~~~~~~
72+
73+
The following table describes the timeout behavior corresponding to the
74+
accepted values for ``timeoutMS``:
75+
76+
.. list-table::
77+
:header-rows: 1
78+
:widths: 35 65
79+
80+
* - Value
81+
- Behavior
82+
83+
* - Positive value
84+
- Sets the timeout to use for operation completion.
85+
86+
* - ``0``
87+
- Sets an infinite timeout.
88+
89+
* - ``null``
90+
- | Defers the timeout behavior to the following settings:
91+
|
92+
| - :manual:`waitQueueTimeoutMS </reference/connection-string-options/#mongodb-urioption-urioption.waitQueueTimeoutMS>`
93+
| - :manual:`socketTimeoutMS </reference/connection-string-options/#mongodb-urioption-urioption.socketTimeoutMS>`
94+
| - :manual:`wTimeoutMS </reference/connection-string-options/#mongodb-urioption-urioption.wtimeoutMS>`
95+
| - :manual:`maxTimeMS </reference/method/cursor.maxTimeMS/>` *(deprecated)*
96+
| - `maxCommitTimeMS <{+core-api+}/com/mongodb/TransactionOptions.Builder.html#maxCommitTime(java.lang.Long,java.util.concurrent.TimeUnit)>`__ *(deprecated)*
97+
|
98+
| When the CSOT feature is no longer experimental, all the
99+
preceding options will be deprecated.
100+
101+
If you specify the ``timeoutMS`` option, the driver automatically applies the
102+
specified timeout for each server operation. The following code example specifies
103+
a timeout of 5 seconds at the client level, and then calls the
104+
``MongoCollection.insertOne()`` method:
105+
106+
.. literalinclude:: /includes/connect/CSOT.java
107+
:language: java
108+
:start-after: start-operation-timeout
109+
:end-before: end-operation-timeout
110+
:dedent:
111+
112+
Timeout Inheritance
113+
~~~~~~~~~~~~~~~~~~~
114+
115+
When you specify the ``timeoutMS`` option, the driver applies the timeout
116+
according to the same inheritance behaviors as the other {+driver-short+} options.
117+
The following table describes how the timeout value is inherited at each level:
118+
119+
.. list-table::
120+
:header-rows: 1
121+
:widths: 30 70
122+
123+
* - Level
124+
- Inheritance Description
125+
126+
* - Operation
127+
- Takes the highest precedence and will override ``timeoutMS``
128+
options set at any other level.
129+
130+
* - Transaction
131+
- Takes precedence over ``timeoutMS`` set at the session,
132+
collection, database, or client level.
133+
134+
* - Session
135+
- Applies to all transactions and operations within
136+
that session, unless the option is overridden by options set at those levels.
137+
138+
* - Database
139+
- Applies to all sessions and operations within that
140+
database, unless the option is overridden by options set at those levels.
141+
142+
* - Collection
143+
- Applies to all sessions and operations on that
144+
collection, unless the option is overridden by options set at those levels.
145+
146+
* - Client
147+
- Applies to all databases, collections, sessions, transactions, and
148+
operations within that client that do not otherwise specify
149+
``timeoutMS``.
150+
151+
For more information on overrides and specific options, see the following
152+
:ref:`java-csot-overrides` section.
153+
154+
.. _java-csot-overrides:
155+
156+
Overrides
157+
---------
158+
159+
The {+driver-short+} supports various levels of configuration to control the
160+
behavior and performance of database operations.
161+
162+
You can specify a ``timeoutMS`` option at the operation level to override the
163+
client-level configuration for a specific operation. This allows you to
164+
customize timeouts based on the needs of individual queries.
165+
166+
The following example demonstrates how an collection-level timeout
167+
configuration can override a client-level timeout configuration:
168+
169+
.. literalinclude:: /includes/connect/CSOT.java
170+
:language: java
171+
:start-after: start-override
172+
:end-before: end-override
173+
:dedent:
174+
:emphasize-lines: 10
175+
176+
.. _java-csot-txn:
177+
178+
Transactions
179+
~~~~~~~~~~~~
180+
181+
When you create a new `ClientSession
182+
<{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html>`__
183+
instance to implement a transaction, use
184+
the ``defaultTimeout()`` method when building a ``ClientSessionOptions``
185+
instance. You can use this option to specify the timeout to apply for
186+
the following methods:
187+
188+
- `commitTransaction() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#commitTransaction()>`__
189+
- `abortTransaction() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#abortTransaction()>`__
190+
- `withTransaction() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/ClientSession.html#withTransaction(com.mongodb.client.TransactionBody)>`__
191+
- `close() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/session/ClientSession.html#close()>`__
192+
193+
If you do not specify the ``defaultTimeout``, the driver uses the timeout
194+
value set on the parent ``MongoClient``.
195+
196+
You can also set a transaction-level timeout by using the ``timeout()``
197+
method when building a ``TransactionOptions`` instance. Setting this
198+
option applies a timeout to all operations performed in the scope of the
199+
transaction.
200+
201+
To learn more about transactions, see the :ref:`java-fundamentals-transactions` guide.
202+
203+
Client Encryption
204+
~~~~~~~~~~~~~~~~~
205+
206+
When you use Client-Side Field Level Encryption (CSFLE), the driver uses the
207+
``timeoutMS`` option to limit the time allowed for encryption and decryption
208+
operations. You can set a timeout option for your ``ClientEncryption``
209+
instance by using the ``timeout()`` method when building a
210+
``ClientEncryptionSettings`` instance.
211+
212+
If you specify the timeout when you construct a
213+
``ClientEncryption`` instance, it controls the lifetime of all operations
214+
performed on that instance. If you do not provide a timeout when
215+
instantiating ``ClientEncryption``, the instance
216+
inherits the timeout setting from the ``MongoClient`` used in the
217+
``ClientEncryption`` constructor.
218+
219+
If you set ``timeoutMS`` on both the client and directly in
220+
``ClientEncryption``, the value provided to ``ClientEncryption`` takes
221+
precedence.
222+
223+
.. _java-csot-cursor:
224+
225+
Cursors
226+
-------
227+
228+
Cursors offer configurable timeout settings when using the CSOT feature. You can
229+
adjust cursor handling by configuring either the cursor lifetime or cursor
230+
iteration mode. To configure the timeout mode, use the ``timeoutMode()``
231+
method when performing any operation that returns an ``Iterable``.
232+
233+
For operations that create cursors, the timeout setting can either cap the
234+
lifetime of the cursor or be applied separately to the original
235+
operation and all subsequent calls.
236+
237+
.. note:: Inherited Timeout
238+
239+
Setting a cursor timeout mode requires that you set a timeout either
240+
in the ``MongoClientSettings``, on ``MongoDatabase``, or on
241+
``MongoCollection``.
242+
243+
To learn more about cursors, see the :ref:`java-fundamentals-cursor` guide.
244+
245+
Cursor Lifetime Mode
246+
~~~~~~~~~~~~~~~~~~~~
247+
248+
The cursor lifetime mode uses the timeout setting to limit the entire lifetime of a
249+
cursor. In this mode, the initialization of the cursor and all subsequent calls
250+
to the cursor methods must complete within the limit specified by the
251+
timeout option. All documents must be returned within this limit.
252+
Otherwise, the cursor's lifetime expires and a timeout error occurs.
253+
254+
When you close a cursor by calling the ``close()`` method, the
255+
timeout resets for the ``killCursors`` command to ensure server-side resources are
256+
cleaned up.
257+
258+
The following example shows how to set a cursor timeout to ensure that
259+
the cursor is initialized and all documents are retrieved within the
260+
inherited timeout:
261+
262+
.. literalinclude:: /includes/connect/CSOT.java
263+
:language: java
264+
:start-after: start-cursor-lifetime
265+
:end-before: end-cursor-lifetime
266+
:dedent:
267+
:emphasize-lines: 3
268+
269+
Cursor Iteration Mode
270+
~~~~~~~~~~~~~~~~~~~~~
271+
272+
The cursor iteration mode sets the timeout to limit each call to
273+
the ``next()``, ``hasNext()``, and ``tryNext()`` methods. The timeout refreshes
274+
after each call completes. This is the default mode for all tailable cursors,
275+
such as the tailable cursors returned by the ``find()`` method on capped
276+
collections or change streams.
277+
278+
The following code example iterates over documents in the ``db.people`` collection
279+
by using a cursor with the ``ITERATION`` timeout mode, and then retrieves
280+
and prints the ``name`` field value for each document:
281+
282+
.. literalinclude:: /includes/connect/CSOT.java
283+
:language: java
284+
:start-after: start-cursor-iteration
285+
:end-before: end-cursor-iteration
286+
:dedent:
287+
:emphasize-lines: 3
288+
289+
API Documentation
290+
-----------------
291+
292+
To learn more about using timeouts with the {+driver-short+}, see the following
293+
API documentation:
294+
295+

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,10 @@ connection behavior:
142142
- Sets the :ref:`server API <stable-api-java>` to use when sending
143143
commands to the server.
144144

145+
* - ``timeout()``
146+
- Sets the time limit for the full execution of an operation. To
147+
learn more, see the :ref:`java-csot` guide.
148+
145149
* - ``transportSettings()``
146150
- Sets `TransportSettings <{+api+}/apidocs/mongodb-driver-core/com/mongodb/connection/TransportSettings.html>`__.
147151

@@ -598,4 +602,4 @@ to MongoDB:
598602
:end-before: end SslSettings
599603
:language: java
600604
:emphasize-lines: 3-4
601-
:dedent:
605+
:dedent:

‎source/crud/read-operations/cursor.txt

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,6 @@
44
Access Data From a Cursor
55
=========================
66

7-
8-
97
.. contents:: On this page
108
:local:
119
:backlinks: none
@@ -15,8 +13,8 @@ Access Data From a Cursor
1513
Overview
1614
--------
1715

18-
In this guide, you can learn how to access data using a **cursor** with the
19-
MongoDB Java driver.
16+
In this guide, you can learn how to access data using a **cursor** in
17+
the {+driver-short+}.
2018

2119
A cursor is a mechanism that allows an application to iterate over database
2220
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
3836
matched by your search criteria and to further specify which documents
3937
to see by setting parameters through methods.
4038

39+
.. tip:: Cursor Timeout
40+
41+
You can set a timeout to limit the amount of time it takes to
42+
retrieve data from a cursor. To learn more, see the
43+
:ref:`java-csot-cursor` section of the Limit Server Execution Time guide.
44+
4145
Terminal Methods
4246
----------------
4347

‎source/crud/transactions.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,12 @@ A ``ClientSession`` also has methods to retrieve session properties and modify m
125125
session properties. View the :ref:`API
126126
documentation <api-docs-transaction>` to learn more about these methods.
127127

128+
.. tip:: Transaction Timeout
129+
130+
You can set a timeout to limit the amount of time it takes operations
131+
to complete in your transactions. To learn more, see the
132+
:ref:`java-csot-txn` section of the Limit Server Execution Time guide.
133+
128134
Example
129135
-------
130136

0 commit comments

Comments
 (0)