Merge remote-tracking branch 'upstream/master' into DOCSP-47273-faq-reorg

Author: norareidy

snooty.toml

@@ -12,7 +12,8 @@ toc_landing_pages = [
     "/crud",
     "/crud/builders",
     "/data-formats",
-    "/api-documentation"
+    "/api-documentation",
+    "/security/auth"
 ]
 
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"

source/connection.txt

@@ -28,7 +28,7 @@ Learn how to set up a connection and specify connection behavior from your
 application to a MongoDB deployment using the driver in the following
 sections:
 
-- :ref:`Connect to MongoDB <connect-to-mongodb>`
+- :ref:`Connect to MongoDB <java-connect-to-mongodb>`
 - :ref:`View a List of Connection Options <connection-options>`
 - :ref:`Specify Connection Behavior with the MongoClient Class <specify-mongoclient-settings>`
 - :ref:`Enable Network Compression <network-compression>`
@@ -38,4 +38,4 @@ sections:
 - :atlas:`Connect to MongoDB Atlas from AWS Lambda </manage-connections-aws-lambda/>`
 
 For information about authenticating with a MongoDB instance,
-see :ref:`<authentication-mechanisms>` and :ref:`<enterprise-authentication-mechanisms>`.
+see the :ref:`<java-authentication-mechanisms>` section.

source/connection/connect.txt

@@ -1,4 +1,4 @@
-.. _connect-to-mongodb:
+.. _java-connect-to-mongodb:
 
 ==================
 Connect to MongoDB
@@ -40,8 +40,8 @@ Use the ``MongoClients.create()`` method to construct a ``MongoClient``.
    As each ``MongoClient`` represents a thread-safe pool of connections to the
    database, most applications only require a single instance of a
    ``MongoClient``, even across multiple threads. 
-All resource usage limits, such as max connections, apply to individual
-``MongoClient`` instances.
+   All resource usage limits, such as max connections, apply to individual
+   ``MongoClient`` instances.
 
 To learn about the different settings you can use to control the
 behavior of your ``MongoClient``, see the guide on

source/connection/connection-troubleshooting.txt

@@ -103,8 +103,8 @@ Connection Troubleshooting
 
    .. replacement:: authentication-guide-reference
 
-      To learn more about specifying authentication mechanisms, see the :ref:`authentication-mechanisms` and
-      :ref:`enterprise-authentication-mechanisms` guides.
+      To learn more about specifying authentication mechanisms, see the :ref:`java-authentication-mechanisms`
+      section.
 
    .. replacement:: verify-authentication-mechanism-anchor
 

source/connection/mongoclientsettings.txt

@@ -116,7 +116,7 @@ connection behavior:
        messages to the server.
 
    * - ``credential()``
-     - Sets the :ref:`credential <authentication-mechanisms-java>`.
+     - Sets the :ref:`credential <java-authentication-mechanisms>`.
 
    * - ``readConcern()``
      - Sets the :manual:`read concern </reference/read-concern/>`.

source/crud/aggregation.txt

@@ -114,7 +114,7 @@ Connect to a MongoDB Deployment
 .. tip::
 
    To learn more about connecting to MongoDB, see the :ref:`Connection
-   Guide <connect-to-mongodb>`.
+   Guide <java-connect-to-mongodb>`.
 
 Insert Sample Data
 ++++++++++++++++++

source/crud/transactions.txt

@@ -28,14 +28,10 @@ error, the driver cancels the transaction and discards all data changes
 before they ever become visible.
 
 In MongoDB, transactions run within logical **sessions**. A
-:manual:`session </reference/server-sessions/>` is a grouping of related
-read or write operations that you intend to run sequentially. Sessions
-enable :manual:`causal consistency
-</core/read-isolation-consistency-recency/#causal-consistency>` for a
-group of operations or allow you to execute operations in an
-:website:`ACID transaction </basics/acid-transactions>`. MongoDB
-guarantees that the data involved in your transaction operations remains
-consistent, even if the operations encounter unexpected errors.
+session is a grouping of related read or write operations that you
+intend to run sequentially. Sessions allow you to run operations
+in an ACID-compliant transaction, which is a transaction that meets
+an expectation of atomicity, consistency, isolation, and durability.
 
 When using the {+driver-short+}, you can create a new session from a 
 ``MongoClient`` instance as a ``ClientSession`` type. We recommend that you reuse
