diff --git a/source/includes/read-write-configuration.java b/source/includes/read-write-configuration.java new file mode 100644 index 0000000..4bfb990 --- /dev/null +++ b/source/includes/read-write-configuration.java @@ -0,0 +1,39 @@ +// start-write-concern-client +MongoClientSettings settings = MongoClientSettings.builder() + .applyConnectionString(new ConnectionString("")) + .writeConcern(WriteConcern.MAJORITY) + .build(); + +MongoClient client = MongoClients.create(settings); +// end-write-concern-client + +// start-write-concern-collection +MongoCollection collection = database.getCollection(""); +collection = collection.withWriteConcern(WriteConcern.MAJORITY); +// end-write-concern-collection + +// start-read-concern-client +MongoClientSettings settings = MongoClientSettings.builder() + .applyConnectionString(new ConnectionString("")) + .readConcern(ReadConcern.MAJORITY) + .build(); + +MongoClient client = MongoClients.create(settings); +// end-read-concern-client + +// start-read-concern-collection +MongoCollection collection = database.getCollection(""); +collection = collection.withReadConcern(ReadConcern.MAJORITY); +// end-read-concern-collection + +// start-read-preference-client +MongoClientSettings settings = MongoClientSettings.builder() + .applyConnectionString(new ConnectionString("")) + .readPreference(ReadPreference.secondary()) + .build(); +// end-read-preference-client + +// start-read-preference-collection +MongoCollection collection = database.getCollection(""); +collection = collection.withReadPreference(ReadPreference.secondary()); +// end-read-preference-collection \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index c538ec4..86006f6 100644 --- a/source/index.txt +++ b/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 ------------------------ diff --git a/source/read-write-configuration.txt b/source/read-write-configuration.txt new file mode 100644 index 0000000..d4f0c52 --- /dev/null +++ b/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 +` in the {+mdb-server+} manual. + +Read Concern +------------ + +Read concern specifies the following behaviors: + +- Level of :manual:`causal consistency + ` across replica sets +- :manual:`Isolation guarantees ` 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 ` 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 +` 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 +` 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)>`__