Adding extension methods for Sorts

Author: nhachicha

config/spotbugs/exclude.xml

@@ -241,6 +241,12 @@
         <Method name="~ascending|descending|geo2dsphere"/>
         <Bug pattern="BC_BAD_CAST_TO_ABSTRACT_COLLECTION"/>
     </Match>
+    <Match>
+        <!-- MongoDB status: "False Positive", SpotBugs rank: 17 -->
+        <Class name="com.mongodb.kotlin.client.model.Sorts"/>
+        <Method name="~ascending|descending"/>
+        <Bug pattern="BC_BAD_CAST_TO_ABSTRACT_COLLECTION"/>
+    </Match>
 
     <!-- Spotbugs reports false positives for suspendable operations with default params
          see: https://github.com/Kotlin/kotlinx.coroutines/issues/3099

driver-kotlin-extensions/src/main/kotlin/com/mongodb/kotlin/client/model/Sorts.kt

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ * Copyright (C) 2016/2022 Litote
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @custom-license-header
+ */
+package com.mongodb.kotlin.client.model
+
+import com.mongodb.client.model.Sorts
+import kotlin.reflect.KProperty
+import org.bson.conversions.Bson
+
+/**
+ * Sorts extension methods to improve Kotlin interop
+ *
+ * @since 5.3
+ */
+public object Sorts {
+
+    /**
+     * Create a sort specification for an ascending sort on the given properties.
+     *
+     * @param properties the properties, which must contain at least one
+     * @return the sort specification @mongodb.driver.manual reference/operator/meta/orderby Sort
+     */
+    public fun ascending(vararg properties: KProperty<*>): Bson = ascending(properties.asList())
+
+    /**
+     * Create a sort specification for an ascending sort on the given properties.
+     *
+     * @param properties the properties, which must contain at least one
+     * @return the sort specification @mongodb.driver.manual reference/operator/meta/orderby Sort
+     */
+    public fun ascending(properties: List<KProperty<*>>): Bson = Sorts.ascending(properties.map { it.path() })
+
+    /**
+     * Create a sort specification for a descending sort on the given properties.
+     *
+     * @param properties the properties, which must contain at least one
+     * @return the sort specification @mongodb.driver.manual reference/operator/meta/orderby Sort
+     */
+    public fun descending(vararg properties: KProperty<*>): Bson = descending(properties.asList())
+
+    /**
+     * Create a sort specification for a descending sort on the given properties.
+     *
+     * @param properties the properties, which must contain at least one
+     * @return the sort specification @mongodb.driver.manual reference/operator/meta/orderby Sort
+     */
+    public fun descending(properties: List<KProperty<*>>): Bson = Sorts.descending(properties.map { it.path() })
+
+    /**
+     * Create a sort specification for the text score meta projection on the given property.
+     *
+     * @param property the data class property
+     * @return the sort specification @mongodb.driver.manual reference/operator/getProjection/meta/#sort textScore
+     */
+    public fun <T> metaTextScore(property: KProperty<T>): Bson = Sorts.metaTextScore(property.path())
+}

driver-kotlin-extensions/src/test/kotlin/com/mongodb/kotlin/client/model/ExtensionsApiTest.kt

@@ -56,6 +56,15 @@ class ExtensionsApiTest {
         assertTrue(notImplemented.isEmpty(), "Some possible Indexes were not implemented: $notImplemented")
     }
 
+    @Test
+    fun shouldHaveAllSortsExtensions() {
+        val kotlinExtensions: Set<String> = getKotlinExtensions("Sorts")
+        val javaMethods: Set<String> = getJavaMethods("Sorts")
+
+        val notImplemented = javaMethods subtract kotlinExtensions
+        assertTrue(notImplemented.isEmpty(), "Some possible Sorts were not implemented: $notImplemented")
+    }
+
     private fun getKotlinExtensions(className: String): Set<String> {
         return ClassGraph()
             .enableClassInfo()

driver-kotlin-extensions/src/test/kotlin/com/mongodb/kotlin/client/model/SortsTest.kt

@@ -0,0 +1,73 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ * Copyright (C) 2016/2022 Litote
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @custom-license-header
+ */
+package com.mongodb.kotlin.client.model
+
+import com.mongodb.client.model.Sorts.orderBy
+import com.mongodb.kotlin.client.model.Sorts.ascending
+import com.mongodb.kotlin.client.model.Sorts.descending
+import com.mongodb.kotlin.client.model.Sorts.metaTextScore
+import kotlin.test.assertEquals
+import org.bson.BsonDocument
+import org.bson.conversions.Bson
+import org.junit.Test
+
+class SortsTest {
+
+    @Test
+    fun ascending() {
+        assertEquals(""" {name : 1}  """, ascending(Person::name))
+        assertEquals(""" {name : 1, age: 1}  """, ascending(Person::name, Person::age))
+        assertEquals(""" {name : 1, age: 1}  """, ascending(listOf(Person::name, Person::age)))
+    }
+
+    @Test
+    fun descending() {
+        assertEquals(""" {name : -1}  """, descending(Person::name))
+        assertEquals(""" {name : -1, age: -1}  """, descending(Person::name, Person::age))
+        assertEquals(""" {name : -1, age: -1}  """, descending(listOf(Person::name, Person::age)))
+    }
+
+    @Test
+    fun metaTextScore() {
+        assertEquals(""" {name : {${'$'}meta : "textScore"}}  """, metaTextScore(Person::name))
+    }
+
+    @Test
+    fun orderBy() {
+        assertEquals(""" {name : 1, age : -1}  """, orderBy(ascending(Person::name), descending(Person::age)))
+        assertEquals(""" {name : 1, age : -1}  """, orderBy(listOf(ascending(Person::name), descending(Person::age))))
+        assertEquals(
+            """ {name : -1, age : -1}  """,
+            orderBy(ascending(Person::name), descending(Person::age), descending(Person::name)))
+        assertEquals(
+            """ {name : 1, age : 1, results: -1, address: -1}  """,
+            orderBy(ascending(Person::name, Person::age), descending(Person::results, Person::address)))
+    }
+
+    @Test
+    fun `should create string representation for compound sorts`() {
+        assertEquals(
+            """Compound Sort{sorts=[{"name": 1, "age": 1}, {"results": -1, "address": -1}]}""",
+            orderBy(ascending(Person::name, Person::age), descending(Person::results, Person::address)).toString())
+    }
+
+    private data class Person(val name: String, val age: Int, val address: List<String>, val results: List<Int>)
+    private fun assertEquals(expected: String, result: Bson) =
+        assertEquals(BsonDocument.parse(expected), result.toBsonDocument())
+}