Skip to content

Commit 1b30805

Browse files
rachel-mackrachel-mack
committed
connection options
1 parent 5fd6d58 commit 1b30805

File tree

9 files changed

+403
-356
lines changed

9 files changed

+403
-356
lines changed

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

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ Specify Connection Options
66

77
.. toctree::
88

9-
Connection URI Options </connection/specify-connection-options/connection-options>
109
MongoClient Settings
1110
</connection/specify-connection-options/mongoclientsettings>
1211
Stable API </connection/specify-connection-options/stable-api>

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

Lines changed: 32 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,11 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available:
3333
.. tab:: Connection String
3434
:tabid: uri
3535

36-
.. list-table::
37-
:header-rows: 1
38-
:widths: 40 40 20
36+
Include the following parameters in your connection string to modify the driver's behavior when interacting with your MongoDB cluster:
37+
38+
.. list-table::
39+
:header-rows: 1
40+
:widths: 20,20,60
3941

4042
* - Option Name
4143
- Type
@@ -52,33 +54,24 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available:
5254
* - **localThresholdMS**
5355
- integer
5456
- When communicating with multiple instances of MongoDB in a replica
55-
set, the driver will only send requests to a server whose response
56-
time is less than or equal to the server with the fastest response
57-
time plus the local threshold, in milliseconds.
57+
set, the driver will only send requests to a server whose response
58+
time is less than or equal to the server with the fastest response
59+
time plus the local threshold, in milliseconds.
5860

5961
**Default**: ``15``
60-
61-
* - **heartbeatFrequencyMS**
62-
- integer
63-
- Specifies the frequency, in milliseconds that the driver will wait
64-
between attempts to determine the current state of each server in
65-
the cluster.
66-
67-
**Default**: ``10000`` (10 seconds)
68-
6962
* - **replicaSet**
7063
- string
7164
- Specifies that the :ref:`connection string <connection-uri>`
72-
provided includes multiple hosts. When specified, the driver
73-
attempts to find all members of that set.
65+
provided includes multiple hosts. When specified, the driver
66+
attempts to find all members of that set.
7467

7568
**Default**: ``null``
7669

7770
* - **directConnection**
7871
- boolean
7972
- Specifies that the driver must connect to the host directly. This
80-
maps to applying ``mode(ClusterConnectionMode.SINGLE)`` to your
81-
``MongoClientSettings``.
73+
maps to applying ``mode(ClusterConnectionMode.SINGLE)`` to your
74+
``MongoClientSettings``.
8275

8376
**Default**: ``false``
8477

@@ -128,8 +121,8 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available:
128121
* - ``localThreshold()``
129122
- Sets the amount of time that a server’s round trip can take and
130123
still be eligible for server selection.
131-
|
132-
| **Default**: ``15 milliseconds``
124+
125+
**Default**: ``15 milliseconds``
133126

134127
* - ``mode()``
135128
- Sets how to connect to a MongoDB deployment.
@@ -142,22 +135,19 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available:
142135

143136
* - ``serverSelectionTimeout()``
144137
- Sets the maximum time to select a primary node before throwing a
145-
timeout exception.
146-
|
147-
| **Default**: ``30 seconds``
138+
timeout exception.
139+
140+
**Default**: ``30 seconds``
148141

149142
* - ``serverSelector()``
150143
- Adds a server selector to apply before server selection.
151144

152145
* - ``srvHost()``
153-
- Sets the host name to use to look up an SRV DNS record to find the
154-
MongoDB hosts.
155-
|
156-
| If you want to enable the processing of TXT records associated
157-
with the host, specify the SRV host in the connection string using
158-
the ``applyConnectionString()`` method.
159-
|
160-
| For example:
146+
- Sets the host name to use to look up an SRV DNS record to find the MongoDB hosts.
147+
148+
If you want to enable the processing of TXT records associated with the host, specify the SRV host in the connection string using the ``applyConnectionString()`` method.
149+
150+
For example:
161151

162152
.. code-block:: java
163153
:emphasize-lines: 3
@@ -170,11 +160,8 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available:
170160
- Sets the maximum number of hosts the driver can connect to when
171161
using the DNS seedlist (SRV) connection protocol, identified by
172162
the ``mongodb+srv`` connection string prefix.
173-
|
174-
| Throws an exception if you are not using the SRV connection protocol.
175-
176-
Example
177-
~~~~~~~
163+
164+
Throws an exception if you are not using the SRV connection protocol.
178165

179166
This example specifies for the driver to connect directly to a server,
180167
regardless of the type of MongoDB cluster it's a part of:
@@ -186,8 +173,12 @@ String` or :guilabel:`MongoClientSettings` tab to see the options available:
186173
:emphasize-lines: 3-4
187174
:dedent:
188175

189-
.. tip::
176+
.. tip::
177+
178+
This is analogous to the ``directConnection`` parameter you can specify
179+
in your connection URI. See :ref:`<connection-options>` for more
180+
information.
190181

191-
This is analogous to the ``directConnection`` parameter you can specify
192-
in your connection URI. See :ref:`<connection-options>` for more
193-
information.
182+
For more information, see the `MongoClientSettings.Builder
183+
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__
184+
API documentation.

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

