docs/kotlinMyBatis3.html

<!DOCTYPE html>


<!--
 | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from src/site/markdown/docs/kotlinMyBatis3.md at 03 Jun 2024
 | Rendered using Apache Maven Fluido Skin 2.0.0-M9
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" />
    <title>MyBatis Dynamic SQL</title>
    <link rel="stylesheet" href="../css/apache-maven-fluido-2.0.0-M9.min.css" />
    <link rel="stylesheet" href="../css/site.css" />
    <link rel="stylesheet" href="../css/print.css" media="print" />
    <script src="../js/apache-maven-fluido-2.0.0-M9.min.js"></script>
  </head>
  <body>
    <div class="container-fluid container-fluid-top">
      <header>
        <div id="banner">
          <div class="pull-left"><div id="bannerLeft"><h1><a href="../docs/introduction.html">MyBatis Dynamic SQL</a></h1></div></div>
          <div class="pull-right"><div id="bannerRight"><h1><a href="http://www.mybatis.org/" class="externalLink"><img class="imageLink" src="https://mybatis.org/images/mybatis-logo.png" alt="MyBatis logo" /> MyBatis</a></h1></div></div>
          <div class="clear"><hr/></div>
        </div>

        <div id="breadcrumbs">
          <ul class="breadcrumb">
        <li id="publishDate">Last Published: 03 Jun 2024<span class="divider">|</span>
</li>
          <li id="projectVersion">Version: 1.5.2</li>
          </ul>
        </div>
      </header>
      <div class="row-fluid">
        <header id="leftColumn" class="span2">
          <nav class="well sidebar-nav">
  <ul class="nav nav-list">
   <li class="nav-header">User&apos;s Guide</li>
    <li><a href="../docs/introduction.html">Introduction</a></li>
    <li><a href="../docs/CHANGELOG.html">Change Log</a></li>
    <li><a href="../docs/quickStart.html">Quick Start</a></li>
    <li><a href="../docs/exceptions.html">Exceptions thrown by the Library</a></li>
    <li><a href="../docs/configuration.html">Configuration of the Library</a></li>
    <li><a href="../docs/databaseObjects.html">Modeling Database Objects</a></li>
    <li><a href="../docs/whereClauses.html"><span class="icon-chevron-down"></span>WHERE Clause Support</a>
     <ul class="nav nav-list">
      <li><a href="../docs/conditions.html">WHERE Conditions</a></li>
     </ul></li>
    <li><a href="../docs/select.html"><span class="icon-chevron-down"></span>SELECT Statements</a>
     <ul class="nav nav-list">
      <li><a href="../docs/caseExpressions.html">Case Expressions</a></li>
      <li><a href="../docs/complexQueries.html">Complex Queries</a></li>
     </ul></li>
    <li><a href="../docs/delete.html">DELETE Statements</a></li>
    <li><a href="../docs/insert.html">INSERT Statements</a></li>
    <li><a href="../docs/update.html">UPDATE Statements</a></li>
    <li><a href="../docs/subQueries.html">SubQuery Support</a></li>
    <li><a href="../docs/functions.html">Database Functions</a></li>
    <li><a href="../docs/mybatis3.html">MyBatis3 Support</a></li>
    <li><a href="../docs/spring.html">Spring Support</a></li>
    <li><a href="../docs/springBatch.html">Spring Batch Support</a></li>
    <li><a href="../docs/kotlinOverview.html"><span class="icon-chevron-down"></span>Kotlin Support</a>
     <ul class="nav nav-list">
      <li><a href="../docs/kotlinCaseExpressions.html">Kotlin Case Expressions</a></li>
      <li><a href="../docs/kotlinWhereClauses.html">Kotlin Where Clauses</a></li>
      <li class="active"><a>Kotlin Support for MyBatis3</a></li>
      <li><a href="../docs/kotlinSpring.html">Kotlin Support for Spring</a></li>
     </ul></li>
    <li><a href="../docs/howItWorks.html">How it Works</a></li>
    <li><a href="../docs/extending.html">Extending the Library</a></li>
    <li><a href="../docs/codingStandards.html">Coding Standards</a></li>
    <li><a href="../docs/motivation.html">Motivation</a></li>
   <li class="nav-header">Project Documentation</li>
    <li><a href="../project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li>
    <li><a href="../project-reports.html"><span class="icon-chevron-right"></span>Project Reports</a></li>
  </ul>
          </nav>
          <div class="well sidebar-nav">
            <div id="poweredBy">
              <div class="clear"></div>
              <div class="clear"></div>
<a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a>
            </div>
          </div>
        </header>
        <main id="bodyColumn" class="span10">
<section><a id="Kotlin_Support_for_MyBatis3"></a>
<h1>Kotlin Support for MyBatis3</h1>
<p>MyBatis Dynamic SQL includes Kotlin extensions for MyBatis3 that simplify execution of statements generated by the
library.</p>
<p>The standard usage patterns for MyBatis Dynamic SQL and MyBatis3 in Java must be modified somewhat for Kotlin.
Kotlin interfaces can contain both abstract and non-abstract methods (somewhat similar to Java's default methods in
an interface). Using these methods in Kotlin based mapper interfaces will cause a failure with MyBatis because of the
underlying Kotlin implementation.</p>
<p>This page will show our recommended pattern for using the MyBatis Dynamic SQL with Kotlin and MyBatis3.
The code shown on this page is from the <code>src/test/kotlin/examples/kotlin/mybatis3/canonical</code> directory in this
repository. That directory contains a complete example of using this library with Kotlin.</p>
<p>All Kotlin support is available in the following packages:</p>
<ul>

<li><code>org.mybatis.dynamic.sql.util.kotlin</code> - contains DSL support classes</li>
<li><code>org.mybatis.dynamic.sql.util.kotlin.elements</code> - contains the basic DSL elements common to all runtimes</li>
<li><code>org.mybatis.dynamic.sql.util.kotlin.mybatis3</code> - contains utilities specifically to simplify MyBatis3 based clients</li>
</ul>
<p>Using the support in these packages, it is possible to create reusable Kotlin classes, interfaces, and extension methods
that simplify usage of the library with MyBatis3.</p>
<p>The Kotlin support for MyBatis3 is implemented as utility functions that can be used with MyBatis3 mapper interfaces.
There are functions to support count, delete, insert, select, and update operations based on SQL generated by this
library. For each operation, there are two different methods of executing SQL:</p>
<ol style="list-style-type: decimal;">

<li>The first method is a two-step method. With this method you build SQL provider objects as shown on the Kotlin
overview page and then execute the generated SQL by passing the provider to a MyBatis3 mapper method</li>
<li>The second method is a one-step method that uses utility functions to combine these operations into a single step.
With this method it is common to build extension methods for MyBatis3 mappers that are specific to a table
(this is the code that MyBatis Generator will create)</li>
</ol>
<p>We will illustrate both approaches below.</p><section><a id="Kotlin_Dynamic_SQL_Support_Objects"></a>
<h2>Kotlin Dynamic SQL Support Objects</h2>
<p>The pattern for the meta-model is the same as shown on the Kotlin overview page. We'll repeat it here to show some
specifics for MyBatis3.</p>

