DOCSP-41769: Improved bulk write API

source/fundamentals/crud/write-operations/bulk.txt

@@ -16,6 +16,16 @@ Overview
 In this guide, you can learn how to use bulk operations in the
 MongoDB Java Driver. 
 
+.. note:: Client Bulk Write Method
+
+   This guide primarily focuses on the ``MongoCollection.bulkWrite()``
+   method, which allows you to perform bulk operations on a collection. 
+   When connecting to a deployment running {+mdb-server+} 8.0 or later,
+   you can use the ``MongoClient.bulkWrite()`` method to write
+   to multiple databases and collections in the same call. See the 
+   :ref:`java-sync-client-bulk-write` section below to learn how to use the
+   ``MongoClient.bulkWrite()`` method.
+
 To perform a create, replace, update, or delete operation,
 use its corresponding method. For example, to insert one document,
 update multiple documents, and delete one document in your collection,
@@ -44,7 +54,7 @@ document. The examples in each section use the following documents in the
    { "_id": 8, "name": "Shayla Ray", "age": 20 }
 
 For more information about the methods and classes mentioned in this section,
-see the following API Documentation:
+see the following API documentation:
 
 - `bulkWrite() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#bulkWrite(java.util.List,com.mongodb.client.model.BulkWriteOptions)>`__
 - `WriteModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/WriteModel.html>`__
@@ -100,7 +110,7 @@ describing people:
 For more information about the methods and classes mentioned in this section,
 see the `InsertOneModel
 <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/InsertOneModel.html>`__
-API Documentation. 
+API documentation. 
 
 Replace Operation
 ~~~~~~~~~~~~~~~~~
@@ -132,7 +142,7 @@ contains an added ``location`` field:
 For more information about the methods and classes mentioned in this section,
 see the following resources:
 
-- `ReplaceOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOneModel.html>`__ API Documentation
+- `ReplaceOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOneModel.html>`__ API documentation
 - :manual:`Unique indexes </core/index-unique/>` Server Manual Explanation
 
 Update Operation
@@ -168,8 +178,8 @@ the ``age`` field in a document where the ``_id`` is ``2``:
 For more information about the methods and classes mentioned in this section,
 see the following resources:
 
-- `UpdateOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOneModel.html>`__ API Documentation
-- `UpdateManyModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateManyModel.html>`__ API Documentation
+- `UpdateOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOneModel.html>`__ API documentation
+- `UpdateManyModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateManyModel.html>`__ API documentation
 - :manual:`unique indexes </core/index-unique/>` Server Manual Explanation
 
 Delete Operation
@@ -202,7 +212,7 @@ a document where the ``_id`` is ``1``:
    :end-before: end deleteDocumentsExample
 
 For more information about the methods and classes mentioned in this section,
-see the following API Documentation:
+see the following API documentation:
 
 - `DeleteOneModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/DeleteOneModel.html>`__
 - `DeleteManyModel <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/DeleteManyModel.html>`__
@@ -288,14 +298,146 @@ operations to execute in any order:
       { "_id": 6, "name": "Zaynab Omar", "age": 37 }
 
 For more information about the methods and classes mentioned in this section,
-see the following API Documentation:
+see the following API documentation:
 
 - `BulkWriteOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/BulkWriteOptions.html>`__
 - `ordered() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/BulkWriteOptions.html#ordered(boolean)>`__
 
