diff --git a/source/crud/write-operations/bulk.txt b/source/crud/write-operations/bulk.txt index a6cd7f110..8d0ee7e59 100644 --- a/source/crud/write-operations/bulk.txt +++ b/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 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 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 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 diff --git a/source/crud/write-operations/modify.txt b/source/crud/write-operations/modify.txt index 9eef1d40b..a8dbdf734 100644 --- a/source/crud/write-operations/modify.txt +++ b/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 diff --git a/source/includes/fundamentals/code-snippets/BulkWrite.java b/source/includes/fundamentals/code-snippets/bulk-write/BulkWrite.java similarity index 100% rename from source/includes/fundamentals/code-snippets/BulkWrite.java rename to source/includes/fundamentals/code-snippets/bulk-write/BulkWrite.java diff --git a/source/includes/fundamentals/code-snippets/bulk-write/ClientBulkWrite.java b/source/includes/fundamentals/code-snippets/bulk-write/ClientBulkWrite.java new file mode 100644 index 000000000..32629e775 --- /dev/null +++ b/source/includes/fundamentals/code-snippets/bulk-write/ClientBulkWrite.java @@ -0,0 +1,179 @@ +package docs; + +import com.mongodb.MongoNamespace; +import com.mongodb.client.MongoClient; +import com.mongodb.client.MongoClients; +import com.mongodb.client.MongoCollection; +import com.mongodb.client.MongoDatabase; + +import com.mongodb.client.model.bulk.ClientBulkWriteOptions; +import com.mongodb.client.model.bulk.ClientBulkWriteResult; +import com.mongodb.client.model.bulk.ClientNamespacedWriteModel; +import org.bson.Document; + +import java.util.*; + +import com.mongodb.client.model.Filters; +import com.mongodb.client.model.Updates; + +public class ClientBulkWrite { + private final MongoClient mongoClient; + private final MongoDatabase database; + private final MongoCollection peopleCollection; + private final MongoCollection thingsCollection; + + private ClientBulkWrite() { + final String uri = System.getenv("DRIVER_REF_URI"); + + mongoClient = MongoClients.create(uri); + database = mongoClient.getDatabase("db"); + + peopleCollection = database.getCollection("people"); + thingsCollection = database.getCollection("things"); + } + + public static void main(String[] args) { + ClientBulkWrite clientBulkWrite = new ClientBulkWrite(); + + System.out.println("Insert Example:"); + clientBulkWrite.insertDocumentsExample(); + + System.out.println("Update Example:"); + clientBulkWrite.setUpCollection(); + clientBulkWrite.updateDocumentsExample(); + + System.out.println("Replace Example:"); + clientBulkWrite.setUpCollection(); + clientBulkWrite.replaceDocumentsExample(); + } + + private void insertDocumentsExample(){ + // start-insert-models + MongoNamespace peopleNamespace = new MongoNamespace("db", "people"); + MongoNamespace thingsNamespace = new MongoNamespace("db", "things"); + + List 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 = mongoClient.bulkWrite(bulkOperations); + // end-insert-models + + System.out.println("# Inserted: " + result.getInsertedCount()); + } + + private void updateDocumentsExample(){ + // start-update-models + MongoNamespace peopleNamespace = new MongoNamespace("db", "people"); + MongoNamespace thingsNamespace = new MongoNamespace("db", "things"); + + List bulkOperations = new ArrayList<>(); + + bulkOperations.add(ClientNamespacedWriteModel.updateOne( + peopleNamespace, + Filters.eq("name", "Freya Polk"), + Updates.inc("age", 1) + ) + ); + + bulkOperations.add(ClientNamespacedWriteModel.updateMany( + thingsNamespace, + Filters.eq("category", "electronic"), + Updates.set("manufacturer", "Premium Technologies") + ) + ); + + ClientBulkWriteResult result = mongoClient.bulkWrite(bulkOperations); + // end-update-models + + System.out.println("# Updated: " + result.getModifiedCount()); + } + private void replaceDocumentsExample(){ + // start-replace-models + MongoNamespace peopleNamespace = new MongoNamespace("db", "people"); + MongoNamespace thingsNamespace = new MongoNamespace("db", "things"); + + List bulkOperations = new ArrayList<>(); + + bulkOperations.add(ClientNamespacedWriteModel.replaceOne( + peopleNamespace, + Filters.eq("_id", 1), + new Document("name", "Frederic Hilbert") + ) + ); + + bulkOperations.add(ClientNamespacedWriteModel.replaceOne( + thingsNamespace, + Filters.eq("_id", 1), + new Document("object", "potato") + ) + ); + + ClientBulkWriteResult result = mongoClient.bulkWrite(bulkOperations); + // end-replace-models + + System.out.println("# Replaced: " + result.getModifiedCount()); + } + + private void orderOfExecutionExample() { + // start-order-exec + MongoNamespace namespace = new MongoNamespace("db", "people"); + + ClientBulkWriteOptions options = ClientBulkWriteOptions + .clientBulkWriteOptions() + .ordered(false); + + List 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); + // end-order-exec + } + + private void setUpCollection(){ + + peopleCollection.deleteMany(Filters.empty()); + thingsCollection.deleteMany(Filters.empty()); + + peopleCollection.insertOne(new Document("_id", 1).append("name", "Freya Polk").append("age", 34)); + thingsCollection.insertMany(Arrays.asList( + new Document("_id", 1).append("object", "notebook"), + new Document("object", "keyboard").append("category", "electronic"), + new Document("object", "blender").append("category", "electronic") + ) + ); + } +} diff --git a/source/versioning/whats-new.txt b/source/versioning/whats-new.txt index 129e425b2..6f332feba 100644 --- a/source/versioning/whats-new.txt +++ b/source/versioning/whats-new.txt @@ -19,6 +19,7 @@ What's New Learn what's new in: +* :ref:`Version 5.4 ` * :ref:`Version 5.3 ` * :ref:`Version 5.2.1 ` * :ref:`Version 5.2 ` @@ -30,6 +31,22 @@ Learn what's new in: * :ref:`Version 4.11 ` * :ref:`Version 4.10 ` +.. _java-version-5.4: + +What's New in 5.4 +----------------- + +The 5.4 driver release includes the following changes, fixes, +and features: + +.. sharedinclude:: dbx/jvm/v5.4-wn-items.rst + + .. replacement:: sort-option-link + + the :ref:`java-sync-client-bulk-write-update` and + :ref:`java-sync-client-bulk-write-replace` sections of the Bulk + Operations guide + .. _java-version-5.3: What's New in 5.3 @@ -468,4 +485,4 @@ New features of the 4.10 driver release include: - Support for :ref:`qe-manual-feature-qe` (QE). To learn more about the requirements for using the QE feature, see the :ref:`Queryable Encryption Driver Compatibility Table - `. \ No newline at end of file + `.