<pre><code class="language-kotlin">import org.mybatis.dynamic.sql.AlisableSqlTable
import org.mybatis.dynamic.sql.util.kotlin.elements.column
import java.sql.JDBCType
import java.util.Date

object PersonDynamicSqlSupport {
    val person = Person()
    val id = person.id
    val firstName = person.firstName
    val lastName = person.lastName
    val birthDate = person.birthDate
    val employed = person.employed
    val occupation = person.occupation
    val addressId = person.addressId

    class Person : AlisableSqlTable&lt;Person&gt;(&quot;Person&quot;, ::Person) {
        val id = column&lt;Int&gt;(name = &quot;id&quot;, jdbcType = JDBCType.INTEGER)
        val firstName = column&lt;String&gt;(name = &quot;first_name&quot;, jdbcType = JDBCType.VARCHAR)
        val lastName = column(
            name = &quot;last_name&quot;,
            jdbcType = JDBCType.VARCHAR,
            typeHandler = &quot;foo.bar.LastNameTypeHandler&quot;
        )
        val birthDate = column&lt;Date&gt;(name = &quot;birth_date&quot;, jdbcType = JDBCType.DATE)
        val employed = column(
            name = &quot;employed&quot;,
            jdbcType = JDBCType.VARCHAR,
            typeHandler = &quot;foo.bar.StringToBooleanTypeHandler&quot;
        )
        val occupation = column&lt;String&gt;(name = &quot;occupation&quot;, jdbcType = JDBCType.VARCHAR)
        val addressId = column&lt;Int&gt;(name = &quot;address_id&quot;, jdbcType = JDBCType.INTEGER)
    }
}
</code></pre>
<p>Note the use of a &#x201c;type handler&#x201d; on the <code>employed</code> and <code>lastName</code> columns. This allows us to use the column as a Boolean in
Kotlin, but store the values &#x201c;Yes&#x201d; or &#x201c;No&#x201d; on the database. This uses the MyBatis3 standard type handler support.</p>
<p>Also note that we specify the &#x201c;jdbcType&#x201d; for each column. This is a best practice with MyBatis3 and will avoid errors
will nullable fields.</p></section><section><a id="About_MyBatis_Mappers"></a>
<h2>About MyBatis Mappers</h2>
<p>Many MyBatis operations can be standardized, and you can use functionality in this library to dramatically reduce the
amount of boilerplate code you need to write. In particular, all COUNT, DELETE, and UPDATE statements can be executed
with utilities built into the library. The examples below will show how this works.</p>
<p>Many INSERT statements can also be executed with built-in utilities. The only INSERT statements that require custom
coding are INSERT statements that return generated keys. For these statements, you must code a custom mapper method
with the MyBatis <code>@Options</code> annotation specifying how to retrieve generated keys.</p>
<p>SELECT statements present unique challenges. One of the key functions of MyBatis is the mapping of result sets to
objects. This is a very useful capability, but it requires that the mapping between result set and object be predefined
and hard coded. Some SELECT statements can be executed without coding custom result maps. This library includes common
SELECT support with the following capabilities:</p>
<ul>

<li>Execute arbitrary SELECT statements and return <code>List&lt;Map&lt;String, Object&gt;&gt;</code> as the return value. This support
essentially bypasses MyBatis' result mapping capabilities and returns a low level list of results.</li>
<li>Execute SELECT statements that return a single column of various types (String, Integer, BigDecimal, etc.)</li>
</ul>
<p>The bottom line is this - if your query returns more than one column, and you want to utilize MyBatis' result mapping
functionality, you will need to code a custom result mapping.</p>
<p>This library was initially conceived as a tool to improve the code created by MyBatis Generator - and the &#x201c;one step&#x201d;
methods shown below are based on the convention used by MyBatis generator where a set of mapper methods is created
for each table individually. If you are not using MyBatis generator, or are adding custom queries such as join
queries to an application bootstrapped with MyBatis Generator, then it is likely you will need to code custom
SELECT methods with custom result maps.</p></section><section><a id="Kotlin_Mappers_for_MyBatis"></a>
<h2>Kotlin Mappers for MyBatis</h2>
<p>The pattern we recommend involves two types of mapper methods: standard MyBatis mapper methods and extension methods.</p>
<p>The standard MyBatis mapper abstract methods accept Provider objects created by the library. These methods use the
normal MyBatis annotations to specify result mappings, generated key mappings, statement types, etc. Using these
methods directly involves two steps: create the provider object, then execute the MyBatis call.</p>
<p>The extension methods will reuse the abstract methods and add functionality to mappers that will build and
execute the SQL statements in a one-step process. The extension methods shown below assume that you will create
a set of CRUD methods for each table you are accessing (as is the case with code created by MyBatis Generator).</p>
<p>If you create a Kotlin mapper interface that includes both abstract and non-abstract methods, MyBatis will
throw errors. By default, Kotlin does not create Java default methods in an interface. For this reason, Kotlin
mapper interfaces should only contain the actual MyBatis mapper abstract interface methods. What would normally be coded
as default or static methods in a Java mapper interface should be coded as extension methods in Kotlin. For example,
a simple MyBatis mapper could be coded like this:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper {
    @SelectProvider(type = SqlProviderAdapter::class, method = &quot;select&quot;)
    @Results(id = &quot;PersonRecordResult&quot;, value = [
        Result(column = &quot;a_id&quot;, property = &quot;id&quot;),
        Result(column = &quot;first_name&quot;, property = &quot;firstName&quot;),
        Result(column = &quot;last_name&quot;, property = &quot;lastName&quot;),
        Result(column = &quot;birth_date&quot;, property = &quot;birthDate&quot;),
        Result(column = &quot;employed&quot;, property = &quot;employed&quot;, typeHandler = YesNoTypeHandler::class),
        Result(column = &quot;occupation&quot;, property = &quot;occupation&quot;),
        Result(column = &quot;address_id&quot;, property = &quot;addressId&quot;)
    ])
    fun selectMany(selectStatement: SelectStatementProvider): List&lt;PersonRecord&gt;
}
</code></pre>
<p>Then extensions could be added to make a shortcut method as follows:</p>

<pre><code class="language-kotlin">import org.mybatis.dynamic.sql.util.kotlin.SelectCompleter
import org.mybatis.dynamic.sql.util.kotlin.mybatis3.selectList
import org.mybatis.dynamic.sql.util.kotlin.elements.`as`

private val columnList = listOf(id `as` &quot;A_ID&quot;, firstName, lastName, birthDate, employed, occupation, addressId)

fun PersonMapper.select(completer: SelectCompleter) =
    selectList(this::selectMany, columnList, Person, completer)
