DOCSP-42299 Add read/write configuration page

source/includes/read-write-configuration.java

@@ -0,0 +1,39 @@
+// start-write-concern-client
+MongoClientSettings settings = MongoClientSettings.builder()
+        .applyConnectionString(new ConnectionString("<your connection string>"))
+        .writeConcern(WriteConcern.MAJORITY)
+        .build();
+
+MongoClient client = MongoClients.create(settings);
+// end-write-concern-client
+
+// start-write-concern-collection
+MongoCollection<Document> collection = database.getCollection("<collection name>");
+collection = collection.withWriteConcern(WriteConcern.MAJORITY);
+// end-write-concern-collection
+
+// start-read-concern-client
+MongoClientSettings settings = MongoClientSettings.builder()
+        .applyConnectionString(new ConnectionString("<your connection string>"))
+        .readConcern(ReadConcern.MAJORITY)
+        .build();
+
+MongoClient client = MongoClients.create(settings);
+// end-read-concern-client
+
+// start-read-concern-collection
+MongoCollection<Document> collection = database.getCollection("<collection name>");
+collection = collection.withReadConcern(ReadConcern.MAJORITY);
+// end-read-concern-collection
+
+// start-read-preference-client
+MongoClientSettings settings = MongoClientSettings.builder()
+        .applyConnectionString(new ConnectionString("<your connection string>"))
+        .readPreference(ReadPreference.secondary())
+        .build();
+// end-read-preference-client
+
+// start-read-preference-collection
+MongoCollection<Document> collection = database.getCollection("<collection name>");
+collection = collection.withReadPreference(ReadPreference.secondary());
+// end-read-preference-collection

source/index.txt

@@ -29,6 +29,7 @@ MongoDB Java Reactive Streams Documentation
    /indexes
    /aggregation
    /secure-your-data
+   /read-write-configuration
    /data-formats
    /logging
    /monitoring
@@ -93,6 +94,12 @@ Secure Your Data
 Learn about ways you can authenticate your application and encrypt your data in
 the :ref:`java-rs-security` section.
 
+Configure Operations on Replica Sets
+------------------------------------
+
+Learn how to configure read and write operations on a replica set in the
+:ref:`java-rs-read-write-config` section.
+
 Specialized Data Formats
 ------------------------
 

source/read-write-configuration.txt

