Merge pull request #594 from jeffgbutler/reusable-where-clauses-v2

Major Refactoring of Where/Having Support

Author: jeffgbutler

CHANGELOG.md

@@ -6,6 +6,38 @@ This log will detail notable changes to MyBatis Dynamic SQL. Full details are av
 
 GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/milestone/12?closed=1](https://github.com/mybatis/mybatis-dynamic-sql/milestone/12?closed=1)
 
+### Potentially Breaking Changes
+
+This release includes a major refactoring of the "where" clause support. This is done to support common code for
+"having" clauses which is a new feature (see below). Most changes are source code compatible with previous
+releases and should be transparent with no impact. Following is a list of some more visible changes...
+
+First, the "where" methods in `SqlBuilder` now return an instance of `WhereDSL.StandaloneWhereFinisher` rather than
+`WhereDSL`. This will only impact you if you are using the WhereDSL directly which is a rare use case.
+
+Second, if you are using independent or reusable where clauses you will need to make changes. Previously you might have
+coded an independent where clause like this:
+
+```java
+private WhereApplier commonWhere = d -> d.where(id, isEqualTo(1)).or(occupation, isNull());
+```
+
+Code like this will no longer compile. There are two options for updates. The simplest change to make is to
+replace "where" with "and" or "or" in the above code. For example...
+
+```java
+private WhereApplier commonWhere = d -> d.and(id, isEqualTo(1)).or(occupation, isNull());
+```
+
+This will function as before, but you may think it looks a bit strange because the phrase starts with "and". If you
+want this to look more like true SQL, you can write code like this:
+
+```java
+private final WhereApplier commonWhere = where(id, isEqualTo(1)).or(occupation, isNull()).toWhereApplier();
+```
+
+This uses a `where` method from `SqlBuilder`. 
+
 ### "Having" Clause Support
 
 This release adds support for "having" clauses in select statements. This includes a refactoring of the "where"
@@ -22,10 +54,6 @@ where (a < 2 and b > 3)
 
 The renderer will now remove the open/close parentheses in a case like this.
 
-The "having" support is not as full-featured as the "where" support in that we don't support independent and
-reusable having clauses, and we don't support composable having functions. If you have a reasonable use case
-for that kind of support, please let us know.
-
 In the Java DSL, a "having" clause can only be coded after a "group by" clause - which is a reasonable restriction
 as "having" is only needed if there is a "group by".
 
@@ -38,7 +66,29 @@ The pull request for this change is ([#550](https://github.com/mybatis/mybatis-d
 ### Multi-Select Queries
 
 A multi-select query is a special case of a union select statement. The difference is that it allows "order by" and
-paging clauses to be applied to the nested queries.
+paging clauses to be applied to the nested queries. A multi-select query looks like this:
+
+```java
+SelectStatementProvider selectStatement = multiSelect(
+        select(id.as("A_ID"), firstName, lastName, birthDate, employed, occupation, addressId)
+        .from(person)
+        .where(id, isLessThanOrEqualTo(2))
+        .orderBy(id)
+        .limit(1)
+).unionAll(
+        select(id.as("A_ID"), firstName, lastName, birthDate, employed, occupation, addressId)
+        .from(person)
+        .where(id, isGreaterThanOrEqualTo(4))
+        .orderBy(id.descending())
+        .limit(1)
+).orderBy(sortColumn("A_ID"))
+.fetchFirst(2).rowsOnly()
+.build()
+.render(RenderingStrategies.MYBATIS3);
+```
+
+Notice how both inner queries have `order by` and `limit` phrases, then there is an `order by` phrase
+for the entire query.
 
 The pull request for this change is ([#591](https://github.com/mybatis/mybatis-dynamic-sql/pull/591))
 

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

@@ -30,6 +30,7 @@
 import org.mybatis.dynamic.sql.insert.MultiRowInsertDSL;
 import org.mybatis.dynamic.sql.select.ColumnSortSpecification;
 import org.mybatis.dynamic.sql.select.CountDSL;
+import org.mybatis.dynamic.sql.select.HavingDSL;
 import org.mybatis.dynamic.sql.select.MultiSelectDSL;
 import org.mybatis.dynamic.sql.select.QueryExpressionDSL.FromGatherer;
 import org.mybatis.dynamic.sql.select.SelectDSL;
@@ -240,21 +241,30 @@ static UpdateDSL<UpdateModel> update(SqlTable table, String tableAlias) {
         return UpdateDSL.update(table, tableAlias);
     }
 
-    static WhereDSL where() {
-        return WhereDSL.where();
+    static WhereDSL.StandaloneWhereFinisher where() {
+        return new WhereDSL().where();
     }
 
-    static <T> WhereDSL where(BindableColumn<T> column, VisitableCondition<T> condition,
-                              AndOrCriteriaGroup... subCriteria) {
-        return WhereDSL.where().where(column, condition, subCriteria);
+    static <T> WhereDSL.StandaloneWhereFinisher where(BindableColumn<T> column, VisitableCondition<T> condition,
+                                                      AndOrCriteriaGroup... subCriteria) {
+        return new WhereDSL().where(column, condition, subCriteria);
     }
 
-    static WhereDSL where(SqlCriterion initialCriterion, AndOrCriteriaGroup... subCriteria) {
-        return WhereDSL.where().where(initialCriterion, subCriteria);
+    static WhereDSL.StandaloneWhereFinisher where(SqlCriterion initialCriterion, AndOrCriteriaGroup... subCriteria) {
+        return new WhereDSL().where(initialCriterion, subCriteria);
     }
 
-    static WhereDSL where(ExistsPredicate existsPredicate, AndOrCriteriaGroup... subCriteria) {
-        return WhereDSL.where().where(existsPredicate, subCriteria);
+    static WhereDSL.StandaloneWhereFinisher where(ExistsPredicate existsPredicate, AndOrCriteriaGroup... subCriteria) {
+        return new WhereDSL().where(existsPredicate, subCriteria);
+    }
+
+    static <T> HavingDSL.StandaloneHavingFinisher having(BindableColumn<T> column, VisitableCondition<T> condition,
+                                              AndOrCriteriaGroup... subCriteria) {
+        return new HavingDSL().having(column, condition, subCriteria);
+    }
+
+    static HavingDSL.StandaloneHavingFinisher having(SqlCriterion initialCriterion, AndOrCriteriaGroup... subCriteria) {
+        return new HavingDSL().having(initialCriterion, subCriteria);
     }
 
     // where condition connectors

src/main/java/org/mybatis/dynamic/sql/common/AbstractBooleanExpressionDSL.java

@@ -145,9 +145,9 @@ private void addSubCriteria(String connector, List<AndOrCriteriaGroup> criteria)
                 .build());
     }
 
-    protected void setInitialCriterion(SqlCriterion initialCriterion) {
+    protected void setInitialCriterion(SqlCriterion initialCriterion, StatementType statementType) {
         if (this.initialCriterion != null) {
-            throw new InvalidSqlException(Messages.getString("ERROR.32")); //$NON-NLS-1$
+            throw new InvalidSqlException(Messages.getString(statementType.messageNumber())); //$NON-NLS-1$
         }
 
         this.initialCriterion = initialCriterion;
@@ -159,4 +159,19 @@ protected SqlCriterion getInitialCriterion() {
     }
 
     protected abstract T getThis();
+
+    public enum StatementType {
+        WHERE("ERROR.32"), //$NON-NLS-1$
+        HAVING("ERROR.31"); //$NON-NLS-1$
+
+        private final String messageNumber;
+
+        public String messageNumber() {
+            return messageNumber;
+        }
+
+        StatementType(String messageNumber) {
+            this.messageNumber = messageNumber;
+        }
+    }
 }

src/main/java/org/mybatis/dynamic/sql/delete/DeleteDSL.java

@@ -27,11 +27,11 @@
 import org.mybatis.dynamic.sql.common.OrderByModel;
 import org.mybatis.dynamic.sql.configuration.StatementConfiguration;
 import org.mybatis.dynamic.sql.util.Buildable;
-import org.mybatis.dynamic.sql.where.AbstractWhereDSL;
-import org.mybatis.dynamic.sql.where.AbstractWhereSupport;
+import org.mybatis.dynamic.sql.where.AbstractWhereFinisher;
+import org.mybatis.dynamic.sql.where.AbstractWhereStarter;
 import org.mybatis.dynamic.sql.where.WhereModel;
 
-public class DeleteDSL<R> extends AbstractWhereSupport<DeleteDSL<R>.DeleteWhereBuilder, DeleteDSL<R>>
+public class DeleteDSL<R> extends AbstractWhereStarter<DeleteDSL<R>.DeleteWhereBuilder, DeleteDSL<R>>
         implements Buildable<R> {
 
     private final Function<DeleteModel, R> adapterFunction;
@@ -109,7 +109,7 @@ public static DeleteDSL<DeleteModel> deleteFrom(SqlTable table, String tableAlia
         return deleteFrom(Function.identity(), table, tableAlias);
     }
 
-    public class DeleteWhereBuilder extends AbstractWhereDSL<DeleteWhereBuilder> implements Buildable<R> {
+    public class DeleteWhereBuilder extends AbstractWhereFinisher<DeleteWhereBuilder> implements Buildable<R> {
 
         private DeleteWhereBuilder() {
             super(statementConfiguration);
@@ -140,7 +140,7 @@ protected DeleteWhereBuilder getThis() {
         }
 
         protected WhereModel buildWhereModel() {
-            return internalBuild();
+            return buildModel();
         }
     }
 }

src/main/java/org/mybatis/dynamic/sql/select/AbstractHavingFinisher.java

@@ -0,0 +1,30 @@
+/*
+ *    Copyright 2016-2023 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.select;
+
+import org.mybatis.dynamic.sql.SqlCriterion;
+import org.mybatis.dynamic.sql.common.AbstractBooleanExpressionDSL;
+
+public abstract class AbstractHavingFinisher<T extends AbstractHavingFinisher<T>>
+        extends AbstractBooleanExpressionDSL<T> {
+    void initialize(SqlCriterion sqlCriterion) {
+        setInitialCriterion(sqlCriterion, StatementType.HAVING);
+    }
+
+    protected HavingModel buildModel() {
+        return new HavingModel(getInitialCriterion(), subCriteria);
+    }
+}

src/main/java/org/mybatis/dynamic/sql/select/AbstractHavingStarter.java

@@ -0,0 +1,71 @@
+/*
+ *    Copyright 2016-2023 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.select;
+
+import java.util.Arrays;
+import java.util.List;
+
+import org.mybatis.dynamic.sql.AndOrCriteriaGroup;
+import org.mybatis.dynamic.sql.BindableColumn;
+import org.mybatis.dynamic.sql.ColumnAndConditionCriterion;
+import org.mybatis.dynamic.sql.CriteriaGroup;
+import org.mybatis.dynamic.sql.SqlCriterion;
+import org.mybatis.dynamic.sql.VisitableCondition;
+
+public abstract class AbstractHavingStarter<F extends AbstractHavingFinisher<?>> {
+
+    public <T> F having(BindableColumn<T> column, VisitableCondition<T> condition,
+                        AndOrCriteriaGroup... subCriteria) {
+        return having(column, condition, Arrays.asList(subCriteria));
+    }
+
+    public <T> F having(BindableColumn<T> column, VisitableCondition<T> condition,
+                        List<AndOrCriteriaGroup> subCriteria) {
+        SqlCriterion sqlCriterion = ColumnAndConditionCriterion.withColumn(column)
+                .withCondition(condition)
+                .withSubCriteria(subCriteria)
+                .build();
+
+        return initialize(sqlCriterion);
+    }
+
+    public F having(SqlCriterion initialCriterion, AndOrCriteriaGroup... subCriteria) {
+        return having(initialCriterion, Arrays.asList(subCriteria));
+    }
+
+    public F having(SqlCriterion initialCriterion, List<AndOrCriteriaGroup> subCriteria) {
+        SqlCriterion sqlCriterion = new CriteriaGroup.Builder()
+                .withInitialCriterion(initialCriterion)
+                .withSubCriteria(subCriteria)
+                .build();
+
+        return initialize(sqlCriterion);
+    }
+
+    protected abstract F having();
+
+    public F applyHaving(HavingApplier havingApplier) {
+        F finisher = having();
+        havingApplier.accept(finisher);
+        return finisher;
+    }
+
+    private F initialize(SqlCriterion sqlCriterion) {
+        F finisher = having();
+        finisher.initialize(sqlCriterion);
+        return finisher;
+    }
+}

src/main/java/org/mybatis/dynamic/sql/select/AbstractQueryExpressionDSL.java

@@ -33,12 +33,12 @@
 import org.mybatis.dynamic.sql.select.join.JoinSpecification;
 import org.mybatis.dynamic.sql.select.join.JoinType;
 import org.mybatis.dynamic.sql.util.Buildable;
-import org.mybatis.dynamic.sql.where.AbstractWhereDSL;
-import org.mybatis.dynamic.sql.where.AbstractWhereSupport;
+import org.mybatis.dynamic.sql.where.AbstractWhereFinisher;
+import org.mybatis.dynamic.sql.where.AbstractWhereStarter;
 
-public abstract class AbstractQueryExpressionDSL<W extends AbstractWhereDSL<?>,
+public abstract class AbstractQueryExpressionDSL<W extends AbstractWhereFinisher<?>,
             T extends AbstractQueryExpressionDSL<W, T>>
-        extends AbstractWhereSupport<W, T> {
+        extends AbstractWhereStarter<W, T> {
 
     private final List<JoinSpecification.Builder> joinSpecificationBuilders = new ArrayList<>();
     private final Map<SqlTable, String> tableAliases = new HashMap<>();

src/main/java/org/mybatis/dynamic/sql/select/CountDSL.java

@@ -25,7 +25,7 @@
 import org.mybatis.dynamic.sql.SqlTable;
 import org.mybatis.dynamic.sql.configuration.StatementConfiguration;
 import org.mybatis.dynamic.sql.util.Buildable;
-import org.mybatis.dynamic.sql.where.AbstractWhereDSL;
+import org.mybatis.dynamic.sql.where.AbstractWhereFinisher;
 import org.mybatis.dynamic.sql.where.WhereModel;
 
 /**
@@ -131,7 +131,7 @@ public CountDSL<R> from(SqlTable table) {
         }
     }
 
-    public class CountWhereBuilder extends AbstractWhereDSL<CountWhereBuilder>
+    public class CountWhereBuilder extends AbstractWhereFinisher<CountWhereBuilder>
             implements Buildable<R> {
         private CountWhereBuilder() {
             super(statementConfiguration);
@@ -149,7 +149,7 @@ protected CountWhereBuilder getThis() {
         }
 
         protected WhereModel buildWhereModel() {
-            return internalBuild();
+            return super.buildModel();
         }
     }
 }

src/main/java/org/mybatis/dynamic/sql/select/HavingApplier.java

@@ -0,0 +1,40 @@
+/*
+ *    Copyright 2016-2023 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.select;
+
+import java.util.function.Consumer;
+
+import org.mybatis.dynamic.sql.common.AbstractBooleanExpressionDSL;
+
+@FunctionalInterface
+public interface HavingApplier {
+
+    void accept(AbstractHavingFinisher<?> havingFinisher);
+
+    /**
+     * Return a composed having applier that performs this operation followed by the after operation.
+     *
+     * @param after the operation to perform after this operation
+     *
+     * @return a composed having applier that performs this operation followed by the after operation.
+     */
+    default HavingApplier andThen(Consumer<AbstractBooleanExpressionDSL<?>> after) {
+        return t -> {
+            accept(t);
+            after.accept(t);
+        };
+    }
+}