</code></pre>
<p>The extension method shows the use of the <code>SelectCompleter</code> type alias. This is a DSL extension supplied with the
library. We will detail its use below. For now see that the extension method can be used in client code to supply a
where clause and an order by clause as follows:</p>

<pre><code class="language-kotlin">val rows = mapper.select {
    where { id isLessThan 100 }
    or {
        employed.isTrue()
        and { occupation isEqualTo &quot;Developer&quot; }
    }
    orderBy(id)
}
</code></pre></section><section><a id="Count_Statements"></a>
<h2>Count Statements</h2><section><a id="Two-Step_Method"></a>
<h3>Two-Step Method</h3>
<p>Count statements are constructed as shown on the Kotlin overview page. These methods create a
<code>SelectStatementProvider</code> that can be executed with a MyBatis3 mapper method. MyBatis3 mappers should declare
a <code>count</code> method as follows:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper {
    @SelectProvider(type = SqlProviderAdapter::class, method = &quot;select&quot;)
    fun count(selectStatement: SelectStatementProvider): Long
}
</code></pre>
<p>This is a standard method for MyBatis Dynamic SQL that executes a query and returns a <code>Long</code>. This method can also be
implemented by using a built-in base interface as follows:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper : CommonCountMapper
</code></pre>
<p><code>CommonCountMapper</code> can also be used on its own if you inject it into a MyBatis configuration.</p>
<p>The mapper method can be used as follows:</p>

<pre><code class="language-kotlin">val countStatement = count() // not shown... see the overview page for examples
val mapper: PersonMapper = getMapper() // not shown
val rows: Long = mapper.count(countStatement)
</code></pre></section><section><a id="One-Step_Method"></a>
<h3>One-Step Method</h3>
<p>You can use built-in utility functions to create mapper extension functions that simplify execution of count statements.
The extension functions will reuse the abstract method and supply everything needed to build the select statement
except the where clause:</p>

<pre><code class="language-kotlin">import org.mybatis.dynamic.sql.util.kotlin.CountCompleter
import org.mybatis.dynamic.sql.util.kotlin.mybatis3.count
import org.mybatis.dynamic.sql.util.kotlin.mybatis3.countDistinct
import org.mybatis.dynamic.sql.util.kotlin.mybatis3.countFrom

fun PersonMapper.count(completer: CountCompleter) = // count(*)
    countFrom(this::count, person, completer)

fun PersonMapper.count(column: BasicColumn, completer: CountCompleter) = // count(column)
    count(this::count, column, person, completer)

fun PersonMapper.countDistinct(column: BasicColumn, completer: CountCompleter) = // count(distinct column)
    countDistinct(this::count, column, person, completer)
</code></pre>
<p>The methods are constructed to execute count queries on one specific table - <code>person</code> in this case.</p>
<p>The methods show the use of <code>CountCompleter</code> which is a Kotlin typealias for a function with a receiver that will
allow a user to supply a where clause. This also shows use of the Kotlin <code>countFrom</code>, <code>count</code>, and <code>countDistinct</code>
methods which are supplied by the library. Those methods will build and execute the select count statements with the
supplied where clause. Clients can use the methods as follows:</p>

<pre><code class="language-kotlin">val rows = mapper.count {
    where { occupation.isNull() }
    and { employed.isFalse() }
}
</code></pre>
<p>There is also a method that can be used to count all rows in a table:</p>

<pre><code class="language-kotlin">val rows = mapper.count { allRows() }
</code></pre></section></section><section><a id="Delete_Method_Support"></a>
<h2>Delete Method Support</h2><section><a id="Two-Step_Method_1"></a>
<h3>Two-Step Method</h3>
<p>Delete statements are constructed as shown on the Kotlin overview page. This method creates a
<code>DeleteStatementProvider</code> that can be executed with a MyBatis3 mapper method. MyBatis3 mappers should declare
a <code>delete</code> method as follows:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper {
   @DeleteProvider(type = SqlProviderAdapter::class, method = &quot;delete&quot;)
   fun delete(deleteStatement: DeleteStatementProvider): Int
}
</code></pre>
<p>This is a standard method for MyBatis Dynamic SQL that executes a query and returns an <code>Int</code> - the number of rows
deleted. This method can also be implemented by using a built-in base interface as follows:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper : CommonDeleteMapper
</code></pre>
<p><code>CommonDeleteMapper</code> can also be used on its own if you inject it into a MyBatis configuration.</p>
<p>The mapper method can be used as follows:</p>

<pre><code class="language-kotlin">val deleteStatement = deleteFrom() // not shown... see the overview page for examples
val mapper: PersonMapper = getMapper() // not shown
val rows: Int = mapper.delete(deleteStatement)
</code></pre></section><section><a id="One-Step_Method_1"></a>
<h3>One-Step Method</h3>
<p>You can use built-in utility functions to create mapper extension functions that simplify execution of delete statements.
The extension functions will reuse the abstract method and supply everything needed to build the delete statement
except the where clause:</p>

<pre><code class="language-kotlin">import org.mybatis.dynamic.sql.util.kotlin.DeleteCompleter
import org.mybatis.dynamic.sql.util.kotlin.mybatis3.deleteFrom

fun PersonMapper.delete(completer: DeleteCompleter) =
    deleteFrom(this::delete, person, completer)
</code></pre>
<p>The method is constructed to execute delete statements on one specific table - <code>person</code> in this case.</p>
<p>The method shows the use of <code>DeleteCompleter</code> which is a Kotlin typealias for a function with a receiver that will
allow a user to supply a where clause. This also shows use of the Kotlin <code>deleteFrom</code> method which are supplied by the
library. Those methods will build and execute the delete statement with the supplied where clause. Clients can use the
method as follows:</p>

<pre><code class="language-kotlin">val rows = mapper.delete {
    where { occupation.isNull() }
}
</code></pre>
<p>There is an extension method that can be used to delete all rows in a table:</p>

<pre><code class="language-kotlin">val rows = mapper.delete { allRows() }
</code></pre></section></section><section><a id="Single_Row_Insert_Statement"></a>
<h2>Single Row Insert Statement</h2><section><a id="Two-Step_Method_2"></a>
<h3>Two-Step Method</h3>
<p>Single row insert statements are constructed as shown on the Kotlin overview page. This method creates
an <code>InsertStatementProvider</code>  that can be executed with a MyBatis3 mapper method. MyBatis3 mappers should declare
an <code>insert</code> method as follows:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper {
    @InsertProvider(type = SqlProviderAdapter::class, method = &quot;insert&quot;)
    fun insert(insertStatement: InsertStatementProvider&lt;PersonRecord&gt;): Int
}
</code></pre>
<p>This is a standard method for MyBatis Dynamic SQL that executes an insert and returns a <code>Int</code> - the number of rows
inserted. This method can also be implemented by using a built-in base interface as follows:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper : CommonInsertMapper&lt;T&gt;
</code></pre>
<p><code>CommonInsertMapper</code> can also be used on its own if you inject it into a MyBatis configuration.</p>
<p>The mapper method can be used as follows:</p>