+.. _java-sync-client-bulk-write:
+
+Client Bulk Write Method
+------------------------
+
+When connecting to a deployment running {+mdb-server+} 8.0 or later,
+you can use the ``MongoClient.bulkWrite()`` method to write
+to multiple databases and collections in the same cluster.
+
+In the examples in preceding sections of this page, the ``MongoCollection.bulkWrite()`` method 
+takes a list of ``WriteModel`` instances in which the specified subclass of 
+``WriteModel`` represents the corresponding write operation. For example, an
+instance of ``InsertOneModel`` represents an operation to insert one document. 
+
+Similarly, the ``MongoClient.bulkWrite()`` method takes a 
+list of ``ClientNamespacedWriteModel`` instances to represent different write operations.
+However, you do not need to specify the subclass that represents the corresponding
+write operation. Instead, the ``ClientNamespacedWriteModel`` object contains different 
+methods to represent different write operations, such as ``ClientNamespacedWriteModel.insertOne()`` or 
+``ClientNamespacedWriteModel.updateOne()``.
+
+These methods take a ``MongoNamespace`` object that defines which
+database and collection to write to, and a ``Document`` object that defines
+information about the write operation. Some methods, such as ``updateOne()`` and 
+``replaceOne()``, also take a ``Filters`` object that defines the filter for the operation.
+
+The following sections describe how to use the client ``bulkWrite()`` method.
+
+Insert Example
+~~~~~~~~~~~~~~
+
+This following example shows how to use the ``bulkWrite()`` method to insert 
+two documents. One document is inserted into the ``people`` collection in a
+database named ``db``. The other document is inserted into a collection called ``things``
+in the ``db`` database.
+We use the ``MongoNamespace`` object to define the database and collection we
+want each write operation to be applied to.
+
+.. code-block:: java
+
+   MongoNamespace peopleNamespace = new MongoNamespace("db", "people");
+   MongoNamespace thingsNamespace = new MongoNamespace("db", "things");
+
+   List<ClientNamespacedWriteModel> bulkOperations = new ArrayList<>();
+
+   bulkOperations.add(ClientNamespacedWriteModel.insertOne(peopleNamespace, new Document("name", "Julia Smith")));
+   bulkOperations.add(ClientNamespacedWriteModel.insertOne(thingsNamespace, new Document("object", "washing machine")));
+
+   ClientBulkWriteResult result = client.bulkWrite(bulkOperations);
+
+.. TODO: link documentation
+
+Replace Example
+~~~~~~~~~~~~~~~
+
+The following example shows how to use the ``bulkWrite()`` method to replace
+existing documents in the ``people`` and ``things`` collections.
+
+.. code-block:: java
+
+   MongoNamespace peopleNamespace = new MongoNamespace("db", "people");
+   MongoNamespace thingsNamespace = new MongoNamespace("db", "things");
+
+   List<ClientNamespacedWriteModel> bulkOperations = new ArrayList<>();
+
+   bulkOperations.add(ClientNamespacedWriteModel.replaceOne(
+         peopleNamespace, 
+         Filters.eq("_id", 1),
+         new Document("name", "Maximus Farquaad")
+      )
+   );
+
+   bulkOperations.add(ClientNamespacedWriteModel.replaceOne(
+         thingsNamespace, 
+         Filters.eq("_id", 1),
+         new Document("object", "potato")
+      )
+   );
+
+   ClientBulkWriteResult result = client.bulkWrite(bulkOperations);
+
+After this example runs successfully, the document in the ``people`` collection in 
+which the ``_id`` field has the value of ``1`` is replaced with a new
+document. The document in the ``things`` collection in which the 
+``_id`` field has the value of ``1`` is replaced with a new document.
+
+.. _java-sync-client-bulk-write-options:
+
+Bulk Write Options
+~~~~~~~~~~~~~~~~~~
+
+You can use the ``ClientBulkWriteOptions`` interface to specify options when
+running the ``bulkWrite()`` method.
+
+Order of Execution Example
+``````````````````````````
+
+By default, the write operations execute in the order that you specify them. However,
+you can pass ``false`` to the ``ordered()`` method on the ``ClientBulkWriteOptions``
+interface to perform write operations in an unordered way. When using the unordered
+option, an error-producing operation will not block execution of other bulk 
+write operations.
+
+The following code shows how to set the ``ordered()`` method when creating an
+instance of ``ClientBulkWriteOptions``.
+
+.. code-block:: java
+
+   MongoNamespace namespace = new MongoNamespace("db", "people");
+
+   ClientBulkWriteOptions options = new ClientBulkWriteOptions().ordered(false);
+
+   List<ClientNamespacedWriteModel> bulkOperations = new ArrayList<>();
+
+   bulkOperations.add(ClientNamespacedWriteModel.insertOne(namespace, new Document("_id", 1).append("name", "Donkey Kong)));
+
+   // duplicate key
+   bulkOperations.add(ClientNamespacedWriteModel.insertOne(namespace, new Document("_id", 1).append("name", "Mario")));
+
+   bulkOperations.add(ClientNamespacedWriteModel.insertOne(namespace, new Document("name", "Princess Peach")));
+
+   ClientBulkWriteResult result = client.bulkWrite(bulkOperations, options);
+
+Even though the write operation inserting a document with a duplicate key will
+result in an error, the other operations will be executed because we have specified
+the ``ordered()`` option to be ``false``.
+
+.. TODO: link documentation
+
 Summary
 -------
 
+``MongoCollection.bulkWrite()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 To perform a bulk operation, you create and pass a list of
 ``WriteModel`` documents to the ``bulkWrite()`` method. 
 
@@ -308,3 +450,23 @@ There are two ways to execute the ``bulkWrite()`` method:
 - Ordered, which performs the bulk operations in order until an error occurs, if any
 - Unordered, which performs all the bulk operations in any order and reports errors
   at the end, if any
+
+``MongoClient.bulkWrite()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In {+mdb-server+} version 8.0 and {+driver-short+} version 5.3 and later, you 
+can use the ``bulkWrite()`` method to perform bulk operations on multiple 
+databases and collections at once.
+
+This method uses the ``ClientNamespacedWriteModel`` and its methods
+``insertOne()``, ``updateOne()``, ``updateMany()``, ``replaceOne()``, 
+``deleteOne()``, and ``deleteMany()``.
+
+The method can also take a ``ClientBulkWriteOptions`` object to specify different
+options for how the command is executed.
+
+To learn more about the client ``bulkWrite`` command, take a look at the 
+:manual:`bulkWrite <reference/command/bulkWrite/>` guide in the {+mdb-server+}
+Manual.
+
+.. TODO: Add API Documentation

source/whats-new.txt

@@ -19,6 +19,7 @@ What's New
 
 Learn what's new in:
 
+* :ref:`Version 5.3 <java-version-5.3>`
 * :ref:`Version 5.2.1 <java-version-5.2.1>`
 * :ref:`Version 5.2 <java-version-5.2>`
 * :ref:`Version 5.1.3 <java-version-5.1.3>`
@@ -29,6 +30,22 @@ Learn what's new in:
 * :ref:`Version 4.11 <version-4.11>`
 * :ref:`Version 4.10 <version-4.10>`
 
+.. _java-version-5.3:
+
+What's New in 5.3
+-----------------
+
+The 5.3 {+driver-short+} release introduces the following improvements, features,
+and fixes:
+
+- Client bulk write API that allows you to perform write operations on multiple
+  databases and collections at once. To learn more about this feature, see the
+  :ref:`java-sync-client-bulk-write` section of the Bulk Operations guide.
+
+- A ``ClientBulkWriteOptions`` object to specify different options for how
+  the client bulk write API is executed. See the :ref:`java-sync-client-bulk-write-options` 
+  section of the Client Bulk Write guide.
+
 .. _java-version-5.2.1:
 
 What's New in 5.2.1