Merge pull request #394 from domaframework/enhance-processors-for-criteira-api

Enhance annotation processors for the Criteria API

Author: nakamura-to

docs/annotation-processing.rst

@@ -13,6 +13,18 @@ and show you how to pass them to build tools.
 Options
 =======
 
+doma.criteria.enabled
+  Whether to generate meta classes for the Criteria API.
+  The default value is ``true``.
+
+doma.criteria.prefix
+  The name prefix of the meta classes for the Criteria API.
+  The default value is an empty string.
+
+doma.criteria.suffix
+  The name suffix of the meta classes for the Criteria API.
+  The default value is ``_``.
+
 doma.dao.package
   The package that the generated implementation classes of interfaces annotated with ``@Dao`` belong to.
   The specified value overrides the value of doma.dao.subpackage.

docs/criteria-api.rst

@@ -61,6 +61,10 @@ We use the following Entity classes to show you some examples:
 Each of the above classes has a corresponding meta class - ``Employee_`` and ``Department_``.
 These meta classes allow you to make your query typesafe.
 
+You can customize the name of the meta classes by specifying annotation processor options.
+See :doc:`annotation-processing` and check the `doma.criteria.prefix`
+and the `doma.criteria.suffix` options.
+
 Entityql DSL
 ============
 
@@ -294,6 +298,8 @@ The above query issues the following SQL statement:
     from EMPLOYEE t0_
     left outer join DEPARTMENT t1_ on (t0_.DEPARTMENT_ID = t1_.DEPARTMENT_ID)
 
+.. _criteria_associate:
+
 associate (Entityql)
 --------------------
 
@@ -653,8 +659,9 @@ The use of the select method (NativeSql)
 
 Be careful of the following points when you use the ``select`` method:
 
-* Specify a type argument to the select method.
-* Use the select method in combination with the following map method.
+* Specify a type argument to the ``select`` method.
+* Use the ``select`` method in combination with the ``map`` method.
+  The object returned by the ``select`` method doesn't have any ``execute`` methods.
 
 .. code-block:: java
 

docs/faq.rst

@@ -31,7 +31,7 @@ Runtime environment
 Which version of JRE does Doma support?
 ---------------------------------------
 
-JRE 8, 9, 10, 11, 12, 13 and 14.
+JRE 8 and above.
 
 Which libraries are required for Doma to work?
 ----------------------------------------------
@@ -48,7 +48,7 @@ Development environment
 Which version of JDK does Doma support?
 ---------------------------------------
 
-JDK 8, 9, 10, 11, 12, 13 and 14.
+JDK 8 and above.
 
 Which IDE do you recommend?
 ---------------------------
@@ -105,30 +105,31 @@ Does Doma generate SQL statements?
 
 Yes, Doma generates the following statements:
 
+- SELECT
 - INSERT
 - DELETE
 - UPDATE
 - Stored procedure call
 - Stored function call
 
-Doma doesn't generate SELECT statements
-but executes arbitrary SELECT statements and maps the results to the Java objects.
-
-See also :doc:`query/index` for detailed information.
-
 How are dynamic SQL statements executed?
 ----------------------------------------
 
-Dynamic SQL statements are built by directives that are represented by the SQL comments.
+There are two ways:
+
+* The SQL Templates.
+* The Criteria API.
 
-See also :doc:`sql` for detail information.
+See :doc:`sql` and :doc:`criteria-api` for detail information.
 
 Does Doma map database relationships such as one-to-one and one-to-many to Java objects?
 ----------------------------------------------------------------------------------------
 
-No.
+Yes.
+
+Doma provides the Criteria API to map database relationships to Java entities.
 
-Doma only maps each row of the SQL result set to a Java entity instance.
+See :ref:`criteria_associate` for detail information.
 
 Does Doma provide a JDBC connection pooling feature?
 ----------------------------------------------------

doma-core/src/main/java/org/seasar/doma/internal/ClassNames.java

@@ -43,6 +43,18 @@ public static ClassName newExternalDomainTypeClassName(CharSequence externalDoma
     return new ExternalDomainClassNameBuilder(externalDomainClassName).build();
   }
 
+  public static ClassName newEntityDefClassNameBuilder(
+      CharSequence entityClassName, String criteriaPrefix, String criteriaSuffix) {
+    assertNotNull(entityClassName, criteriaPrefix, criteriaSuffix);
+    return new DefClassNameBuilder(entityClassName, criteriaPrefix, criteriaSuffix).build();
+  }
+
+  public static ClassName newEmbeddableDefClassNameBuilder(
+      CharSequence entityClassName, String criteriaPrefix, String criteriaSuffix) {
+    assertNotNull(entityClassName, criteriaPrefix, criteriaSuffix);
+    return new DefClassNameBuilder(entityClassName, criteriaPrefix, criteriaSuffix).build();
+  }
+
   private static class ClassNameBuilder {
 
     final String binaryName;
@@ -88,4 +100,26 @@ protected String prefix() {
           + ".";
     }
   }