<pre><code class="language-kotlin">val insertStatement = insert() // not shown, see overview page
val mapper: PersonMapper = getMapper() // not shown
val rows: Int = mapper.insert(insertStatement)
</code></pre></section><section><a id="One-Step_Method_2"></a>
<h3>One-Step Method</h3>
<p>You can use built-in utility functions to create mapper extension functions that simplify execution of single record
insert statements. The extension functions will reuse the abstract method and supply everything needed to build the
insert statement:</p>

<pre><code class="language-kotlin">import org.mybatis.dynamic.sql.util.kotlin.mybatis3.insert

fun PersonMapper.insert(row: PersonRecord) =
    insert(this::insert, row, Person) {
        map(id) toProperty &quot;id&quot;
        map(firstName) toProperty &quot;firstName&quot;
        map(lastName) toProperty &quot;lastName&quot;
        map(birthDate) toProperty &quot;birthDate&quot;
        map(employed) toProperty &quot;employed&quot;
        map(occupation) toProperty &quot;occupation&quot;
        map(addressId) toProperty &quot;addressId&quot;
    }
</code></pre>
<p>This extension method reuses the mapper method and supplies all the column mappings. Clients can use the method
as follows:</p>

<pre><code class="language-kotlin">val record = PersonRecord(100, &quot;Joe&quot;, LastName(&quot;Jones&quot;), Date(), true, &quot;Developer&quot;, 1)
val mapper: PersonMapper = getMapper() // not shown
val rows = mapper.insert(record)
</code></pre></section><section><a id="Generated_Key_Support"></a>
<h3>Generated Key Support</h3>
<p>Single record insert statements support returning a generated key using normal MyBatis generated key support. When
generated keys are expected you must code the mapper method manually and supply the <code>@Options</code> annotation that
configures generated key support. You cannot use the built-in base interface when there are generated keys. For example:</p>

<pre><code class="language-kotlin">interface GeneratedAlwaysMapper {
    @InsertProvider(type = SqlProviderAdapter::class, method = &quot;insert&quot;)
    @Options(useGeneratedKeys = true, keyProperty = &quot;row.id,row.fullName&quot;, keyColumn = &quot;id,full_name&quot;)
    fun insert(insertStatement: InsertStatementProvider&lt;GeneratedAlwaysRecord&gt;): Int
}
</code></pre>
<p>This method will return two generated values in each row: <code>id</code> and <code>full_name</code>. The values will be placed into the
row properties <code>id</code> and <code>fullName</code> respectively.</p></section></section><section><a id="General_Insert_Statement"></a>
<h2>General Insert Statement</h2><section><a id="Two-Step_Method_3"></a>
<h3>Two-Step Method</h3>
<p>General insert statements are constructed as shown on the Kotlin overview page. This method creates
a <code>GeneralInsertStatementProvider</code>  that can be executed with a MyBatis3 mapper method. MyBatis3 mappers should declare
a <code>generalInsert</code> method as follows:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper {
    @InsertProvider(type = SqlProviderAdapter::class, method = &quot;generalInsert&quot;)
    fun generalInsert(insertStatement: GeneralInsertStatementProvider): Int
}
</code></pre>
<p>This is a standard method for MyBatis Dynamic SQL that executes an insert and returns a <code>Int</code> - the number of rows
inserted. This method can also be implemented by using a built-in base interface as follows:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper : CommonInsertMapper&lt;T&gt;
</code></pre>
<p><code>CommonInsertMapper</code> can also be used on its own if you inject it into a MyBatis configuration.</p>
<p>The mapper method can be used as follows:</p>

<pre><code class="language-kotlin">val insertStatement = insertInto() // not shown, see overview page
val mapper: PersonMapper = getMapper() // not shown
val rows: Int = mapper.generalInsert(insertStatement)
</code></pre></section><section><a id="One-Step_Method_3"></a>
<h3>One-Step Method</h3>
<p>You can use built-in utility functions to create mapper extension functions that simplify execution of general
insert statements. The extension functions will reuse the abstract method and supply everything needed to build the
insert statement except the values to insert:</p>

<pre><code class="language-kotlin">import org.mybatis.dynamic.sql.util.kotlin.GeneralInsertCompleter
import org.mybatis.dynamic.sql.util.kotlin.mybatis3.insertInto

fun PersonMapper.generalInsert(completer: GeneralInsertCompleter) =
    insertInto(this::generalInsert, person, completer)
</code></pre>
<p>The method is constructed to execute insert statements on one specific table - <code>person</code> in this case.</p>
<p>The method shows the use of <code>GeneralInsertCompleter</code> which is a Kotlin typealias for a function with a receiver that will
allow a user to supply values to insert. This also shows use of the Kotlin <code>insertInto</code> method which are supplied by the
library. Those methods will build and execute the insert statement with the supplied values. Clients can use the
method as follows:</p>

<pre><code class="language-kotlin">val rows = mapper.generalInsert {
    set(id) toValue 100
    set(firstName) toValue &quot;Joe&quot;
    set(lastName) toValue LastName(&quot;Jones&quot;)
    set(employed) toValue true
    set(occupation) toValue &quot;Developer&quot;
    set(addressId) toValue 1
    set(birthDate) toValue Date()
}
</code></pre></section><section><a id="Generated_Key_Support_1"></a>
<h3>Generated Key Support</h3>
<p>You cen retrieve generated keys from general insert statements if you use the two-step method.
You cannot use the built-in base interface when there are generated keys. First, code the
abstract mapper method as follows:</p>

<pre><code class="language-kotlin">interface GeneratedAlwaysMapper {
    @InsertProvider(type = SqlProviderAdapter::class, method = &quot;generalInsert&quot;)
    @Options(useGeneratedKeys = true, keyProperty=&quot;parameters.id,parameters.fullName&quot;, keyColumn = &quot;id,full_name&quot;)
    fun generalInsert(insertStatement: GeneralInsertStatementProvider): Int
}
</code></pre>
<p>This method will return two generated values: <code>id</code> and <code>full_name</code>. The values will be placed into the
parameter map in the <code>GeneralInsertStatementProvider</code> with keys <code>id</code> and <code>fullName</code> respectively.</p>
<p>The method can be used as follows:</p>

<pre><code class="language-kotlin">val mapper = getMapper() // not shown
val insertStatement = insertInto(generatedAlways) {
    set(firstName).toValue(&quot;Fred&quot;)
    set(lastName).toValue(&quot;Flintstone&quot;)
}

val rows = mapper.generalInsert(insertStatement)
</code></pre>
<p>After the statement completes, then generated keys are available in the mapper:</p>

