Skip to content

Commit b28718b

Browse files
rachel-mackrachel-mack
committed
crud config
1 parent bdae003 commit b28718b

File tree

9 files changed

+230
-115
lines changed

9 files changed

+230
-115
lines changed

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Specify Connection Options
1111
Stable API </connection/specify-connection-options/stable-api>
1212
Connection Pools </connection/specify-connection-options/connection-pools>
1313
Cluster Settings </connection/specify-connection-options/cluster-settings>
14+
Configure Client-level CRUD Settings </connection/specify-connection-options/configure-crud>
1415
Network Compression </connection/specify-connection-options/network-compression>
1516
JNDI Datasource </connection/specify-connection-options/jndi>
1617
AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ In this guide, you can learn about how the {+driver-short+} manages clusters.
2424

2525
You can specify settings for your clusters using either a :ref:`connection
2626
string <connection-uri>` or by passing a ``MongoClientSettings`` object to the
27-
:ref:`MongoClients <mongoclient>` contructor. Select the :guilabel:`Connection
27+
:ref:`MongoClients <mongoclient>` constructor. Select the :guilabel:`Connection
2828
String` or :guilabel:`MongoClientSettings` tab to see the options available:
2929

3030

@@ -35,7 +35,7 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available:
3535

3636
.. list-table::
3737
:header-rows: 1
38-
:widths: 20 20 60
38+
:widths: 40 40 20
3939

4040
* - Option Name
4141
- Type

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

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
.. _configure-client-crud:
2+
3+
====================================
4+
Configure Client-level CRUD Settings
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+
Overview
18+
--------
19+
20+
In this guide, you can learn about how the {+driver-short+} configures CRUD
21+
operations for ``MongoClient`` instances.
22+
23+
.. include:: /includes/crud/read-write-pref-concerns.rst
24+
25+
``MongoDatabase`` and ``MongoCollection`` instances inherit their preferences
26+
and concerns from the ``MongoClient`` that accesses them. However, you can apply
27+
custom settings to your databases and collections. See the :ref:`Configure Custom
28+
CRUD Settings <java-configure-custom-crud>` page for more information.
29+
30+
You can specify client-level CRUD settings by using either a :ref:`connection
31+
string <connection-uri>` or by passing a ``MongoClientSettings`` object to the
32+
:ref:`MongoClients <mongoclient>` constructor. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to see the options available:
33+
34+
.. tabs::
35+
36+
.. tab:: Connection String
37+
:tabid: uri
38+
39+
.. code-block:: java
40+
41+
ConnectionString connectionString = "mongodb://<host>:<port>/?readPreference=nearest"
42+
MongoClient mongoClient = MongoClients.create(connectionString)
43+
44+
.. list-table::
45+
:header-rows: 1
46+
:widths: 20 10 20
47+
48+
* - Option Name
49+
- Type
50+
- Description
51+
52+
* - **journal**
53+
- boolean
54+
- | Specifies that the driver must wait for the connected MongoDB
55+
instance to group commit to the journal file on disk for all
56+
writes.
57+
|
58+
| **Default**: ``false``
59+
60+
* - **w**
61+
- string or integer
62+
- | Specifies the write concern. For more information about values, see the server documentation for the :manual:`w option </reference/write-concern/#w-option>`.
63+
|
64+
| **Default**: ``1``
65+
66+
* - **wtimeoutMS**
67+
- integer
68+
- | Specifies a time limit, in milliseconds, for the write concern. For
69+
more information, see the server documentation for the
70+
:manual:`wtimeoutMS option
71+
</reference/connection-string/#write-concern-options>`. A value of
72+
``0`` instructs the driver to never time out write operations.
73+
|
74+
| **Default**: ``0``
75+
76+
* - **readPreference**
77+
- string
78+
- | Specifies the read preference. For more information about values,
79+
see the server documentation for the :manual:`readPreference option
80+
</reference/connection-string/#urioption.readPreference>`.
81+
|
82+
| **Default**: ``primary``
83+
84+
* - **readPreferenceTags**
85+
- string
86+
- | Specifies the read preference tags. For more information about
87+
values, see the server documentation for the
88+
:manual:`readPreferenceTags option
89+
</reference/connection-string/#urioption.readPreferenceTags>`.
90+
|
91+
| **Default**: ``null``
92+
93+
* - **maxStalenessSeconds**
94+
- integer
95+
- | Specifies, in seconds, how stale a secondary can be before the
96+
driver stops communicating with that secondary. The minimum value
97+
is either 90 seconds or the heartbeat frequency plus 10 seconds,
98+
whichever is greater. For more information, see the server
99+
documentation for the :manual:`maxStalenessSeconds option
100+
</reference/connection-string/#urioption.maxStalenessSeconds>`. Not
101+
providing a parameter or explicitly specifying ``-1`` indicates
102+
that there must be no staleness check for secondaries.
103+
|
104+
| **Default**: ``-1``
105+
106+
* - **uuidRepresentation**
107+
- string
108+
- | Specifies the UUID representation to use for read and write
109+
operations. For more information, see the driver documentation for
110+
the `MongoClientSettings.getUuidRepresentation() method
111+
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html#getUuidRepresentation()>`__.
112+
|
113+
| **Default**: ``unspecified``
114+
115+
.. tab:: MongoClientSettings
116+
:tabid: MongoClient
117+
118+
Chain the `readConcern() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readConcern(com.mongodb.ReadConcern)>`__,
119+
`readPreference()
120+
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readPreference(com.mongodb.ReadPreference)>`__,
121+
or `writeConcern()
122+
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#writeConcern(com.mongodb.WriteConcern)>`__
123+
method to modify the way the driver manages its connection pool. The
124+
following example chains the ``readPreference()`` method to
125+
set the read preference level to the ``nearest`` replica set member:
126+
127+
.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java
128+
:start-after: begin ReadConcern
129+
:end-before: end ReadConcern
130+
:language: java
131+
:dedent:
132+
133+

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

