DOCSP-33345: Java comments pt. 3

source/includes/usage-examples/code-snippets/ReplaceOne.java

@@ -1,3 +1,10 @@
+/**
+ * This file demonstrates how to replace a document in a collection by using
+ * the Java driver.
+ * It connects to a MongoDB deployment, accesses the "sample_mflix" database,
+ * and replaces a single document in the "movies" collection.
+ */
+
 package usage.examples;
 
 import static com.mongodb.client.model.Filters.eq;
@@ -20,23 +27,27 @@ public static void main(String[] args) {
         String uri = "<connection string uri>";
 
         try (MongoClient mongoClient = MongoClients.create(uri)) {
-
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
             Bson query = eq("title", "Music of the Heart");
 
+            // Creates a new document containing "title" and "fullplot" fields
             Document replaceDocument = new Document().
                     append("title", "50 Violins").
                     append("fullplot", " A dramatization of the true story of Roberta Guaspari who co-founded the Opus 118 Harlem School of Music");
 
+            // Instructs the driver to insert a new document if none match the query
             ReplaceOptions opts = new ReplaceOptions().upsert(true);
 
+            // Runs a write operation that replaces a matching document with the new document
             UpdateResult result = collection.replaceOne(query, replaceDocument, opts);
 
+            // Prints the number of modified documents and the upserted document ID, which only contains a value if an upsert was performed
             System.out.println("Modified document count: " + result.getModifiedCount());
-            System.out.println("Upserted id: " + result.getUpsertedId()); // only contains a value when an upsert is performed
+            System.out.println("Upserted id: " + result.getUpsertedId());
 
+        // Prints a message if an error occurs during the operation
         } catch (MongoException me) {
             System.err.println("Unable to replace due to an error: " + me);
         }

source/includes/usage-examples/code-snippets/UpdateMany.java

@@ -1,3 +1,10 @@
+/**
+ * This file demonstrates how to update multiple documents in a collection by using
+ * the Java driver.
+ * It connects to a MongoDB deployment, accesses the "sample_mflix" database, and updates
+ * documents in the "movies" collection that match a specified query.
+ */
+
 package usage.examples;
 
 import static com.mongodb.client.model.Filters.gt;
@@ -20,21 +27,24 @@ public static void main(String[] args) {
         String uri = "<connection string uri>";
 
         try (MongoClient mongoClient = MongoClients.create(uri)) {
-
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
             Bson query = gt("num_mflix_comments", 50);
 
+            // Creates instructions to update documents
             Bson updates = Updates.combine(
                     Updates.addToSet("genres", "Frequently Discussed"),
                     Updates.currentTimestamp("lastUpdated"));
 
             try {
+                // Runs a write operation that updates the matching documents
                 UpdateResult result = collection.updateMany(query, updates);
 
+                // Prints the number of updated documents
                 System.out.println("Modified document count: " + result.getModifiedCount());
 
+            // Prints a message if an error occurs during the operation
             } catch (MongoException me) {
                 System.err.println("Unable to update due to an error: " + me);
             }

source/includes/usage-examples/code-snippets/UpdateOne.java

@@ -1,3 +1,10 @@
+/**
+ * This file demonstrates how to update a document in a collection by using
+ * the Java driver.
+ * It connects to a MongoDB deployment, accesses the "sample_mflix" database, and
+ * updates a document in the "movies" collection that matches a specified query.
+ */
+
 package usage.examples;
 
 import org.bson.Document;
@@ -19,25 +26,29 @@ public static void main(String[] args) {
         String uri = "<connection string uri>";
 
         try (MongoClient mongoClient = MongoClients.create(uri)) {
-
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
             Document query = new Document().append("title",  "Cool Runnings 2");
 
+            // Creates instructions to update a document
             Bson updates = 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 {
+                // Runs a write operation that updates the matching document
                 UpdateResult result = collection.updateOne(query, updates, options);
 
+                // Prints the number of updated documents and the upserted document ID
                 System.out.println("Modified document count: " + result.getModifiedCount());
-
-                System.out.println("Upserted id: " + result.getUpsertedId()); // only contains a value when an upsert is performed
+                System.out.println("Upserted id: " + result.getUpsertedId());
+
+            // Prints a message if an error occurs during the operation
             } catch (MongoException me) {
                 System.err.println("Unable to update due to an error: " + me);
             }

source/includes/usage-examples/code-snippets/Watch.java

@@ -1,5 +1,15 @@
+/**
+ * This file demonstrates how to open a change stream by using the Java driver.
+ * It connects to a MongoDB deployment, accesses the "sample_mflix" database, and listens
+ * to change events in the "movies" collection. The code uses a change stream with a pipeline
+ * to only filter for "insert" and "update" events.
+ */
+
 package usage.examples;
 
+import java.util.Arrays;
+import java.util.List;
+
 import org.bson.Document;
 import org.bson.conversions.Bson;
 
@@ -18,18 +28,22 @@ public static void main( String[] args ) {
         String uri = "<connection string uri>";
 
         try (MongoClient mongoClient = MongoClients.create(uri)) {
-
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
+            // Creates instructions to filter for insert and update change events
             List<Bson> pipeline = Arrays.asList(
                 Aggregates.match(
                         Filters.in("operationType",
                                 Arrays.asList("insert", "update"))));
+
+            // Opens a change stream that returns the entire updated document
             ChangeStreamIterable<Document> changeStream = database.watch(pipeline)
                 .fullDocument(FullDocument.UPDATE_LOOKUP);
-            // variables referenced in a lambda must be final; final array gives us a mutable integer
+
             final int[] numberOfEvents = {0};
+
+            // Prints a message if a change event occurs until two events are received
             changeStream.forEach(event -> {
             System.out.println("Received a change to the collection: " + event);
                 if (++numberOfEvents[0] >= 2) {

source/includes/usage-examples/code-snippets/WatchCompanion.java

@@ -1,3 +1,10 @@
+/**
+ * This file performs basic CRUD operations and generates change events when run with the
+ * Watch application.
+ * It connects to a MongoDB deployment, accesses the "sample_mflix" database, and performs
+ * insert, update, and delete operations on the "movies" collection. 
+ */
+
 package usage.examples;
 
 import java.util.Arrays;
@@ -18,19 +25,23 @@ public static void main(String[] args) {
         String uri = "<connection string uri>";
 
         try (MongoClient mongoClient = MongoClients.create(uri)) {
-
             MongoDatabase database = mongoClient.getDatabase("sample_mflix");
             MongoCollection<Document> collection = database.getCollection("movies");
 
             try {
+                // Inserts a sample document into the "movies" collection and print its ID
                 InsertOneResult insertResult = collection.insertOne(new Document("test", "sample movie document"));
                 System.out.println("Success! Inserted document id: " + insertResult.getInsertedId());
 
+                // Updates the sample document and prints the number of modified documents
                 UpdateResult updateResult = collection.updateOne(new Document("test", "sample movie document"), Updates.set("field2", "sample movie document update"));
                 System.out.println("Updated " + updateResult.getModifiedCount() + " document.");
 
+                // Deletes the sample document and prints the number of deleted documents
                 DeleteResult deleteResult = collection.deleteOne(new Document("field2", "sample movie document update"));
                 System.out.println("Deleted " + deleteResult.getDeletedCount() + " document.");
+
+            // Prints a message if errors occur during the operations
             } catch (MongoException me) {
                 System.err.println("Unable to insert, update, or replace due to an error: " + me);
             }