<pre><code class="language-kotlin">val id = insertStatement.parameters[&quot;id&quot;] as Int
val fullName = insertStatement.parameters[&quot;fullName&quot;] as String
</code></pre></section></section><section><a id="Multi-Row_Insert_Statement"></a>
<h2>Multi-Row Insert Statement</h2><section><a id="Two-Step_Method_4"></a>
<h3>Two-Step Method</h3>
<p>Multi-row insert statements are constructed as shown on the Kotlin overview page. This method creates
a <code>MultiRowInsertStatementProvider</code> that can be executed with a MyBatis3 mapper method. MyBatis3 mappers should declare
an <code>insertMultiple</code> method as follows:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper {
    @InsertProvider(type = SqlProviderAdapter::class, method = &quot;insertMultiple&quot;)
    fun insertMultiple(insertStatement: MultiRowInsertStatementProvider&lt;PersonRecord&gt;): Int
}
</code></pre>
<p>This is a standard method for MyBatis Dynamic SQL that executes an insert and returns a <code>Int</code> - the number of rows
inserted. This method can also be implemented by using a built-in base interface as follows:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper : CommonInsertMapper&lt;T&gt;
</code></pre>
<p><code>CommonInsertMapper</code> can also be used on its own if you inject it into a MyBatis configuration.</p>
<p>The mapper method can be used as follows:</p>

<pre><code class="language-kotlin">val insertStatement = insertMultiple() // not shown, see overview page
val mapper: PersonMapper = getMapper() // not shown
val rows: Int = mapper.insertMultiple(insertStatement)
</code></pre></section><section><a id="One-Step_Method_4"></a>
<h3>One-Step Method</h3>
<p>You can use built-in utility functions to create mapper extension functions that simplify execution of multi-row
insert statements. The extension functions will reuse the abstract method and supply everything needed to build the
insert statement except the values to insert:</p>

<pre><code class="language-kotlin">import org.mybatis.dynamic.sql.util.kotlin.mybatis3.insertMultiple

fun PersonMapper.insertMultiple(vararg records: PersonRecord) =
    insertMultiple(records.toList())

fun PersonMapper.insertMultiple(records: Collection&lt;PersonRecord&gt;) =
    insertMultiple(this::insertMultiple, records, person) {
        map(id) toProperty &quot;id&quot;
        map(firstName) toProperty &quot;firstName&quot;
        map(lastName) toProperty &quot;lastName&quot;
        map(birthDate) toProperty &quot;birthDate&quot;
        map(employed) toProperty &quot;employed&quot;
        map(occupation) toProperty &quot;occupation&quot;
        map(addressId) toProperty &quot;addressId&quot;
    }
</code></pre>
<p>The method is constructed to execute multi-row insert statements on one specific table - <code>person</code> in this case.</p>
<p>This extension method reuses the mapper method and supplies all the column mappings. Clients can use the method
as follows:</p>

<pre><code class="language-kotlin">val record1 = PersonRecord(100, &quot;Joe&quot;, LastName(&quot;Jones&quot;), Date(), true, &quot;Developer&quot;, 1)
val record2 = PersonRecord(101, &quot;Sarah&quot;, LastName(&quot;Smith&quot;), Date(), true, &quot;Architect&quot;, 2)

val rows = mapper.insertMultiple(record1, record2)
</code></pre></section><section><a id="Generated_Key_Support_2"></a>
<h3>Generated Key Support</h3>
<p>Multi-row insert statements support returning a generated key using normal MyBatis generated key support. However,
generated keys require some care for multi-row insert statements. In this section we will show how to use the
library's built-in support. When generated keys are expected you must code the mapper method manually and supply the
<code>@Options</code> annotation that configures generated key support. You cannot use the built-in base interface when there are
generated keys. For example:</p>

<pre><code class="language-kotlin">interface GeneratedAlwaysMapper {
    @InsertProvider(type = SqlProviderAdapter::class, method = &quot;insertMultipleWithGeneratedKeys&quot;)
    @Options(useGeneratedKeys = true, keyProperty=&quot;records.id,records.fullName&quot;, keyColumn = &quot;id,full_name&quot;)
    fun insertMultiple(insertStatement: String, @Param(&quot;records&quot;) records: List&lt;GeneratedAlwaysRecord&gt;): Int
}
</code></pre>
<p>Note that this method uses a different <code>SQLProviderAdapter</code> method and also uses a decomposed version of the
provider class. This is done to code around some limitations in MyBatis3. This method will return two generated values
in each row: <code>id</code> and <code>full_name</code>. The values will be placed into the record properties <code>id</code> and <code>fullName</code> respectively.</p>
<p>For the one-step method, the mapper extension method should use a different utility function as shown below:</p>

<pre><code class="language-kotlin">import org.mybatis.dynamic.sql.util.kotlin.mybatis3.insertMultipleWithGeneratedKeys

fun GeneratedAlwaysMapper.insertMultiple(records: Collection&lt;GeneratedAlwaysRecord&gt;): Int {
    return insertMultipleWithGeneratedKeys(this::insertMultiple, records, generatedAlways) {
        map(firstName).toProperty(&quot;firstName&quot;)
        map(lastName).toProperty(&quot;lastName&quot;)
    }
}
</code></pre></section></section><section><a id="Batch_Insert_Statement"></a>
<h2>Batch Insert Statement</h2><section><a id="Two-Step_Method_5"></a>
<h3>Two-Step Method</h3>
<p>Batch insert statements are constructed as shown on the Kotlin overview page. This method creates
a <code>BatchInsert</code> that can be executed with a MyBatis3 mapper method.</p>
<p>Batch inserts will reuse the regular <code>insert</code> method created for single record inserts. It is also convenient to create
a method to flush the batch statements - this causes a commit and returns detailed information about the
batch such as update counts. The methods are coded as follows:</p>

<pre><code class="language-kotlin">import org.apache.ibatis.annotations.Flush
import org.apache.ibatis.annotations.InsertProvider
import org.apache.ibatis.executor.BatchResult

@Mapper
interface PersonMapper {
    @InsertProvider(type = SqlProviderAdapter::class, method = &quot;insert&quot;)
    fun insert(insertStatement: InsertStatementProvider&lt;PersonRecord&gt;): Int

    @Flush
    fun flush(): List&lt;BatchResult&gt;
}
</code></pre>
<p>These are standard methods for MyBatis. Note that the return value of the &#x201c;insert&#x201d; statement will NOT be the number of
rows when using batch mode operations. In batch mode the rows are not actually inserted until the statements
are flushed, or the session is committed. In batch mode, the return value is a constant with no actual meaning.
The methods can also be implemented by using a built-in base interface as follows:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper : CommonInsertMapper&lt;T&gt;
</code></pre>
<p><code>CommonInsertMapper</code> can also be used on its own if you inject it into a MyBatis configuration.</p>
<p>MyBatis batch executions are coded as multiple invocations of a simple insert method. The difference is in the
construction of the mapper. The <code>SqlSession</code> associated with the mapper must be in &#x201c;batch mode&#x201d;. This is accomplished
when opening the session. For example:</p>