Lines changed: 89 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -38,96 +38,106 @@ string <connection-uri>` or by passing a ``MongoClientSettings`` object to the
3838

3939
.. tab:: Connection String
4040
:tabid: uri
41-
42-
.. code-block:: java
43-
44-
ConnectionString connectionString = "mongodb://<host>:<port>/?readPreference=nearest"
45-
MongoClient mongoClient = MongoClients.create(connectionString)
4641

42+
Include the following parameters in your connection string to modify the
43+
driver's read/write behavior:
44+
4745
.. list-table::
4846
:header-rows: 1
49-
:widths: 25,25,50
47+
:widths: 20,20,60
5048

5149
* - Option Name
5250
- Type
5351
- Description
5452

5553
* - **journal**
5654
- boolean
57-
- | Specifies that the driver must wait for the connected MongoDB
58-
instance to group commit to the journal file on disk for all
59-
writes.
60-
|
61-
| **Default**: ``false``
55+
- Specifies that the driver must wait for the connected MongoDB instance to group commit to the journal file on disk for all writes.
56+
57+
**Default**: ``false``
6258

6359
* - **w**
6460
- string or integer
65-
- | Specifies the write concern. For more information about values, see the server documentation for the :manual:`w option </reference/write-concern/#w-option>`.
66-
|
67-
| **Default**: ``1``
61+
- Specifies the write concern. For more information about values, see
62+
the server documentation for the :manual:`w option
63+
</reference/write-concern/#w-option>`.
64+
65+
**Default**: ``1``
6866

6967
* - **wtimeoutMS**
7068
- integer
71-
- | Specifies a time limit, in milliseconds, for the write concern. For
72-
more information, see the server documentation for the
73-
:manual:`wtimeoutMS option
74-
</reference/connection-string/#write-concern-options>`. A value of
75-
``0`` instructs the driver to never time out write operations.
76-
|
77-
| **Default**: ``0``
69+
- Specifies a time limit, in milliseconds, for the write concern. For
70+
more information, see the server documentation for the
71+
:manual:`wtimeoutMS option
72+
</reference/connection-string/#write-concern-options>`. A value of
73+
``0`` instructs the driver to never time out write operations.
74+
75+
**Default**: ``0``
7876

7977
* - **readPreference**
8078
- string
81-
- | Specifies the read preference. For more information about values,
82-
see the server documentation for the :manual:`readPreference option
83-
</reference/connection-string/#urioption.readPreference>`.
84-
|
85-
| **Default**: ``primary``
79+
- Specifies the read preference. For more information about values, see
80+
the server documentation for the :manual:`readPreference option
81+
</reference/connection-string/#urioption.readPreference>`.
82+
83+
**Default**: ``primary``
8684

8785
* - **readPreferenceTags**
8886
- string
89-
- | Specifies the read preference tags. For more information about
90-
values, see the server documentation for the
91-
:manual:`readPreferenceTags option
92-
</reference/connection-string/#urioption.readPreferenceTags>`.
93-
|
94-
| **Default**: ``null``
87+
- Specifies the read preference tags. For more information about
88+
values, see the server documentation for the
89+
:manual:`readPreferenceTags option
90+
</reference/connection-string/#urioption.readPreferenceTags>`.
91+
92+
**Default**: ``null``
9593

9694
* - **maxStalenessSeconds**
9795
- integer
98-
- | Specifies, in seconds, how stale a secondary can be before the
99-
driver stops communicating with that secondary. The minimum value
100-
is either 90 seconds or the heartbeat frequency plus 10 seconds,
101-
whichever is greater. For more information, see the server
102-
documentation for the :manual:`maxStalenessSeconds option
103-
</reference/connection-string/#urioption.maxStalenessSeconds>`. Not
104-
providing a parameter or explicitly specifying ``-1`` indicates
105-
that there must be no staleness check for secondaries.
106-
|
107-
| **Default**: ``-1``
96+
- Specifies, in seconds, how stale a secondary can be before the driver
97+
stops communicating with that secondary. The minimum value is either
98+
90 seconds or the heartbeat frequency plus 10 seconds, whichever is
99+
greater. For more information, see the server documentation for the
100+
:manual:`maxStalenessSeconds option
101+
</reference/connection-string/#urioption.maxStalenessSeconds>`. Not
102+
providing a parameter or explicitly specifying ``-1`` indicates that
103+
there must be no staleness check for secondaries.
104+
105+
**Default**: ``-1``
108106

