DATACMNS-1584 - Add documentation for Kotlin support.

Original Pull Request: #407

src/main/asciidoc/kotlin-coroutines.adoc

@@ -0,0 +1,53 @@
+[[kotlin.coroutines]]
+= Coroutines
+
+Kotlin https://kotlinlang.org/docs/reference/coroutines-overview.html[Coroutines] are Kotlin lightweight threads allowing to write non-blocking code imperatively.
+On language side, suspending functions provides an abstraction for asynchronous operations while on library side https://github.com/Kotlin/kotlinx.coroutines[kotlinx.coroutines] provides functions like https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/async.html[`async { }`] and types like https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html[`Flow`].
+
+Spring Data modules provide support for Coroutines on the following scope:
+
+* https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/index.html[Deferred] and https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html[Flow] return values support in Kotlin extensions
+
+[[kotlin.coroutines.dependencies]]
+== Dependencies
+
+Coroutines support is enabled when `kotlinx-coroutines-core` and `kotlinx-coroutines-reactor` dependencies are in the classpath:
+
+.Dependencies to add in Maven pom.xml
+====
+[source,xml]
+----
+<dependency>
+	<groupId>org.jetbrains.kotlinx</groupId>
+	<artifactId>kotlinx-coroutines-core</artifactId>
+</dependency>
+
+<dependency>
+	<groupId>org.jetbrains.kotlinx</groupId>
+	<artifactId>kotlinx-coroutines-reactor</artifactId>
+</dependency>
+----
+====
+
+Version `1.3.0` and above are supported.
+
+[[kotlin.coroutines.reactive]]
+== How Reactive translates to Coroutines?
+
+For return values, the translation from Reactive to Coroutines APIs is the following:
+
+* `fun handler(): Mono<Void>` becomes `suspend fun handler()`
+* `fun handler(): Mono<T>` becomes `suspend fun handler(): T` or `suspend fun handler(): T?` depending on if the `Mono` can be empty or not (with the advantage of being more statically typed)
+* `fun handler(): Flux<T>` becomes `fun handler(): Flow<T>`
+
+https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html[`Flow`] is `Flux` equivalent in Coroutines world, suitable for hot or cold stream, finite or infinite streams, with the following main differences:
+
+* `Flow` is push-based while `Flux` is push-pull hybrid
+* Backpressure is implemented via suspending functions
+* `Flow` has only a https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/collect.html[single suspending `collect` method] and operators are implemented as https://kotlinlang.org/docs/reference/extensions.html[extensions]
+* https://github.com/Kotlin/kotlinx.coroutines/tree/master/kotlinx-coroutines-core/common/src/flow/operators[Operators are easy to implement] thanks to Coroutines
+* Extensions allow adding custom operators to `Flow`
+* Collect operations are suspending functions
+* https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/map.html[`map` operator] supports asynchronous operation (no need for `flatMap`) since it takes a suspending function parameter
+
+Read this blog post about https://spring.io/blog/2019/04/12/going-reactive-with-spring-coroutines-and-kotlin-flow[Going Reactive with Spring, Coroutines and Kotlin Flow] for more details, including how to run code concurrently with Coroutines.

src/main/asciidoc/kotlin-extensions.adoc

@@ -0,0 +1,10 @@
+[[kotlin.extensions]]
+= Extensions
+
+Kotlin https://kotlinlang.org/docs/reference/extensions.html[extensions] provide the ability to extend existing classes with additional functionality. Spring Data Kotlin APIs use these extensions to add new Kotlin-specific conveniences to existing Spring APIs.
+
+NOTE: Keep in mind that Kotlin extensions need to be imported to be used.
+Similar to static imports, an IDE should automatically suggest the import in most cases.
+
+For example, https://kotlinlang.org/docs/reference/inline-functions.html#reified-type-parameters[Kotlin reified type parameters] provide a workaround for JVM https://docs.oracle.com/javase/tutorial/java/generics/erasure.html[generics type erasure], and Spring Data provides some extensions to take advantage of this feature.
+This allows for a better Kotlin API.

src/main/asciidoc/kotlin.adoc