Lines changed: 0 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -17,76 +17,6 @@ parameters of the connection URI to specify the behavior of the client.
1717
- Type
1818
- Description
1919

20-
* - **connectTimeoutMS**
21-
- integer
22-
- Specifies the maximum amount of time, in milliseconds, the Java
23-
driver waits for a connection to open before timing out. A value of
24-
``0`` instructs the driver to never time out while waiting for a connection
25-
to open.
26-
27-
| **Default**: ``10000`` (10 seconds)
28-
29-
* - **maxLifeTimeMS**
30-
- integer
31-
- Specifies the maximum amount of time, in milliseconds, the Java
32-
driver will continue to use a pooled connection before closing the
33-
connection. A value of ``0`` indicates that there is no upper bound
34-
on how long the driver can keep a pooled connection open.
35-
36-
| **Default**: ``0``
37-
38-
* - **journal**
39-
- boolean
40-
- Specifies that the driver must wait for the connected MongoDB
41-
instance to group commit to the journal file on disk for all writes.
42-
43-
| **Default**: ``false``
44-
45-
* - **w**
46-
- string or integer
47-
- Specifies the write concern. For more information about values, see
48-
the server documentation for the :manual:`w option
49-
</reference/write-concern/#w-option>`.
50-
51-
| **Default**: ``1``
52-
53-
* - **wtimeoutMS**
54-
- integer
55-
- Specifies a time limit, in milliseconds, for the write concern. For
56-
more information, see the server documentation for the
57-
:manual:`wtimeoutMS option </reference/connection-string/#write-concern-options>`.
58-
A value of ``0`` instructs the driver to never time out write operations.
59-
60-
| **Default**: ``0``
61-
62-
* - **readPreference**
63-
- string
64-
- Specifies the read preference. For more information about values, see
65-
the server documentation for the
66-
:manual:`readPreference option </reference/connection-string/#urioption.readPreference>`.
67-
68-
| **Default**: ``primary``
69-
70-
* - **readPreferenceTags**
71-
- string
72-
- Specifies the read preference tags. For more information about values, see
73-
the server documentation for the
74-
:manual:`readPreferenceTags option </reference/connection-string/#urioption.readPreferenceTags>`.
75-
76-
| **Default**: ``null``
77-
78-
* - **maxStalenessSeconds**
79-
- integer
80-
- Specifies, in seconds, how stale a secondary can be before the
81-
driver stops communicating with that secondary. The minimum value is
82-
either 90 seconds or the heartbeat frequency plus 10 seconds, whichever
83-
is greater. For more information, see the server documentation for the
84-
:manual:`maxStalenessSeconds option </reference/connection-string/#urioption.maxStalenessSeconds>`.
85-
Not providing a parameter or explicitly specifying ``-1`` indicates
86-
that there must be no staleness check for secondaries.
87-
88-
| **Default**: ``-1``
89-
9020
* - **authMechanism**
9121
- string
9222
- Specifies the :ref:`authentication mechanism
@@ -165,48 +95,6 @@ parameters of the connection URI to specify the behavior of the client.
16595

16696
| **Default**: ``auto``
16797

168-
* - **uuidRepresentation**
169-
- string
170-
- Specifies the UUID representation to use for read and write
171-
operations. For more information, see the driver documentation
172-
for the
173-
`MongoClientSettings.getUuidRepresentation() method <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html#getUuidRepresentation()>`__.
174-
175-
| **Default**: ``unspecified``
176-
177-
* - **proxyHost**
178-
- string
179-
- Specifies the SOCKS5 proxy IPv4 address, IPv6 address, or hostname.
180-
You must provide this value to connect to a SOCKS5 proxy.
181-
182-
| To learn how to connect to a SOCKS5 proxy, see the :ref:`Connect to
183-
MongoDB by Using a SOCKS5 Proxy <java-connect-socks>` guide.
184-
185-
| **Default**: ``null``
186-
187-
* - **proxyPort**
188-
- non-negative integer
189-
- Specifies the TCP port number of the SOCKS5 proxy server.
190-
191-
| **Default**: ``1080`` when you set ``proxyHost``
192-
193-
* - **proxyUsername**
194-
- string
195-
- Specifies the username for authentication to the SOCKS5 proxy server.
196-
The driver ignores ``null`` and empty string values for this setting.
197-
The driver requires that you pass values for both ``proxyUsername``
198-
and ``proxyPassword`` or that you omit both values.
199-
200-
| **Default**: ``null``
201-
202-
* - **proxyPassword**
203-
- string
204-
- Specifies the password for authentication to the SOCKS5 proxy server.
205-
The driver ignores ``null`` and empty string values for this setting.
206-
The driver requires that you pass values for both ``proxyUsername``
207-
and ``proxyPassword`` or that you omit both values.
208-
209-
| **Default**: ``null``
21098