109107
* - **uuidRepresentation**
110108
- string
111-
- | Specifies the UUID representation to use for read and write
112-
operations. For more information, see the driver documentation for
113-
the `MongoClientSettings.getUuidRepresentation() method
114-
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html#getUuidRepresentation()>`__.
115-
|
116-
| **Default**: ``unspecified``
109+
- Specifies the UUID representation to use for read and write
110+
operations. For more information, see the driver documentation for
111+
the `MongoClientSettings.getUuidRepresentation() method
112+
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html#getUuidRepresentation()>`__.
113+
114+
**Default**: ``unspecified``
117115

118116
* - **retryWrites**
119117
- boolean
120-
- | Specifies that the driver must retry supported write operations if
121-
they are unable to complete due to a network error.
122-
|
123-
| **Default**: ``true``
118+
- Specifies that the driver must retry supported write operations if
119+
they are unable to complete due to a network error.
120+
121+
**Default**: ``true``
124122

125123
* - **retryReads**
126124
- boolean
127-
- | Specifies that the driver must retry supported read operations if
128-
they are unable to complete due to a network error.
129-
|
130-
| **Default**: ``true``
125+
- Specifies that the driver must retry supported read operations if
126+
they are unable to complete due to a network error.
127+
128+
**Default**: ``true``
129+
130+
The following example sets the read preference to read from the nearest
131+
replica set member:
132+
133+
.. code-block:: java
134+
135+
ConnectionString connectionString = "mongodb://<host>:<port>/?readPreference=nearest"
136+
MongoClient mongoClient = MongoClients.create(connectionString)
137+
138+
For more information about these parameters, see the `ConnectionString
139+
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__
140+
API documentation.
131141

132142
.. tab:: MongoClientSettings
133143
:tabid: MongoClient
@@ -140,56 +150,48 @@ string <connection-uri>` or by passing a ``MongoClientSettings`` object to the
140150
:widths: 40 60
141151

142152
* - ``readConcern()``
143-
- | Sets the read concern.
144-
| - :manual:`Server manual page </reference/read-concern/>`
145-
| - `API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readConcern(com.mongodb.ReadConcern)>`__
153+
- Sets the read concern.
154+
:manual:`Server manual page </reference/read-concern/>`
155+
`API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readConcern(com.mongodb.ReadConcern)>`__
146156

147157
* - ``readPreference()``
148-
- | Sets the read preference.
149-
| - :manual:`Server manual page </reference/read-preference/>`
150-
| - `API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readPreference(com.mongodb.ReadPreference)>`__
151-
|
152-
| **Default**: ``primary``
158+
- Sets the :manual:`read preference </reference/read-preference/>`
159+
160+
**Default**: ``primary``
153161

154162
* - ``retryReads()``
155-
- | Whether the driver performs :manual:`retry reads
156-
</core/retryable-reads/>` if a network error occurs.
157-
| - :manual:`Server manual page </core/retryable-reads/>`
158-
|
159-
| **Default**: ``true``
163+
- Whether the driver performs :manual:`retry reads
164+
</core/retryable-reads/>` if a network error occurs.
165+
166+
**Default**: ``true``
160167

161168
* - ``retryWrites()``
162-
- | Whether the driver performs :manual:`retry writes
163-
</core/retryable-writes/>` if a network error occurs.
164-
|
165-
| **Default**: ``true``
169+
- Whether the driver performs :manual:`retry writes
170+
</core/retryable-writes/>` if a network error occurs.
171+
172+
**Default**: ``true``
166173

167174
* - ``uuidRepresentation()``
168175
- Sets the UUID representation to use when encoding instances of UUID
169176
and decoding BSON binary values with subtype of 3.
170177

171178
* - ``writeConcern()``
172-
- | Sets the :manual:`write concern </reference/write-concern/>`.
173-
|
174-
| **Default**: ``WriteConcern#ACKNOWLEDGED``.
179+
- Sets the :manual:`write concern </reference/write-concern/>`.
180+
181+
**Default**: ``WriteConcern#ACKNOWLEDGED``.
175182
| For more information about the default value, see :manual:`Implicit Default Write Concern </reference/write-concern/#implicit-default-write-concern>`.
176183

177-
178-
179-
`readConcern()
180-
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readConcern(com.mongodb.ReadConcern)>`__,
181-
`readPreference()
182-
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#readPreference(com.mongodb.ReadPreference)>`__,
183-
or `writeConcern()
184-
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#writeConcern(com.mongodb.WriteConcern)>`__
185-
method to modify the way the driver manages its connection pool. The
186-
following example chains the ``readPreference()`` method to
187-
set the read preference level to the ``nearest`` replica set member:
184+
The following example sets the read preference to read from the nearest
185+
replica set member:
188186

189187
.. literalinclude:: /includes/fundamentals/code-snippets/MCSettings.java
190188
:start-after: begin ReadConcern
191189
:end-before: end ReadConcern
192190
:language: java
193191
:dedent:
192+
193+
For more information about these methods, see the `MongoClientSettings.Builder
194+
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html#>`__
195+
API documentation.
194196

195197

0 commit comments

Comments
 (0)