DOCSP-33345: Java comments pt. 4

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
 
@@ -30,6 +31,8 @@ public static void main(String[] args) {
         // end connection
 
         collection.drop();
+
+        // Inserts sample documents describing restaurants
         // 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 +48,7 @@ public static void main(String[] args) {
         ));
         // end insert
 
+        // Groups matching documents by the "stars" field and accumulates a count of distinct "stars" values
         // begin aggregation one
         collection.aggregate(
             Arrays.asList(
@@ -53,24 +57,28 @@ public static void main(String[] args) {
             )
         ).forEach(doc -> System.out.println(doc.toJson()));
         // end aggregation one
+
+        // Outputs the operation's winning and rejected execution plans
         // 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);
 
         List<Document> stages = explanation.get("stages", List.class);
         List<String> keys = Arrays.asList("queryPlanner", "winningPlan");
 
+        // Prints the JSON representation of the winning execution 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
+        // Prints the documents' "name" values and the values of a new "firstCategory" field
         // begin aggregation two
         collection.aggregate(
             Arrays.asList(

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

@@ -77,15 +77,16 @@ private void insertExceptionExample() {
         // begin insertExceptionExample
         try {
             List<WriteModel<Document>> bulkOperations = new ArrayList<>();
-
             InsertOneModel<Document> doc1 = new InsertOneModel<>(new Document("_id", 1));
             InsertOneModel<Document> doc3 = new InsertOneModel<>(new Document("_id", 3));
 
             bulkOperations.add(doc1);
             bulkOperations.add(doc3);
 
+            // Runs write operations on the insert WriteModels
             collection.bulkWrite(bulkOperations); 
 
+        // Prints a message if any exceptions occur during the operations
         } catch (MongoBulkWriteException e){
             System.out.println("A MongoBulkWriteException occured with the following message: " + e.getMessage());
         }
@@ -95,74 +96,90 @@ private void insertExceptionExample() {
     private void bulkWriteNotOrderedExample() {
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
-
+        // Creates instructions to insert a new document
         InsertOneModel<Document> insertDoc = new InsertOneModel<>(new Document("_id", 6)
                                                                 .append("name", "Zaynab Omar")
                                                                 .append("age", 37));
+
+        // Creates instructions to replace the matching document
         ReplaceOneModel<Document> replaceDoc = new ReplaceOneModel<>(Filters.eq("_id", 1), 
                                                 new Document("name", "Sandy Kane")
-                                                    .append("location", "Helena, MT"));                            
+                                                    .append("location", "Helena, MT")); 
+
+        // Creates instructions to update the matching document
         UpdateOneModel<Document> updateDoc = new UpdateOneModel<>(Filters.eq("name", "Zaynab Omar"), 
                                                 Updates.set("name", "Zaynab Hassan"));
+
+        // Creates instructions to delete the matching document  
         DeleteManyModel<Document> deleteDoc = new DeleteManyModel<>(Filters.gt("age", 50));
 
         bulkOperations.add(insertDoc);
         bulkOperations.add(replaceDoc);
         bulkOperations.add(updateDoc);
         bulkOperations.add(deleteDoc);
 
-
         // begin bulkWriteNotOrderedExample
         BulkWriteOptions options = new BulkWriteOptions().ordered(false);
 
+        // Runs write operations on the insert, replace, update, and delete WriteModels in any order
         collection.bulkWrite(bulkOperations, options); 
         //end bulkWriteNotOrderedExample
     }
 
     private void bulkWriteExample() {
         // begin bulkWriteExample
-
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
-
+        // Creates instructions to insert a new document
         InsertOneModel<Document> insertDoc = new InsertOneModel<>(new Document("_id", 6)
-                                                                    .append("name", "Zaynab Omar")
-                                                                    .append("age", 37));
+                                                                .append("name", "Zaynab Omar")
+                                                                .append("age", 37));
+
+        // Creates instructions to replace the matching document                                            
         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")); 
+
+        // Creates instructions to update the matching document                                                                 
+        UpdateOneModel<Document> updateDoc = new UpdateOneModel<>(Filters.eq("name", "Zaynab Omar"), 
                                                 Updates.set("name", "Zaynab Hassan"));
+
+        // Creates instructions to delete the matching document                                    
         DeleteManyModel<Document> deleteDoc = new DeleteManyModel<>(Filters.gt("age", 50));
 
         bulkOperations.add(insertDoc);
         bulkOperations.add(replaceDoc);
         bulkOperations.add(updateDoc);
         bulkOperations.add(deleteDoc);
 
+        // Runs write operations on the insert, replace, update, and delete WriteModels in order
         collection.bulkWrite(bulkOperations);               
         //end bulkWriteExample
     }
 
     private void insertDocumentsExample(){
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
+        // Creates instructions to insert two new documents
         // begin insertDocumentsExample
         InsertOneModel<Document> juneDoc = new InsertOneModel<>(new Document("name", "June Carrie")
                                                                     .append("age", 17));
+
         InsertOneModel<Document> kevinDoc = new InsertOneModel<>(new Document("name", "Kevin Moss")
                                                                     .append("age", 22));
         //end insertDocumentsExample
 
         bulkOperations.add(juneDoc);
         bulkOperations.add(kevinDoc);
 
+        // Runs write operations on the insert WriteModels
         collection.bulkWrite(bulkOperations);
     }
 
     private void replaceDocumentsExample(){
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
+        // Creates instructions to replace the matching document
         // begin replaceDocumentsExample
         ReplaceOneModel<Document> celineDoc = new ReplaceOneModel<>(
                                             Filters.eq("_id", 1), 
@@ -172,12 +189,14 @@ private void replaceDocumentsExample(){
 
         bulkOperations.add(celineDoc);
 
+        // Runs the write operation on the replace WriteModel
         collection.bulkWrite(bulkOperations);
     }
 
     private void updateDocumentsExample(){
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
+        // Creates instructions to update the matching document
         // begin updateDocumentsExample
         UpdateOneModel<Document> updateDoc = new UpdateOneModel<>(
                                             Filters.eq("_id", 2), 
@@ -186,22 +205,26 @@ private void updateDocumentsExample(){
 
         bulkOperations.add(updateDoc);
 
+        // Runs the write operation on the update WriteModel
         collection.bulkWrite(bulkOperations);
     }
 
     private void deleteDocumentsExample(){
         List<WriteModel<Document>> bulkOperations = new ArrayList<>();
 
+        // Creates instructions to delete the matching document
         // begin deleteDocumentsExample
         DeleteOneModel<Document> deleteDoc = new DeleteOneModel<>(Filters.eq("_id", 1));
         //end deleteDocumentsExample
 
         bulkOperations.add(deleteDoc);
 
+        // Runs the write operation on the delete WriteModel
         collection.bulkWrite(bulkOperations);
     }
 
     private void preview(){
+        // Prints the JSON representation of each document in the collection
         collection.find().forEach(doc -> System.out.println(doc.toJson()));
     }
 
@@ -215,18 +238,19 @@ private void setUpCollection(){
         InsertOneModel<Document> karen = new InsertOneModel<>(new Document("_id", 1)
                                                                 .append("name", "Karen Sandoval")
                                                                 .append("age", 31));
+
         InsertOneModel<Document> william = new InsertOneModel<>(new Document("_id", 2)
                                                                     .append("name", "William Chin")
                                                                     .append("age", 54));
+
         InsertOneModel<Document> shayla = new InsertOneModel<>(new Document("_id", 8)
                                                                     .append("name", "Shayla Ray")
                                                                     .append("age", 20));
-        
+
         bulkOperations.add(karen);
         bulkOperations.add(william);
         bulkOperations.add(shayla);
 
-
         collection.bulkWrite(bulkOperations);
     }
 }