Merge pull request #1062 from jeffgbutler/remove-generics2

Significant Refactoring of the DSLs That Support Where Clauses

Author: jeffgbutler

CHANGELOG.md

@@ -4,12 +4,93 @@ This log will detail notable changes to MyBatis Dynamic SQL. Full details are av
 
 ## Release 2.0.0 - Unreleased
 
-Release 2.0.0 is a significant milestone for the library. We have moved to Java 17 as the minimum version supported. If
-you are unable to move to this version of Java then the releases in the 1.x line can be used with Java 8.
+Release 2.0.0 is a significant milestone for the library with many enhancements and changes. We have moved to Java 17
+as the minimum version supported. If you are unable to move to this version of Java then the releases in the 1.x line
+can be used with Java 8.
 
-In addition, we have taken the opportunity to make changes to the library that may break existing code. We have
+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.
 
+Please read these release notes carefully as there are changes that may impact many users.
+
+### DSL Updates and Migration Plan
+
+With this release, I have started a long-term plan to update the DSLs that have "where" clauses – namely, CountDSL,
+DeleteDSL, SelectDSL, and UpdateDSL. All of these DSLs are generic and allow you to specify a function
+that can modify the model created when invoking `build()`. I now view this as a design flaw that provides very
+little benefit and makes direct use of a DSL more complex. For example, direct usage of a DSL often requires declaring
+a variable like `DeleteDSL<DeleteModel>` instead of simply `DeleteDSL`. This gets worse when you have more complex
+situations involving DSL inner classes.
+
+Another issue is the tight coupling between `SelectDSL` and `QueryExpressionDSL`. It is confusing to have the `select`
+method actually return `QueryExpressionDSL<SelectModel>`.
+
+So this release includes new, non-generic, versions of the DSLs in a new package structure. The new DSLs will live
+side by side with the old DSLs for now to maintain backwards compatibility. Eventually, the old DSls will be removed.
+
+Here is the migration plan:
+
+1. In this release I have updated the Kotlin support to use the new DSLs under the covers. This should be completely
+   transparent to Kotlin users as all the prior complexity was hidden by the Kotlin DSLs.
+2. After the 2.0.0 release of this library, I will update MyBatis Generator so that it creates code based on the new DSL
+   versions.
+3. In the next minor release of this library, I will deprecate all the old DSLs. I will also change the methods in
+   `SqlBuilder` to use the new DSLs. In many cases you will be able to update to the new DSL by simply changing a
+   package name.
+4. In the next major release of this library, I will delete the old DSLs.
+
+I expect these next releases to be a relatively fast follow after the 2.0.0 release.
+
+This table shows the old and new versions of the DSLs:
+
+| New DSL                                 | Old DSL (Will Be Removed Eventually)                                                               |
+|-----------------------------------------|----------------------------------------------------------------------------------------------------|
+| `org.mybatis.dynamic.sql.dsl.CountDSL`  | `org.mybatis.dynamic.sql.select.CountDSL`                                                          |
+| `org.mybatis.dynamic.sql.dsl.DeleteDSL` | `org.mybatis.dynamic.sql.delete.DeleteDSL`                                                         |
+| `org.mybatis.dynamic.sql.dsl.SelectDSL` | `org.mybatis.dynamic.sql.select.SelectDSL` and `org.mybatis.dynamic.sql.select.QueryExpressionDSL` |
+| `org.mybatis.dynamic.sql.dsl.UpdateDSL` | `org.mybatis.dynamic.sql.update.UpdateDSL`                                                         |
+
+The "completer" classes are also impacted and will need to change. This table shows the old and new versions:
+
+| New Completer                                    | Old Completer (Will Be Removed Eventually)          |
+|--------------------------------------------------|-----------------------------------------------------|
+| `org.mybatis.dynamic.sql.dsl.CountDSLCompleter`  | `org.mybatis.dynamic.sql.select.CountDSLCompleter`  |
+| `org.mybatis.dynamic.sql.dsl.DeleteDSLCompleter` | `org.mybatis.dynamic.sql.delete.DeleteDSLCompleter` |
+| `org.mybatis.dynamic.sql.dsl.SelectDSLCompleter` | `org.mybatis.dynamic.sql.select.SelectDSLCompleter` |
+| `org.mybatis.dynamic.sql.dsl.UpdateDSLCompleter` | `org.mybatis.dynamic.sql.update.UpdateDSLCompleter` |
+
+If you are actually using the generic function in the old DSLs to alter the model class produced by a DSL, then you can
+replace it with the new `map` method on all affected model classes to achieve the same result.
+
+If you are using the DSLs directly (for example, not with code generated by MyBatis Generator), I encourage you to
+update your code to use the new DSLs now. As always, if you experience any difficulties with this new version of the
+library or in migrating to the new DSLs, please let us know by opening an issue on GitHub.
+
+### Other Important Changes:
+
+- The library now requires Java 17
+- Deprecated code from prior releases is removed
+- We now allow CASE expressions in ORDER BY Clauses
+- The "In" conditions will now throw `InvalidSqlException` during rendering if the list of values is empty. Previously
+  an empty In condition would render as invalid SQL and would usually cause a runtime exception from the database.
+  With this change, the exception thrown is more predictable and the error is caught before sending the SQL to the
+  database.
+- All the paging methods (limit, offset, fetchFirst) now have "WhenPresent" variations that will drop the phrase from
+  rendering if a null value is passed in
+- The JOIN syntax is updated and now allows full boolean expressions like a WHERE clause. The prior JOIN syntax
+  is deprecated and will be removed in a future release.
+- Add support for locking options in select statements (for update, for share, etc.) This is not an abstraction of
+  these concepts for different databases it simply adds known clauses to a generated SQL statement. You should always
+  test to make sure these functions work in your target database. Currently, we support and test the options
+  supported by PostgreSQL.
+- Rendering for all the conditions (isEqualTo, etc.) has changed. This should be transparent to most users unless you
+  have coded a direct implementation of `VisitableCondition`. The change makes it easier to code custom conditions that
+  are not supported by the library out of the box. The statement renderers now call methods `renderCondition` and
+  `renderLeftColumn` that you can override to implement any rendering you need. In addition, we've made `filter` and
+  `map` support optional if you implement custom conditions
+- Added support for configuring a Java property name to be associated with an `SqlColumn`. This property name can be
+  used with the record-based insert methods to reduce the boilerplate code for mapping columns to Java properties.
+
 ### Potentially Breaking Changes:
 
 - If you use this library with MyBatis' Spring Batch integration, you will need to make changes as we have
