Skip to content

Commit 0263227

Browse files
jeffgbutlerjeffgbutler
committed
Documentation for the new where clause DSL
1 parent 2aa3f6c commit 0263227

File tree

6 files changed

+241
-43
lines changed

6 files changed

+241
-43
lines changed

‎CHANGELOG.md‎

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

2230
## Release 1.3.1 - December 18, 2021
2331

‎src/site/markdown/docs/kotlinMyBatis3.md‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -156,9 +156,10 @@ where clause and an order by clause as follows:
156156

157157
```kotlin
158158
val rows = mapper.select {
159-
where(id, isLessThan(100))
160-
or (employed, isTrue()) {
161-
and (occupation, isEqualTo("Developer"))
159+
where { id isLessThan 100 }
160+
or {
161+
employed.isTrue())
162+
and { occupation isEqualTo "Developer" }
162163
}
163164
orderBy(id)
164165
}
@@ -227,9 +228,8 @@ supplied where clause. Clients can use the methods as follows:
227228

228229
```kotlin
229230
val rows = mapper.count {
230-
where(occupation, isNull()) {
231-
and(employed, isFalse())
232-
}
231+
where { occupation.isNull() }
232+
and { employed.isFalse() }
233233
}
234234
```
235235

@@ -294,7 +294,7 @@ method as follows:
294294

295295
```kotlin
296296
val rows = mapper.delete {
297-
where(occupation, isNull())
297+
where { occupation.isNull() }
298298
}
299299
```
300300

@@ -870,17 +870,17 @@ the methods as follows:
870870
```kotlin
871871
val mapper = getMapper() // not shown
872872
val distinctRecords = mapper.selectDistinct {
873-
where(id, isGreaterThan(5))
873+
where { id isGreaterThan 5 }
874874
}
875875

876876
val rows = mapper.select {
877-
where(firstName, isIn("Fred", "Barney"))
877+
where { firstName.isIn("Fred", "Barney") }
878878
orderBy(id)
879879
limit(3)
880880
}
881881

882882
val record = mapper.selectOne {
883-
where(id, isEqualTo(1))
883+
where { id isEqualTo 1 }
884884
}
885885

886886
```
@@ -890,7 +890,7 @@ The general `selectOne` method can also be used to implement a `selectByPrimaryK
890890
```kotlin
891891
fun PersonMapper.selectByPrimaryKey(id_: Int) =
892892
selectOne {
893-
where(id, isEqualTo(id_))
893+
where { id isEqualTo id_ }
894894
}
895895
```
896896

@@ -934,7 +934,7 @@ select list. Like other select methods, this method can be used as follows:
934934

935935
```kotlin
936936
val records = mapper.select {
937-
where(id, isLessThan(100))
937+
where { id isLessThan 100 }
938938
limit(5)
939939
}
940940
```
@@ -995,7 +995,7 @@ where clause. Clients can use the method as follows:
995995
```kotlin
996996
val rows = mapper.update {
997997
set(occupation).equalTo("Programmer")
998-
where(id, isEqualTo(100))
998+
where { id isEqualTo 100 }
999999
and(firstName, isEqualTo("Joe"))
10001000
}
10011001
```
@@ -1030,7 +1030,7 @@ follows:
10301030
```kotlin
10311031
val rows = mapper.update {
10321032
updateSelectiveColumns(updateRecord)
1033-
where(id, isEqualTo(100))
1033+
where { id isEqualTo 100 }
10341034
}
10351035
```
10361036

@@ -1045,7 +1045,7 @@ fun PersonMapper.updateByPrimaryKey(record: PersonRecord) =
10451045
set(employed).equalToOrNull(record::employed)
10461046
set(occupation).equalToOrNull(record::occupation)
10471047
set(addressId).equalToOrNull(record::addressId)
1048-
where(id, isEqualTo(record.id!!))
1048+
where { id isEqualTo record.id!! }
10491049
}
10501050

10511051
fun PersonMapper.updateByPrimaryKeySelective(record: PersonRecord) =
@@ -1056,7 +1056,7 @@ fun PersonMapper.updateByPrimaryKeySelective(record: PersonRecord) =
10561056
set(employed).equalToWhenPresent(record::employed)
10571057
set(occupation).equalToWhenPresent(record::occupation)
10581058
set(addressId).equalToWhenPresent(record::addressId)
1059-
where(id, isEqualTo(record.id!!))
1059+
where { id isEqualTo record.id!! }
10601060
}
10611061
```
10621062

‎src/site/markdown/docs/kotlinOverview.md‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ of the DSL will yield correct results. However, it would be best to use the DSL
2525
diagnose problems.
2626

2727
If you plan to use the Kotlin DSL, we recommend that you do not use any function from
28-
`org.mybatis.dynamic.sql.SqlBuilder` (the Java DSL entry points). Many functions from that class has been duplicated
28+
`org.mybatis.dynamic.sql.SqlBuilder` (the Java DSL entry points). Many functions from that class have been duplicated
2929
for the Kotlin DSL, but in a more Kotlin native manner.
3030

3131
## Package Structure
@@ -158,7 +158,7 @@ The DSL for count statements looks like this:
158158
```kotlin
159159
// count(*)
160160
val countRowsStatement = countFrom(person) {
161-
where(id, isLessThan(4))
161+
where { id isLessThan 4 }
162162
}
163163

164164
// count(column)
@@ -188,7 +188,7 @@ The DSL for delete statements looks like this:
188188

189189
```kotlin
190190
val deleteStatement = deleteFrom(person) {
191-
where(id, isLessThan(4))
191+
where { id isLessThan 4 }
192192
}
193193
```
194194