@@ -54,6 +50,35 @@ instantiating a new client each time.
    You must include the ``session`` as a parameter for any operations that you
    want to include in a transaction.
 
+Causal Consistency
+~~~~~~~~~~~~~~~~~~
+
+.. sharedinclude:: dbx/causal-consistency.rst
+
+   .. replacement:: insert-one-method
+
+      ``insertOne()``
+
+   .. replacement:: update-one-method
+
+      ``updateOne()``
+
+   .. replacement:: find-one-method
+
+      ``find()``
+
+   .. replacement:: delete-one-method
+
+      ``deleteOne()``
+
+   .. replacement:: majority-rc
+
+      ``MAJORITY``
+
+   .. replacement:: majority-wc
+
+      ``MAJORITY``
+      
 Methods
 -------
 

source/crud/write-operations/bulk.txt

@@ -96,7 +96,7 @@ Example
 The following example creates an ``InsertOneModel`` for two documents
 describing people:
 
-.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
+.. literalinclude:: /includes/fundamentals/code-snippets/bulk-write/BulkWrite.java
    :language: java
    :dedent:
    :start-after: begin insertDocumentsExample
@@ -111,7 +111,7 @@ describing people:
    The following example tries to insert two documents where the ``_id`` is
    ``1`` and ``3``:
 
-   .. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
+   .. literalinclude:: /includes/fundamentals/code-snippets/bulk-write/BulkWrite.java
       :language: java
       :dedent:
       :start-after: begin insertExceptionExample
@@ -156,7 +156,7 @@ The following example creates a ``ReplaceOneModel`` to
 replace a document where the ``_id`` is ``1`` with a document that
 contains an added ``location`` field: 
 
-.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
+.. literalinclude:: /includes/fundamentals/code-snippets/bulk-write/BulkWrite.java
    :language: java
    :dedent:
    :start-after: begin replaceDocumentsExample
@@ -165,7 +165,7 @@ contains an added ``location`` field:
 If multiple documents match the query filter specified in
 the ``ReplaceOneModel`` instance, the operation replaces the first
 result. You can specify a sort in a ``ReplaceOptions`` instance to apply
-an order to matched documents before the driver performs the replace
+an order to matched documents before the server performs the replace
 operation, as shown in the following code:
 
 .. code-block:: java
@@ -207,7 +207,7 @@ Example
 The following example creates an ``UpdateOneModel`` to update
 the ``age`` field in a document where the ``_id`` is ``2``:
 
-.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
+.. literalinclude:: /includes/fundamentals/code-snippets/bulk-write/BulkWrite.java
    :language: java
    :dedent:
    :start-after: begin updateDocumentsExample
@@ -216,7 +216,7 @@ the ``age`` field in a document where the ``_id`` is ``2``:
 If multiple documents match the query filter specified in
 the ``UpdateOneModel`` instance, the operation updates the first
 result. You can specify a sort in an ``UpdateOptions`` instance to apply
-an order to matched documents before the driver performs the update
+an order to matched documents before the server performs the update
 operation, as shown in the following code:
 
 .. code-block:: java
@@ -260,7 +260,7 @@ Example
 The following example creates a ``DeleteOneModel`` to delete
 a document where the ``_id`` is ``1``:
 
-.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
+.. literalinclude:: /includes/fundamentals/code-snippets/bulk-write/BulkWrite.java
    :language: java
    :dedent:
    :start-after: begin deleteDocumentsExample
@@ -301,7 +301,7 @@ The following example performs these bulk operations:
   changes the ``name`` to ``"Zaynab Hassan"``
 - An operation that deletes all documents where the ``age`` value is greater than ``50``
 
-.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
+.. literalinclude:: /includes/fundamentals/code-snippets/bulk-write/BulkWrite.java
    :language: java
    :dedent:
    :start-after: begin bulkWriteExample