@@ -21,24 +102,24 @@ worked to make these changes as minimal as possible.
   are removed in favor of a new method `renderForOrderBy` 
 - If you have implemented any custom functions, you will likely need to make changes. The supplied base classes now
   hold an instance of `BasicColumn` rather than `BindableColumn`. This change was made to make the functions more
-  useful in variety of circumstances. If you follow the patterns shown on the
+  useful in a variety of circumstances. If you follow the patterns shown on the
   [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`.
 
 ### Adoption of JSpecify (https://jspecify.dev/)
 
 Following the lead of many other projects (including The Spring Framework), we have adopted JSpecify to fully
-document the null handling properties of this library. JSpecify is now a runtime dependency - as is
+document the null handling properties of this library. JSpecify is now a runtime dependency – as is
 recommended practice with JSpecify.
 
-This change should not impact the running of any existing code, but depending on your usage you may see new IDE or
+This change should not impact the running of any existing code, but depending on your usage, you may see new IDE or
 tooling warnings based on the declared nullability of methods in the library. You may choose to ignore the
-warnings and things should continue to function. Of course, we recommend that you do not ignore these warnings!
+ warnings, and things should continue to function. Of course, we recommend that you do not ignore these warnings!
 
 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
+1. Some builder methods will accept a null value if the target object properly handles null values through the
    use of java.util.Optional
 2. Methods with names that include "WhenPresent" will properly handle null parameters
    (for example, "isEqualToWhenPresent")
@@ -49,7 +130,7 @@ Fixing compiler warnings and errors:
 
 1. We expect that most of the warnings you encounter will be related to passing null values into a where condition.
    These warnings should be resolved by changing your code to use the "WhenPresent" versions of methods as those
-   methods handle null values in a predictable way.
+   methods handle null values predictably.
 2. Java Classes that extend "AliasableSqlTable" will likely see IDE warnings about non-null type arguments. This can be
    resolved by adding a "@NullMarked" annotation to the class or package. This issue does not affect Kotlin classes
    that extend "AliasableSqlTable".
@@ -59,57 +140,28 @@ Fixing compiler warnings and errors:
    change the type parameter definition to specify a non-nullable type. For example...
 
    ```kotlin
-   import org.mybatis.dynamic.sql.SqlColumn
-
    fun <T> foo(column: SqlColumn<T>) {
    }
    ```
 
    Should change to:
 
    ```kotlin
-   import org.mybatis.dynamic.sql.SqlColumn
-
    fun <T : Any> foo(column: SqlColumn<T>) {
    }
    ```
 
 Runtime behavior changes:
 
-1. 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.
+1. 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 `java.util.NoSuchElementException`. This should not impact you in normal usage.
 2. We have updated the "ParameterTypeConverter" used in Spring applications to maintain compatibility with Spring's
    "Converter" interface. The primary change is that the framework will no longer call a type converter if the
    input value is null. This should simplify the coding of converters and foster reuse with existing Spring converters.
 3. The "map" method on the "WhenPresent" conditions will accept a mapper function that may return a null value. The
    conditions will now properly handle this outcome 
 
-### Other important changes:
-
-- The library now requires Java 17
-- Deprecated code from prior releases is removed
-- We now allow CASE expressions in ORDER BY Clauses
-- The "In" conditions will now throw `InvalidSqlException` during rendering if the list of values is empty. Previously
-  an empty In condition would render as invalid SQL and would usually cause a runtime exception from the database.
-  With this change, the exception thrown is more predictable and the error is caught before sending the SQL to the
-  database.
-- All the paging methods (limit, offset, fetchFirst) now have "WhenPresent" variations that will drop the phrase from
-  rendering if a null value is passed in
-- The JOIN syntax is updated and now allows full boolean expressions like a WHERE clause. The prior JOIN syntax
-  is deprecated and will be removed in a future release.
-- Add support for locking options in select statements (for update, for share, etc.) This is not an abstraction of
-  these concepts for different databases it simply adds known clauses to a generated SQL statement. You should always
-  test to make sure these functions work in your target database. Currently, we support, and test, the options
-  supported by PostgreSQL.
-- Rendering for all the conditions (isEqualTo, etc.) has changed. This should be transparent to most users unless you
-  have coded a direct implementation of `VisitableCondition`. The change makes it easier to code custom conditions that
-  are not supported by the library out of the box. The statement renderers now call methods `renderCondition` and
-  `renderLeftColumn` that you can override to implement any rendering you need. In addition, we've made `filter` and
-  `map` support optional if you implement custom conditions
-- Added support for configuring a Java property name to be associated with an `SqlColumn`. This property name can be
-  used with the record based insert methods to reduce the boilerplate code for mapping columns to Java properties.
-
 ## Release 1.5.2 - June 3, 2024
 
 This is a small maintenance release with the following changes:

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

@@ -1,5 +1,5 @@
 /*
- *    Copyright 2016-2025 the original author or authors.
+ *    Copyright 2016-2026 the original author or authors.
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -19,7 +19,6 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Objects;
-import java.util.Optional;
 
 import org.jspecify.annotations.Nullable;
 
@@ -34,21 +33,21 @@
  */
 public class AndOrCriteriaGroup {
     private final String connector;
-    private final @Nullable SqlCriterion initialCriterion;
+    private final SqlCriterion initialCriterion;
     private final List<AndOrCriteriaGroup> subCriteria;
 
     private AndOrCriteriaGroup(Builder builder) {
         connector = Objects.requireNonNull(builder.connector);
-        initialCriterion = builder.initialCriterion;
+        initialCriterion = Objects.requireNonNull(builder.initialCriterion);
         subCriteria = builder.subCriteria;
     }
 
     public String connector() {
         return connector;
     }
 
-    public Optional<SqlCriterion> initialCriterion() {
-        return Optional.ofNullable(initialCriterion);
+    public SqlCriterion initialCriterion() {
+        return initialCriterion;
     }
 
     public List<AndOrCriteriaGroup> subCriteria() {
@@ -65,7 +64,7 @@ public Builder withConnector(String connector) {
             return this;
         }
 
-        public Builder withInitialCriterion(@Nullable SqlCriterion initialCriterion) {
+        public Builder withInitialCriterion(SqlCriterion initialCriterion) {
             this.initialCriterion = initialCriterion;
             return this;
         }

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

@@ -1,5 +1,5 @@
 /*
- *    Copyright 2016-2025 the original author or authors.
+ *    Copyright 2016-2026 the original author or authors.
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -15,7 +15,7 @@
  */
 package org.mybatis.dynamic.sql;
 
-import java.util.Optional;
+import java.util.Objects;
 
 import org.jspecify.annotations.Nullable;
 
@@ -29,15 +29,15 @@
  * @since 1.4.0
  */
 public class CriteriaGroup extends SqlCriterion {
-    private final @Nullable SqlCriterion initialCriterion;
+    private final SqlCriterion initialCriterion;
 
     protected CriteriaGroup(AbstractGroupBuilder<?> builder) {
         super(builder);
-        initialCriterion = builder.initialCriterion;
+        initialCriterion = Objects.requireNonNull(builder.initialCriterion);
     }
 
-    public Optional<SqlCriterion> initialCriterion() {
-        return Optional.ofNullable(initialCriterion);
+    public SqlCriterion initialCriterion() {
+        return initialCriterion;
     }
 
     @Override
@@ -48,7 +48,7 @@ public <R> R accept(SqlCriterionVisitor<R> visitor) {
     public abstract static class AbstractGroupBuilder<T extends AbstractGroupBuilder<T>> extends AbstractBuilder<T> {
         private @Nullable SqlCriterion initialCriterion;
 
-        public T withInitialCriterion(@Nullable SqlCriterion initialCriterion) {
+        public T withInitialCriterion(SqlCriterion initialCriterion) {
             this.initialCriterion = initialCriterion;
             return getThis();
         }

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

@@ -0,0 +1,27 @@
+/*
+ *    Copyright 2016-2026 the original author or authors.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *       https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+package org.mybatis.dynamic.sql;
+
+/**
+ * A simple SqlCriterion that does nothing and will not render. This is to solve the problem of
+ * awkward nullability operations in various classes. We can now say that an initial criterion is never null.
+ */
+public class NullCriterion extends SqlCriterion {
+    @Override
+    public <R> R accept(SqlCriterionVisitor<R> visitor) {
+        return visitor.visit(this);
+    }
+}