<pre><code class="language-kotlin">import org.apache.ibatis.session.ExecutorType
import org.apache.ibatis.session.SqlSession
import org.apache.ibatis.session.SqlSessionFactory

val sqlSessionFactory: SqlSessionFactory = getSessionFactory() // not shown
val sqlSession: SqlSession = sqlSessionFactory.openSession(ExecutorType.BATCH)
val mapper: PersonMaper = sqlSession.getMapper(PersonMapper::class.java)
</code></pre>
<p>The mapper is now associated with a BATCH session. The mapper method can be used as follows:</p>

<pre><code class="language-kotlin">import org.apache.ibatis.executor.BatchResult
import org.mybatis.dynamic.sql.util.kotlin.mybatis3.insertBatch

val sqlSessionFactory: SqlSessionFactory = getSessionFactory() // not shown
val sqlSession: SqlSession = sqlSessionFactory.openSession(ExecutorType.BATCH)
val mapper: PersonMapper = sqlSession.getMapper(PersonMapper::class.java)

val batchInsert = insertBatch() // not shown, see overview page
batchInsert.execute(mapper) // see note below about return value
val batchResults = mapper.flush()
</code></pre>
<p>Note the use of the extension function <code>BatchInsert.execute(mapper)</code>. This function simply loops over all
insert statements in the batch and executes them with the supplied mapper. Note also that
<code>BatchInsert.execute(mapper)</code> will return a <code>List&lt;Int&gt;</code>. However, when the mapper is in batch mode the
values in the list will not be useful. In batch mode you must execute the flush method (or <code>sqlSession.flushStatements()</code>)
to obtain update counts. The <code>flush</code> call will also commit the batch. Note that this built-in support executes all inserts
as a single transaction. If you have a large batch of records and want to process intermediate commits, you can do so
by writing code to loop through the list of insert statements obtained from <code>BatchInsert.insertStatements()</code> and execute
flush/commit as desired.</p></section><section><a id="One-Step_Method_5"></a>
<h3>One-Step Method</h3>
<p>You can use built-in utility functions to create mapper extension functions that simplify execution of batch
insert statements. The extension functions will reuse the abstract method and supply everything needed to build the
insert statement except the values to insert:</p>

<pre><code class="language-kotlin">import org.mybatis.dynamic.sql.util.kotlin.mybatis3.insertBatch

fun PersonMapper.insertBatch(vararg records: PersonRecord): List&lt;Int&gt; =
    insertBatch(records.toList())

fun PersonMapper.insertBatch(records: Collection&lt;PersonRecord&gt;): List&lt;Int&gt; =
    insertBatch(this::insert, records, person) {
        map(id) toProperty &quot;id&quot;
        map(firstName) toProperty &quot;firstName&quot;
        map(lastName) toProperty &quot;lastName&quot;
        map(birthDate) toProperty &quot;birthDate&quot;
        map(employed) toProperty &quot;employed&quot;
        map(occupation) toProperty &quot;occupation&quot;
        map(addressId) toProperty &quot;addressId&quot;
    }
</code></pre>
<p>The method is constructed to execute batch insert statements on one specific table - <code>person</code> in this case.</p>
<p>This extension method reuses the mapper method and supplies all the column mappings. Clients can use the method
as follows:</p>

<pre><code class="language-kotlin">val record1 = PersonRecord(100, &quot;Joe&quot;, LastName(&quot;Jones&quot;), Date(), true, &quot;Developer&quot;, 1)
val record2 = PersonRecord(101, &quot;Sarah&quot;, LastName(&quot;Smith&quot;), Date(), true, &quot;Architect&quot;, 2)

val sqlSessionFactory: SqlSessionFactory = getSessionFactory() // not shown
val sqlSession: SqlSession = sqlSessionFactory.openSession(ExecutorType.BATCH)
val mapper: PersonMapper = sqlSession.getMapper(PersonMapper::class.java)
mapper.insertBatch(record1, record2)
val batchResults = mapper.flush()
</code></pre></section><section><a id="Generated_Key_Support_3"></a>
<h3>Generated Key Support</h3>
<p>Batch insert statements support returning a generated key using normal MyBatis generated key support. If you code
the <code>@Options</code> annotation on the <code>insert</code> statement, then the generated keys will be populated into the input records
when the transaction is committed or flushed. When generated keys are expected you must code the mapper method manually
and supply the <code>@Options</code> annotation that configures generated key support. You cannot use the built-in base interface
when there are generated keys. For example:</p>

<pre><code class="language-kotlin">interface GeneratedAlwaysMapper {
    @InsertProvider(type = SqlProviderAdapter::class, method = &quot;insert&quot;)
    @Options(useGeneratedKeys = true, keyProperty=&quot;record.id,record.fullName&quot;, keyColumn = &quot;id,full_name&quot;)
    fun insert(insertStatement: InsertStatementProvider&lt;GeneratedAlwaysRecord&gt;): Int
}
</code></pre>
<p>This insert method can be used with mappers in batch mode as shown above.</p></section></section><section><a id="Insert_Select_Statement"></a>
<h2>Insert Select Statement</h2><section><a id="Two-Step_Method_6"></a>
<h3>Two-Step Method</h3>
<p>Insert select statements are constructed as shown on the Kotlin overview page. This method creates
an <code>InsertSelectStatementProvider</code> that can be executed with a MyBatis3 mapper method. MyBatis3 mappers should declare
a <code>generalInsert</code> method as follows:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper {
    @InsertProvider(type = SqlProviderAdapter::class, method = &quot;insertSelect&quot;)
    fun insertSelect(insertSelectStatement: InsertSelectStatementProvider): Int
}
</code></pre>
<p>This is a standard method for MyBatis Dynamic SQL that executes an insert and returns a <code>Int</code> - the number of rows
inserted. This method can also be implemented by using a built-in base interface as follows:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper : CommonInsertMapper&lt;T&gt;
</code></pre>
<p><code>CommonInsertMapper</code> can also be used on its own if you inject it into a MyBatis configuration.</p>
<p>The mapper method can be used as follows:</p>

<pre><code class="language-kotlin">val insertStatement = insertSelect() // not shown, see overview page
val mapper: PersonMapper = getMapper() // not shown
val rows: Int = mapper.insertSelect(insertStatement)
</code></pre></section><section><a id="One-Step_Method_6"></a>
<h3>One-Step Method</h3>
<p>You can use built-in utility functions to create mapper extension functions that simplify execution of insert select
statements. The extension functions will reuse the abstract method and supply everything needed to build the
insert statement except the values to insert:</p>

<pre><code class="language-kotlin">import org.mybatis.dynamic.sql.util.kotlin.InsertSelectCompleter
import org.mybatis.dynamic.sql.util.kotlin.mybatis3.insertSelect

