Merge pull request #595 from jeffgbutler/deprecationsv2

[Kotlin] Deprecate the general and/or methods

Author: jeffgbutler

CHANGELOG.md

@@ -36,7 +36,7 @@ want this to look more like true SQL, you can write code like this:
 private final WhereApplier commonWhere = where(id, isEqualTo(1)).or(occupation, isNull()).toWhereApplier();
 ```
 
-This uses a `where` method from `SqlBuilder`. 
+This uses a `where` method from the `SqlBuilder` class. 
 
 ### "Having" Clause Support
 
@@ -59,7 +59,8 @@ as "having" is only needed if there is a "group by".
 
 In the Kotlin DSL, the "group by" restriction is not present because of the free form nature of that DSL - but you 
 should probably only use "having" if there is a "group by". Also note that the freestanding "and" and "or"
-functions in the Kotlin DSL still only apply to the where clause.
+functions in the Kotlin DSL still only apply to the where clause. For this reason, the freestanding "and" and "or"
+methods are deprecated. Please only use the "and" and "or" methods inside a "where" or "having" lambda.
 
 The pull request for this change is ([#550](https://github.com/mybatis/mybatis-dynamic-sql/pull/550))
 
@@ -110,6 +111,7 @@ The pull request for this change is ([#591](https://github.com/mybatis/mybatis-d
    ([#572](https://github.com/mybatis/mybatis-dynamic-sql/pull/572))
 5. Add `SqlBuilder.concat` and the equivalent in Kotlin. This is a concatenate function that works on more databases.
    ([#573](https://github.com/mybatis/mybatis-dynamic-sql/pull/573))
+6. Several classes and methods in the Kotlin DSL are deprecated in response to the new "having" support
 
 ## Release 1.4.1 - October 7, 2022
 

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

@@ -51,20 +51,24 @@ abstract class KotlinBaseBuilder<D : AbstractWhereStarter<*,*>> {
         getDsl().where(criteria)
     }
 
+    @Deprecated("Please move the \"and\" function into the where lambda. If the where lambda has more than one condition, you may need to surround the existing conditions with \"group\" first.")
     fun and(criteria: GroupingCriteriaReceiver): Unit =
         GroupingCriteriaCollector().apply(criteria).let {
             getDsl().where().and(it.initialCriterion, it.subCriteria)
         }
 
+    @Deprecated("Please move the \"and\" function into the where lambda. If the where lambda has more than one condition, you may need to surround the existing conditions with \"group\" first.")
     fun and(criteria: List<AndOrCriteriaGroup>) {
         getDsl().where().and(criteria)
     }
 
+    @Deprecated("Please move the \"or\" function into the where lambda. If the where lambda has more than one condition, you may need to surround the existing conditions with \"group\" first.")
     fun or(criteria: GroupingCriteriaReceiver): Unit =
         GroupingCriteriaCollector().apply(criteria).let {
             getDsl().where().or(it.initialCriterion, it.subCriteria)
         }
 
+    @Deprecated("Please move the \"or\" function into the where lambda. If the where lambda has more than one condition, you may need to surround the existing conditions with \"group\" first.")
     fun or(criteria: List<AndOrCriteriaGroup>) {
         getDsl().where().or(criteria)
     }

src/test/kotlin/examples/kotlin/mybatis3/canonical/PersonMapperTest.kt

@@ -63,8 +63,10 @@ class PersonMapperTest {
             val mapper = session.getMapper(PersonMapper::class.java)
 
             val rows = mapper.select {
-                where { id isEqualTo 1 }
-                or { occupation.isNull() }
+                where {
+                    id isEqualTo 1
+                    or { occupation.isNull() }
+                }
             }
 
             assertThat(rows).hasSize(3)
@@ -106,8 +108,10 @@ class PersonMapperTest {
             val mapper = session.getMapper(PersonMapper::class.java)
 
             val rows = mapper.selectDistinct {
-                where { id isGreaterThan 1 }
-                or { occupation.isNull() }
+                where {
+                    id isGreaterThan 1
+                    or { occupation.isNull() }
+                }
             }
 
             assertThat(rows).hasSize(5)
@@ -375,8 +379,10 @@ class PersonMapperTest {
 
             rows = mapper.update {
                 set(occupation) equalTo "Programmer"
-                where { id isEqualTo 100 }
-                and { firstName isEqualTo "Joe" }
+                where {
+                    id isEqualTo 100
+                    and { firstName isEqualTo "Joe" }
+                }
             }
 
             assertThat(rows).isEqualTo(1)
@@ -494,8 +500,10 @@ class PersonMapperTest {
             val mapper = session.getMapper(PersonMapper::class.java)
 
             val rows = mapper.count {
-                where { employed.isTrue() }
-                and { occupation isEqualTo "Brontosaurus Operator" }
+                where {
+                    employed.isTrue()
+                    and { occupation isEqualTo "Brontosaurus Operator" }
+                }
             }
 
             assertThat(rows).isEqualTo(2L)
@@ -524,10 +532,12 @@ class PersonMapperTest {
             val mapper = session.getMapper(PersonMapper::class.java)
 
             val rows = mapper.count {
-                where { id isEqualTo 1 }
-                or {
-                    id isEqualTo 2
-                    or { id isEqualTo 3 }
+                where {
+                    id isEqualTo 1
+                    or {
+                        id isEqualTo 2
+                        or { id isEqualTo 3 }
+                    }
                 }
             }
 
@@ -541,10 +551,12 @@ class PersonMapperTest {
             val mapper = session.getMapper(PersonMapper::class.java)
 
             val rows = mapper.count {
-                where { id isLessThan 5 }
-                and {
-                    id isLessThan 3
-                    and { id isEqualTo 1 }
+                where {
+                    id isLessThan 5
+                    and {
+                        id isLessThan 3
+                        and { id isEqualTo 1 }
+                    }
                 }
             }