@@ -0,0 +1,206 @@
+.. _java-rs-read-write-config:
+
+====================================
+Configure Operations on Replica Sets
+====================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: configuration, availability, causal consistency, code example
+
+Overview
+--------
+
+In this guide, you can learn how to use the **write concern**, **read concern**,
+and **read preference** configurations to modify the way that MongoDB runs
+create, read, update, and delete (CRUD) operations on replica sets.
+
+You can set these configurations at the following levels:
+
+1. Client, which sets the default for all operation executions unless overridden
+#. Transaction
+#. Database
+#. Collection
+
+The preceding list is in increasing order of precedence. For example, if you set
+read concerns at both the client and the database levels, the read
+concern specified at the database level overrides the read concern at the
+client level.
+
+Write Concern
+-------------
+
+Write concern specifies the level of acknowledgement requested from MongoDB for
+write operations before the operation successfully returns. Operations that
+don't specify an explicit write concern inherit the global default write concern
+setting.
+
+You can set the write concern by using the ``writeConcern()`` method on a
+client or transaction, or by using the ``withWriteConcern()`` method
+on a database or collection.
+
+The ``writeConcern()`` and ``withWriteConcern()`` methods accept a
+``WriteConcern`` instance as a parameter. You can specify the write concern by 
+using one of the following values:
+
+- ``WriteConcern.ACKNOWLEDGED``: The write operation returns after the operation
+  is written to memory.
+- ``WriteConcern.W1``: The write operation returns after only the primary node acknowledges
+  the write operation, without waiting for acknowledgement from secondary nodes.
+- ``WriteConcern.W2``: The write operation returns after the primary node and
+  at least one secondary node acknowledge the write operation.
+- ``WriteConcern.W3``: The write operation returns after the primary node and
+  at least two secondary nodes acknowledge the write operation.
+- ``WriteConcern.MAJORITY``: The write operation returns after a majority of the
+  replica set members acknowledge the write operation.
+- ``WriteConcern.UNACKNOWLEDGED``: The write operation returns after the primary
+  node processes the write operation.
+- ``WriteConcern.JOURNALED``: The write operation returns after the primary node
+  writes the data to the on-disk journal.
+
+The following example sets the write concern to ``"majority"`` for an instance of
+``MongoClient``:
+
+.. literalinclude:: /includes/read-write-configuration.java
+   :start-after: // start-write-concern-client
+   :end-before: // end-write-concern-client
+   :language: java
+   :emphasize-lines: 3
+
+The following example sets the write concern to ``"majority"`` for a collection:
+
+.. literalinclude:: /includes/read-write-configuration.java
+   :start-after: // start-write-concern-collection
+   :end-before: // end-write-concern-collection
+   :language: java
+
+.. note:: Collections and Databases are Immutable
+
+   ``MongoDatabase`` and ``MongoCollection`` instances are immutable. When you
+   set the write concern on a database or collection, the method returns a new
+   instance and does not affect the original instance.
+
+For more information about write concern, see :manual:`Write Concern
+</reference/write-concern/>` in the {+mdb-server+} manual.
+
+Read Concern
+------------
+
+Read concern specifies the following behaviors:
+
+- Level of :manual:`causal consistency
+  </core/causal-consistency-read-write-concerns>` across replica sets
+- :manual:`Isolation guarantees </core/read-isolation-consistency-recency/>` maintained
+  during a query
+
+You can specify the read concern by using the ``readConcern()`` method on a
+client or transaction, or by using the ``withReadConcern()`` method on
+a database or collection. The ``readConcern()`` and ``withReadConcern()``
+methods accept a single parameter that specifies the read concern level.
+
+You can set the following read concern levels:
+
+- ``ReadConcern.LOCAL``: The query returns the instance's most recent data. Provides no guarantee
+  that the data has been written to a majority of the replica set members.
+- ``ReadConern.AVAILABLE``: The query returns the instance's most recent data.
+  Provides no guarantee that the data has been written to a majority of the
+  replica set members. ``ReadConcern.AVAILABLE`` is not available for use with
+  causally consistent sessions and transactions.
+- ``ReadConcern.MAJORITY``: The query returns data that has been acknowledged by
+  a majority of the replica set members.
+- ``ReadConcern.LINEARIZABLE``: The query returns data that reflects all
+  successful writes that completed prior to the start of the read operation.
+  ``ReadConcern.LINEARIZABLE`` is not available for use with causally consistent
+  sessions and transactions.
+- ``ReadConcern.SNAPSHOT``: The query returns majority-committed data as it appears across shards, from a
+  specific single point in the recent past.
+
+For more information about the read concern levels, see :manual:`Read Concern
+Levels </reference/read-concern/#read-concern-levels>` in the {+mdb-server+}
+manual.
+
+The following example sets the read concern to ``ReadConcern.MAJORITY`` for an instance of
+``MongoClient``:
+
+.. literalinclude:: /includes/read-write-configuration.java
+   :start-after: // start-read-concern-client
+   :end-before: // end-read-concern-client
+   :language: java
+   :emphasize-lines: 3
+
+The following example sets the read concern to ``ReadConcern.MAJORITY`` for a
+collection:
+
+.. literalinclude:: /includes/read-write-configuration.java
+   :start-after: // start-read-concern-collection
+   :end-before: // end-read-concern-collection
+   :language: java
+
+To learn more about read concern, see :manual:`Read Concern
+<reference/read-concern>` in the {+mdb-server+} manual.
+
+Read Preference
+---------------
+
+Read preference determines which member of a replica set MongoDB reads when
+running a query. You can set the read preference by using the ``readPreference()`` method
+on a client or transaction, or by using the ``withReadPreference()``
+method on a database or collection.
+
+The ``readPreference()`` and ``withReadPreference()`` methods accept a read
+preference mode as a parameter. You can set the read preference mode to one of
+the following values:
+
+- ``ReadPreference.primary()``: The query returns data from the primary node.
+- ``ReadPreference.primaryPreferred()``: The query returns data from the primary node if
+  available. Otherwise, the query returns data from a secondary node.
+- ``ReadPreference.secondary()``: The query returns data from a secondary node.
+- ``ReadPreference.secondaryPreferred()``: The query returns data from a secondary node if
+  available, Otherwise, the query returns data from the primary node.
+- ``ReadPreference.nearest()``: The query returns data from the node with the lowest
+  network latency.
+
+The following example sets the read preference to ``ReadPreference.secondary()``
+for an instance of ``MongoClient``:
+
+.. literalinclude:: /includes/read-write-configuration.java
+   :start-after: // start-read-preference-client
+   :end-before: // end-read-preference-client
+   :language: java
+   :emphasize-lines: 3
+
+The following example sets the read preference to ``ReadPreference.secondary()``
+for a collection:
+
+.. literalinclude:: /includes/read-write-configuration.java
+   :start-after: // start-read-preference-collection
+   :end-before: // end-read-preference-collection
+   :language: java
+
+For more information about read preference, see :manual:`Read Preference
+</core/read-preference/>` in the {+mdb-server+} manual.
+
+API Documentation
+-----------------
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API documentation:
+
+- `WriteConcern <{+api+}//mongodb-driver-core/com/mongodb/WriteConcern.html>`__
+- `MongoDatabase.withWriteConcern <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoDatabase.html#withWriteConcern(com.mongodb.WriteConcern)>`__
+- `MongoCollection.withWriteConcern <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoCollection.html#withWriteConcern(com.mongodb.WriteConcern)>`__
+- `ReadConcern <{+api+}/mongodb-driver-core/com/mongodb/ReadConcern.html>`__
+- `MongoDatabase.withReadConcern <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoDatabase.html#withReadConcern(com.mongodb.ReadConcern)>`__
+- `MongoCollection.withReadConcern <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoCollection.html#withReadPreference(com.mongodb.ReadPreference)>`__
+- `ReadPreference <{+api+}/mongodb-driver-core/com/mongodb/ReadPreference.html>`__
+- `MongoDatabase.withReadPreference <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoDatabase.html#withReadPreference(com.mongodb.ReadPreference)>`__
+- `MongoDatabase.withReadPreference <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoCollection.html#withReadPreference(com.mongodb.ReadPreference)>`__