fun PersonMapper.insertSelect(completer: InsertSelectCompleter) =
    insertSelect(this::insertSelect, person, completer)
</code></pre>
<p>The method is constructed to execute insert statements on one specific table - <code>person</code> in this case.</p>
<p>The method shows the use of <code>InsertSelectCompleter</code> which is a Kotlin typealias for a function with a receiver that will
allow a user to supply value column list ans select statement. This also shows use of the Kotlin <code>insertSelect</code> method
which is supplied by the library. This method will build and execute the insert statement with the supplied column
list and select statement. Clients can use the method as follows:</p>

<pre><code class="language-kotlin">val mapper = getMapper() // not shown
val rows = mapper.insertSelect {
    columns(id, firstName, lastName, employed, occupation, addressId, birthDate)
    select(add(id, constant&lt;Int&gt;(&quot;100&quot;)), firstName, lastName, employed, occupation, addressId, birthDate) {
        from(person)
        orderBy(id)
    }
}
</code></pre></section><section><a id="Generated_Key_Support_4"></a>
<h3>Generated Key Support</h3>
<p>Generated keys with insert select are not directly supported by library utilities and can be quite challenging.
There are examples in the source repository if you have a need to do this.</p></section></section><section><a id="Select_Method_Support"></a>
<h2>Select Method Support</h2><section><a id="Two-Step_Method_7"></a>
<h3>Two-Step Method</h3>
<p>Select statements are constructed as shown on the Kotlin overview page. Those methods create a
<code>SelectStatementProvider</code> that can be executed with MyBatis3 mapper methods. We recommend creating two mapper methods:
one that returns a list of records, and another that returns a single record or null:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper {
    @SelectProvider(type = SqlProviderAdapter::class, method = &quot;select&quot;)
    @Results(id = &quot;PersonResult&quot;, value = [
        Result(column = &quot;A_ID&quot;, property = &quot;id&quot;, jdbcType = JdbcType.INTEGER, id = true),
        Result(column = &quot;first_name&quot;, property = &quot;firstName&quot;, jdbcType = JdbcType.VARCHAR),
        Result(column = &quot;last_name&quot;, property = &quot;lastName&quot;, jdbcType = JdbcType.VARCHAR,
                typeHandler = LastNameTypeHandler::class),
        Result(column = &quot;birth_date&quot;, property = &quot;birthDate&quot;, jdbcType = JdbcType.DATE),
        Result(column = &quot;employed&quot;, property = &quot;employed&quot;, jdbcType = JdbcType.VARCHAR,
                typeHandler = YesNoTypeHandler::class),
        Result(column = &quot;occupation&quot;, property = &quot;occupation&quot;, jdbcType = JdbcType.VARCHAR),
        Result(column = &quot;address_id&quot;, property = &quot;addressId&quot;, jdbcType = JdbcType.INTEGER)])
    fun selectMany(selectStatement: SelectStatementProvider): List&lt;PersonRecord&gt;

    @SelectProvider(type = SqlProviderAdapter::class, method = &quot;select&quot;)
    @ResultMap(&quot;PersonResult&quot;)
    fun selectOne(selectStatement: SelectStatementProvider): PersonRecord?
}
</code></pre>
<p>Note that the result map is shared between the two methods.</p>
<p>The methods can be used as follows:</p>

<pre><code class="language-kotlin">val mapper: PersonMapper = getMapper() // not shown

val selectStatement = select() // not shown... see the overview page for examples
val rows: List&lt;PersonRecord&gt; = mapper.selectMany(selectStatement)

val selectOneStatement = select() // not shown... see the overview page for examples
val row: PersonRecord? = mapper.selectOne(selectStatement)
</code></pre>
<p>Note that the select statement is the same whether multiple or single rows are expected. Also note that a select
distinct can be executed with the <code>selectMany</code> method.</p></section><section><a id="One-Step_Method_7"></a>
<h3>One-Step Method</h3>
<p>You can use built-in utility functions to create mapper extension functions that simplify execution of select statements.
The extension functions will reuse the abstract methods and supply the table and column list for the statement.
We recommend three extension methods for select multiple records, select multiple records with the distinct keyword,
and selecting a single record:</p>

<pre><code class="language-kotlin">import org.mybatis.dynamic.sql.util.kotlin.SelectCompleter
import org.mybatis.dynamic.sql.util.kotlin.elements.`as`
import org.mybatis.dynamic.sql.util.kotlin.mybatis3.selectDistinct
import org.mybatis.dynamic.sql.util.kotlin.mybatis3.selectList
import org.mybatis.dynamic.sql.util.kotlin.mybatis3.selectOne

private val columnList = listOf(id `as` &quot;A_ID&quot;, firstName, lastName, birthDate, employed, occupation, addressId)

fun PersonMapper.selectOne(completer: SelectCompleter) =
    selectOne(this::selectOne, columnList, Person, completer)

fun PersonMapper.select(completer: SelectCompleter) =
    selectList(this::selectMany, columnList, Person, completer)

fun PersonMapper.selectDistinct(completer: SelectCompleter) =
    selectDistinct(this::selectMany, columnList, Person, completer)
</code></pre>
<p>The methods are constructed to execute select statements on one specific table - <code>person</code> in this case - and with a fixed
column list that matches the MyBatis result mapping.</p>
<p>The methods show the use of <code>SelectCompleter</code> which is a Kotlin typealias for a function with a receiver that will
allow a user to supply a where clause. This also shows use of the Kotlin <code>selectDistinct</code>, <code>selectList</code>, and <code>selectOne</code>
methods which are supplied by the library. Those methods will build and execute the select statement. Clients can use
the methods as follows:</p>

<pre><code class="language-kotlin">val mapper = getMapper() // not shown
val distinctRecords = mapper.selectDistinct {
    where { id isGreaterThan 5 }
}

val rows = mapper.select {
    where { firstName.isIn(&quot;Fred&quot;, &quot;Barney&quot;) }
    orderBy(id)
    limit(3)
}

val record = mapper.selectOne {
    where { id isEqualTo 1 }
}

</code></pre>
<p>The general <code>selectOne</code> method can also be used to implement a <code>selectByPrimaryKey</code> method:</p>

<pre><code class="language-kotlin">fun PersonMapper.selectByPrimaryKey(id_: Int) =
    selectOne {
        where { id isEqualTo id_ }
    }
</code></pre>
<p>There is a utility method that will select all rows in a table:</p>

<pre><code class="language-kotlin">val rows = mapper.select { allRows() }
</code></pre>
<p>The following query will select all rows in a specified order:</p>

<pre><code class="language-kotlin">val rows = mapper.select {
    allRows()
    orderBy(lastName, firstName)
}
</code></pre></section><section><a id="Join_Support"></a>
<h3>Join Support</h3>
<p>You can implement functions that support a reusable select method based on a join. In this way, you can create
the start of the select statement (the column list and join specifications) and allow the user to supply where clauses
and other parts of a select statement. For example, you could code a mapper extension method like this:</p>

