Merge pull request #454 from domaframework/semantics-of-condition-operators

Change the semantics of condition operators.

Author: nakamura-to

docs/criteria-api.rst

@@ -494,9 +494,16 @@ We support the following operators and predicates:
 
 .. 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``.
+    If the right hand operand is ``null``, the WHERE or the HAVING clause doesn't include the operator.
+    See WhereDeclaration_ and HavingDeclaration_ javadoc for more details.
 
+.. _WhereDeclaration: https://www.javadoc.io/doc/org.seasar.doma/doma-core/latest/org/seasar/doma/jdbc/criteria/declaration/WhereDeclaration.html
+.. _HavingDeclaration: https://www.javadoc.io/doc/org.seasar.doma/doma-core/latest/org/seasar/doma/jdbc/criteria/declaration/HavingDeclaration.html
+
+We also support the following utility operators:
+
+* eqOrIsNull - ("=" or "is null")
+* neOrIsNotNull - ("<>" or "is not null")
 
 We also support the following logical operators:
 
@@ -579,13 +586,13 @@ For example, suppose that a where expression contains a conditional expression a
             .where(
                 c -> {
                   c.eq(e.departmentId, 1);
-                  if (name != null) {
+                  if (enableNameCondition) {
                     c.like(e.employeeName, name);
                   }
                 })
             .fetch();
 
-In the case that the ``name`` variable is ``null``, the ``like`` expression is ignored.
+In the case that the ``enableNameCondition`` variable is ``false``, the ``like`` expression is ignored.
 The above query issues the following SQL statement:
 
 .. code-block:: sql

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

@@ -132,7 +132,7 @@ class Like implements Criterion {
 
     public Like(Operand.Prop left, CharSequence right, LikeOption option) {
       this.left = Objects.requireNonNull(left);
-      this.right = right;
+      this.right = Objects.requireNonNull(right);
       this.option = Objects.requireNonNull(option);
     }
 
@@ -149,7 +149,7 @@ class NotLike implements Criterion {
 
     public NotLike(Operand.Prop left, CharSequence right, LikeOption option) {
       this.left = Objects.requireNonNull(left);
-      this.right = right;
+      this.right = Objects.requireNonNull(right);
       this.option = Objects.requireNonNull(option);
     }
 

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

@@ -21,82 +21,274 @@ protected ComparisonDeclaration(
     this.setter = Objects.requireNonNull(setter);
   }
 
+  /**
+   * Adds a {@code =} operator.
+   *
+   * @param left the left hand operand
+   * @param right the right hand operand. If this value is null, the query condition does'nt include
+   *     the operand.
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code left} is null
+   */
   public <PROPERTY> void eq(PropertyMetamodel<PROPERTY> left, PROPERTY right) {
     Objects.requireNonNull(left);
-    add(new Criterion.Eq(new Operand.Prop(left), new Operand.Param(left, right)));
+    if (right != null) {
+      add(new Criterion.Eq(new Operand.Prop(left), new Operand.Param(left, right)));
+    }
   }
 
+  /**
+   * Adds a {@code =} operator.
+   *
+   * @param left the left hand operand
+   * @param right the right hand operand
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code left} or {@code right} is null
+   */
   public <PROPERTY> void eq(PropertyMetamodel<PROPERTY> left, PropertyMetamodel<PROPERTY> right) {
     Objects.requireNonNull(left);
     Objects.requireNonNull(right);
     add(new Criterion.Eq(new Operand.Prop(left), new Operand.Prop(right)));
   }
 
+  /**
+   * Adds a {@code <>} operator.
+   *
+   * @param left the left hand operand
+   * @param right the right hand operand. If this value is null, the query condition does'nt include
+   *     the operand.
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code left} is null
+   */
   public <PROPERTY> void ne(PropertyMetamodel<PROPERTY> left, PROPERTY right) {
     Objects.requireNonNull(left);
-    add(new Criterion.Ne(new Operand.Prop(left), new Operand.Param(left, right)));
+    if (right != null) {
+      add(new Criterion.Ne(new Operand.Prop(left), new Operand.Param(left, right)));
+    }
   }
 
+  /**
+   * Adds a {@code <>} operator.
+   *
+   * @param left the left hand operand
+   * @param right the right hand operand
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code left} or {@code right} is null
+   */
   public <PROPERTY> void ne(PropertyMetamodel<PROPERTY> left, PropertyMetamodel<PROPERTY> right) {
     Objects.requireNonNull(left);
     Objects.requireNonNull(right);
     add(new Criterion.Ne(new Operand.Prop(left), new Operand.Prop(right)));
   }
 
+  /**
+   * Adds a {@code >} operator.
+   *
+   * @param left the left hand operand
+   * @param right the right hand operand. If this value is null, the query condition does'nt include
+   *     the operand.
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code left} is null
+   */
   public <PROPERTY> void gt(PropertyMetamodel<PROPERTY> left, PROPERTY right) {
     Objects.requireNonNull(left);
-    add(new Criterion.Gt(new Operand.Prop(left), new Operand.Param(left, right)));
+    if (right != null) {
+      add(new Criterion.Gt(new Operand.Prop(left), new Operand.Param(left, right)));
+    }
   }
 
+  /**
+   * Adds a {@code >} operator.
+   *
+   * @param left the left hand operand
+   * @param right the right hand operand
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code left} or {@code right} is null
+   */
   public <PROPERTY> void gt(PropertyMetamodel<PROPERTY> left, PropertyMetamodel<PROPERTY> right) {
     Objects.requireNonNull(left);
     Objects.requireNonNull(right);
     add(new Criterion.Gt(new Operand.Prop(left), new Operand.Prop(right)));
   }
 
+  /**
+   * Adds a {@code >=} operator.
+   *
+   * @param left the left hand operand
+   * @param right the right hand operand. If this value is null, the query condition does'nt include
+   *     the operand.
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code left} is null
+   */
   public <PROPERTY> void ge(PropertyMetamodel<PROPERTY> left, PROPERTY right) {
     Objects.requireNonNull(left);
-    add(new Criterion.Ge(new Operand.Prop(left), new Operand.Param(left, right)));
+    if (right != null) {
+      add(new Criterion.Ge(new Operand.Prop(left), new Operand.Param(left, right)));
+    }
   }
 
+  /**
+   * Adds a {@code >=} operator.
+   *
+   * @param left the left hand operand
+   * @param right the right hand operand
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code left} or {@code right} is null
+   */
   public <PROPERTY> void ge(PropertyMetamodel<PROPERTY> left, PropertyMetamodel<PROPERTY> right) {
     Objects.requireNonNull(left);
     Objects.requireNonNull(right);
     add(new Criterion.Ge(new Operand.Prop(left), new Operand.Prop(right)));
   }
 
+  /**
+   * Adds a {@code <} operator.
+   *
+   * @param left the left hand operand
+   * @param right the right hand operand. If this value is null, the query condition does'nt include
+   *     the operand.
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code left} is null
+   */
   public <PROPERTY> void lt(PropertyMetamodel<PROPERTY> left, PROPERTY right) {
     Objects.requireNonNull(left);
-    add(new Criterion.Lt(new Operand.Prop(left), new Operand.Param(left, right)));
+    if (right != null) {
+      add(new Criterion.Lt(new Operand.Prop(left), new Operand.Param(left, right)));
+    }
   }
 
+  /**
+   * Adds a {@code <} operator.
+   *
+   * @param left the left hand operand
+   * @param right the right hand operand
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code left} or {@code right} is null
+   */
   public <PROPERTY> void lt(PropertyMetamodel<PROPERTY> left, PropertyMetamodel<PROPERTY> right) {
     Objects.requireNonNull(left);
     Objects.requireNonNull(right);
     add(new Criterion.Lt(new Operand.Prop(left), new Operand.Prop(right)));
   }
 
+  /**
+   * Adds a {@code <=} operator.
+   *
+   * @param left the left hand operand
+   * @param right the right hand operand. If this value is null, the query condition does'nt include
+   *     the operand.
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code left} is null
+   */
   public <PROPERTY> void le(PropertyMetamodel<PROPERTY> left, PROPERTY right) {
     Objects.requireNonNull(left);
-    add(new Criterion.Le(new Operand.Prop(left), new Operand.Param(left, right)));
+    if (right != null) {
+      add(new Criterion.Le(new Operand.Prop(left), new Operand.Param(left, right)));
+    }
   }
 
+  /**
+   * Adds a {@code <=} operator.
+   *
+   * @param left the left hand operand
+   * @param right the right hand operand
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code left} or {@code right} is null
+   */
   public <PROPERTY> void le(PropertyMetamodel<PROPERTY> left, PropertyMetamodel<PROPERTY> right) {
     Objects.requireNonNull(left);
     Objects.requireNonNull(right);
     add(new Criterion.Le(new Operand.Prop(left), new Operand.Prop(right)));
   }
 
+  /**
+   * Adds a {@code IS NULL} operator.
+   *
+   * @param propertyMetamodel the left hand operand
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code propertyMetamodel} is null
+   */
+  public <PROPERTY> void isNull(PropertyMetamodel<PROPERTY> propertyMetamodel) {
+    Objects.requireNonNull(propertyMetamodel);
+    add(new Criterion.IsNull(new Operand.Prop(propertyMetamodel)));
+  }
+
+  /**
+   * Adds a {@code IS NOT NULL} operator.
+   *
+   * @param propertyMetamodel the left hand operand
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code propertyMetamodel} is null
+   */
+  public <PROPERTY> void isNotNull(PropertyMetamodel<PROPERTY> propertyMetamodel) {
+    Objects.requireNonNull(propertyMetamodel);
+    add(new Criterion.IsNotNull(new Operand.Prop(propertyMetamodel)));
+  }
+
+  /**
+   * Adds a {@code =} operator or a {@code IS NULL} operator.
+   *
+   * @param left the left hand operand
+   * @param right the right hand operand. If this value is null, the query condition includes the
+   *     {@code IS NULL} operator.
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code left} is null
+   */
+  public <PROPERTY> void eqOrIsNull(PropertyMetamodel<PROPERTY> left, PROPERTY right) {
+    Objects.requireNonNull(left);
+    if (right == null) {
+      add(new Criterion.IsNull(new Operand.Prop(left)));
+    } else {
+      add(new Criterion.Eq(new Operand.Prop(left), new Operand.Param(left, right)));
+    }
+  }
+
+  /**
+   * Adds a {@code <>} operator or a {@code IS NOT NULL} operator.
+   *
+   * @param left the left hand operand
+   * @param right the right hand operand. If this value is null, the query condition includes the
+   *     {@code IS NOT NULL} operator.
+   * @param <PROPERTY> the property type
+   * @throws NullPointerException if {@code left} is null
+   */
+  public <PROPERTY> void neOrIsNotNull(PropertyMetamodel<PROPERTY> left, PROPERTY right) {
+    Objects.requireNonNull(left);
+    if (right == null) {
+      add(new Criterion.IsNotNull(new Operand.Prop(left)));
+    } else {
+      add(new Criterion.Ne(new Operand.Prop(left), new Operand.Param(left, right)));
+    }
+  }
+
+  /**
+   * Add a {@code AND} operator.
+   *
+   * @param block the right hand operand
+   * @throws NullPointerException if {@code block} is null
+   */
   public void and(Runnable block) {
     Objects.requireNonNull(block);
     runBlock(block, Criterion.And::new);
   }
 
+  /**
+   * Add a {@code OR} operator.
+   *
+   * @param block the right hand operand
+   * @throws NullPointerException if {@code block} is null
+   */
   public void or(Runnable block) {
     Objects.requireNonNull(block);
     runBlock(block, Criterion.Or::new);
   }
 
+  /**
+   * Add a {@code NOT} operator.
+   *
+   * @param block the right hand operand
+   * @throws NullPointerException if {@code block} is null
+   */
   public void not(Runnable block) {
     Objects.requireNonNull(block);
     runBlock(block, Criterion.Not::new);

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

@@ -3,6 +3,7 @@
 import java.util.Objects;
 import org.seasar.doma.jdbc.criteria.context.SelectContext;
 
+/** The having declaration. */
 public class HavingDeclaration extends ComparisonDeclaration {
 
   public HavingDeclaration(SelectContext context) {