DOCSP-33345: Java code comments pt. 4

Author: norareidy

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

@@ -14,6 +14,7 @@
 import org.bson.Document;
 
 import java.util.Arrays;
+import java.util.List;
 
 // end imports
 
@@ -24,12 +25,16 @@ public static void main(String[] args) {
         // Replace the uri string with your MongoDB deployment's connection string
         final String uri = "<connection string uri>";
 
+        // Create a client and access the "restaurants" collection in the "aggregation" database
         MongoClient mongoClient = MongoClients.create(uri);
         MongoDatabase database = mongoClient.getDatabase("aggregation");
         MongoCollection<Document> collection = database.getCollection("restaurants");
         // end connection
 
+        // Drop the collection, if it exists, to ensure the collection initally does not contain any documents
         collection.drop();
+        
+        // Insert sample restaurant documents
         // begin insert
         collection.insertMany(Arrays.asList(
             new Document("name", "Sun Bakery Trattoria").append("contact", new Document().append("phone", "386-555-0189").append("email", "[email protected]").append("location", Arrays.asList(-74.0056649, 40.7452371))).append("stars", 4).append("categories", Arrays.asList("Pizza", "Pasta", "Italian", "Coffee", "Sandwiches")),
@@ -45,6 +50,8 @@ public static void main(String[] args) {
         ));
         // end insert
 
+        // Filter for documents whose "categories" array field contains "Bakery"
+        // Then, group documents by the "stars" field and accumulate a count of distinct "stars" values
         // begin aggregation one
         collection.aggregate(
             Arrays.asList(
@@ -53,24 +60,29 @@ public static void main(String[] args) {
             )
         ).forEach(doc -> System.out.println(doc.toJson()));
         // end aggregation one
+
+        // Use the "explain()" method to see the operation's execution plans and performance statistics
         // begin aggregation three
         Document explanation = collection.aggregate(
             Arrays.asList(
-                    Aggregates.match(Filters.eq("categories", "bakery")),
+                    Aggregates.match(Filters.eq("categories", "Bakery")),
                     Aggregates.group("$stars", Accumulators.sum("count", 1))
             )
         ).explain(ExplainVerbosity.EXECUTION_STATS);
 
+        // Obtain the winning plans for aggregation stages that produce execution plans
         List<Document> stages = explanation.get("stages", List.class);
         List<String> keys = Arrays.asList("queryPlanner", "winningPlan");
 
+        // Print the JSON representation of the winning plans
         for (Document stage : stages) {
             Document cursorStage = stage.get("$cursor", Document.class);
             if (cursorStage != null) {
                 System.out.println(cursorStage.getEmbedded(keys, Document.class).toJson());
             }
         }
         // end aggregation three
+        // Use a $project stage to return the "name" field and the calculated field "firstCategory" 
         // begin aggregation two
         collection.aggregate(
             Arrays.asList(

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

@@ -30,12 +30,14 @@ public class BulkWrite {
     private BulkWrite() {
         final String uri = System.getenv("DRIVER_REF_URI");
 
+        // Create a client and access the "bulkWrite" collection in the "crudOps" database
         mongoClient = MongoClients.create(uri);
         database = mongoClient.getDatabase("crudOps");
         collection = database.getCollection("bulkWrite");
     }
 
     public static void main(String[] args) {
+        // For each operation, set up the collection, run the operation, and print the results
         BulkWrite bulkWrite = new BulkWrite();
         System.out.println("Ordered BulkWrite");
         bulkWrite.setUpCollection();
@@ -76,157 +78,207 @@ public static void main(String[] args) {
     private void insertExceptionExample() {
         // begin insertExceptionExample
         try {
+            // Create a List that will store the bulk operations
             List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
+            // Create an InsertOneModel for two documents with ID values of 1 and 3
             InsertOneModel<Document> doc1 = new InsertOneModel<>(new Document("_id", 1));
             InsertOneModel<Document> doc3 = new InsertOneModel<>(new Document("_id", 3));
 
+            // Add the InsertOneModel instances to the bulkOperations list
             bulkOperations.add(doc1);
             bulkOperations.add(doc3);
 
+            // Run the bulk operations on your collection
             collection.bulkWrite(bulkOperations); 
 
+        // Handle any exceptions that occur during the operations
         } catch (MongoBulkWriteException e){
             System.out.println("A MongoBulkWriteException occured with the following message: " + e.getMessage());
         }
         //end insertExceptionExample
     }
 
     private void bulkWriteNotOrderedExample() {
+        // Create a List that will store the bulk operations
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
-
+        // Create an InsertOneModel for a document with a "name" value of "Zaynab Omar"
         InsertOneModel<Document> insertDoc = new InsertOneModel<>(new Document("_id", 6)
                                                                 .append("name", "Zaynab Omar")
                                                                 .append("age", 37));
+
+        // Create a ReplaceOneModel for a document with a "name" value of "Sandy Kane"                                                       
         ReplaceOneModel<Document> replaceDoc = new ReplaceOneModel<>(Filters.eq("_id", 1), 
                                                 new Document("name", "Sandy Kane")
-                                                    .append("location", "Helena, MT"));                            
+                                                    .append("location", "Helena, MT")); 
+        
+        // Create an UpdateOneModel to change the "name" value of a document                                                                    
         UpdateOneModel<Document> updateDoc = new UpdateOneModel<>(Filters.eq("name", "Zaynab Omar"), 
                                                 Updates.set("name", "Zaynab Hassan"));
+        
+        // Create a DeleteManyModel that matches documents with an "age" value greater than 50                                       
         DeleteManyModel<Document> deleteDoc = new DeleteManyModel<>(Filters.gt("age", 50));
 
+        // Add each model instance to the bulkOperations list
         bulkOperations.add(insertDoc);
         bulkOperations.add(replaceDoc);
         bulkOperations.add(updateDoc);
         bulkOperations.add(deleteDoc);
 
-        
+        // Instruct the driver to execute the bulk operations in any order
         // begin bulkWriteNotOrderedExample
         BulkWriteOptions options = new BulkWriteOptions().ordered(false);
 
+        // Run the bulk operations on your collection with an options parameter
         collection.bulkWrite(bulkOperations, options); 
         //end bulkWriteNotOrderedExample
     }
 
     private void bulkWriteExample() {
+        // Create a List that will store the bulk operations
         // begin bulkWriteExample
-
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
 
+        // Create an InsertOneModel for a document with a "name" value of "Zaynab Omar"
         InsertOneModel<Document> insertDoc = new InsertOneModel<>(new Document("_id", 6)
-                                                                    .append("name", "Zaynab Omar")
-                                                                    .append("age", 37));
+                                                                .append("name", "Zaynab Omar")
+                                                                .append("age", 37));
+
+        // Create a ReplaceOneModel for a document with a "name" value of "Sandy Kane"                                                       
         ReplaceOneModel<Document> replaceDoc = new ReplaceOneModel<>(Filters.eq("_id", 1), 
-                                            new Document("name", "Sandy Kane")
-                                                .append("location", "Helena, MT"));                            
-        UpdateOneModel<Document> updateDoc = new UpdateOneModel<>(Filters.eq("name", "Zaynab Omar"),
+                                                new Document("name", "Sandy Kane")
+                                                    .append("location", "Helena, MT")); 
+        
+        // Create an UpdateOneModel to change the "name" value of a document                                                                    
+        UpdateOneModel<Document> updateDoc = new UpdateOneModel<>(Filters.eq("name", "Zaynab Omar"), 
                                                 Updates.set("name", "Zaynab Hassan"));
+        
+        // Create a DeleteManyModel that matches documents with an "age" value greater than 50                                       
         DeleteManyModel<Document> deleteDoc = new DeleteManyModel<>(Filters.gt("age", 50));
 
+        // Add each model instance to the bulkOperations list
         bulkOperations.add(insertDoc);
         bulkOperations.add(replaceDoc);
         bulkOperations.add(updateDoc);
         bulkOperations.add(deleteDoc);
 
+        // Run the bulk operations on your collection
         collection.bulkWrite(bulkOperations);               
         //end bulkWriteExample
     }
 
     private void insertDocumentsExample(){
+        // Create a List that will store the bulk operations
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
         // begin insertDocumentsExample
+        // Create an InsertOneModel for a document with a "name" value of "June Carrie"
         InsertOneModel<Document> juneDoc = new InsertOneModel<>(new Document("name", "June Carrie")
                                                                     .append("age", 17));
+
+        // Create an InsertOneModel for a document with a "name" value of "Kevin Moss"                                                            
         InsertOneModel<Document> kevinDoc = new InsertOneModel<>(new Document("name", "Kevin Moss")
                                                                     .append("age", 22));
         //end insertDocumentsExample
 
+        // Add each model instance to the bulkOperations list
         bulkOperations.add(juneDoc);
         bulkOperations.add(kevinDoc);
 
+        // Run the bulk operations on your collection
         collection.bulkWrite(bulkOperations);
     }
 
     private void replaceDocumentsExample(){
+        // Create a List that will store the bulk operations
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
+        // Create a ReplaceOneModel to replace a document with a "_id" value of 1
         // begin replaceDocumentsExample
         ReplaceOneModel<Document> celineDoc = new ReplaceOneModel<>(
                                             Filters.eq("_id", 1), 
                                             new Document("name", "Celine Stork")
                                                 .append("location", "San Diego, CA"));
         //end replaceDocumentsExample
 
+        // Add the ReplaceOneModel instance to the bulkOperations list
         bulkOperations.add(celineDoc);
 
+        // Run the replace operation on your collection
         collection.bulkWrite(bulkOperations);
     }
 
     private void updateDocumentsExample(){
+        // Create a List that will store the bulk operations
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
+        // Create an UpdateOneModel to modify a document with a "_id" value of 2
         // begin updateDocumentsExample
         UpdateOneModel<Document> updateDoc = new UpdateOneModel<>(
                                             Filters.eq("_id", 2), 
                                             Updates.set("age", 31));
         //end updateDocumentsExample
 
+        // Add the UpdateOneModel instance to the bulkOperations list
         bulkOperations.add(updateDoc);
 
+        // Run the update operation on your collection
         collection.bulkWrite(bulkOperations);
     }
 
     private void deleteDocumentsExample(){
+        // Create a List that will store the bulk operations
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
+        // Create a DeleteOneModel to delete a document with a "_id" value of 1
         // begin deleteDocumentsExample
         DeleteOneModel<Document> deleteDoc = new DeleteOneModel<>(Filters.eq("_id", 1));
         //end deleteDocumentsExample
 
+        // Add the DeleteOneModel instance to the bulkOperations list
         bulkOperations.add(deleteDoc);
 
+        // Run the delete operation on your collection
         collection.bulkWrite(bulkOperations);
     }
 
     private void preview(){
+        // Print the JSON representation of the returned documents
         collection.find().forEach(doc -> System.out.println(doc.toJson()));
     }
 
     private void setUpCollection(){
+        // Delete the collection so each operation starts with an empty collection
         collection.drop();
 
+        // Create a List that will store the bulk operations
         //begin bulkOpsList
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
         //end bulkOpsList
 
+        // Create an InsertOneModel for a document with a "name" value of "Karen Sandoval"
         InsertOneModel<Document> karen = new InsertOneModel<>(new Document("_id", 1)
                                                                 .append("name", "Karen Sandoval")
                                                                 .append("age", 31));
+
+        // Create an InsertOneModel for a document with a "name" value of "William Chin"                                                        
         InsertOneModel<Document> william = new InsertOneModel<>(new Document("_id", 2)
                                                                     .append("name", "William Chin")
                                                                     .append("age", 54));
+
+        // Create an InsertOneModel for a document with a "name" value of "Shayla Ray"                                                            
         InsertOneModel<Document> shayla = new InsertOneModel<>(new Document("_id", 8)
                                                                     .append("name", "Shayla Ray")
                                                                     .append("age", 20));
-        
+
+        // Add the model instances to the bulkOperations list
         bulkOperations.add(karen);
         bulkOperations.add(william);
         bulkOperations.add(shayla);
 
-
+        // Run the bulk operations on your collection
         collection.bulkWrite(bulkOperations);
     }
 }