Skip to content

Commit 0f4e862

Browse files
jordan-smith721jordan-smith721
authored
DOCSP-42299 Add read/write configuration page (#80)
1 parent 2a6232a commit 0f4e862

File tree

3 files changed

+252
-0
lines changed

3 files changed

+252
-0
lines changed

‎source/includes/read-write-configuration.java‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
// start-write-concern-client
2+
MongoClientSettings settings = MongoClientSettings.builder()
3+
.applyConnectionString(new ConnectionString("<your connection string>"))
4+
.writeConcern(WriteConcern.MAJORITY)
5+
.build();
6+
7+
MongoClient client = MongoClients.create(settings);
8+
// end-write-concern-client
9+
10+
// start-write-concern-collection
11+
MongoCollection<Document> collection = database.getCollection("<collection name>");
12+
collection = collection.withWriteConcern(WriteConcern.MAJORITY);
13+
// end-write-concern-collection
14+
15+
// start-read-concern-client
16+
MongoClientSettings settings = MongoClientSettings.builder()
17+
.applyConnectionString(new ConnectionString("<your connection string>"))
18+
.readConcern(ReadConcern.MAJORITY)
19+
.build();
20+
21+
MongoClient client = MongoClients.create(settings);
22+
// end-read-concern-client
23+
24+
// start-read-concern-collection
25+
MongoCollection<Document> collection = database.getCollection("<collection name>");
26+
collection = collection.withReadConcern(ReadConcern.MAJORITY);
27+
// end-read-concern-collection
28+
29+
// start-read-preference-client
30+
MongoClientSettings settings = MongoClientSettings.builder()
31+
.applyConnectionString(new ConnectionString("<your connection string>"))
32+
.readPreference(ReadPreference.secondary())
33+
.build();
34+
// end-read-preference-client
35+
36+
// start-read-preference-collection
37+
MongoCollection<Document> collection = database.getCollection("<collection name>");
38+
collection = collection.withReadPreference(ReadPreference.secondary());
39+
// end-read-preference-collection

‎source/index.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ MongoDB Java Reactive Streams Documentation
2929
/indexes
3030
/aggregation
3131
/secure-your-data
32+
/read-write-configuration
3233
/data-formats
3334
/logging
3435
/monitoring
@@ -93,6 +94,12 @@ Secure Your Data
9394
Learn about ways you can authenticate your application and encrypt your data in
9495
the :ref:`java-rs-security` section.
9596

97+
Configure Operations on Replica Sets
98+
------------------------------------
99+
100+
Learn how to configure read and write operations on a replica set in the
101+
:ref:`java-rs-read-write-config` section.
102+
96103
Specialized Data Formats
97104
------------------------
98105

‎source/read-write-configuration.txt‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
.. _java-rs-read-write-config:
2+
3+
====================================
4+
Configure Operations on Replica Sets
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: configuration, availability, causal consistency, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the **write concern**, **read concern**,
24+
and **read preference** configurations to modify the way that MongoDB runs
25+
create, read, update, and delete (CRUD) operations on replica sets.
26+
27+
You can set these configurations at the following levels:
28+
29+
1. Client, which sets the default for all operation executions unless overridden
30+
#. Transaction
31+
#. Database
32+
#. Collection
33+
34+
The preceding list is in increasing order of precedence. For example, if you set
35+
read concerns at both the client and the database levels, the read
36+
concern specified at the database level overrides the read concern at the
37+
client level.
38+
39+
Write Concern
40+
-------------
41+
42+
Write concern specifies the level of acknowledgement requested from MongoDB for
43+
write operations before the operation successfully returns. Operations that
44+
don't specify an explicit write concern inherit the global default write concern
45+
setting.
46+
47+
You can set the write concern by using the ``writeConcern()`` method on a
48+
client or transaction, or by using the ``withWriteConcern()`` method
49+
on a database or collection.
50+
51+
The ``writeConcern()`` and ``withWriteConcern()`` methods accept a
52+
``WriteConcern`` instance as a parameter. You can specify the write concern by
53+
using one of the following values:
54+
55+
- ``WriteConcern.ACKNOWLEDGED``: The write operation returns after the operation
56+
is written to memory.
57+
- ``WriteConcern.W1``: The write operation returns after only the primary node acknowledges
58+
the write operation, without waiting for acknowledgement from secondary nodes.
59+
- ``WriteConcern.W2``: The write operation returns after the primary node and
60+
at least one secondary node acknowledge the write operation.
61+
- ``WriteConcern.W3``: The write operation returns after the primary node and
62+
at least two secondary nodes acknowledge the write operation.
63+
- ``WriteConcern.MAJORITY``: The write operation returns after a majority of the
64+
replica set members acknowledge the write operation.
65+
- ``WriteConcern.UNACKNOWLEDGED``: The write operation returns after the primary
66+
node processes the write operation.
67+
- ``WriteConcern.JOURNALED``: The write operation returns after the primary node
68+
writes the data to the on-disk journal.
69+
70+
The following example sets the write concern to ``"majority"`` for an instance of
71+
``MongoClient``:
72+
73+
.. literalinclude:: /includes/read-write-configuration.java
74+
:start-after: // start-write-concern-client
75+
:end-before: // end-write-concern-client
76+
:language: java
77+
:emphasize-lines: 3
78+
79+
The following example sets the write concern to ``"majority"`` for a collection:
80+
81+
.. literalinclude:: /includes/read-write-configuration.java
82+
:start-after: // start-write-concern-collection
83+
:end-before: // end-write-concern-collection
84+
:language: java
85+
86+
.. note:: Collections and Databases are Immutable
87+
88+
``MongoDatabase`` and ``MongoCollection`` instances are immutable. When you
89+
set the write concern on a database or collection, the method returns a new
90+
instance and does not affect the original instance.
91+
92+
For more information about write concern, see :manual:`Write Concern
93+
</reference/write-concern/>` in the {+mdb-server+} manual.
94+
95+
Read Concern
96+
------------
97+
98+
Read concern specifies the following behaviors:
99+
100+
- Level of :manual:`causal consistency
101+
</core/causal-consistency-read-write-concerns>` across replica sets
102+
- :manual:`Isolation guarantees </core/read-isolation-consistency-recency/>` maintained
103+
during a query
104+
105+
You can specify the read concern by using the ``readConcern()`` method on a
106+
client or transaction, or by using the ``withReadConcern()`` method on
107+
a database or collection. The ``readConcern()`` and ``withReadConcern()``
108+
methods accept a single parameter that specifies the read concern level.
109+
110+
You can set the following read concern levels:
111+
112+
- ``ReadConcern.LOCAL``: The query returns the instance's most recent data. Provides no guarantee
113+
that the data has been written to a majority of the replica set members.
114+
- ``ReadConern.AVAILABLE``: The query returns the instance's most recent data.
115+
Provides no guarantee that the data has been written to a majority of the
116+
replica set members. ``ReadConcern.AVAILABLE`` is not available for use with
117+
causally consistent sessions and transactions.
118+
- ``ReadConcern.MAJORITY``: The query returns data that has been acknowledged by
119+
a majority of the replica set members.
120+
- ``ReadConcern.LINEARIZABLE``: The query returns data that reflects all
121+
successful writes that completed prior to the start of the read operation.
122+
``ReadConcern.LINEARIZABLE`` is not available for use with causally consistent
123+
sessions and transactions.
124+
- ``ReadConcern.SNAPSHOT``: The query returns majority-committed data as it appears across shards, from a
125+
specific single point in the recent past.
126+
127+
For more information about the read concern levels, see :manual:`Read Concern
128+
Levels </reference/read-concern/#read-concern-levels>` in the {+mdb-server+}
129+
manual.
130+
131+
The following example sets the read concern to ``ReadConcern.MAJORITY`` for an instance of
132+
``MongoClient``:
133+
134+
.. literalinclude:: /includes/read-write-configuration.java
135+
:start-after: // start-read-concern-client
136+
:end-before: // end-read-concern-client
137+
:language: java
138+
:emphasize-lines: 3
139+
140+
The following example sets the read concern to ``ReadConcern.MAJORITY`` for a
141+
collection:
142+
143+
.. literalinclude:: /includes/read-write-configuration.java
144+
:start-after: // start-read-concern-collection
145+
:end-before: // end-read-concern-collection
146+
:language: java
147+
148+
To learn more about read concern, see :manual:`Read Concern
149+
<reference/read-concern>` in the {+mdb-server+} manual.
150+
151+
Read Preference
152+
---------------
153+
154+
Read preference determines which member of a replica set MongoDB reads when
155+
running a query. You can set the read preference by using the ``readPreference()`` method
156+
on a client or transaction, or by using the ``withReadPreference()``
157+
method on a database or collection.
158+
159+
The ``readPreference()`` and ``withReadPreference()`` methods accept a read
160+
preference mode as a parameter. You can set the read preference mode to one of
161+
the following values:
162+
163+
- ``ReadPreference.primary()``: The query returns data from the primary node.
164+
- ``ReadPreference.primaryPreferred()``: The query returns data from the primary node if
165+
available. Otherwise, the query returns data from a secondary node.
166+
- ``ReadPreference.secondary()``: The query returns data from a secondary node.
167+
- ``ReadPreference.secondaryPreferred()``: The query returns data from a secondary node if
168+
available, Otherwise, the query returns data from the primary node.
169+
- ``ReadPreference.nearest()``: The query returns data from the node with the lowest
170+
network latency.
171+
172+
The following example sets the read preference to ``ReadPreference.secondary()``
173+
for an instance of ``MongoClient``:
174+
175+
.. literalinclude:: /includes/read-write-configuration.java
176+
:start-after: // start-read-preference-client
177+
:end-before: // end-read-preference-client
178+
:language: java
179+
:emphasize-lines: 3
180+
181+
The following example sets the read preference to ``ReadPreference.secondary()``
182+
for a collection:
183+
184+
.. literalinclude:: /includes/read-write-configuration.java
185+
:start-after: // start-read-preference-collection
186+
:end-before: // end-read-preference-collection
187+
:language: java
188+
189+
For more information about read preference, see :manual:`Read Preference
190+
</core/read-preference/>` in the {+mdb-server+} manual.
191+
192+
API Documentation
193+
-----------------
194+
195+
To learn more about any of the methods or types discussed in this
196+
guide, see the following API documentation:
197+
198+
- `WriteConcern <{+api+}//mongodb-driver-core/com/mongodb/WriteConcern.html>`__
199+
- `MongoDatabase.withWriteConcern <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoDatabase.html#withWriteConcern(com.mongodb.WriteConcern)>`__
200+
- `MongoCollection.withWriteConcern <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoCollection.html#withWriteConcern(com.mongodb.WriteConcern)>`__
201+
- `ReadConcern <{+api+}/mongodb-driver-core/com/mongodb/ReadConcern.html>`__
202+
- `MongoDatabase.withReadConcern <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoDatabase.html#withReadConcern(com.mongodb.ReadConcern)>`__
203+
- `MongoCollection.withReadConcern <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoCollection.html#withReadPreference(com.mongodb.ReadPreference)>`__
204+
- `ReadPreference <{+api+}/mongodb-driver-core/com/mongodb/ReadPreference.html>`__
205+
- `MongoDatabase.withReadPreference <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoDatabase.html#withReadPreference(com.mongodb.ReadPreference)>`__
206+
- `MongoDatabase.withReadPreference <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoCollection.html#withReadPreference(com.mongodb.ReadPreference)>`__

0 commit comments

Comments
 (0)