modify

Author: rachel-mack

source/crud/update-documents.txt

@@ -170,4 +170,119 @@ documents match.
     to a document that violate unique index constraints on the
     collection. For more information about constraints on unique indexes,
     see :manual:`Unique Indexes </core/index-unique/>` in the
-    {+mdb-server+} manual.
+    {+mdb-server+} manual.
+
+Update Example
+~~~~~~~~~~~~~~
+
+The following code is a complete, standalone file that performs an update one
+operation and an update many operation. 
+
+.. include:: /includes/crud/example-intro.rst
+
+.. io-code-block::
+
+   .. input:: /includes/crud/Insert.java
+      :language: java
+      :dedent:
+
+   .. output:: 
+      :language: none
+      :visible: false
+
+      InsertOne document id: BsonObjectId{value=...}
+      InsertMany document ids: {0=BsonObjectId{value=...}, 1=BsonObjectId{value=...}}
+
+.. _replace-operation:
+
+Replace
+-------
+
+A replace operation substitutes one document from your collection. The
+substitution occurs between a document your query filter matches and a
+replacement document. 
+
+The `replaceOne() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#replaceOne(org.bson.conversions.Bson,TDocument)>`__
+method removes all the existing fields and values in the
+matching document (except the ``_id`` field) and substitutes it with the
+replacement document. 
+
+You can call the ``replaceOne()`` method on a ``MongoCollection``
+instance as follows: 
+
+.. code-block:: java
+
+    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.
+- ``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>`__.
+
+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. 
+
+To update the inventory, call the ``replaceOne()`` method specifying the
+following:
+
+- A query filter that matches documents where the ``color`` is "pink" 
+- A replacement document where the ``color`` is "orange" and the ``qty`` is "25"
+
+.. literalinclude:: /includes/fundamentals/code-snippets/Update.java
+   :language: java
+   :dedent:
+   :start-after: begin replaceOneExample
+   :end-before: end replaceOneExample
+
+The output of the preceding code resembles the following:
+
+.. code-block:: none   
+   :copyable: false
+
+    Matched document count: 1
+    Modified document count: 1
+
+The following shows the updated document:
+
+.. code-block:: json
+   :copyable: false
+
+    { "_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 server 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 :ref:`upsert guide <java-upsert>` to
+learn how to insert a new document instead of replacing one if no
+documents match.
+
+.. important::
+
+    The ``replaceOne()`` method cannot make changes to a document that
+    violate unique index constraints on the collection.
+    For more information about constraints on unique indexes,
+    see :manual:`Unique Indexes </core/index-unique/>` in the
+    {+mdb-server+} manual.

source/includes/crud/Delete.java

@@ -29,8 +29,8 @@ public static void main(String[] args) {
 
             try {
                 // Deletes the first document that has a "title" value of "The Garbage Pail Kids Movie"
-                DeleteResult deleteOneResult = collection.deleteOne(deleteOneQuery);
-                System.out.println("DeleteOne document count: " + deleteOneResult.getDeletedCount());
+                DeleteResult result = collection.deleteOne(deleteOneQuery);
+                System.out.println("DeleteOne document count: " + result.getDeletedCount());
 
             // Prints a message if any exceptions occur during the operation
             } catch (MongoException me) {
@@ -41,10 +41,10 @@ public static void main(String[] args) {
 
             try {
                 // Deletes all documents that have an "imdb.rating" value less than 1.9
-                DeleteResult deleteManyResult = collection.deleteMany(deleteManyQuery);
+                DeleteResult result = collection.deleteMany(deleteManyQuery);
 
                 // Prints the number of deleted documents
-                System.out.println("DeleteMany document count: " + deleteManyResult.getDeletedCount());
+                System.out.println("DeleteMany document count: " + result.getDeletedCount());
 
             // Prints a message if any exceptions occur during the operation
             } catch (MongoException me) {

source/includes/crud/Insert.java

@@ -26,7 +26,7 @@ public static void main(String[] args) {
 
             try {
                 // Inserts a sample document describing a movie into the collection
-                InsertOneResult iOResult = collection.insertOne(new Document()
+                InsertOneResult result = collection.insertOne(new Document()
                         .append("_id", new ObjectId())
                         .append("title", "Ski Bloopers")
                         .append("genres", Arrays.asList("Documentary", "Comedy")));

source/includes/usage-examples/code-snippets/UpdateOne.java renamed to source/includes/crud/Update.java

@@ -24,20 +24,21 @@ public static void main(String[] args) {
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
-            Document query = new Document().append("title",  "Cool Runnings 2");
+            // Instructs the driver to insert a new document if none match the query
+            UpdateOptions options = new UpdateOptions().upsert(true);
+
+
+            Document updateOneQuery = new Document().append("title",  "Cool Runnings 2");
 
             // Creates instructions to update the values of three document fields
-            Bson updates = Updates.combine(
+            Bson updateOneUpdates = Updates.combine(
                     Updates.set("runtime", 99),
                     Updates.addToSet("genres", "Sports"),
                     Updates.currentTimestamp("lastUpdated"));
 
-            // Instructs the driver to insert a new document if none match the query
-            UpdateOptions options = new UpdateOptions().upsert(true);
-
             try {
                 // Updates the first document that has a "title" value of "Cool Runnings 2"
-                UpdateResult result = collection.updateOne(query, updates, options);
+                UpdateResult result = collection.updateOne(updateOneQuery, updateOneUpdates, options);
 
                 // Prints the number of updated documents and the upserted document ID, if an upsert was performed
                 System.out.println("Modified document count: " + result.getModifiedCount());
@@ -47,6 +48,25 @@ public static void main(String[] args) {
             } catch (MongoException me) {
                 System.err.println("Unable to update due to an error: " + me);
             }
+
+            Bson updateManyQuery = gt("num_mflix_comments", 50);
+
+            // Creates instructions to update the values of two document fields
+            Bson updateManyUpdates = Updates.combine(
+                    Updates.addToSet("genres", "Frequently Discussed"),
+                    Updates.currentTimestamp("lastUpdated"));
+
+            try {
+                // Updates documents that have a "num_mflix_comments" value over 50
+                UpdateResult result = collection.updateMany(updateManyQuery, updateManyUpdates);
+
+                // Prints the number of updated documents
+                System.out.println("Modified document count: " + result.getModifiedCount());
+
+            // Prints a message if any exceptions occur during the operation
+            } catch (MongoException me) {
+                System.err.println("Unable to update due to an error: " + me);
+            }
         }
     }
 }