Update a document about the Criteria API [skip ci]

Author: nakamura-to

docs/criteria-api.rst

@@ -36,7 +36,7 @@ We use the following Entity classes to show you some examples:
       @Transient private Employee manager;
       @Transient private Address address;
 
-      // getter and setter
+      // getters and setters
     }
 
 .. code-block:: java
@@ -52,14 +52,50 @@ We use the following Entity classes to show you some examples:
       @OriginalStates private Department originalStates;
       @Transient private List<Employee> employeeList = new ArrayList<>();
 
-      // getter and setter
+      // getters and setters
     }
 
-Note that both of the above classes are annotated with ``@Entity(metamodel = @Metamodel)``.
+.. code-block:: java
+
+    @Entity(immutable = true, metamodel = @Metamodel)
+    @Table(name = "EMPLOYEE")
+    public class Emp {
+
+      @Id private final Integer employeeId;
+      private final Integer employeeNo;
+      private final String employeeName;
+      private final Integer managerId;
+      private final LocalDate hiredate;
+      private final Salary salary;
+      private final Integer departmentId;
+      private final Integer addressId;
+      @Version private final Integer version;
+      @Transient private final Dept department;
+      @Transient private final Emp manager;
+
+      // constructor and getters
+    }
+
+.. code-block:: java
+
+    @Entity(immutable = true, metamodel = @Metamodel)
+    @Table(name = "DEPARTMENT")
+    public class Dept {
+
+      @Id private final Integer departmentId;
+      private final Integer departmentNo;
+      private final String departmentName;
+      private final String location;
+      @Version private final Integer version;
+
+      // constructor and getters
+    }
+
+Note that the above classes are annotated with ``@Entity(metamodel = @Metamodel)``.
 The ``metamodel = @Metamodel`` indicates that the annotated entity
 has a corresponding metamodel class generated by Doma's annotation processor .
 
-In our examples, the metamodel classes are ``Employee_`` and ``Department_``.
+In our examples, the metamodel classes are ``Employee_``, ``Department_``, ``Emp_`` and ``Dept_``.
 These metamodels allow you to make your query typesafe.
 
 You can customize the name of the metamodels by the Metamodel annotation elements.
@@ -456,6 +492,12 @@ We support the following operators and predicates:
 * exists
 * notExists - (not exists)
 
+.. note::
+
+    The ``eq`` operator generates the ``is null`` predicate if the second operand is ``null``.
+    Also, the ``ne`` operator generates the ``is not null`` predicate if the second operand is ``null``.
+
+
 We also support the following logical operators:
 
 * and
@@ -661,6 +703,42 @@ You can associate many entities:
             .associate(e, a, Employee::setAddress)
             .fetch();
 
+association for immutable entities (Entityql)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can associate immutable entities with the ``associateWith`` operation in the Entityql DSL.
+You have to use the ``associateWith`` operation with join expression.
+
+.. code-block:: java
+
+    Emp_ e = new Emp_();
+    Emp_ m = new Emp_();
+    Dept_ d = new Dept_();
+
+    List<Emp> list =
+        entityql
+            .from(e)
+            .innerJoin(d, on -> on.eq(e.departmentId, d.departmentId))
+            .leftJoin(m, on -> on.eq(e.managerId, m.employeeId))
+            .where(c -> c.eq(d.departmentName, "SALES"))
+            .associateWith(e, d, Emp::withDept)
+            .associateWith(e, m, Emp::withManager)
+            .fetch();
+
+The above query issues the following SQL statement:
+
+.. code-block:: sql
+
+    select t0_.EMPLOYEE_ID, t0_.EMPLOYEE_NO, t0_.EMPLOYEE_NAME, t0_.MANAGER_ID, t0_.HIREDATE,
+    t0_.SALARY, t0_.DEPARTMENT_ID, t0_.ADDRESS_ID, t0_.VERSION,
+    t1_.DEPARTMENT_ID, t1_.DEPARTMENT_NO, t1_.DEPARTMENT_NAME, t1_.LOCATION, t1_.VERSION,
+    t2_.EMPLOYEE_ID, t2_.EMPLOYEE_NO, t2_.EMPLOYEE_NAME, t2_.MANAGER_ID, t2_.HIREDATE,
+    t2_.SALARY, t2_.DEPARTMENT_ID, t2_.ADDRESS_ID, t2_.VERSION
+    from EMPLOYEE t0_
+    inner join DEPARTMENT t1_ on (t0_.DEPARTMENT_ID = t1_.DEPARTMENT_ID)
+    left outer join EMPLOYEE t2_ on (t0_.MANAGER_ID = t2_.EMPLOYEE_ID)
+    where t1_.DEPARTMENT_NAME = ?
+
 Dynamic join expression (Entityql, NativeSql)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1092,6 +1170,7 @@ We support the following settings:
 * queryTimeout
 * sqlLogType
 * batchSize
+* excludeNull
 
 They are all optional.
 
@@ -1108,6 +1187,7 @@ You can apply them as follows:
                 settings.setQueryTimeout(1000);
                 settings.setSqlLogType(SqlLogType.RAW);
                 settings.setBatchSize(20);
+                settings.excludeNull(true);
             })
             .values(
                 c -> {
@@ -1227,6 +1307,7 @@ We support the following settings:
 * queryTimeout
 * sqlLogType
 * suppressOptimisticLockException
+* excludeNull
 
 They are all optional.
 
@@ -1244,6 +1325,7 @@ You can apply them as follows:
       settings.setQueryTimeout(1000);
       settings.setSqlLogType(SqlLogType.RAW);
       settings.setSuppressOptimisticLockException(true);
+      settings.excludeNull(true);
     }).set(c -> {
       c.value(e.employeeName, "aaa");
     }).execute();