Merge 96a1b72 into cf62191

Author: jeffgbutler

CHANGELOG.md

@@ -18,6 +18,15 @@ GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/issues?q=miles
    `where (a < 5 and B = 3) and (not (C = 4 or D = 5) and E = 6)`. With this enhancement (and the enhancement for
    arbitrary grouping) it should now be possible to write virtually any where clause imaginable.
    ([#438](https://github.com/mybatis/mybatis-dynamic-sql/pull/438))
+4. Major update to the Kotlin where clause DSL. Where clauses now support the "group" and "not" features from above. In
+   addition, the where clause DSL has been fully updated to make it feel more like natural SQL. The previous version
+   of the where clause DSL yielded almost unreadable code when the "group" and "not" functions were added. This update
+   is better all around and yields a DSL that is very similar to native SQL. The new DSL includes many Kotlin DSL
+   construction features including infix functions, operator overloads, and functions with receivers. We believe it
+   will be well worth the effort to migrate to the new DSL. The prior where clause DSL remains in the library for now,
+   but is deprecated. It will be removed in version 1.5.0 of the library. Documentation for the new DSL is here:
+   https://github.com/mybatis/mybatis-dynamic-sql/blob/master/src/site/markdown/docs/kotlinWhereClauses.md
+   ([#442](https://github.com/mybatis/mybatis-dynamic-sql/pull/442))
 
 ## Release 1.3.1 - December 18, 2021
 

README.md

@@ -22,12 +22,12 @@ For example, a typical search can be coded with a query like this (the following
    fun search(id: String?, firstName: String?, lastName: String?) =
         select(Customer.id, Customer.firstName, Customer.lastName) {
             from(Customer)
-            where(Customer.active, isEqualTo(true))
-            and(Customer.id, isEqualToWhenPresent(id).map{ it?.padStart(5, '0') })
-            and(Customer.firstName, isLikeCaseInsensitiveWhenPresent(firstName)
-                .map{ "%" + it.trim() + "%" })
-            and(Customer.lastName, isLikeCaseInsensitiveWhenPresent(lastName)
-                .map{ "%" + it.trim() + "%" })
+            where { Customer.active.isTrue() }
+            and { Customer.id (isEqualToWhenPresent(id).map{ it?.padStart(5, '0') }) }
+            and { Customer.firstName (isLikeCaseInsensitiveWhenPresent(firstName)
+                .map{ "%" + it.trim() + "%" }) }
+            and { Customer.lastName (isLikeCaseInsensitiveWhenPresent(lastName)
+                .map{ "%" + it.trim() + "%" }) }
             orderBy(Customer.lastName, Customer.firstName)
             limit(500)
         }

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

@@ -19,6 +19,7 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Objects;
+import java.util.Optional;
 
 /**
  * This class represents a criteria group with either an AND or an OR connector.
@@ -35,16 +36,16 @@ public class AndOrCriteriaGroup {
 
     private AndOrCriteriaGroup(Builder builder) {
         connector = Objects.requireNonNull(builder.connector);
-        initialCriterion = Objects.requireNonNull(builder.initialCriterion);
+        initialCriterion = builder.initialCriterion;
         subCriteria = builder.subCriteria;
     }
 
     public String connector() {
         return connector;
     }
 
-    public SqlCriterion initialCriterion() {
-        return initialCriterion;
+    public Optional<SqlCriterion> initialCriterion() {
+        return Optional.ofNullable(initialCriterion);
     }
 
     public List<AndOrCriteriaGroup> subCriteria() {

src/main/java/org/mybatis/dynamic/sql/where/render/CriterionRenderer.java

@@ -149,7 +149,8 @@ private List<RenderedCriterion> renderSubCriteria(List<AndOrCriteriaGroup> subCr
     }
 
     private Optional<RenderedCriterion> renderAndOrCriteriaGroup(AndOrCriteriaGroup criterion) {
-        return render(criterion.initialCriterion(), criterion.subCriteria(), this::calculateFragment)
+        return criterion.initialCriterion().map(ic -> render(ic, criterion.subCriteria(), this::calculateFragment))
+                .orElseGet(() -> render(criterion.subCriteria(), this::calculateFragment))
                 .map(rc -> rc.withConnector(criterion.connector()));
     }
 
@@ -159,6 +160,18 @@ private Optional<RenderedCriterion> calculateRenderedCriterion(FragmentAndParame
                 collectSqlFragments(initialCriterion, renderedSubCriteria), fragmentCalculator));
     }
 
+    private RenderedCriterion calculateRenderedCriterion(FragmentCollector fragmentCollector,
+                                                         Function<FragmentCollector, String> fragmentCalculator) {
+        FragmentAndParameters fragmentAndParameters = FragmentAndParameters
+                .withFragment(fragmentCalculator.apply(fragmentCollector))
+                .withParameters(fragmentCollector.parameters())
+                .build();
+
+        return new RenderedCriterion.Builder()
+                .withFragmentAndParameters(fragmentAndParameters)
+                .build();
+    }
+
     private Optional<RenderedCriterion> calculateRenderedCriterion(List<RenderedCriterion> renderedSubCriteria,
             Function<FragmentCollector, String> fragmentCalculator) {
         return collectSqlFragments(renderedSubCriteria).map(fc -> calculateRenderedCriterion(fc, fragmentCalculator));
@@ -180,8 +193,7 @@ private <T> FragmentAndParameters renderCondition(ColumnAndConditionCriterion<T>
      * and there may be subcriteria. The collector will contain the initial condition and any rendered subcriteria
      * in order.
      *
-     * @param initialCondition - may be null if there is no rendered initial condition (as can be the case of
-     *                         optional conditions like isEqualToWhenPresent)
+     * @param initialCondition - may not be null. If there is no initial condition, then use the other overload
      * @param renderedSubCriteria - a list of previously rendered sub criteria. The sub criteria will all
      *                            have connectors (either an AND or an OR)
      * @return a fragment collector whose fragments represent the final calculated list of fragments and parameters.
@@ -222,18 +234,6 @@ private Optional<FragmentCollector> collectSqlFragments(List<RenderedCriterion>
         return Optional.of(fc);
     }
 
-    private RenderedCriterion calculateRenderedCriterion(FragmentCollector fragmentCollector,
-                                                         Function<FragmentCollector, String> fragmentCalculator) {
-        FragmentAndParameters fragmentAndParameters = FragmentAndParameters
-                .withFragment(fragmentCalculator.apply(fragmentCollector))
-                .withParameters(fragmentCollector.parameters())
-                .build();
-
-        return new RenderedCriterion.Builder()
-                .withFragmentAndParameters(fragmentAndParameters)
-                .build();
-    }
-
     private String calculateFragment(FragmentCollector collector) {
         if (collector.hasMultipleFragments()) {
             return collector.fragments()

src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/CriteriaCollector.kt

@@ -17,15 +17,16 @@ package org.mybatis.dynamic.sql.util.kotlin
 
 import org.mybatis.dynamic.sql.BindableColumn
 import org.mybatis.dynamic.sql.ColumnAndConditionCriterion
-import org.mybatis.dynamic.sql.CriteriaGroup
 import org.mybatis.dynamic.sql.AndOrCriteriaGroup
 import org.mybatis.dynamic.sql.ExistsCriterion
 import org.mybatis.dynamic.sql.ExistsPredicate
 import org.mybatis.dynamic.sql.SqlCriterion
 import org.mybatis.dynamic.sql.VisitableCondition
 
+@Deprecated("Deprecated in favor of the new where clause DSL. Please see the documentation for new usage.")
 typealias CriteriaReceiver = CriteriaCollector.() -> Unit
 
+@Deprecated("Deprecated in favor of the new where clause DSL. Please see the documentation for new usage.")
 @MyBatisDslMarker
 class CriteriaCollector {
     val criteria = mutableListOf<AndOrCriteriaGroup>()
@@ -40,9 +41,6 @@ class CriteriaCollector {
     fun and(existsPredicate: ExistsPredicate, criteriaReceiver: CriteriaReceiver = {}): CriteriaCollector =
         addCriteriaGroup("and", buildCriterion(existsPredicate), criteriaReceiver)
 
-    fun and(criteriaGroup: CriteriaGroup, criteriaReceiver: CriteriaReceiver): CriteriaCollector =
-        addCriteriaGroup("and", buildCriterion(criteriaGroup), criteriaReceiver)
-
     fun <T> or(
         column: BindableColumn<T>,
         condition: VisitableCondition<T>,
@@ -53,9 +51,6 @@ class CriteriaCollector {
     fun or(existsPredicate: ExistsPredicate, criteriaReceiver: CriteriaReceiver = {}): CriteriaCollector =
         addCriteriaGroup("or", buildCriterion(existsPredicate), criteriaReceiver)
 
-    fun or(criteriaGroup: CriteriaGroup, criteriaReceiver: CriteriaReceiver): CriteriaCollector =
-        addCriteriaGroup("or", buildCriterion(criteriaGroup), criteriaReceiver)
-
     private fun <T> buildCriterion(
         column: BindableColumn<T>,
         condition: VisitableCondition<T>
@@ -65,9 +60,6 @@ class CriteriaCollector {
     private fun buildCriterion(existsPredicate: ExistsPredicate): ExistsCriterion =
         ExistsCriterion.Builder().withExistsPredicate(existsPredicate).build()
 
-    private fun buildCriterion(criteriaGroup: CriteriaGroup): CriteriaGroup =
-        CriteriaGroup.Builder().withInitialCriterion(criteriaGroup).build()
-
     private fun addCriteriaGroup(
         connector: String,
         initialCriterion: SqlCriterion,

src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/DuplicateInitialCriterionException.kt

@@ -0,0 +1,26 @@
+/*
+ *    Copyright 2016-2022 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
+ *
+ *       http://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.util.kotlin
+
+/**
+ * This exception is thrown when a where clause contains more than one criterion and there
+ * is not an "and" or an "or" to connect them.
+ *
+ * @since 1.4.0
+ */
+class DuplicateInitialCriterionException : RuntimeException(
+    "Setting more than one initial criterion is not allowed. " +
+            "Additional criteria should be added with \"and\" or \"or\" expression")