From a56116978cee5750dbdc6aebd55d05e41e13b857 Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Fri, 23 Aug 2024 12:23:34 -0700 Subject: [PATCH 1/4] add read/write config page --- source/includes/read-write-configuration.java | 39 ++++ source/read-write-configuration.txt | 204 ++++++++++++++++++ 2 files changed, 243 insertions(+) create mode 100644 source/includes/read-write-configuration.java create mode 100644 source/read-write-configuration.txt 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/read-write-configuration.txt b/source/read-write-configuration.txt new file mode 100644 index 0000000..3888fcf --- /dev/null +++ b/source/read-write-configuration.txt @@ -0,0 +1,204 @@ +.. _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 primary + node acknowledges the write operation. +- ``WriteConcern.W1``: The write operation returns after only the primary node acknowledges + the write operation. +- ``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 on a client +instance: + +.. literalinclude:: /includes/read-write-configuration.java + :start-after: // start-write-concern-client + :end-before: // end-write-concern-client + :language: java + +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 + +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 also customize how the server evaluates a replica set +member. 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 + +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)>`__ From ff4a806935e414b73187a550456b82616600fbff Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Fri, 23 Aug 2024 12:31:17 -0700 Subject: [PATCH 2/4] add to index --- source/index.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/source/index.txt b/source/index.txt index c21fa21..91feff9 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 /logging /monitoring /validate-signatures @@ -91,6 +92,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. + What's New ---------- From 0050be00e0b5017724d7c74140560053f1ff5b99 Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Fri, 23 Aug 2024 12:52:56 -0700 Subject: [PATCH 3/4] edits --- source/read-write-configuration.txt | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/source/read-write-configuration.txt b/source/read-write-configuration.txt index 3888fcf..1d496f6 100644 --- a/source/read-write-configuration.txt +++ b/source/read-write-configuration.txt @@ -52,28 +52,29 @@ 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 primary - node acknowledges the write operation. +- ``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. + 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. + 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. + replica set members acknowledge the write operation. - ``WriteConcern.UNACKNOWLEDGED``: The write operation returns after the primary - node processes the write operation. + node processes the write operation. - ``WriteConcern.JOURNALED``: The write operation returns after the primary node - writes the data to the on-disk journal. + writes the data to the on-disk journal. -The following example sets the write concern to ``"majority"`` for on a client -instance: +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: @@ -109,7 +110,7 @@ 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. + 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 @@ -120,7 +121,7 @@ You can set the following read concern levels: 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 +- ``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 @@ -134,6 +135,7 @@ The following example sets the read concern to ``ReadConcern.MAJORITY`` for an i :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: @@ -150,8 +152,7 @@ Read Preference --------------- Read preference determines which member of a replica set MongoDB reads when -running a query. You can also customize how the server evaluates a replica set -member. You can set the read preference by using the ``readPreference()`` method +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. @@ -175,6 +176,7 @@ for an instance of ``MongoClient``: :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: From 851fb6367d2a8a0c2391a2e67cbeaf755b8f025e Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Mon, 26 Aug 2024 06:31:39 -0700 Subject: [PATCH 4/4] Michael feedback --- source/read-write-configuration.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/read-write-configuration.txt b/source/read-write-configuration.txt index 1d496f6..d4f0c52 100644 --- a/source/read-write-configuration.txt +++ b/source/read-write-configuration.txt @@ -99,7 +99,7 @@ Read concern specifies the following behaviors: - Level of :manual:`causal consistency ` across replica sets -- :manual:`Isolation Guarantees ` maintained +- :manual:`Isolation guarantees ` maintained during a query You can specify the read concern by using the ``readConcern()`` method on a