Skip to content

Commit 898993d

Browse files
jeffgbutlerjeffgbutler
committed
Documentation
1 parent 1c9ce84 commit 898993d

File tree

4 files changed

+139
-111
lines changed

4 files changed

+139
-111
lines changed

‎CHANGELOG.md

+11
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@ This log will detail notable changes to MyBatis Dynamic SQL. Full details are av
44

55
## Release 1.4.0 - Unreleased
66

7+
The release includes new function in the Where Clause DSL to support arbitrary grouping of conditions, and also use
8+
of a "not" condition. It should now be possible to write any type of where clause.
9+
10+
Additionally, there were significant updates to the Kotlin DSL - both to support the new functionality in the
11+
where clause, and significant updates to insert statements. There were also many minor updates in Kotlin
12+
to make more use of Kotlin language features like infix functions and operator overloads.
13+
714
GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/issues?q=milestone%3A1.4.0+](https://github.com/mybatis/mybatis-dynamic-sql/issues?q=milestone%3A1.4.0+)
815

916
1. Added support for arbitrary placement of nested criteria. For example, it is now
@@ -33,6 +40,10 @@ GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/issues?q=miles
3340
([#446](https://github.com/mybatis/mybatis-dynamic-sql/pull/446))
3441
6. Minor update the Kotlin join DSL to make it closer to natural SQL. The existing join methods are deprecated and
3542
will be removed in version 1.5.0. ([#447](https://github.com/mybatis/mybatis-dynamic-sql/pull/447))
43+
7. Updated most of the Kotlin insert DSL functions to be more like natural SQL. The main difference is that for insert,
44+
insertBatch, and insertMultiple, the "into" function is moved inside the completer lambda. The old methods are now
45+
deprecated and will be removed in version 1.5.0 of the library. This also allowed us to make some insert DSL
46+
methods into infix functions.
3647

3748
## Release 1.3.1 - December 18, 2021
3849

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

+28-28
Original file line numberDiff line numberDiff line change
@@ -349,13 +349,13 @@ import org.mybatis.dynamic.sql.util.kotlin.mybatis3.insert
349349

350350
fun PersonMapper.insert(row: PersonRecord) =
351351
insert(this::insert, row, Person) {
352-
map(id).toProperty("id")
353-
map(firstName).toProperty("firstName")
354-
map(lastName).toProperty("lastName")
355-
map(birthDate).toProperty("birthDate")
356-
map(employed).toProperty("employed")
357-
map(occupation).toProperty("occupation")
358-
map(addressId).toProperty("addressId")
352+
map(id) toProperty "id"
353+
map(firstName) toProperty "firstName"
354+
map(lastName) toProperty "lastName"
355+
map(birthDate) toProperty "birthDate"
356+
map(employed) toProperty "employed"
357+
map(occupation) toProperty "occupation"
358+
map(addressId) toProperty "addressId"
359359
}
360360
```
361361

@@ -440,13 +440,13 @@ method as follows:
440440

441441
```kotlin
442442
val rows = mapper.generalInsert {
443-
set(id).toValue(100)
444-
set(firstName).toValue("Joe")
445-
set(lastName).toValue(LastName("Jones"))
446-
set(employed).toValue(true)
447-
set(occupation).toValue("Developer")
448-
set(addressId).toValue(1)
449-
set(birthDate).toValue(Date())
443+
set(id) toValue 100
444+
set(firstName) toValue "Joe"
445+
set(lastName) toValue LastName("Jones")
446+
set(employed) toValue true
447+
set(occupation) toValue "Developer"
448+
set(addressId) toValue 1
449+
set(birthDate) toValue Date()
450450
}
451451
```
452452

@@ -532,13 +532,13 @@ fun PersonMapper.insertMultiple(vararg records: PersonRecord) =
532532

533533
fun PersonMapper.insertMultiple(records: Collection<PersonRecord>) =
534534
insertMultiple(this::insertMultiple, records, person) {
535-
map(id).toProperty("id")
536-
map(firstName).toProperty("firstName")
537-
map(lastName).toProperty("lastName")
538-
map(birthDate).toProperty("birthDate")
539-
map(employed).toProperty("employed")
540-
map(occupation).toProperty("occupation")
541-
map(addressId).toProperty("addressId")
535+
map(id) toProperty "id"
536+
map(firstName) toProperty "firstName"
537+
map(lastName) toProperty "lastName"
538+
map(birthDate) toProperty "birthDate"
539+
map(employed) toProperty "employed"
540+
map(occupation) toProperty "occupation"
541+
map(addressId) toProperty "addressId"
542542
}
543543
```
544544

@@ -677,13 +677,13 @@ fun PersonMapper.insertBatch(vararg records: PersonRecord): List<Int> =
677677

678678
fun PersonMapper.insertBatch(records: Collection<PersonRecord>): List<Int> =
679679
insertBatch(this::insert, records, person) {
680-
map(id).toProperty("id")
681-
map(firstName).toProperty("firstName")
682-
map(lastName).toProperty("lastName")
683-
map(birthDate).toProperty("birthDate")
684-
map(employed).toProperty("employed")
685-
map(occupation).toProperty("occupation")
686-
map(addressId).toProperty("addressId")
680+
map(id) toProperty "id"
681+
map(firstName) toProperty "firstName"
682+
map(lastName) toProperty "lastName"
683+
map(birthDate) toProperty "birthDate"
684+
map(employed) toProperty "employed"
685+
map(occupation) toProperty "occupation"
686+
map(addressId) toProperty "addressId"
687687
}
688688
```
689689

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

+43-31
Original file line numberDiff line numberDiff line change
@@ -228,20 +228,22 @@ data class PersonRecord(
228228

229229
val row = PersonRecord(100, "Joe", "Jones", Date(), true, "Developer", 1)
230230

231-
val insertRecordStatement = insert(row).into(person) {
232-
map(id).toProperty("id")
233-
map(firstName).toProperty("firstName")
234-
map(lastName).toProperty("lastName")
235-
map(birthDate).toProperty("birthDate")
236-
map(employed).toProperty("employedAsString")
231+
val insertRecordStatement = insert(row) {
232+
into(person)
233+
map(id) toProperty "id"
234+
map(firstName) toProperty "firstName"
235+
map(lastName) toProperty "lastName"
236+
map(birthDate) toProperty "birthDate"
237+
map(employed) toProperty "employedAsString"
237238
map(occupation).toPropertyWhenPresent("occupation", row::occupation)
238-
map(addressId).toProperty("addressId")
239+
map(addressId) toProperty "addressId"
239240
}
240241
```
241242

242243
This statement maps insert columns to properties in a class. Note the use of the `toPropertyWhenPresent` mapping - this
243244
will only set the insert value if the value of the property is non-null. Also note that you can use other mapping
244-
methods to map insert fields to nulls and constants if desired.
245+
methods to map insert fields to nulls and constants if desired. Many of the mappings can be called via infix
246+
as shown above.
245247

246248
This method creates models or providers depending on which package is used:
247249

@@ -260,13 +262,13 @@ The DSL for general insert statements looks like this:
260262

261263
```kotlin
262264
val generalInsertStatement = insertInto(person) {
263-
set(id).toValue(100)
264-
set(firstName).toValue("Joe")
265-
set(lastName).toValue("Jones")
266-
set(birthDate).toValue(Date())
267-
set(employed).toValue(true)
268-
set(occupation).toValue("Developer")
269-
set(addressId).toValue(1)
265+
set(id) toValue 100
266+
set(firstName) toValue "Joe"
267+
set(lastName) toValue "Jones"
268+
set(birthDate) toValue Date()
269+
set(employed) toValue true
270+
set(occupation) toValue "Developer"
271+
set(addressId) toValue 1
270272
}
271273
```
272274

@@ -302,19 +304,24 @@ The DSL for multi-row insert statements looks like this:
302304
val record1 = PersonRecord(100, "Joe", "Jones", Date(), true, "Developer", 1)
303305
val record2 = PersonRecord(101, "Sarah", "Smith", Date(), true, "Architect", 2)
304306

305-
val multiRowInsertStatement = insertMultiple(record1, record2).into(person) {
306-
map(id).toProperty("id")
307-
map(firstName).toProperty("firstName")
308-
map(lastName).toProperty("lastNameAsString")
309-
map(birthDate).toProperty("birthDate")
310-
map(employed).toProperty("employedAsString")
311-
map(occupation).toProperty("occupation")
312-
map(addressId).toProperty("addressId")
307+
val multiRowInsertStatement = insertMultiple(listOf(record1, record2)) {
308+
into(person)
309+
map(id) toProperty "id"
310+
map(firstName) toProperty "firstName"
311+
map(lastName) toProperty "lastNameAsString"
312+
map(birthDate) toProperty "birthDate"
313+
map(employed) toProperty "employedAsString"
314+
map(occupation) toProperty "occupation"
315+
map(addressId) toProperty "addressId"
313316
}
314317
```
315318

316319
Note there is no `toPropertyWhenPresent` mapping available on a multi-row insert.
317320

321+
Also note that there is no overload of this function that accepts a vararg of rows because it would cause an overload
322+
resolution ambiguity error. This limitation is overcome in the utility functions for MyBatis and Spring as shown on
323+
the documentation pages for those utilities.
324+
318325
This method creates models or providers depending on which package is used:
319326

320327
| Package | Resulting Object |
@@ -340,19 +347,24 @@ The DSL for batch insert statements looks like this:
340347
val record1 = PersonRecord(100, "Joe", "Jones", Date(), true, "Developer", 1)
341348
val record2 = PersonRecord(101, "Sarah", "Smith", Date(), true, "Architect", 2)
342349

343-
val batchInsertStatement = insertBatch(record1, record2).into(person) {
344-
map(id).toProperty("id")
345-
map(firstName).toProperty("firstName")
346-
map(lastName).toProperty("lastNameAsString")
347-
map(birthDate).toProperty("birthDate")
348-
map(employed).toProperty("employedAsString")
349-
map(occupation).toProperty("occupation")
350-
map(addressId).toProperty("addressId")
350+
val batchInsertStatement = insertBatch(listOf(record1, record2)) {
351+
into(person)
352+
map(id) toProperty "id"
353+
map(firstName) toProperty "firstName"
354+
map(lastName) toProperty "lastNameAsString"
355+
map(birthDate) toProperty "birthDate"
356+
map(employed) toProperty "employedAsString"
357+
map(occupation) toProperty "occupation"
358+
map(addressId) toProperty "addressId"
351359
}
352360
```
353361

354362
Note there is no `toPropertyWhenPresent` mapping available on a batch insert.
355363

364+
Also note that there is no overload of this function that accepts a vararg of rows because it would cause an overload
365+
resolution ambiguity error. This limitation is overcome in the utility functions for MyBatis and Spring as shown on
366+
the documentation pages for those utilities.
367+
356368
This method creates models or providers depending on which package is used:
357369

358370
| Package | Resulting Object |

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

+57-52
Original file line numberDiff line numberDiff line change
@@ -196,14 +196,15 @@ Single record insert statements can be constructed and executed in a single step
196196
```kotlin
197197
val row = PersonRecord(100, "Joe", "Jones", Date(), true, "Developer", 1)
198198

199-
val rows = template.insert(row).into(Person) {
200-
map(id).toProperty("id")
201-
map(firstName).toProperty("firstName")
202-
map(lastName).toProperty("lastName")
203-
map(birthDate).toProperty("birthDate")
204-
map(employed).toProperty("employedAsString")
199+
val rows = template.insert(row) {
200+
into(Person)
201+
map(id) toProperty "id"
202+
map(firstName) toProperty "firstName"
203+
map(lastName) toProperty "lastName"
204+
map(birthDate) toProperty "birthDate"
205+
map(employed) toProperty "employedAsString"
205206
map(occupation).toPropertyWhenPresent("occupation", row::occupation)
206-
map(addressId).toProperty("addressId")
207+
map(addressId) toProperty "addressId"
207208
}
208209
```
209210

@@ -217,14 +218,15 @@ val keyHolder = GeneratedKeyHolder()
217218
val row = PersonRecord(100, "Joe", "Jones", Date(), true, "Developer", 1)
218219

219220
val rows = template.withKeyHolder(keyHolder) {
220-
insert(row).into(Person) {
221-
map(id).toProperty("id")
222-
map(firstName).toProperty("firstName")
223-
map(lastName).toProperty("lastName")
224-
map(birthDate).toProperty("birthDate")
225-
map(employed).toProperty("employedAsString")
221+
insert(row) {
222+
into(Person)
223+
map(id) toProperty"id"
224+
map(firstName) toProperty "firstName"
225+
map(lastName) toProperty "lastName"
226+
map(birthDate) toProperty "birthDate"
227+
map(employed) toProperty "employedAsString"
226228
map(occupation).toPropertyWhenPresent("occupation", row::occupation)
227-
map(addressId).toProperty("addressId")
229+
map(addressId) toProperty "addressId"
228230
}
229231
}
230232
```
@@ -255,13 +257,13 @@ General insert statements can be constructed and executed in a single step with
255257
val myOccupation = "Developer"
256258

257259
val rows = template.insertInto(Person) {
258-
set(id).toValue(100)
259-
set(firstName).toValue("Joe")
260-
set(lastName).toValue("Jones")
261-
set(birthDate).toValue(Date())
262-
set(employed).toValue(true)
263-
set(occupation).toValueWhenPresent(myOccupation)
264-
set(addressId).toValue(1)
260+
set(id) toValue 100
261+
set(firstName) toValue "Joe"
262+
set(lastName) toValue "Jones"
263+
set(birthDate) toValue Date()
264+
set(employed) toValue true
265+
set(occupation) toValueWhenPresent myOccupation
266+
set(addressId) toValue 1
265267
}
266268
```
267269

@@ -276,13 +278,13 @@ val myOccupation = "Developer"
276278

277279
val rows = template.withKeyHolder(keyHolder) {
278280
insertInto(Person) {
279-
set(id).toValue(100)
280-
set(firstName).toValue("Joe")
281-
set(lastName).toValue("Jones")
282-
set(birthDate).toValue(Date())
283-
set(employed).toValue(true)
284-
set(occupation).toValueWhenPresent(myOccupation)
285-
set(addressId).toValue(1)
281+
set(id) toValue 100
282+
set(firstName) toValue "Joe"
283+
set(lastName) toValue "Jones"
284+
set(birthDate) toValue Date()
285+
set(employed) toValue true
286+
set(occupation) toValueWhenPresent myOccupation
287+
set(addressId) toValue 1
286288
}
287289
}
288290
```
@@ -313,14 +315,15 @@ Multi-Row insert statements can be constructed and executed in a single step wit
313315
val record1 = PersonRecord(100, "Joe", LastName("Jones"), Date(), true, "Developer", 1)
314316
val record2 = PersonRecord(101, "Sarah", LastName("Smith"), Date(), true, "Architect", 2)
315317

316-
val rows = template.insertMultiple(record1, record2).into(Person) {
317-
map(id).toProperty("id")
318-
map(firstName).toProperty("firstName")
319-
map(lastName).toProperty("lastNameAsString")
320-
map(birthDate).toProperty("birthDate")
321-
map(employed).toProperty("employedAsString")
322-
map(occupation).toProperty("occupation")
323-
map(addressId).toProperty("addressId")
318+
val rows = template.insertMultiple(record1, record2) {
319+
into(Person)
320+
map(id) toProperty "id"
321+
map(firstName) toProperty "firstName"
322+
map(lastName) toProperty "lastNameAsString"
323+
map(birthDate) toProperty "birthDate"
324+
map(employed) toProperty "employedAsString"
325+
map(occupation) toProperty "occupation"
326+
map(addressId) toProperty "addressId"
324327
}
325328
```
326329

@@ -332,14 +335,15 @@ val record1 = PersonRecord(100, "Joe", LastName("Jones"), Date(), true, "Develop
332335
val record2 = PersonRecord(101, "Sarah", LastName("Smith"), Date(), true, "Architect", 2)
333336

334337
val rows = template.withKeyHolder(keyHolder) {
335-
insertMultiple(record1, record2).into(Person) {
336-
map(id).toProperty("id")
337-
map(firstName).toProperty("firstName")
338-
map(lastName).toProperty("lastNameAsString")
339-
map(birthDate).toProperty("birthDate")
340-
map(employed).toProperty("employedAsString")
341-
map(occupation).toProperty("occupation")
342-
map(addressId).toProperty("addressId")
338+
insertMultiple(record1, record2) {
339+
into(Person)
340+
map(id) toProperty "id"
341+
map(firstName) toProperty "firstName"
342+
map(lastName) toProperty "lastNameAsString"
343+
map(birthDate) toProperty "birthDate"
344+
map(employed) toProperty "employedAsString"
345+
map(occupation) toProperty "occupation"
346+
map(addressId) toProperty "addressId"
343347
}
344348
}
345349
```
@@ -365,14 +369,15 @@ Batch statements can be constructed and executed in a single step with code like
365369
val record1 = PersonRecord(100, "Joe", LastName("Jones"), Date(), true, "Developer", 1)
366370
val record2 = PersonRecord(101, "Sarah", LastName("Smith"), Date(), true, "Architect", 2)
367371

368-
val rows = template.insertBatch(record1, record2).into(Person) {
369-
map(id).toProperty("id")
370-
map(firstName).toProperty("firstName")
371-
map(lastName).toProperty("lastNameAsString")
372-
map(birthDate).toProperty("birthDate")
373-
map(employed).toProperty("employedAsString")
374-
map(occupation).toProperty("occupation")
375-
map(addressId).toProperty("addressId")
372+
val rows = template.insertBatch(record1, record2) {
373+
into(Person)
374+
map(id) toProperty "id"
375+
map(firstName) toProperty "firstName"
376+
map(lastName) toProperty "lastNameAsString"
377+
map(birthDate) toProperty "birthDate"
378+
map(employed) toProperty "employedAsString"
379+
map(occupation) toProperty "occupation"
380+
map(addressId) toProperty "addressId"
376381
}
377382
```
378383

0 commit comments

Comments
 (0)