21199
For a complete list of options, see the
212100
`ConnectionString <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,15 @@ see the corresponding syntax:
116116

117117
*Default*: ``120000`` (120 seconds)
118118

119+
* - ``maxLifeTimeMS``
120+
121+
- Specifies the maximum amount of time, in milliseconds, the Java driver
122+
will continue to use a pooled connection before closing the
123+
connection. A value of ``0`` indicates that there is no upper bound on
124+
how long the driver can keep a pooled connection open.
125+
126+
*Default*: ``0``
127+
119128
.. tab:: MongoClientSettings
120129
:tabid: MongoClient
121130

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

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ settings.
2222

2323
You can specify settings for your sockets using either a :ref:`connection
2424
string <connection-uri>` or by passing a ``MongoClientSettings`` object to the
25-
:ref:`MongoClients <mongoclient>` contructor. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to see the options available:
25+
:ref:`MongoClients <mongoclient>` constructor. Select the :guilabel:`Connection String` or :guilabel:`MongoClientSettings` tab to see the options available:
2626

2727
.. tabs::
2828

@@ -37,6 +37,15 @@ string <connection-uri>` or by passing a ``MongoClientSettings`` object to the
3737
- Type
3838
- Description
3939

40+
* - **connectTimeoutMS**
41+
- integer
42+
- Specifies the maximum amount of time, in milliseconds, the Java
43+
driver waits for a connection to open before timing out. A value of
44+
``0`` instructs the driver to never time out while waiting for a
45+
connection to open.
46+
|
47+
| **Default**: ``10000`` (10 seconds)
48+
4049
* - **socketTimeoutMS**
4150
- integer
4251
- | 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.

‎source/crud/crud-settings.txt

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
.. _java-configure-custom-crud:
2+
3+
==============================
4+
Configure Custom CRUD Settings
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+
Overview
18+
--------
19+
20+
In this guide, you can learn about how the {+driver-short+} configures CRUD
21+
operations for ``MongoDatabase`` and ``MongoCollection`` instances.
22+
23+
.. include:: /includes/crud/read-write-pref-concerns.rst
24+
25+
By default, ``MongoDatabase`` and ``MongoCollection`` instances inherit their preferences
26+
and concerns from the ``MongoClient`` that accesses them. See the
27+
:ref:`Configure Client-level CRUD Settings <configure-client-crud>` page for
28+
more information. However, you can apply custom settings to your individual databases and
29+
collections by using the following methods:
30+
31+
- `MongoDatabase.withReadConcern() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoDatabase.html#withReadConcern(com.mongodb.ReadConcern)>`__
32+
33+
- `MongoDatabase.withReadPreference() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoDatabase.html#withReadPreference(com.mongodb.ReadPreference)>`__
34+
35+
- `MongoDatabase.withWriteConcern() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoDatabase.html#withWriteConcern(com.mongodb.WriteConcern)>`__
36+
37+
- `MongoCollection.withReadConcern() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#withReadConcern(com.mongodb.ReadConcern)>`__
38+
39+
- `MongoCollection.withReadPreference() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#withReadPreference(com.mongodb.ReadPreference)>`__
40+
41+
- `MongoCollection.withWriteConcern() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#withWriteConcern(com.mongodb.WriteConcern)>`__
42+
43+
.. tip::
44+
45+
The ``withReadConcern()``, ``withReadPreference()``, and
46+
``withWriteConcern`` methods create a new instance of a
47+
``MongoDatabase`` or ``MongoCollection`` with the desired preference
48+
or concern. The ``MongoDatabase`` or ``MongoCollection`` upon which
49+
the method is called retains its original preference and concern
50+
settings.

‎source/includes/crud/read-write-pref-concerns.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
**Read preferences**, **read concerns**, and **write concerns** control
2+
how the driver routes read operations and waits for acknowledgment for
3+
read and write operations when connected to a MongoDB replica set.
4+
Read preferences and read concerns apply to all read operations;
5+
write concerns apply to all write operations.
6+
7+
For more information, see the server documentation on
8+
:manual:`read preferences </core/read-preference/>`,
9+
:manual:`read concerns </reference/read-concern/>`, and
10+
:manual:`write concerns </reference/write-concern/>`.

0 commit comments

Comments
 (0)