Skip to content

Commit a561169

Browse files
jordan-smith721jordan-smith721
committed
add read/write config page
1 parent 7836171 commit a561169

File tree

2 files changed

+243
-0
lines changed

2 files changed

+243
-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/read-write-configuration.txt‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
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 primary
56+
node acknowledges the write operation.
57+
- ``WriteConcern.W1``: The write operation returns after only the primary node acknowledges
58+
the write operation.
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 on a client
71+
instance:
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+
78+
The following example sets the write concern to ``"majority"`` for a collection:
79+
80+
.. literalinclude:: /includes/read-write-configuration.java
81+
:start-after: // start-write-concern-collection
82+
:end-before: // end-write-concern-collection
83+
:language: java
84+
85+
.. note:: Collections and Databases are Immutable
86+
87+
``MongoDatabase`` and ``MongoCollection`` instances are immutable. When you
88+
set the write concern on a database or collection, the method returns a new
89+
instance and does not affect the original instance.
90+
91+
For more information about write concern, see :manual:`Write Concern
92+
</reference/write-concern/>` in the {+mdb-server+} manual.
93+
94+
Read Concern
95+
------------
96+
97+
Read concern specifies the following behaviors:
98+
99+
- Level of :manual:`causal consistency
100+
</core/causal-consistency-read-write-concerns>` across replica sets
101+
- :manual:`Isolation Guarantees </core/read-isolation-consistency-recency/>` maintained
102+
during a query
103+
104+
You can specify the read concern by using the ``readConcern()`` method on a
105+
client or transaction, or by using the ``withReadConcern()`` method on
106+
a database or collection. The ``readConcern()`` and ``withReadConcern()``
107+
methods accept a single parameter that specifies the read concern level.
108+
109+
You can set the following read concern levels:
110+
111+
- ``ReadConcern.LOCAL``: The query returns the instance's most recent data. Provides no guarantee
112+
that the data has been written to a majority of the replica set members.
113+
- ``ReadConern.AVAILABLE``: The query returns the instance's most recent data.
114+
Provides no guarantee that the data has been written to a majority of the
115+
replica set members. ``ReadConcern.AVAILABLE`` is not available for use with
116+
causally consistent sessions and transactions.
117+
- ``ReadConcern.MAJORITY``: The query returns data that has been acknowledged by
118+
a majority of the replica set members.
119+
- ``ReadConcern.LINEARIZABLE``: The query returns data that reflects all
120+
successful writes that completed prior to the start of the read operation.
121+
``ReadConcern.LINEARIZABLE`` is not available for use with causally consistent
122+
sessions and transactions.
123+
- ``ReadConcern.SNAPSHOT``: The query returns majority-committed data as it appears across shards from a
124+
specific single point in the recent past.
125+
126+
For more information about the read concern levels, see :manual:`Read Concern
127+
Levels </reference/read-concern/#read-concern-levels>` in the {+mdb-server+}
128+
manual.
129+
130+
The following example sets the read concern to ``ReadConcern.MAJORITY`` for an instance of
131+
``MongoClient``:
132+
133+
.. literalinclude:: /includes/read-write-configuration.java
134+
:start-after: // start-read-concern-client
135+
:end-before: // end-read-concern-client
136+
:language: java
137+
138+
The following example sets the read concern to ``ReadConcern.MAJORITY`` for a
139+
collection:
140+
141+
.. literalinclude:: /includes/read-write-configuration.java
142+
:start-after: // start-read-concern-collection
143+
:end-before: // end-read-concern-collection
144+
:language: java
145+
146+
To learn more about read concern, see :manual:`Read Concern
147+
<reference/read-concern>` in the {+mdb-server+} manual.
148+
149+
Read Preference
150+
---------------
151+
152+
Read preference determines which member of a replica set MongoDB reads when
153+
running a query. You can also customize how the server evaluates a replica set
154+
member. You can set the read preference by using the ``readPreference()`` method
155+
on a client or transaction, or by using the ``withReadPreference()``
156+
method on a database or collection.
157+
158+
The ``readPreference()`` and ``withReadPreference()`` methods accept a read
159+
preference mode as a parameter. You can set the read preference mode to one of
160+
the following values:
161+
162+
- ``ReadPreference.primary()``: The query returns data from the primary node.
163+
- ``ReadPreference.primaryPreferred()``: The query returns data from the primary node if
164+
available. Otherwise, the query returns data from a secondary node.
165+
- ``ReadPreference.secondary()``: The query returns data from a secondary node.
166+
- ``ReadPreference.secondaryPreferred()``: The query returns data from a secondary node if
167+
available, Otherwise, the query returns data from the primary node.
168+
- ``ReadPreference.nearest()``: The query returns data from the node with the lowest
169+
network latency.
170+
171+
The following example sets the read preference to ``ReadPreference.secondary()``
172+
for an instance of ``MongoClient``:
173+
174+
.. literalinclude:: /includes/read-write-configuration.java
175+
:start-after: // start-read-preference-client
176+
:end-before: // end-read-preference-client
177+
:language: java
178+
179+
The following example sets the read preference to ``ReadPreference.secondary()``
180+
for a collection:
181+
182+
.. literalinclude:: /includes/read-write-configuration.java
183+
:start-after: // start-read-preference-collection
184+
:end-before: // end-read-preference-collection
185+
:language: java
186+
187+
For more information about read preference, see :manual:`Read Preference
188+
</core/read-preference/>` in the {+mdb-server+} manual.
189+
190+
API Documentation
191+
-----------------
192+
193+
To learn more about any of the methods or types discussed in this
194+
guide, see the following API documentation:
195+
196+
- `WriteConcern <{+api+}//mongodb-driver-core/com/mongodb/WriteConcern.html>`__
197+
- `MongoDatabase.withWriteConcern <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoDatabase.html#withWriteConcern(com.mongodb.WriteConcern)>`__
198+
- `MongoCollection.withWriteConcern <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoCollection.html#withWriteConcern(com.mongodb.WriteConcern)>`__
199+
- `ReadConcern <{+api+}/mongodb-driver-core/com/mongodb/ReadConcern.html>`__
200+
- `MongoDatabase.withReadConcern <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoDatabase.html#withReadConcern(com.mongodb.ReadConcern)>`__
201+
- `MongoCollection.withReadConcern <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoCollection.html#withReadPreference(com.mongodb.ReadPreference)>`__
202+
- `ReadPreference <{+api+}/mongodb-driver-core/com/mongodb/ReadPreference.html>`__
203+
- `MongoDatabase.withReadPreference <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoDatabase.html#withReadPreference(com.mongodb.ReadPreference)>`__
204+
- `MongoDatabase.withReadPreference <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoCollection.html#withReadPreference(com.mongodb.ReadPreference)>`__

0 commit comments

Comments
 (0)