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

Lines changed: 11 additions & 0 deletions
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

Lines changed: 28 additions & 28 deletions
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

Lines changed: 43 additions & 31 deletions
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

Lines changed: 57 additions & 52 deletions
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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy