Support Kotlin 1.4.0 or later (#565)

* Improve Kotlin documentation

* Improve Doma introduction

Author: nakamura-to

README.md

@@ -5,9 +5,9 @@ Doma 2 is a database access framework for Java 8+.
 Doma has various strengths:
 
 - Verifies and generates source code **at compile time** using [annotation processing][apt].
-- Maps database columns to user-defined Java objects.
-- Uses SQL templates, called “two-way SQL”.
-- Supports classes introduced in Java 8, such as `java.time.LocalDate`, `java.util.Optional`, and `java.util.stream.Stream`.
+- Provides type-safe Criteria API.
+- Supports Kotlin.
+- Uses SQL templates, called "two-way SQL".
 - Has no dependence on other libraries.
 
 [![Build Status](https://github.com/domaframework/doma/workflows/Java%20CI%20with%20Gradle/badge.svg)](https://github.com/domaframework/doma/actions?query=workflow%3A%22Java+CI+with+Gradle%22)
@@ -20,47 +20,74 @@ Doma has various strengths:
 Examples
 ---------------------
 
-Define an entity class:
+## type-safe Criteria API
+
+Written in Java 8:
+
 ```java
-@Entity
-public class Employee {
-    @Id
-    @GeneratedValue(strategy = GenerationType.SEQUENCE)
-    @SequenceGenerator(sequence = "EMPLOYEE_SEQ")
-    public Integer id;
-    public String name;
-    public Integer age;
-    @Version
-    public Integer version;
-}
+Entityql entityql = new Entityql(config);
+Employee_ e = new Employee_();
+Department_ d = new Department_();
+
+List<Employee> list =
+    entityql
+        .from(e)
+        .innerJoin(d, on -> on.eq(e.departmentId, d.departmentId))
+        .where(c -> c.eq(d.departmentName, "SALES"))
+        .associate(
+            e,
+            d,
+            (employee, department) -> {
+              employee.setDepartment(department);
+              department.getEmployeeList().add(employee);
+            })
+        .fetch();
+```
+
+Written in Kotlin:
+
+```kotlin
+val entityql = KEntityql(config)
+val e = Employee_()
+val d = Department_()
+
+val list = entityql
+    .from(e)
+    .innerJoin(d) { eq(e.departmentId, d.departmentId) }
+    .where { eq(d.departmentName, "SALES") }
+    .associate(e, d) { employee, department ->
+        employee.department = department
+        department.employeeList += employee
+    }
+    .fetch()
 ```
 
-Define a DAO interface:
+## two-way SQL
+
+DAO interface written in Java 8:
+
 ```java
-@Dao(config = AppConfig.class)
+@Dao
 public interface EmployeeDao {
-    @Select
-    Employee selectById(Integer id);
-    @Update
-    int update(Employee employee);
+
+  @Select
+  List<Employee> selectByExample(Employee e);
 }
 ```
 
-Execute queries:
-```java
-public class App {
-    public static void main(String[] args) {
-        TransactionManager tm = AppConfig.singleton().getTransactionManager();
-        tm.required(() -> {
-            EmployeeDao dao = new EmployeeDaoImpl();
-            Employee employee = dao.selectById(1);
-            employee.age++;
-            dao.update(employee);
-        });
-    }
-}
+selectByExample.sql:
+
+```sql
+select * from EMPLOYEE where
+/*%if e.employeeNo > 7800*/
+  /*%if e.managerId != null*/
+    salary >= /*e.salary*/9999
+  /*%end*/
+/*%end*/
 ```
 
+## Other Examples
+
 Try following getting started examples:
 - [Get started! (IntelliJ IDEA)](https://doma.readthedocs.io/en/latest/getting-started-idea/)
 - [Get started! (Eclipse)](https://doma.readthedocs.io/en/latest/getting-started-eclipse/)

docs/criteria-api.rst

@@ -8,12 +8,17 @@ Criteria API
 Introduction
 ============
 
+.. note::
+
+    In Kotlin environment, use Kotlin specific DSLs instead of the following DSLs.
+    See :ref:`kotlin-specific-criteria-api`.
+
 There are two kinds of DSLs in the Criteria API:
 
 * The Entityql DSL
 * The NativeSql DSL
 
-Both require predefined Entity classes and metamodel classes.
+Both requires predefined Entity classes and metamodel classes.
 
 We use the following Entity classes to show you some examples:
 

docs/index.rst

@@ -16,10 +16,9 @@ Doma 2 is a database access framework for Java 8+.
 Doma has various strengths:
 
 * Verifies and generates source code at compile time using annotation processing.
-* Maps database columns to user-defined Java objects.
+* Provides type-safe Criteria API.
+* Supports Kotlin.
 * Uses SQL templates, called "two-way SQL".
-* Supports classes introduced in Java 8, such as ``java.time.LocalDate``,
-  ``java.util.Optional``, and ``java.util.stream.Stream``.
 * Has no dependence on other libraries.
 
 This document consists of following sections:

docs/kotlin-support.rst

@@ -5,31 +5,40 @@ Kotlin support
 .. contents::
    :depth: 3
 
-Doma supports `Kotlin <https://kotlinlang.org/>`_ 1.3.11 or above **experimentally**.
+Doma supports `Kotlin <https://kotlinlang.org/>`_ 1.4.0 or later.
 
 Best practices
 ==============
 
-We show you recommended ways to define classes and build them with Kotlin.
+Here are some recommended methods, such as defining classes and building them with Kotlin.
 
 Entity classes
 --------------
 
-* Define as a data class
-* Specify ``true`` to the ``immutable`` element of ``@Entity``
-* Define only one constructor
-* Define properties only in the constructor
-* Use `val` for the property definitions
+* Define as a plain class
+* Specify a ``Metamodel`` annotation to the ``metamodel`` element of ``@Entity``
 
 .. code-block:: java
 
-  @Entity(immutable = true)
-  data class Person(
+    @Entity(metamodel = Metamodel())
+    class Person : AbstractPerson() {
+
         @Id
         @GeneratedValue(strategy = GenerationType.IDENTITY)
-        val id: Int? = null,
-        val name: Name,
-        val address: Address)
+        var id: Int = -1
+
+        var name: Name? = null
+
+        var age: Int? = -1
+
+        var address: Address? = null
+
+        @Column(name = "DEPARTMENT_ID")
+        var departmentId: Int = -1
+
+        @Version
+        var version: Int = -1
+    }
 
 Domain classes
 --------------
@@ -88,41 +97,94 @@ Dao interfaces
   val person = Person(name = Name("Jhon"), address = Address(city = "Tokyo", street = "Yaesu"))
   val (newPerson, count) = dao.insert(person)
 
-Using kapt in Gradle
---------------------
+.. _kotlin-specific-criteria-api:
 
-Annotation processors are supported in Kotlin with the
-`kapt <https://kotlinlang.org/docs/reference/kapt.html>`_ compiler plugin.
+Kotlin specific Criteria API
+----------------------------
 
-Add the dependencies using the `kapt` and `implementation` configuration in your dependencies block:
+.. note::
 
-.. code-block:: groovy
+    Prefer the Kotlin specific Criteria API to DAO interfaces.
 
-  dependencies {
-      implementation "org.seasar.doma:doma-core:2.41.0"
-      kapt "org.seasar.doma:doma-processor:2.41.0"
-  }
+Doma provides Kotlin specific Criteria API, ``KEntityql`` and ``KNativeQl`` DSLs.
+They are very similar with the ``Entityql`` and ``NativeQl`` DSLs, which are described in :doc:`criteria-api`.
+The biggest feature of the ``KEntityql`` and ``KNativeQl`` DSLs is simplicity.
 
-To simplify your build.script, we recommend you use
-the `Doma Compile Plugin <https://github.com/domaframework/doma-compile-plugin>`_:
+For example, when you use ``KEntityql``, you have to accept a lambda parameter in a WHERE expression as follows:
 
-.. code-block:: groovy
+.. code-block:: kotlin
 
-  plugins {
-    id 'org.seasar.doma.compile' version '1.1.0'
-  }
+    val entityql = Entityql(config)
+    val e = Employee_()
 
-For more details, see this `build.gradle <https://github.com/domaframework/kotlin-sample/blob/master/build.gradle>`_.
+    val list = entityql
+        .from(e)
+        .where { c ->
+            c.eq(e.departmentId, 2)
+            c.isNotNull(e.managerId)
+            c.or {
+                c.gt(e.salary, Salary("1000"))
+                c.lt(e.salary, Salary("2000"))
+            }
+        }
+        .fetch()
 
-.. note::
+The lambda parameter ``c`` is a bit annoying.
+On the other hand, when you use ``KEntityql``, the parameter is gone.
+
+.. code-block:: kotlin
+
+    val entityql = KEntityql(config)
+    val e = Employee_()
+
+    val list = entityql
+        .from(e)
+        .where {
+            eq(e.departmentId, 2)
+            isNotNull(e.managerId)
+            or {
+                gt(e.salary, Salary("1000"))
+                lt(e.salary, Salary("2000"))
+            }
+        }
+        .fetch()
+
+You can see a lot of sample code `here<https://github.com/domaframework/doma-it/tree/master/kotlin/src/test/kotlin/org/seasar/doma/it/criteria>`_.
+
+The ``KEntityql`` and ``KNativeQl`` DSLs are included in doma-kotlin.jar.
+Note that you should depend on doma-kotlin instead of doma-core in your build script.
+You can write build.gradle.kts as follows:
+
+.. code-block:: kotlin
+
+    dependencies {
+        implementation("org.seasar.doma:doma-kotlin:2.41.0")
+    }
+
+Code Generation
+---------------
 
-    Remember that you always have options as follows:
+Use `Doma CodeGen Plugin <https://github.com/domaframework/doma-codegen-plugin>`_.
+This plugin support Kotlin code generation.
 
-    - Write all code in Kotlin
-    - Write all code in Java
-    - Write code annotated with Doma's annotations in Java and others in Kotlin
+Using kapt in Gradle
+--------------------
+
+Annotation processors are supported in Kotlin with the
+`kapt <https://kotlinlang.org/docs/reference/kapt.html>`_ compiler plugin.
 
-    The third option is worth considering, because it can avoid some troubles with the kapt.
+Add the dependencies using the `kapt` and `implementation` configuration in your dependencies block.
+For example, you can write build.gradle.kts as follows:
+
+.. code-block:: kotlin
+
+    dependencies {
+        kapt("org.seasar.doma:doma-processor:2.41.0")
+        implementation("org.seasar.doma:doma-kotlin:2.41.0")
+    }
+
+To simplify your build script, we recommend you use
+the `Doma Compile Plugin <https://github.com/domaframework/doma-compile-plugin>`_:
 
 Sample project
 ==============