(DOCSP-29219): CRUD > Insert Operations page (#11)

* (DOCSP-29219): CRUD > Insert page

* Update tests

* Fix failing InsertManyTest

* Apply tech review feedback

* Apply initiial internal review feedback

* Refactor tests

* Refactor to use only one data class

* add io block

* Convert to Flow.collect { }

Author: cbullinger

examples/build.gradle.kts

@@ -15,6 +15,7 @@ dependencies {
     testImplementation(kotlin("test"))
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.0-Beta")
     implementation("org.mongodb:mongodb-driver-kotlin-coroutine:4.10.0-SNAPSHOT")
+    implementation("org.mongodb:mongodb-driver-core:4.10.0-SNAPSHOT")
     implementation("org.slf4j:slf4j-api:1.7.32")
     implementation("ch.qos.logback:logback-classic:1.2.6")
     implementation("io.github.cdimascio:dotenv-kotlin:6.4.1")

examples/src/test/kotlin/InsertTest.kt

@@ -0,0 +1,95 @@
+
+
+import com.mongodb.MongoBulkWriteException
+import com.mongodb.kotlin.client.coroutine.MongoClient
+import io.github.cdimascio.dotenv.dotenv
+import kotlinx.coroutines.flow.toList
+import kotlinx.coroutines.runBlocking
+import org.bson.codecs.pojo.annotations.BsonId
+import org.bson.types.ObjectId
+import org.junit.jupiter.api.AfterAll
+import org.junit.jupiter.api.Assertions.*
+import org.junit.jupiter.api.TestInstance
+import java.util.*
+import kotlin.test.*
+
+// :snippet-start: data-model
+data class PaintOrder(
+    @BsonId val id: ObjectId? = null,
+    val qty: Int,
+    val color: String
+)
+// :snippet-end:
+
+@TestInstance(TestInstance.Lifecycle.PER_CLASS)
+internal class InsertTest {
+
+    companion object {
+        val dotenv = dotenv()
+        val client = MongoClient.create(dotenv["MONGODB_CONNECTION_URI"])
+        val database = client.getDatabase("paint_store")
+        val collection = database.getCollection<PaintOrder>("paint_order")
+
+        @AfterAll
+        @JvmStatic
+        private fun afterAll() {
+            runBlocking {
+                client.close()
+            }
+        }
+    }
+    @Test
+    fun insertManyErrorTest() = runBlocking {
+        val paintOrders = listOf(
+            PaintOrder(ObjectId(), 5, "red"),
+            PaintOrder(ObjectId(), 10, "purple"),
+            PaintOrder(ObjectId(), 3, "yellow"),
+            PaintOrder(ObjectId(), 8, "blue")
+        )
+        // :snippet-start: insert-many-error
+        val result = collection.insertMany(paintOrders)
+        try {
+            println("Inserted documents with the following ids: ${result.insertedIds}")
+        } catch(e: MongoBulkWriteException){
+            val insertedIds = e.writeResult.inserts.map { it.id.asInt32().value }
+            println(
+                "A MongoBulkWriteException occurred, but there are " +
+                "successfully processed documents with the following ids: $insertedIds"
+            )
+            collection.find().collect { println(it) }
+        }
+        // :snippet-end:
+        //Junit test for the above code
+        assertTrue(result.wasAcknowledged())
+    }
+
+    @Test
+    fun insertOneTest() = runBlocking {
+        // :snippet-start: insert-one
+        val paintOrder = PaintOrder(ObjectId(), 5, "red")
+        val result = collection.insertOne(paintOrder)
+
+        val insertedId = result.insertedId?.asObjectId()?.value
+
+        println("Inserted a document with the following id: $insertedId")
+        // :snippet-end:
+        // Junit test for the above code
+        assertTrue(result.wasAcknowledged())
+    }
+
+    @Test
+    fun insertManyTest() = runBlocking {
+        // :snippet-start: insert-many
+        val paintOrders = listOf(
+            PaintOrder(ObjectId(), 5, "red"),
+            PaintOrder(ObjectId(), 10, "purple")
+        )
+        val result = collection.insertMany(paintOrders)
+
+        println("Inserted a document with the following ids: ${result.insertedIds.toList()}")
+        // :snippet-end:
+        // Junit test for the above code
+        assertTrue(result.wasAcknowledged())
+    }
+}
+

source/examples/generated/InsertTest.snippet.data-model.kt

@@ -0,0 +1,5 @@
+data class PaintOrder(
+    @BsonId val id: ObjectId? = null,
+    val qty: Int,
+    val color: String
+)

source/examples/generated/InsertTest.snippet.insert-many-error.kt

@@ -0,0 +1,11 @@
+val result = collection.insertMany(paintOrders)
+try {
+    println("Inserted documents with the following ids: ${result.insertedIds}")
+} catch(e: MongoBulkWriteException){
+    val insertedIds = e.writeResult.inserts.map { it.id.asInt32().value }
+    println(
+        "A MongoBulkWriteException occurred, but there are " +
+        "successfully processed documents with the following ids: $insertedIds"
+    )
+    collection.find().collect { println(it) }
+}

source/examples/generated/InsertTest.snippet.insert-many.kt

@@ -0,0 +1,7 @@
+val paintOrders = listOf(
+    PaintOrder(ObjectId(), 5, "red"),
+    PaintOrder(ObjectId(), 10, "purple")
+)
+val result = collection.insertMany(paintOrders)
+
+println("Inserted a document with the following ids: ${result.insertedIds.toList()}")

source/examples/generated/InsertTest.snippet.insert-one.kt

@@ -0,0 +1,6 @@
+val paintOrder = PaintOrder(ObjectId(), 5, "red")
+val result = collection.insertOne(paintOrder)
+
+val insertedId = result.insertedId?.asObjectId()?.value
+
+println("Inserted a document with the following id: $insertedId")

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

@@ -15,7 +15,7 @@ Insert Operations
 Overview
 --------
 
-In this guide, you can learn how to insert documents with the MongoDB Java
+In this guide, you can learn how to insert documents with the MongoDB Kotlin
 driver. 
 
 You can use MongoDB to retrieve, update, and delete information. To
@@ -32,6 +32,12 @@ The following sections focus on ``insertOne()`` and
 method, see our
 :doc:`guide on Bulk Operations </fundamentals/crud/write-operations/bulk/>`. 
 
+In the following examples, a paint store has an inventory of different colors
+of paint. This data is modeled with the following Kotlin data class:
+
+.. literalinclude:: /examples/generated/InsertTest.snippet.data-model.kt
+   :language: kotlin
+
 A Note About ``_id``
 --------------------
 
@@ -70,24 +76,21 @@ Example
 The following example creates and inserts a document using the
 ``insertOne()`` method: 
 
-.. literalinclude:: /includes/fundamentals/code-snippets/Insert.java
-   :language: java
-   :dedent:
-   :start-after: begin insertOneExample
-   :end-before: end insertOneExample
-
-Your output should look something like this:
+.. io-code-block::
+   
+      .. input:: /examples/generated/InsertTest.snippet.insert-one.kt
+         :language: kotlin
 
-.. code-block:: none
-   :copyable: false
+      .. output:: 
+         :language: console
 
-   Inserted a document with the following id: 60930c39a982931c20ef6cd6
+         Inserted a document with the following id: 60930c39a982931c20ef6cd6
 
 For more information about the methods and classes mentioned in this section,
 see the following resources: 
 
-- `insertOne() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#insertOne(TDocument)>`__ API Documentation
-- `InsertOneResult <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/result/InsertOneResult.html>`__ API Documentation
+- `insertOne() <TODO:(DOCSP-29169)>`__ API Documentation
+- `InsertOneResult <TODO:(DOCSP-29169)>`__ API Documentation
 - Manual Explanation on :manual:`insertOne() </reference/method/db.collection.insertOne/>`
 - Runnable :doc:`Insert a Document Example </usage-examples/insertOne>` 
 
@@ -102,10 +105,10 @@ For example, assume you want to insert the following documents:
 
 .. code-block:: json
 
-   { "_id": 3, "color": "red", "qty": 5 }
-   { "_id": 4, "color": "purple", "qty": 10 }
-   { "_id": 3, "color": "yellow", "qty": 3 }
-   { "_id": 6, "color": "blue", "qty": 8 }
+   { "color": "red", "qty": 5 }
+   { "color": "purple", "qty": 10 }
+   { "color": "yellow", "qty": 3 }
+   { "color": "blue", "qty": 8 }
 
 If you attempt to insert these documents, a ``WriteError`` occurs at the
 third document and the documents prior to the error get inserted into
@@ -114,30 +117,28 @@ your collection.
 .. tip::
 
    Use a try-catch block to get an acknowledgment for successfully
-   processed documents before the error occurs:
+   processed documents before the error occurs. The output consists of 
+   documents MongoDB can process:
 
-   .. literalinclude:: /includes/fundamentals/code-snippets/Insert.java
-      :language: java
-      :dedent:
-      :start-after: begin insertManyErrorExample
-      :end-before: end insertManyErrorExample
+   .. io-code-block::
+   
+      .. input:: /examples/generated/InsertTest.snippet.insert-many-error.kt
+         :language: kotlin
 
-   The output consists of documents MongoDB can process and should look
-   something like this:
+      .. output:: 
+         :language: console
 
-   .. code-block:: 
-      :copyable: false
-      
-      A MongoBulkWriteException occurred, but there are successfully processed 
-      documents with the following ids: [3, 4, 6] 
+         A MongoBulkWriteException occurred, but there are successfully processed 
+         documents with the following ids: [60930c3aa982931c20ef6cd7, 644ad1378ea29443837a14e9, 60930c3aa982931c20ef6cd8]
+ 
 
    If you look inside your collection, you should see the following documents:
 
    .. code-block:: json
       :copyable: false
 
-      { "_id": 3, "color": "red", "qty": 5 }
-      { "_id": 4, "color": "purple", "qty": 10 }
+      { "color": "red", "qty": 5 }
+      { "color": "purple", "qty": 10 }
 
 On successful insertion, the method returns an ``InsertManyResult``
 instance representing the ``_id`` of each new document. 
@@ -148,24 +149,21 @@ Example
 The following example creates and adds two documents to a ``List``, and
 inserts the ``List`` using the ``insertMany()`` method: 
 
-.. literalinclude:: /includes/fundamentals/code-snippets/Insert.java
-   :language: java
-   :dedent:
-   :start-after: begin insertManyExample
-   :end-before: end insertManyExample
-
-Your output should look something like this:
+.. io-code-block::
+   
+   .. input:: /examples/generated/InsertTest.snippet.insert-many.kt
+      :language: kotlin
 
-.. code-block::
-   :copyable: false
+   .. output:: 
+      :language: console
 
-   Inserted documents with the following ids: [60930c3aa982931c20ef6cd7, 60930c3aa982931c20ef6cd8] 
+      Inserted documents with the following ids: [60930c3aa982931c20ef6cd7, 60930c3aa982931c20ef6cd8] 
 
 For more information about the methods and classes mentioned in this section,
 see the following resources: 
 
-- `insertMany() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#insertMany(java.util.List)>`__ API Documentation
-- `InsertManyResult <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/result/InsertManyResult.html>`__ API Documentation
+- `insertMany() <TODO:(DOCSP-29169)>`__ API Documentation
+- `InsertManyResult <TODO:(DOCSP-29169)>`__ API Documentation
 - Manual Explanation on :manual:`insertMany() </reference/method/db.collection.insertMany/>`
 - Runnable :doc:`Insert Multiple Documents Example </usage-examples/insertMany>`