Helper methods and extensions to improve kotlin interop. (#1478)

Adds a new package `org.mongodb.mongodb-driver-kotlin-extensions`. Its both, kotlin driver and bson kotlin implementation agnostic. Can be used with any combination of `bson-kotlin`, `bson-kotlinx`, `mongodb-driver-kotlin-sync` and `mongodb-driver-kotlin-coroutine`.

Initial Filters extensions support, with both inflix and nested helpers eg:

```
import com.mongodb.kotlin.client.model.Filters.eq

// infix
Person::name.eq(person.name)

// nested
val bson = eq(Person::name, person.name)
```

Also adds path based support which works with vairous annotations on the data class: `@SerialName("_id")`, `@BsonId`, `@BsonProperty("_id")`:

```
(Restaurant::reviews / Review::score).path() == "reviews.rating"
```

JAVA-5308 JAVA-5484

Author: rozza

Diff for: THIRD-PARTY-NOTICES

@@ -161,3 +161,26 @@ https://github.com/mongodb/mongo-java-driver.
     See the License for the specific language governing permissions and
     limitations under the License.
 
+8) The following files (originally from https://github.com/Litote/kmongo):
+
+    Filters.kt
+    Properties.kt
+    KPropertyPath.kt
+    FiltersTest.kt
+    KPropertiesTest.kt
+
+    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.
+

Diff for: config/spotbugs/exclude.xml

@@ -223,6 +223,12 @@
         <Method name="~.*validateAnnotations.*"/>
         <Bug pattern="BC_BAD_CAST_TO_ABSTRACT_COLLECTION"/>
     </Match>
+    <Match>
+        <!-- MongoDB status: "False Positive", SpotBugs rank: 17 -->
+        <Class name="com.mongodb.kotlin.client.model.PropertiesKt$path$1"/>
+        <Method name="~.*invoke.*"/>
+        <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

Diff for: driver-kotlin-extensions/build.gradle.kts

@@ -0,0 +1,163 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * 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.
+ */
+import io.gitlab.arturbosch.detekt.Detekt
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+
+plugins {
+    id("org.jetbrains.kotlin.jvm")
+    `java-library`
+
+    // Test based plugins
+    id("com.diffplug.spotless")
+    id("org.jetbrains.dokka")
+    id("io.gitlab.arturbosch.detekt")
+}
+
+repositories {
+    mavenCentral()
+    google()
+}
+
+base.archivesName.set("mongodb-driver-kotlin-extensions")
+
+description = "The MongoDB Kotlin Driver Extensions"
+
+ext.set("pomName", "MongoDB Kotlin Driver Extensions")
+
+dependencies {
+    // Align versions of all Kotlin components
+    implementation(platform("org.jetbrains.kotlin:kotlin-bom"))
+    implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8")
+
+    api(project(path = ":driver-core", configuration = "default"))
+
+    testImplementation("org.jetbrains.kotlin:kotlin-reflect")
+    testImplementation("org.jetbrains.kotlin:kotlin-test-junit")
+    testImplementation("org.assertj:assertj-core:3.24.2")
+    testImplementation("io.github.classgraph:classgraph:4.8.154")
+}
+
+kotlin { explicitApi() }
+
+tasks.withType<KotlinCompile> {
+    kotlinOptions {
+        jvmTarget = "1.8"
+        freeCompilerArgs =
+            listOf(
+                // Adds OnlyInputTypes support
+                "-Xallow-kotlin-package",
+            )
+    }
+}
+
+// ===========================
+//     Code Quality checks
+// ===========================
+val customLicenseHeader = "/^(?s)(?!.*@custom-license-header).*/"
+
+spotless {
+    kotlinGradle {
+        ktfmt("0.39").dropboxStyle().configure { it.setMaxWidth(120) }
+        trimTrailingWhitespace()
+        indentWithSpaces()
+        endWithNewline()
+        licenseHeaderFile(rootProject.file("config/mongodb.license"), "(group|plugins|import|buildscript|rootProject)")
+    }
+
+    kotlin {
+        target("**/*.kt")
+        ktfmt().dropboxStyle().configure { it.setMaxWidth(120) }
+        trimTrailingWhitespace()
+        indentWithSpaces()
+        endWithNewline()
+
+        licenseHeaderFile(rootProject.file("config/mongodb.license"))
+            .named("standard")
+            .onlyIfContentMatches("^(?!Copyright .*? Litote).*\$")
+    }
+
+    format("extraneous") {
+        target("*.xml", "*.yml", "*.md")
+        trimTrailingWhitespace()
+        indentWithSpaces()
+        endWithNewline()
+    }
+}
+
+tasks.named("check") { dependsOn("spotlessApply") }
+
+detekt {
+    allRules = true // fail build on any finding
+    buildUponDefaultConfig = true // preconfigure defaults
+    config = rootProject.files("config/detekt/detekt.yml") // point to your custom config defining rules to run,
+    // overwriting default behavior
+    baseline = rootProject.file("config/detekt/baseline.xml") // a way of suppressing issues before introducing detekt
+    source = files(file("src/main/kotlin"), file("src/test/kotlin"))
+}
+
+tasks.withType<Detekt>().configureEach {
+    reports {
+        html.required.set(true) // observe findings in your browser with structure and code snippets
+        xml.required.set(true) // checkstyle like format mainly for integrations like Jenkins
+        txt.required.set(false) // similar to the console output, contains issue signature to manually edit
+    }
+}
+
+spotbugs { showProgress.set(true) }
+
+// ===========================
+//     Test Configuration
+// ===========================
+
+tasks.create("kotlinCheck") {
+    description = "Runs all the kotlin checks"
+    group = "verification"
+
+    dependsOn("clean", "check")
+    tasks.findByName("check")?.mustRunAfter("clean")
+}
+
+tasks.test { useJUnitPlatform() }
+
+// ===========================
+//     Dokka Configuration
+// ===========================
+val dokkaOutputDir = "${rootProject.buildDir}/docs/${base.archivesName.get()}"
+
+tasks.dokkaHtml.configure {
+    outputDirectory.set(file(dokkaOutputDir))
+    moduleName.set(base.archivesName.get())
+}
+
+val cleanDokka by tasks.register<Delete>("cleanDokka") { delete(dokkaOutputDir) }
+
+project.parent?.tasks?.named("docs") {
+    dependsOn(tasks.dokkaHtml)
+    mustRunAfter(cleanDokka)
+}
+
+tasks.javadocJar.configure {
+    dependsOn(cleanDokka, tasks.dokkaHtml)
+    archiveClassifier.set("javadoc")
+    from(dokkaOutputDir)
+}
+
+// ===========================
+//     Sources publishing configuration
+// ===========================
+tasks.sourcesJar { from(project.sourceSets.main.map { it.kotlin }) }
+
+afterEvaluate { tasks.jar { manifest { attributes["Automatic-Module-Name"] = "org.mongodb.driver.kotlin.core" } } }