DOCSP-46124: sort option in updateoptions and replaceoptions (#609)

* DOCSP-46124: sort option for updateone and replaceone

* add links

* wip

* wip

* NR PR fixes 1

* add bulk info

* JK tech review 1

Author: rustagir

source/fundamentals/builders/updates.txt

@@ -1,3 +1,5 @@
+.. _updates-builders:
+
 ================
 Updates Builders
 ================
@@ -8,8 +10,6 @@ Updates Builders
    :depth: 2
    :class: singlecol
 
-.. _updates-builders:
-
 Overview
 --------
 

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

@@ -157,10 +157,25 @@ contains an added ``location`` field:
    :start-after: begin replaceDocumentsExample
    :end-before: end replaceDocumentsExample
 
+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
+operation, as shown in the following code:
+
+.. code-block:: java
+
+   ReplaceOptions options = ReplaceOptions.sort(Sorts.ascending("_id"));
+
 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
+- `ReplaceOptions
+  <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOptions.html>`__
+  API documentation
 - :manual:`Unique indexes </core/index-unique/>` Server Manual Explanation
 
 Update Operation
@@ -193,11 +208,28 @@ the ``age`` field in a document where the ``_id`` is ``2``:
    :start-after: begin updateDocumentsExample
    :end-before: end updateDocumentsExample
 
+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
+operation, as shown in the following code:
+
+.. code-block:: java
+
+   UpdateOptions options = UpdateOptions.sort(Sorts.ascending("_id"));
+
 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
+- `UpdateOptions
+  <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOptions.html>`__
+  API documentation
 - :manual:`unique indexes </core/index-unique/>` Server Manual Explanation
 
 Delete Operation

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

@@ -44,7 +44,7 @@ Update
 
 Update operations can modify fields and values. They apply changes
 specified in an update document to one or more documents that match your
-query filter. 
+query filter.
 
 The `updateOne() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#updateOne(org.bson.conversions.Bson,org.bson.conversions.Bson)>`__
 method changes the first document your query filter matches and the
@@ -56,40 +56,73 @@ You can call the ``updateOne()`` and ``updateMany()`` methods on a
 
 .. code-block:: java
 
-    collection.updateOne(query, updateDocument);
-
-    collection.updateMany(query, updateDocument);
+    collection.updateOne(<query>, <updateDocument>);
+    collection.updateMany(<query>, <updateDocument>);
 
 Update Operation Parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``updateOne()`` and ``updateMany()`` methods both have the following
 parameters:
 
-- ``query`` specifies a query filter with the criteria to match documents to update in your collection
-- ``updateDocument`` specifies the fields and values to modify in the matching document or documents. For this example, we use the :doc:`Updates builder </fundamentals/builders/updates>` to create the update document.
+- ``query`` specifies a query filter with the criteria to match
+  documents to update in your collection.
+- ``update`` specifies the fields and values to modify in the matching
+  document or documents. The examples in this section use the
+  :ref:`updates-builders` to create the update document.
+- *(Optional)* ``updateOptions`` specifies options that you can set to
+  customize how the driver performs the update operation. To learn more
+  about this type, see the API documentation for `UpdateOptions
+  <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/UpdateOptions.html>`__.
 
 You can create the ``updateDocument`` using an ``Updates`` builder as
 follows:
 
 .. code-block:: java
 
-    Bson updateDocument = Updates.operator(field, value);
+   Bson update = Updates.operator(<field>, <value>);
+
+To view a complete list of Updates builders and their usage, see `Updates
+<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Updates.html>`__
+in the API documentation.
+
+Update One Example
+~~~~~~~~~~~~~~~~~~
+
+The following example demonstrates how to change the value of the
+``color`` field in the first matching document in which the value of
+``qty`` is ``0``:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/Update.java
+   :language: java
+   :dedent:
+   :start-after: begin updateOneExample
+   :end-before: end updateOneExample
 
-See the MongoDB API documentation for a `complete list of
-Updates builders and their usage <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Updates.html>`__.
+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
+shown in the following code:
 
-Example
-```````
+.. literalinclude:: /includes/fundamentals/code-snippets/Update.java
+   :language: java
+   :dedent:
+   :start-after: begin updateoptions
+   :end-before: end updateoptions
+
+Update Many Example
+~~~~~~~~~~~~~~~~~~~
 
 The paint store receives a fresh shipment and needs to update their inventory.
 The shipment contains 20 cans of each paint color.
 
 To update the inventory, call the ``updateMany()`` method specifying the
 following:
 
-- A query filter that matches all the colors 
-- An update document that contains instructions to increment the ``qty`` field by "20"
+- Query filter that matches all the colors
+- Update document that contains instructions to increment the ``qty``
+  field by ``20``
 
 .. literalinclude:: /includes/fundamentals/code-snippets/Update.java
    :language: java
@@ -149,18 +182,24 @@ instance as follows:
 
 .. code-block:: java
 
-    collection.replaceOne(query, replacementDocument);
+    collection.replaceOne(<query>, <replacement>);
 
 Replace Operation Parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``replaceOne()`` method has the following parameters:
 
-- ``query`` specifies a query filter with the criteria to match a document to replace in your collection
-- ``replacementDocument`` specifies fields and values of a new ``Document`` object to replace in the matched document 
+- ``query`` specifies a query filter with the criteria to match a
+  document to replace in your collection.
+- ``replacement`` specifies fields and values of a new ``Document``
+  object to replace the matched document.
+- *(Optional)* ``replaceOptions`` specifies options that you can set to
+  customize how the driver performs the replace operation. To learn more
+  about this type, see the API documentation for `ReplaceOptions
+  <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/ReplaceOptions.html>`__.
 
-Example
-```````
+Replace One Example
+~~~~~~~~~~~~~~~~~~~
 
 The paint store realizes they must update their inventory again.  What they
 thought was 20 cans of pink paint is actually 25 cans of orange paint. 
@@ -192,14 +231,23 @@ The following shows the updated document:
 
     { "_id": 5, "color": "orange", "qty": 25 }
 
+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
+shown in the following code:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/Update.java
+   :language: java
+   :dedent:
+   :start-after: begin replaceoptions
+   :end-before: end replaceoptions
+
 If zero documents match the query filter in the replace operation,
 ``replaceOne()`` makes no changes to documents in the collection. See
 our :doc:`upsert guide </fundamentals/crud/write-operations/upsert>` to
 learn how to insert a new document instead of replacing one if no
-documents match. 
-
-If multiple documents match the query filter specified in
-the ``replaceOne()`` method, it replaces the first result. 
+documents match.
 
 .. important::
 
@@ -208,4 +256,3 @@ the ``replaceOne()`` method, it replaces the first result.
     For more information about constraints on unique indexes,
     see :manual:`Unique Indexes </core/index-unique/>` in the
     {+mdb-server+} manual.
-

source/includes/fundamentals/code-snippets/Update.java

@@ -14,6 +14,8 @@
 import com.mongodb.client.model.Updates;
 import com.mongodb.client.result.UpdateResult;
 
+import static com.mongodb.client.model.Sorts.ascending;
+
 public class Update {
     private final MongoCollection<Document> collection;
     private final MongoClient mongoClient;
@@ -41,6 +43,25 @@ public static void main(String [] args){
         update.preview(false);
     }
 
+    private void updateOneExample(){
+        // Creates a filter and update document to change the value of ``color``
+        // begin updateOneExample
+        Bson filter = Filters.eq("qty", 0);
+        Bson update = Updates.set("color", "dandelion");
+
+        // Updates first matching document
+        UpdateResult result = collection.updateOne(filter, update);
+        // end updateOneExample
+        
+        System.out.println("Matched document count: " + result.getMatchedCount());
+        System.out.println("Modified document count: " + result.getModifiedCount());
+
+        // begin updateoptions
+        UpdateOptions options = UpdateOptions.sort(ascending("color"));
+        UpdateResult result = collection.updateOne(filter, document, options);
+        // end updateoptions
+    }
+
     private void updateManyExample(){
         // Creates a filter and update document to increase the "qty" value of all documents
         // begin updateManyExample
@@ -67,6 +88,11 @@ private void replaceOneExample(){
         System.out.println("Matched document count: " + result.getMatchedCount());
         System.out.println("Modified document count: " + result.getModifiedCount());
         // end replaceOneExample
+
+        // begin replaceoptions
+        ReplaceOptions options = ReplaceOptions.sort(ascending("qty"));
+        UpdateResult result = collection.replaceOne(filter, document, options);
+        // end replaceoptions
     }
 
     private void preview(boolean drop){

source/whats-new.txt

@@ -45,6 +45,11 @@ and features:
       To learn about how to use this type when using the Atlas
       Vector Search feature, see the :ref:`java-atlas-vector-search` guide.
 
+   .. replacement:: update-replace-example-link
+      
+      the :ref:`java-fundamentals-change-document` and :ref:`java-fundamentals-bulkwrite` 
+      guides
+
 - Adds a 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.