@@ -328,7 +328,7 @@ the bulk operation reports them at the end.
 Adding to the preceding example, including the following specifies the bulk
 operations to execute in any order: 
 
-.. literalinclude:: /includes/fundamentals/code-snippets/BulkWrite.java
+.. literalinclude:: /includes/fundamentals/code-snippets/bulk-write/BulkWrite.java
    :language: java
    :dedent:
    :start-after: begin bulkWriteNotOrderedExample
@@ -479,6 +479,8 @@ see the following API documentation:
   <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/bulk/ClientNamespacedWriteModel.html>`__
 - `MongoNamespace <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoNamespace.html>`__
 
+.. _java-sync-client-bulk-write-insert:
+
 Insert Example
 ~~~~~~~~~~~~~~
 
@@ -488,63 +490,77 @@ the other document is inserted into the ``db.things`` collection.
 The ``MongoNamespace`` instance defines the databases and collections that 
 each write operation applies to.
 
-.. code-block:: java
+.. literalinclude:: /includes/fundamentals/code-snippets/bulk-write/ClientBulkWrite.java
+   :language: java
+   :dedent:
+   :start-after: start-insert-models
+   :end-before: end-insert-models
 
-   MongoNamespace peopleNamespace = new MongoNamespace("db", "people");
-   MongoNamespace thingsNamespace = new MongoNamespace("db", "things");
+.. _java-sync-client-bulk-write-update:
 
-   List<ClientNamespacedWriteModel> bulkOperations = new ArrayList<>();
+Update Example
+~~~~~~~~~~~~~~
 
-   bulkOperations.add(ClientNamespacedWriteModel
-      .insertOne(
-         peopleNamespace, 
-         new Document("name", "Julia Smith")
-      )
-   );
+The following example shows how to use the ``bulkWrite()`` method to update
+existing documents in the ``db.people`` and ``db.things`` collections:
 
-   bulkOperations.add(ClientNamespacedWriteModel
-      .insertOne(
-         thingsNamespace, 
-         new Document("object", "washing machine")
-      )
-   );
+.. literalinclude:: /includes/fundamentals/code-snippets/bulk-write/ClientBulkWrite.java
+   :language: java
+   :dedent:
+   :start-after: start-update-models
+   :end-before: end-update-models
 
-   ClientBulkWriteResult result = mongoClient.bulkWrite(bulkOperations);
+This example increments the value of the ``age`` field by ``1`` in the
+document that has a ``name`` value of ``"Freya Polk"`` in the ``people``
+collection. It also sets the value of the ``manufacturer`` field to
+``"Premium Technologies"`` in all documents that have a ``category``
+value of ``"electronic"`` in the ``things`` collection.
 
-Replace Example
-~~~~~~~~~~~~~~~
-
-The following example shows how to use the ``bulkWrite()`` method to replace
-existing documents in the ``db.people`` and ``db.things`` collections.
+If multiple documents match the query filter specified in
+a ``ClientNamespacedUpdateOneModel`` instance, the operation updates the
+first result. You can specify a sort order in a `ClientUpdateOneOptions
+<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/bulk/ClientUpdateOneOptions.html>`__
+instance to apply an order to matched documents before the driver
+performs the update operation, as shown in the following code:
 
 .. code-block:: java
 
-   MongoNamespace peopleNamespace = new MongoNamespace("db", "people");
-   MongoNamespace thingsNamespace = new MongoNamespace("db", "things");
+   ClientUpdateOneOptions options = ClientUpdateOneOptions
+           .clientUpdateOneOptions()
+           .sort(Sorts.ascending("_id"));
 
-   List<ClientNamespacedWriteModel> bulkOperations = new ArrayList<>();
+.. _java-sync-client-bulk-write-replace:
 
-   bulkOperations.add(ClientNamespacedWriteModel.replaceOne(
-         peopleNamespace, 
-         Filters.eq("_id", 1),
-         new Document("name", "Frederic Hilbert")
-      )
-   );
+Replace Example
+~~~~~~~~~~~~~~~
 
-   bulkOperations.add(ClientNamespacedWriteModel.replaceOne(
-         thingsNamespace, 
-         Filters.eq("_id", 1),
-         new Document("object", "potato")
-      )
-   );
+The following example shows how to use the ``bulkWrite()`` method to replace
+existing documents in the ``db.people`` and ``db.things`` collections:
 
-   ClientBulkWriteResult result = mongoClient.bulkWrite(bulkOperations);
+.. literalinclude:: /includes/fundamentals/code-snippets/bulk-write/ClientBulkWrite.java
+   :language: java
+   :dedent:
+   :start-after: start-replace-models
+   :end-before: end-replace-models
 
 After this example runs successfully, the document that has an ``_id`` value of ``1`` 
 in the ``people`` collection is replaced with a new document. The document in 
 the ``things`` collection that has an ``_id`` value of ``1`` 
 is replaced with a new document.
 
+If multiple documents match the query filter specified in
+a ``ClientNamespacedReplaceOneModel`` instance, the operation replaces the
+first result. You can specify a sort order in a `ClientReplaceOneOptions
+<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/bulk/ClientReplaceOneOptions.html>`__
+instance to apply an order to matched documents before the driver
+performs the replace operation, as shown in the following code:
+
+.. code-block:: java
+
+   ClientReplaceOneOptions options = ClientReplaceOneOptions
+           .clientReplaceOneOptions()
+           .sort(Sorts.ascending("_id"));
+
 .. _java-sync-client-bulk-write-options:
 
 Bulk Write Options
@@ -568,39 +584,11 @@ The following code sets the ``ordered()`` method on an
 instance of ``ClientBulkWriteOptions`` and performs a bulk write operation to 
 insert multiple documents.
 
-.. code-block:: java
-
-   MongoNamespace namespace = new MongoNamespace("db", "people");
-
-   ClientBulkWriteOptions options = ClientBulkWriteOptions
-           .clientBulkWriteOptions()
-           .ordered(false);
-
-   List<ClientNamespacedWriteModel> bulkOperations = new ArrayList<>();
-
-   bulkOperations.add(
-      ClientNamespacedWriteModel.insertOne(
-         namespace, 
-         new Document("_id", 1).append("name", "Rudra Suraj")
-      )
-   );
-   
-   // Causes a duplicate key error
-   bulkOperations.add(
-      ClientNamespacedWriteModel.insertOne(
-         namespace, 
-         new Document("_id", 1).append("name", "Mario Bianchi")
-      )
-   );
-
-   bulkOperations.add(
-      ClientNamespacedWriteModel.insertOne(
-         namespace, 
-         new Document("name", "Wendy Zhang")
-      )
-   );
-
-   ClientBulkWriteResult result = mongoClient.bulkWrite(bulkOperations, options);
+.. literalinclude:: /includes/fundamentals/code-snippets/bulk-write/ClientBulkWrite.java
+   :language: java
+   :dedent:
+   :start-after: start-order-exec
+   :end-before: end-order-exec
 
 Even though the write operation inserting a document with a duplicate key results
 in an error, the other operations are executed because the write operation is

source/crud/write-operations/modify.txt

@@ -102,7 +102,7 @@ The following example demonstrates how to change the value of the
 If multiple documents match the query filter specified in
 the ``updateOne()`` method, it updates the first result. You can
 specify a sort in an ``UpdateOptions`` instance to apply an order to
-matched documents before the driver performs the update operation, as
+matched documents before the server performs the update operation, as
 shown in the following code:
 
 .. literalinclude:: /includes/fundamentals/code-snippets/Update.java
@@ -234,7 +234,7 @@ The following shows the updated document:
 If multiple documents match the query filter specified in
 the ``replaceOne()`` method, it replaces the first result. You can
 specify a sort in a ``ReplaceOptions`` instance to apply an order to
-matched documents before the driver performs the replace operation, as
+matched documents before the server performs the replace operation, as
 shown in the following code:
 
 .. literalinclude:: /includes/fundamentals/code-snippets/Update.java