@@ -374,7 +374,7 @@ val insertSelectStatement = insertSelect(person) {
374374
add(id, constant<Int>("100")), firstName, lastName, birthDate, employed, occupation, addressId
375375
) {
376376
from(person)
377-
where(employed, isTrue())
377+
where { employed.isTrue() }
378378
}
379379
}
380380
```
@@ -401,10 +401,12 @@ The DSL for select statements looks like this:
401401
```kotlin
402402
val selectStatement = select(id, firstName, lastName, birthDate, employed, occupation, addressId) {
403403
from(person)
404-
where(id, isLessThan(5))
405-
and(id, isLessThan(4)) {
406-
and(id, isLessThan(3)) {
407-
and(id, isLessThan(2))
404+
where { id isLessThan 5 }
405+
and {
406+
id isLessThan 4
407+
and {
408+
id isLessThan 3
409+
or { id isLessThan 2 }
408410
}
409411
}
410412
orderBy(id)
@@ -419,10 +421,12 @@ There is also a method that will create a "distinct" query (`select distinct ...
419421
```kotlin
420422
val selectStatement = selectDistinct(id, firstName, lastName, birthDate, employed, occupation, addressId) {
421423
from(person)
422-
where(id, isLessThan(5))
423-
and(id, isLessThan(4)) {
424-
and(id, isLessThan(3)) {
425-
and(id, isLessThan(2))
424+
where { id isLessThan 5 }
425+
and {
426+
id isLessThan 4
427+
and {
428+
id isLessThan 3
429+
or { id isLessThan 2 }
426430
}
427431
}
428432
orderBy(id)
@@ -448,7 +452,7 @@ The DSL for update statements looks like this:
448452
```kotlin
449453
val updateStatement = update(person) {
450454
set(firstName).equalTo("Sam")
451-
where(firstName, isEqualTo("Fred"))
455+
where { firstName isEqualTo "Fred" }
452456
}
453457
```
454458

‎src/site/markdown/docs/kotlinSpring.md‎

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -114,17 +114,17 @@ import org.mybatis.dynamic.sql.util.kotlin.spring.countFrom
114114
val template: NamedParameterJdbcTemplate = getTemplate() // not shown
115115

116116
val rowcount = template.countFrom(person) {
117-
where(id, isLessThan(4))
117+
where { id isLessThan 4 }
118118
}
119119

120120
val columnCount = template.count(lastName) {
121121
from(person)
122-
where(id, isLessThan(4))
122+
where { id isLessThan 4 }
123123
}
124124

125125
val distinctColumnCount = template.countDistinct(lastName) {
126126
from(person)
127-
where(id, isLessThan(4))
127+
where { id isLessThan 4 }
128128
}
129129
```
130130

@@ -159,7 +159,7 @@ import org.mybatis.dynamic.sql.util.kotlin.spring.deleteFrom
159159
val template: NamedParameterJdbcTemplate = getTemplate() // not shown
160160

161161
val rows = template.deleteFrom(person) {
162-
where(id, isLessThan(4))
162+
where { id isLessThan 4 }
163163
}
164164
```
165165

@@ -405,7 +405,7 @@ val insertSelectRows: Int = template.insertSelect(person) {
405405
add(id, constant<Int>("100")), firstName, lastName, birthDate, employed, occupation, addressId
406406
) {
407407
from(person)
408-
where(employed, isTrue())
408+
where { employed.isTrue() }
409409
}
410410
}
411411
```
@@ -422,7 +422,7 @@ val rows = template.withKeyHolder(keyHolder) {
422422
add(id, constant<Int>("100")), firstName, lastName, birthDate, employed, occupation, addressId
423423
) {
424424
from(person)
425-
where(employed, isTrue())
425+
where { employed.isTrue() }
426426
}
427427
}
428428
}
@@ -513,11 +513,13 @@ Select statements can be constructed and executed in a single step with code lik
513513
```kotlin
514514
val personRecords: List<PersonRecord> = template.select(id, firstName, lastName, birthDate, employed, occupation, addressId) {
515515
from(person)
516-
where(id, isLessThan(5))
517-
and(id, isLessThan(4)) {
518-
and(id, isLessThan(3)) {
519-
and(id, isLessThan(2))
520-
}
516+
where { id isLessThan 5 }
517+
and {
518+
id isLessThan 4
519+
and {
520+
id isLessThan 3
521+
or { id isLessThan 2 }
522+
}
521523
}
522524
orderBy(id)
523525
limit(3)
@@ -540,7 +542,7 @@ like this:
540542
```kotlin
541543
val personRecord: PersonRecord? = template.selectOne(id, firstName, lastName, birthDate, employed, occupation, addressId) {
542544
from(Person)
543-
where(id, isEqualTo(key))
545+
where { id isEqualTo key }
544546
}.withRowMapper { rs, _ ->
545547
PersonRecord(
546548
id = rs.getInt(id.name()),
@@ -559,7 +561,7 @@ A distinct query looks like this:
559561
```kotlin
560562
val personRecord: List<PersonRecord> = template.selectDistinct(id, firstName, lastName, birthDate, employed, occupation, addressId) {
561563
from(Person)
562-
where(id, isLessThan(key))
564+
where { id isLessThan key }
563565
}.withRowMapper { rs, _ ->
564566
PersonRecord(
565567
id = rs.getInt(id.name()),
@@ -591,7 +593,7 @@ Update statements can be constructed and executed in a single step with code lik
591593
```kotlin
592594
val rows = template.update(Person) {
593595
set(firstName).equalTo("Sam")
594-
where(firstName, isEqualTo("Fred"))
596+
where { firstName isEqualTo "Fred" }
595597
}
596598
```
597599

0 commit comments

Comments
 (0)