Merge pull request #21 from mongodben/DOCSP-29202

(DOCSP-29202): Kotlin Builders page

Author: mongodben

examples/src/test/kotlin/BuildersTest.kt

@@ -0,0 +1,85 @@
+
+import com.mongodb.*
+import com.mongodb.client.model.Filters.*
+import com.mongodb.client.model.Projections.*
+import com.mongodb.kotlin.client.coroutine.MongoClient
+import io.github.cdimascio.dotenv.dotenv
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.runBlocking
+import org.bson.BsonObjectId
+import org.bson.Document
+import org.bson.codecs.pojo.annotations.BsonId
+import org.junit.jupiter.api.AfterAll
+import org.junit.jupiter.api.Assertions.*
+import org.junit.jupiter.api.BeforeAll
+import org.junit.jupiter.api.TestInstance
+import java.util.*
+import kotlin.test.*
+
+@TestInstance(TestInstance.Lifecycle.PER_CLASS)
+internal class BuildersTest {
+
+    // :snippet-start: user-data-class
+    data class User(
+        @BsonId
+        val id: BsonObjectId = BsonObjectId(),
+        val gender: String,
+        val age: Int,
+        val email: String,
+    )
+    // :snippet-end:
+
+    companion object {
+        val dotenv = dotenv()
+        val client = MongoClient.create(dotenv["MONGODB_CONNECTION_URI"])
+        val database = client.getDatabase("marketing")
+        val collection = database.getCollection<User>("users")
+
+        @BeforeAll
+        @JvmStatic
+        private fun beforeAll() {
+            runBlocking {
+                val users = listOf(
+                    User(BsonObjectId(), "female", 29, "[email protected]"),
+                    User(BsonObjectId(), "male", 92, "[email protected]"),
+                    User(BsonObjectId(), "female", 35, "[email protected]"),
+                )
+                collection.insertMany(users)
+            }
+        }
+
+        @AfterAll
+        @JvmStatic
+        private fun afterAll() {
+            runBlocking {
+                collection.drop()
+                client.close()
+            }
+        }
+
+    }
+
+    @Test
+    fun noBuildersTest() = runBlocking {
+        // :snippet-start: no-builders
+        data class Results(val email: String)
+
+        val filter = Document().append("gender", "female").append("age", Document().append("\$gt", 29))
+        val projection = Document().append("_id", 0).append("email", 1)
+        val results = collection.find<Results>(filter).projection(projection)
+        // :snippet-end:
+        assertEquals("[email protected]", results.first().email)
+    }
+
+    @Test
+    fun buildersTest() = runBlocking {
+        // :snippet-start: builders
+        data class Results(val email: String)
+
+        val filter = and(eq(User::gender.name, "female"), gt(User::age.name, 29))
+        val projection = fields(excludeId(), include("email"))
+        val results = collection.find<Results>(filter).projection(projection)
+        // :snippet-end:
+        assertEquals("[email protected]", results.first().email)
+    }
+}

source/examples/generated/BuildersTest.snippet.builders.kt

@@ -0,0 +1,5 @@
+data class Results(val email: String)
+
+val filter = and(eq(User::gender.name, "female"), gt(User::age.name, 29))
+val projection = fields(excludeId(), include("email"))
+val results = collection.find<Results>(filter).projection(projection)

source/examples/generated/BuildersTest.snippet.no-builders.kt

@@ -0,0 +1,5 @@
+data class Results(val email: String)
+
+val filter = Document().append("gender", "female").append("age", Document().append("\$gt", 29))
+val projection = Document().append("_id", 0).append("email", 1)
+val results = collection.find<Results>(filter).projection(projection)

source/examples/generated/BuildersTest.snippet.user-data-class.kt

@@ -0,0 +1,7 @@
+data class User(
+    @BsonId
+    val id: BsonObjectId = BsonObjectId(),
+    val gender: String,
+    val age: Int,
+    val email: String,
+)

source/fundamentals/builders.txt

@@ -7,11 +7,13 @@ Builders
 .. toctree::
 
    /fundamentals/builders/aggregates