+
+  private static class DefClassNameBuilder extends ClassNameBuilder {
+    private final String criteriaPrefix;
+    private final String criteriaSuffix;
+
+    public DefClassNameBuilder(
+        CharSequence binaryName, String criteriaPrefix, String criteriaSuffix) {
+      super(binaryName);
+      this.criteriaPrefix = criteriaPrefix;
+      this.criteriaSuffix = criteriaSuffix;
+    }
+
+    @Override
+    protected String infix() {
+      return criteriaPrefix;
+    }
+
+    @Override
+    protected String suffix() {
+      return super.suffix() + criteriaSuffix;
+    }
+  }
 }

doma-core/src/main/java/org/seasar/doma/jdbc/criteria/AggregateFunctions.java

@@ -1,7 +1,7 @@
 package org.seasar.doma.jdbc.criteria;
 
-import org.seasar.doma.def.PropertyDef;
 import org.seasar.doma.jdbc.criteria.declaration.AggregateFunction;
+import org.seasar.doma.jdbc.criteria.def.PropertyDef;
 
 public final class AggregateFunctions {
 

doma-core/src/main/java/org/seasar/doma/jdbc/criteria/Entityql.java

@@ -1,9 +1,9 @@
 package org.seasar.doma.jdbc.criteria;
 
 import java.util.Objects;
-import org.seasar.doma.def.EntityDef;
 import org.seasar.doma.jdbc.criteria.context.SelectContext;
 import org.seasar.doma.jdbc.criteria.declaration.SelectFromDeclaration;
+import org.seasar.doma.jdbc.criteria.def.EntityDef;
 import org.seasar.doma.jdbc.criteria.statement.EntityqlSelectStatement;
 
 public final class Entityql {

doma-core/src/main/java/org/seasar/doma/jdbc/criteria/NativeSql.java

@@ -1,7 +1,6 @@
 package org.seasar.doma.jdbc.criteria;
 
 import java.util.Objects;
-import org.seasar.doma.def.EntityDef;
 import org.seasar.doma.jdbc.criteria.context.DeleteContext;
 import org.seasar.doma.jdbc.criteria.context.InsertContext;
 import org.seasar.doma.jdbc.criteria.context.SelectContext;
@@ -10,6 +9,7 @@
 import org.seasar.doma.jdbc.criteria.declaration.InsertIntoDeclaration;
 import org.seasar.doma.jdbc.criteria.declaration.SelectFromDeclaration;
 import org.seasar.doma.jdbc.criteria.declaration.UpdateDeclaration;
+import org.seasar.doma.jdbc.criteria.def.EntityDef;
 import org.seasar.doma.jdbc.criteria.statement.NativeSqlDeleteStarting;
 import org.seasar.doma.jdbc.criteria.statement.NativeSqlInsertStarting;
 import org.seasar.doma.jdbc.criteria.statement.NativeSqlSelectStarting;

doma-core/src/main/java/org/seasar/doma/jdbc/criteria/command/AssociateCommand.java

@@ -7,11 +7,11 @@
 import java.util.Map;
 import java.util.Objects;
 import java.util.function.BiConsumer;
-import org.seasar.doma.def.EntityDef;
 import org.seasar.doma.internal.util.Pair;
 import org.seasar.doma.jdbc.command.Command;
 import org.seasar.doma.jdbc.command.SelectCommand;
 import org.seasar.doma.jdbc.criteria.context.SelectContext;
+import org.seasar.doma.jdbc.criteria.def.EntityDef;
 import org.seasar.doma.jdbc.entity.EntityType;
 import org.seasar.doma.jdbc.query.Query;
 import org.seasar.doma.jdbc.query.SelectQuery;

doma-core/src/main/java/org/seasar/doma/jdbc/criteria/command/EntityKey.java

@@ -3,7 +3,7 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Objects;
-import org.seasar.doma.def.EntityDef;
+import org.seasar.doma.jdbc.criteria.def.EntityDef;
 
 public final class EntityKey {
   private final EntityDef<?> entityDef;

doma-core/src/main/java/org/seasar/doma/jdbc/criteria/command/EntityPoolIterationHandler.java

@@ -2,10 +2,10 @@
 
 import java.util.List;
 import java.util.Objects;
-import org.seasar.doma.def.EntityDef;
 import org.seasar.doma.internal.jdbc.command.AbstractIterationHandler;
 import org.seasar.doma.internal.jdbc.command.ResultListCallback;
 import org.seasar.doma.jdbc.ObjectProvider;
+import org.seasar.doma.jdbc.criteria.def.EntityDef;
 import org.seasar.doma.jdbc.query.SelectQuery;
 
 public class EntityPoolIterationHandler