@@ -0,0 +1,40 @@
+[[kotlin]]
+= Kotlin Support
+
+https://kotlinlang.org[Kotlin] is a statically typed language that targets the JVM (and other platforms) which allows writing concise and elegant code while providing excellent https://kotlinlang.org/docs/reference/java-interop.html[interoperability] with existing libraries written in Java.
+
+Spring Data provides first-class support for Kotlin and lets developers write Kotlin applications almost as if Spring Data was a Kotlin-native framework.
+
+The easiest way to build a Spring application with Kotlin is to leverage Spring Boot and its https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-kotlin.html[dedicated Kotlin support].
+https://spring.io/guides/tutorials/spring-boot-kotlin/[This comprehensive tutorial] will teach you how to build Spring Boot applications with Kotlin using https://start.spring.io/#!language=kotlin&type=gradle-project[start.spring.io].
+
+[[kotlin.requirements]]
+== Requirements
+
+Spring Data supports Kotlin 1.3 and requires https://bintray.com/bintray/jcenter/org.jetbrains.kotlin%3Akotlin-stdlib[`kotlin-stdlib`] (or one of its variants, such as https://bintray.com/bintray/jcenter/org.jetbrains.kotlin%3Akotlin-stdlib-jdk8[`kotlin-stdlib-jdk8`]) and https://bintray.com/bintray/jcenter/org.jetbrains.kotlin%3Akotlin-reflect[`kotlin-reflect`] to be present on the classpath.
+They are provided by default if you bootstrap a Kotlin project on https://start.spring.io/#!language=kotlin&type=gradle-project[start.spring.io].
+
+[[kotlin.null-safety]]
+== Null-safety
+
+One of Kotlin's key features is https://kotlinlang.org/docs/reference/null-safety.html[null-safety], which cleanly deals with `null` values at compile time rather than bumping into the famous `NullPointerException` at runtime.
+This makes applications safer through nullability declarations and expressing "`value or no value`" semantics without paying the cost of wrappers, such as `Optional`.
+(Kotlin allows using functional constructs with nullable values. See this https://www.baeldung.com/kotlin-null-safety[comprehensive guide to Kotlin null-safety].)
+
+Although Java does not let you express null-safety in its type-system, Spring Data API is annotated with JSR-305 tooling-friendly annotations declared in the `org.springframework.lang` package.
+By default, types from Java APIs used in Kotlin are recognized as https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types[platform types], for which null-checks are relaxed.
+https://kotlinlang.org/docs/reference/java-interop.html#jsr-305-support[Kotlin support for JSR-305 annotations] and Spring nullability annotations provide null-safety for the whole Spring Data API to Kotlin developers, with the advantage of dealing with `null`-related issues at compile time.
+
+You can configure JSR-305 checks by adding the `-Xjsr305` compiler flag with the following options: `-Xjsr305={strict|warn|ignore}`.
+
+For kotlin versions 1.1+, the default behavior is the same as `-Xjsr305=warn`.
+The `strict` value is required take Spring Data API null-safety into account. Kotlin types inferred from Spring API but should be used with the knowledge that Spring API nullability declaration could evolve, even between minor releases and that more checks may be added in the future.
+
+NOTE: Generic type arguments, varargs, and array elements nullability are not supported yet, but should be in an upcoming release.
+
+See <<repositories.nullability>> how Null-safety applies to Spring Data Repositories.
+
+[[kotlin.mapping]]
+== Object Mapping
+
+See <<mapping.kotlin>> for details on how Kotlin objects are materialized.

src/main/asciidoc/object-mapping.adoc

@@ -217,6 +217,7 @@ It's an established pattern to rather use static factory methods to expose these
 * _For identifiers to be generated, still use a final field in combination with a wither method_ --
 * _Use Lombok to avoid boilerplate code_ -- As persistence operations usually require a constructor taking all arguments, their declaration becomes a tedious repetition of boilerplate parameter to field assignments that can best be avoided by using Lombok's `@AllArgsConstructor`.
 
+[[mapping.kotlin]]
 == Kotlin support
 
 Spring Data adapts specifics of Kotlin to allow object creation and mutation.