<pre><code class="language-kotlin">fun PersonWithAddressMapper.select(completer: SelectCompleter): List&lt;PersonWithAddress&gt; =
    select(
        id `as` &quot;A_ID&quot;, firstName, lastName, birthDate,
        employed, occupation, address.id, address.streetAddress, address.city, address.state
    ) {
        from(person, &quot;p&quot;)
        fullJoin(address) {
            on(person.addressId) equalTo address.id
        }
        completer()
    }.run(this::selectMany)
</code></pre>
<p>This method creates the start of a select statement with a join, and accepts user input to complete the statement.
This shows reuse of a regular MyBatis mapper method - <code>selectMany</code> as shown above - with a result map that matches the
select list. Like other select methods, this method can be used as follows:</p>

<pre><code class="language-kotlin">val records = mapper.select {
    where { id isLessThan 100 }
    limit(5)
}
</code></pre></section></section><section><a id="Multi-Select_Statement_Support"></a>
<h2>Multi-Select Statement Support</h2>
<p>Multi-select statements are a special case of select statement. All the above information about MyBatis mappers applies
equally to multi-select statements.</p>
<p>The library does not provide a &#x201c;one-step&#x201d; shortcut for multi-select queries. You can execute a multi-select query
with the two-step method using either a &#x201c;selectMany&#x201d; or &#x201c;selectOne&#x201d; mapper method as shown above.</p></section><section><a id="Update_Method_Support"></a>
<h2>Update Method Support</h2><section><a id="Two-Step_Method_8"></a>
<h3>Two-Step Method</h3>
<p>Update statements are constructed as shown on the Kotlin overview page. This method creates an
<code>UpdateStatementProvider</code> that can be executed with a MyBatis3 mapper method. MyBatis3 mappers should declare
an <code>update</code> method as follows:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper {
    @UpdateProvider(type = SqlProviderAdapter::class, method = &quot;update&quot;)
    fun update(updateStatement: UpdateStatementProvider): Int
}
</code></pre>
<p>This is a standard method for MyBatis Dynamic SQL that executes an update and returns an <code>Int</code> - the number of rows
updated. This method can also be implemented by using a built-in base interface as follows:</p>

<pre><code class="language-kotlin">@Mapper
interface PersonMapper : CommonUpdateMapper
</code></pre>
<p><code>CommonUpdateMapper</code> can also be used on its own if you inject it into a MyBatis configuration.</p>
<p>The mapper method can be used as follows:</p>

<pre><code class="language-kotlin">val updateStatement = update() // not shown... see the overview page for examples
val mapper: PersonMapper = getMapper() // not shown
val rows: Int = mapper.update(updateStatement)
</code></pre></section><section><a id="One-Step_Method_8"></a>
<h3>One-Step Method</h3>
<p>You can use built-in utility functions to create mapper extension functions that simplify execution of update statements.
The extension functions will reuse the abstract method and supply everything needed to build the update statement
except the set and where clauses:</p>

<pre><code class="language-kotlin">import org.mybatis.dynamic.sql.util.kotlin.UpdateCompleter
import org.mybatis.dynamic.sql.util.kotlin.mybatis3.update

fun PersonMapper.update(completer: UpdateCompleter) =
    update(this::update, person, completer)
</code></pre>
<p>The method is constructed to execute update statements on one specific table - <code>person</code> in this case.</p>
<p>The method shows the use of <code>UpdateCompleter</code> which is a Kotlin typealias for a function with a receiver that will
allow a user to supply set phrases and a where clause. This also shows use of the Kotlin <code>update</code> method which is
supplied by the library. Those methods will build and execute the update statement with the supplied set phrases and
where clause. Clients can use the method as follows:</p>

<pre><code class="language-kotlin">val rows = mapper.update {
    set(occupation).equalTo(&quot;Programmer&quot;)
    where { id isEqualTo 100 }
    and(firstName, isEqualTo(&quot;Joe&quot;))
}
</code></pre>
<p>If you wish to update all rows in a table, you can simply omit the where clause as follows:</p>

<pre><code class="language-kotlin">// update all rows...
val rows = mapper.update {
    set(occupation) equalTo &quot;Programmer&quot;
}
</code></pre>
<p>It is also possible to write utility methods that will set values. For example:</p>

<pre><code class="language-kotlin">fun KotlinUpdateBuilder.updateSelectiveColumns(record: PersonRecord) =
    apply {
        set(id) equalToWhenPresent record::id
        set(firstName) equalToWhenPresent record::firstName
        set(lastName) equalToWhenPresent record::lastName
        set(birthDate) equalToWhenPresent record::birthDate
        set(employed) equalToWhenPresent record::employed
        set(occupation) equalToWhenPresent record::occupation
        set(addressId) equalToWhenPresent record::addressId
    }
</code></pre>
<p>This method will selectively set values if corresponding fields in a record are non-null. This method can be used as
follows:</p>

<pre><code class="language-kotlin">val rows = mapper.update {
    updateSelectiveColumns(updateRecord)
    where { id isEqualTo 100 }
}
</code></pre>
<p>If you wish to implement an &#x201c;update by primary key&#x201d; method, you can reuse the extension method as follows:</p>

<pre><code class="language-kotlin">fun PersonMapper.updateByPrimaryKey(record: PersonRecord) =
    update {
        set(firstName) equalToOrNull record::firstName
        set(lastName) equalToOrNull record::lastName
        set(birthDate) equalToOrNull record::birthDate
        set(employed) equalToOrNull record::employed
        set(occupation) equalToOrNull record::occupation
        set(addressId) equalToOrNull record::addressId
        where { id isEqualTo record.id!! }
    }

fun PersonMapper.updateByPrimaryKeySelective(record: PersonRecord) =
    update {
        set(firstName) equalToWhenPresent record::firstName
        set(lastName) equalToWhenPresent record::lastName
        set(birthDate) equalToWhenPresent record::birthDate
        set(employed) equalToWhenPresent record::employed
        set(occupation) equalToWhenPresent record::occupation
        set(addressId) equalToWhenPresent record::addressId
        where { id isEqualTo record.id!! }
    }
</code></pre>
<p>The method <code>updateByPrimaryKey</code> will update every column - if a property in the record is null, the column will be set
to null.</p>
<p>The method <code>updateByPrimaryKeySelective</code> will update every column that has a non-null corresponding property
in the record. If a property in the record is null, the column will not be updated.</p></section></section></section>
        </main>
      </div>
    </div>
    <hr/>
    <footer>
      <div class="container-fluid">
        <div class="row-fluid">
            <p>©      2016–2024
<a href="https://www.mybatis.org/">MyBatis.org</a>
</p>
        </div>
      </div>
    </footer>
<script>
  if(anchors) {
    anchors.add();
  }
</script>
  </body>
</html>