Single value conditions do not expect null values

Author: jeffgbutler

CHANGELOG.md

@@ -10,7 +10,7 @@ you are unable to move to this version of Java then the releases in the 1.x line
 In addition, we have taken the opportunity to make changes to the library that may break existing code. We have
 worked to make these changes as minimal as possible.
 
-**Potentially Breaking Changes:**
+### Potentially Breaking Changes:
 
 - If you use this library with MyBatis' Spring Batch integration, you will need to make changes as we have
   refactored that support to be more flexible. Please see the
@@ -25,7 +25,27 @@ worked to make these changes as minimal as possible.
   [Extending the Library](https://mybatis.org/mybatis-dynamic-sql/docs/extending.html) page, the change should be
   limited to changing the private constructor to accept `BasicColumn` rather than `BindableColumn`.
 
-Other important changes:
+### Adoption of JSpecify (https://jspecify.dev/)
+
+Following the lead of many other projects (including The Spring Framework), we have adopted JSpecify to fully
+specify the null handling properties of this library. In general, the library does not expect that you will pass a null
+value into any method. There are two exceptions to this rule:
+
+1. Some builder methods will accept a null value if the target object will properly handle null values through the
+   use of java.util.Optional
+2. Methods with names that include "WhenPresent" will properly handle null parameters
+   (for example, "isEqualToWhenPresent")
+
+As you might expect, standardizing null handling revealed some issues in the library that may impact you:
+
+Case-insensitive conditions like "isLikeCaseInsensitive" will now throw a NullPointerException if you pass in null
+values.
+
+The where conditions (isEqualTo, isLessThan, etc.) can be filtered and result in an "empty" condition -
+similar to java.util.Optional. Previously, calling a "value" method of the condition would return null. Now
+those methods will throw "NoSuchElementException". This should not impact you in normal usage.
+
+### Other important changes:
 
 - The library now requires Java 17
 - Deprecated code from prior releases is removed

src/main/java/org/mybatis/dynamic/sql/AbstractSingleValueCondition.java

@@ -19,16 +19,14 @@
 import java.util.function.Predicate;
 import java.util.function.Supplier;
 
-import org.jspecify.annotations.Nullable;
-
 public abstract class AbstractSingleValueCondition<T> implements VisitableCondition<T> {
-    protected final @Nullable T value;
+    protected final T value;
 
-    protected AbstractSingleValueCondition(@Nullable T value) {
+    protected AbstractSingleValueCondition(T value) {
         this.value = value;
     }
 
-    public @Nullable T value() {
+    public T value() {
         return value;
     }
 

src/main/java/org/mybatis/dynamic/sql/SqlBuilder.java

@@ -618,11 +618,11 @@ static <T> IsNotNull<T> isNotNull() {
         return new IsNotNull<>();
     }
 
-    static <T> IsEqualTo<T> isEqualTo(@Nullable T value) {
+    static <T> IsEqualTo<T> isEqualTo(T value) {
         return IsEqualTo.of(value);
     }
 
-    static <T> IsEqualTo<T> isEqualTo(Supplier<@Nullable T> valueSupplier) {
+    static <T> IsEqualTo<T> isEqualTo(Supplier<T> valueSupplier) {
         return isEqualTo(valueSupplier.get());
     }
 
@@ -635,18 +635,18 @@ static <T> IsEqualToColumn<T> isEqualTo(BasicColumn column) {
     }
 
     static <T> IsEqualTo<T> isEqualToWhenPresent(@Nullable T value) {
-        return IsEqualTo.of(value).filter(Objects::nonNull);
+        return value == null ? IsEqualTo.empty() : IsEqualTo.of(value);
     }
 
     static <T> IsEqualTo<T> isEqualToWhenPresent(Supplier<@Nullable T> valueSupplier) {
         return isEqualToWhenPresent(valueSupplier.get());
     }
 
-    static <T> IsNotEqualTo<T> isNotEqualTo(@Nullable T value) {
+    static <T> IsNotEqualTo<T> isNotEqualTo(T value) {
         return IsNotEqualTo.of(value);
     }
 
-    static <T> IsNotEqualTo<T> isNotEqualTo(Supplier<@Nullable T> valueSupplier) {
+    static <T> IsNotEqualTo<T> isNotEqualTo(Supplier<T> valueSupplier) {
         return isNotEqualTo(valueSupplier.get());
     }
 
@@ -659,18 +659,18 @@ static <T> IsNotEqualToColumn<T> isNotEqualTo(BasicColumn column) {
     }
 
     static <T> IsNotEqualTo<T> isNotEqualToWhenPresent(@Nullable T value) {
-        return IsNotEqualTo.of(value).filter(Objects::nonNull);
+        return value == null ? IsNotEqualTo.empty() : IsNotEqualTo.of(value);
     }
 
     static <T> IsNotEqualTo<T> isNotEqualToWhenPresent(Supplier<@Nullable T> valueSupplier) {
         return isNotEqualToWhenPresent(valueSupplier.get());
     }
 
-    static <T> IsGreaterThan<T> isGreaterThan(@Nullable T value) {
+    static <T> IsGreaterThan<T> isGreaterThan(T value) {
         return IsGreaterThan.of(value);
     }
 
-    static <T> IsGreaterThan<T> isGreaterThan(Supplier<@Nullable T> valueSupplier) {
+    static <T> IsGreaterThan<T> isGreaterThan(Supplier<T> valueSupplier) {
         return isGreaterThan(valueSupplier.get());
     }
 
@@ -683,18 +683,18 @@ static <T> IsGreaterThanColumn<T> isGreaterThan(BasicColumn column) {
     }
 
     static <T> IsGreaterThan<T> isGreaterThanWhenPresent(@Nullable T value) {
-        return IsGreaterThan.of(value).filter(Objects::nonNull);
+        return value == null ? IsGreaterThan.empty() : IsGreaterThan.of(value);
     }
 
     static <T> IsGreaterThan<T> isGreaterThanWhenPresent(Supplier<@Nullable T> valueSupplier) {
         return isGreaterThanWhenPresent(valueSupplier.get());
     }
 
-    static <T> IsGreaterThanOrEqualTo<T> isGreaterThanOrEqualTo(@Nullable T value) {
+    static <T> IsGreaterThanOrEqualTo<T> isGreaterThanOrEqualTo(T value) {
         return IsGreaterThanOrEqualTo.of(value);
     }
 
-    static <T> IsGreaterThanOrEqualTo<T> isGreaterThanOrEqualTo(Supplier<@Nullable T> valueSupplier) {
+    static <T> IsGreaterThanOrEqualTo<T> isGreaterThanOrEqualTo(Supplier<T> valueSupplier) {
         return isGreaterThanOrEqualTo(valueSupplier.get());
     }
 
@@ -708,18 +708,18 @@ static <T> IsGreaterThanOrEqualToColumn<T> isGreaterThanOrEqualTo(BasicColumn co
     }
 
     static <T> IsGreaterThanOrEqualTo<T> isGreaterThanOrEqualToWhenPresent(@Nullable T value) {
-        return IsGreaterThanOrEqualTo.of(value).filter(Objects::nonNull);
+        return value == null ? IsGreaterThanOrEqualTo.empty() : IsGreaterThanOrEqualTo.of(value);
     }
 
     static <T> IsGreaterThanOrEqualTo<T> isGreaterThanOrEqualToWhenPresent(Supplier<@Nullable T> valueSupplier) {
         return isGreaterThanOrEqualToWhenPresent(valueSupplier.get());
     }
 
-    static <T> IsLessThan<T> isLessThan(@Nullable T value) {
+    static <T> IsLessThan<T> isLessThan(T value) {
         return IsLessThan.of(value);
     }
 
-    static <T> IsLessThan<T> isLessThan(Supplier<@Nullable T> valueSupplier) {
+    static <T> IsLessThan<T> isLessThan(Supplier<T> valueSupplier) {
         return isLessThan(valueSupplier.get());
     }
 
@@ -732,18 +732,18 @@ static <T> IsLessThanColumn<T> isLessThan(BasicColumn column) {
     }
 
     static <T> IsLessThan<T> isLessThanWhenPresent(@Nullable T value) {
-        return IsLessThan.of(value).filter(Objects::nonNull);
+        return value == null ? IsLessThan.empty() : IsLessThan.of(value);
     }
 
     static <T> IsLessThan<T> isLessThanWhenPresent(Supplier<@Nullable T> valueSupplier) {
         return isLessThanWhenPresent(valueSupplier.get());
     }
 
-    static <T> IsLessThanOrEqualTo<T> isLessThanOrEqualTo(@Nullable T value) {
+    static <T> IsLessThanOrEqualTo<T> isLessThanOrEqualTo(T value) {
         return IsLessThanOrEqualTo.of(value);
     }
 
-    static <T> IsLessThanOrEqualTo<T> isLessThanOrEqualTo(Supplier<@Nullable T> valueSupplier) {
+    static <T> IsLessThanOrEqualTo<T> isLessThanOrEqualTo(Supplier<T> valueSupplier) {
         return isLessThanOrEqualTo(valueSupplier.get());
     }
 
@@ -756,7 +756,7 @@ static <T> IsLessThanOrEqualToColumn<T> isLessThanOrEqualTo(BasicColumn column)
     }
 
     static <T> IsLessThanOrEqualTo<T> isLessThanOrEqualToWhenPresent(@Nullable T value) {
-        return IsLessThanOrEqualTo.of(value).filter(Objects::nonNull);
+        return value == null ? IsLessThanOrEqualTo.empty() : IsLessThanOrEqualTo.of(value);
     }
 
     static <T> IsLessThanOrEqualTo<T> isLessThanOrEqualToWhenPresent(Supplier<@Nullable T> valueSupplier) {
@@ -840,32 +840,32 @@ static <T> IsNotBetween.WhenPresentBuilder<T> isNotBetweenWhenPresent(Supplier<@
     }
 
     // for string columns, but generic for columns with type handlers
-    static <T> IsLike<T> isLike(@Nullable T value) {
+    static <T> IsLike<T> isLike(T value) {
         return IsLike.of(value);
     }
 
-    static <T> IsLike<T> isLike(Supplier<@Nullable T> valueSupplier) {
+    static <T> IsLike<T> isLike(Supplier<T> valueSupplier) {
         return isLike(valueSupplier.get());
     }
 
     static <T> IsLike<T> isLikeWhenPresent(@Nullable T value) {
-        return IsLike.of(value).filter(Objects::nonNull);
+        return value == null ? IsLike.empty() : IsLike.of(value);
     }
 
     static <T> IsLike<T> isLikeWhenPresent(Supplier<@Nullable T> valueSupplier) {
         return isLikeWhenPresent(valueSupplier.get());
     }
 
-    static <T> IsNotLike<T> isNotLike(@Nullable T value) {
+    static <T> IsNotLike<T> isNotLike(T value) {
         return IsNotLike.of(value);
     }
 
-    static <T> IsNotLike<T> isNotLike(Supplier<@Nullable T> valueSupplier) {
+    static <T> IsNotLike<T> isNotLike(Supplier<T> valueSupplier) {
         return isNotLike(valueSupplier.get());
     }
 
     static <T> IsNotLike<T> isNotLikeWhenPresent(@Nullable T value) {
-        return IsNotLike.of(value).filter(Objects::nonNull);
+        return value == null ? IsNotLike.empty() : IsNotLike.of(value);
     }
 
     static <T> IsNotLike<T> isNotLikeWhenPresent(Supplier<@Nullable T> valueSupplier) {
@@ -882,32 +882,32 @@ static IsEqualTo<Boolean> isFalse() {
     }
 
     // conditions for strings only
-    static IsLikeCaseInsensitive isLikeCaseInsensitive(@Nullable String value) {
+    static IsLikeCaseInsensitive isLikeCaseInsensitive(String value) {
         return IsLikeCaseInsensitive.of(value);
     }
 
-    static IsLikeCaseInsensitive isLikeCaseInsensitive(Supplier<@Nullable String> valueSupplier) {
+    static IsLikeCaseInsensitive isLikeCaseInsensitive(Supplier<String> valueSupplier) {
         return isLikeCaseInsensitive(valueSupplier.get());
     }
 
     static IsLikeCaseInsensitive isLikeCaseInsensitiveWhenPresent(@Nullable String value) {
-        return IsLikeCaseInsensitive.of(value).filter(Objects::nonNull);
+        return value == null ? IsLikeCaseInsensitive.empty() : IsLikeCaseInsensitive.of(value);
     }
 
     static IsLikeCaseInsensitive isLikeCaseInsensitiveWhenPresent(Supplier<@Nullable String> valueSupplier) {
         return isLikeCaseInsensitiveWhenPresent(valueSupplier.get());
     }
 
-    static IsNotLikeCaseInsensitive isNotLikeCaseInsensitive(@Nullable String value) {
+    static IsNotLikeCaseInsensitive isNotLikeCaseInsensitive(String value) {
         return IsNotLikeCaseInsensitive.of(value);
     }
 
-    static IsNotLikeCaseInsensitive isNotLikeCaseInsensitive(Supplier<@Nullable String> valueSupplier) {
+    static IsNotLikeCaseInsensitive isNotLikeCaseInsensitive(Supplier<String> valueSupplier) {
         return isNotLikeCaseInsensitive(valueSupplier.get());
     }
 
     static IsNotLikeCaseInsensitive isNotLikeCaseInsensitiveWhenPresent(@Nullable String value) {
-        return IsNotLikeCaseInsensitive.of(value).filter(Objects::nonNull);
+        return value == null ? IsNotLikeCaseInsensitive.empty() : IsNotLikeCaseInsensitive.of(value);
     }
 
     static IsNotLikeCaseInsensitive isNotLikeCaseInsensitiveWhenPresent(Supplier<@Nullable String> valueSupplier) {

src/main/java/org/mybatis/dynamic/sql/where/condition/IsEqualTo.java

@@ -15,15 +15,20 @@
  */
 package org.mybatis.dynamic.sql.where.condition;
 
+import java.util.NoSuchElementException;
 import java.util.function.Function;
 import java.util.function.Predicate;
 
-import org.jspecify.annotations.Nullable;
 import org.mybatis.dynamic.sql.AbstractSingleValueCondition;
 
 public class IsEqualTo<T> extends AbstractSingleValueCondition<T> {
 
-    private static final IsEqualTo<?> EMPTY = new IsEqualTo<>(null) {
+    private static final IsEqualTo<?> EMPTY = new IsEqualTo<Object>(-1) {
+        @Override
+        public Object value() {
+            throw new NoSuchElementException("No value present"); //$NON-NLS-1$
+        }
+
         @Override
         public boolean isEmpty() {
             return true;
@@ -36,7 +41,7 @@ public static <T> IsEqualTo<T> empty() {
         return t;
     }
 
-    protected IsEqualTo(@Nullable T value) {
+    protected IsEqualTo(T value) {
         super(value);
     }
 
@@ -45,7 +50,7 @@ public String operator() {
         return "="; //$NON-NLS-1$
     }
 
-    public static <T> IsEqualTo<T> of(@Nullable T value) {
+    public static <T> IsEqualTo<T> of(T value) {
         return new IsEqualTo<>(value);
     }
 

src/main/java/org/mybatis/dynamic/sql/where/condition/IsGreaterThan.java

@@ -15,14 +15,19 @@
  */
 package org.mybatis.dynamic.sql.where.condition;
 
+import java.util.NoSuchElementException;
 import java.util.function.Function;
 import java.util.function.Predicate;
 
-import org.jspecify.annotations.Nullable;
 import org.mybatis.dynamic.sql.AbstractSingleValueCondition;
 
 public class IsGreaterThan<T> extends AbstractSingleValueCondition<T> {
-    private static final IsGreaterThan<?> EMPTY = new IsGreaterThan<>(null) {
+    private static final IsGreaterThan<?> EMPTY = new IsGreaterThan<Object>(-1) {
+        @Override
+        public Object value() {
+            throw new NoSuchElementException("No value present"); //$NON-NLS-1$
+        }
+
         @Override
         public boolean isEmpty() {
             return true;
@@ -35,7 +40,7 @@ public static <T> IsGreaterThan<T> empty() {
         return t;
     }
 
-    protected IsGreaterThan(@Nullable T value) {
+    protected IsGreaterThan(T value) {
         super(value);
     }
 
@@ -44,7 +49,7 @@ public String operator() {
         return ">"; //$NON-NLS-1$
     }
 
-    public static <T> IsGreaterThan<T> of(@Nullable T value) {
+    public static <T> IsGreaterThan<T> of(T value) {
         return new IsGreaterThan<>(value);
     }
 

src/main/java/org/mybatis/dynamic/sql/where/condition/IsGreaterThanOrEqualTo.java

@@ -15,14 +15,19 @@
  */
 package org.mybatis.dynamic.sql.where.condition;
 
+import java.util.NoSuchElementException;
 import java.util.function.Function;
 import java.util.function.Predicate;
 
-import org.jspecify.annotations.Nullable;
 import org.mybatis.dynamic.sql.AbstractSingleValueCondition;
 
 public class IsGreaterThanOrEqualTo<T> extends AbstractSingleValueCondition<T> {
-    private static final IsGreaterThanOrEqualTo<?> EMPTY = new IsGreaterThanOrEqualTo<>(null) {
+    private static final IsGreaterThanOrEqualTo<?> EMPTY = new IsGreaterThanOrEqualTo<Object>(-1) {
+        @Override
+        public Object value() {
+            throw new NoSuchElementException("No value present"); //$NON-NLS-1$
+        }
+
         @Override
         public boolean isEmpty() {
             return true;
@@ -35,7 +40,7 @@ public static <T> IsGreaterThanOrEqualTo<T> empty() {
         return t;
     }
 
-    protected IsGreaterThanOrEqualTo(@Nullable T value) {
+    protected IsGreaterThanOrEqualTo(T value) {
         super(value);
     }
 
@@ -44,7 +49,7 @@ public String operator() {
         return ">="; //$NON-NLS-1$
     }
 
-    public static <T> IsGreaterThanOrEqualTo<T> of(@Nullable T value) {
+    public static <T> IsGreaterThanOrEqualTo<T> of(T value) {
         return new IsGreaterThanOrEqualTo<>(value);
     }