-   /fundamentals/builders/filters
-   /fundamentals/builders/indexes
-   /fundamentals/builders/projections
-   /fundamentals/builders/sort
-   /fundamentals/builders/updates
+
+.. TODO: add these back after Must-Have phase complete
+   .. /fundamentals/builders/filters
+   .. /fundamentals/builders/indexes
+   .. /fundamentals/builders/projections
+   .. /fundamentals/builders/sort
+   .. /fundamentals/builders/updates
 
 .. contents:: On this page
    :local:
@@ -23,10 +25,10 @@ Overview
 --------
 
 This section includes guides on how to use each of the available
-builders, and demonstrates the utility the MongoDB Java driver builder classes
+builders, and demonstrates the utility the MongoDB Kotlin driver builder classes
 provide.
 
-The Java driver provides classes to simplify the process for developers
+The Kotlin driver provides classes to simplify the process for developers
 to use CRUD operations and the Aggregation API. The static utility methods allow you
 to build a query more efficiently.
 
@@ -35,11 +37,11 @@ Why Use Builders?
 
 Using the builders class, you leverage the power of:
 
-- The Java compiler and the IDE to find errors during development
+- The Kotlin compiler and the IDE to find errors during development
 - The IDE for discovery and code completion
 
-When using builders, the Java compiler and the IDE catch errors such as misspelled
-operators early on. When using the MongoDB shell or plain Java, you
+When using builders, the Kotlin compiler and the IDE catch errors such as misspelled
+operators early on. When using the MongoDB shell or plain Kotlin, you
 write operators as strings and get no visual indication of a problem,
 pushing these errors to runtime instead of compile time
 
@@ -61,6 +63,12 @@ collection with the following criteria:
 We only want their email address, so we'll ensure our query doesn't
 return data we pay bandwidth costs for but don't need.
 
+The documents in the ``users`` collection are modeled with the following data class
+in our application:
+
+.. literalinclude:: /examples/generated/BuildersTest.snippet.user-data-class.kt
+   :language: kotlin
+
 Using the MongoDB Shell
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -71,32 +79,29 @@ Using the MongoDB Shell
 Without Using Builders
 ~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: java
-
-   Bson filter = new Document().append("gender", "female").append("age", new Document().append("$gt", 29));
-   Bson projection = new Document().append("_id", 0).append("email", 1);
-   collection.find(filter).projection(projection);
+.. literalinclude:: /examples/generated/BuildersTest.snippet.no-builders.kt
+   :language: kotlin
 
 Using Builders
 ~~~~~~~~~~~~~~
 
-.. code-block:: java
+.. code-block:: kotlin
 
-   import static com.mongodb.client.model.Filters.*;
-   import static com.mongodb.client.model.Projections.*;
-   ...
+   import com.mongodb.client.model.Filters.*
+   import com.mongodb.client.model.Projections.*
 
-   Bson filter = and(eq("gender", "female"), gt("age", 29));
-   Bson projection = fields(excludeId(), include("email"));
-   collection.find(filter).projection(projection);
+.. literalinclude:: /examples/generated/BuildersTest.snippet.builders.kt
+   :language: kotlin
 
 Available Builders
 ------------------
 
-- :ref:`Filters <filters-builders>` for building query filters.
-- :ref:`Projections <projections-builders>` for building projections.
-- :ref:`Sorts <sorts-builders>` for building sort criteria.
-- :ref:`Updates <updates-builders>` for building updates.
 - :ref:`Aggregates <aggregates-builders>` for building aggregation pipelines.
-- :ref:`Indexes <indexes-builders>` for creating index keys.
+
+.. TODO: add these back after Must-Have phase complete
+.. - :ref:`Filters <filters-builders>` for building query filters.
+.. - :ref:`Projections <projections-builders>` for building projections.
+.. - :ref:`Sorts <sorts-builders>` for building sort criteria.
+.. - :ref:`Updates <updates-builders>` for building updates.
+.. - :ref:`Indexes <indexes-builders>` for creating index keys.