<?xml version="1.0" encoding="UTF-8"?>
<!--

       Copyright ${license.git.copyrightYears} the original author or authors.

       Licensed under the Apache License, Version 2.0 (the "License");
       you may not use this file except in compliance with the License.
       You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

       Unless required by applicable law or agreed to in writing, software
       distributed under the License is distributed on an "AS IS" BASIS,
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
       See the License for the specific language governing permissions and
       limitations under the License.

-->
<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

  <properties>
    <title>MyBatis 3 | Mapper XML Files</title>
    <author email="clinton.begin@gmail.com">Clinton Begin</author>
  </properties>

  <body>
    <section name="Mapper XML Files">
      <p>
        The true power of MyBatis is in the Mapped Statements. This is where the magic happens.
        For all of their power, the Mapper XML files are relatively simple. Certainly if you were
        to compare them to the equivalent JDBC code, you would immediately see a savings of 95% of the code.
        MyBatis was built to focus on the SQL, and does its best to stay out of your way.
      </p>
      <p>The Mapper XML files have only a few first class elements (in the order that they should be defined):
      </p>
      <ul>
        <li>
          <code>cache</code>
          – Configuration of the cache for a given namespace.
        </li>
        <li>
          <code>cache-ref</code>
          – Reference to a cache configuration from another namespace.
        </li>
        <li>
          <code>resultMap</code>
          – The most complicated and powerful element that describes how to load your objects from the
          database result sets.
        </li>
        <li>
          <strike>
            <code>parameterMap</code>
            – Deprecated! Old-school way to map parameters. Inline parameters are preferred and this element
            may be removed in the future. Not documented here.
          </strike>
        </li>
        <li>
          <code>sql</code>
          – A reusable chunk of SQL that can be referenced by other statements.
        </li>
        <li>
          <code>insert</code>
          – A mapped INSERT statement.
        </li>
        <li>
          <code>update</code>
          – A mapped UPDATE statement.
        </li>
        <li>
          <code>delete</code>
          – A mapped DELETE statement.
        </li>
        <li>
          <code>select</code>
          – A mapped SELECT statement.
        </li>
      </ul>
      <p>The next sections will describe each of these elements in detail, starting with the statements
        themselves.
      </p>

      <subsection name="select">
        <p>
          The select statement is one of the most popular elements that you'll use in MyBatis.
          Putting data in a database isn't terribly valuable until you get it back out, so most
          applications query far more than they modify the data. For every insert, update or delete,
          there are probably many selects. This is one of the founding principles of MyBatis, and is the
          reason so much focus and effort was placed on querying and result mapping. The select element is
          quite simple for simple cases. For example:
        </p>

        <source><![CDATA[<select id="selectPerson" parameterType="int" resultType="hashmap">
  SELECT * FROM PERSON WHERE ID = #{id}
</select>]]></source>

        <p>
          This statement is called selectPerson, takes a parameter of type int (or Integer), and returns a
          HashMap
          keyed by column names mapped to row values.
        </p>

        <p>
          Notice the parameter notation:
        </p>

        <source><![CDATA[#{id}]]></source>

        <p>
          This tells MyBatis to create a PreparedStatement parameter. With JDBC, such a parameter would be
          identified by a "?" in SQL passed to a new PreparedStatement, something like this:
        </p>

        <source><![CDATA[// Similar JDBC code, NOT MyBatis…
String selectPerson = "SELECT * FROM PERSON WHERE ID=?";
PreparedStatement ps = conn.prepareStatement(selectPerson);
ps.setInt(1,id);]]></source>

        <p>
          Of course, there's a lot more code required by JDBC alone to extract the results and map them to an
          instance of an object, which is what MyBatis saves you from having to do. There's a lot more to know
          about parameter and result mapping. Those details warrant their own section, which follows later in
          this section.
        </p>

        <p>
          The select element has more attributes that allow you to configure the details of how each statement
          should behave.
        </p>

        <source><![CDATA[<select
  id="selectPerson"
  parameterType="int"
  parameterMap="deprecated"
  resultType="hashmap"
  resultMap="personResultMap"
  flushCache="false"
  useCache="true"
  timeout="10"
  fetchSize="256"
  statementType="PREPARED"
  resultSetType="FORWARD_ONLY">]]></source>

        <table>
          <caption>Select Attributes</caption>
          <thead>
            <tr>
              <th>Attribute</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td><code>id</code></td>
              <td>A unique identifier in this namespace that can be used to reference this statement.</td>
            </tr>
            <tr>
              <td><code>parameterType</code></td>
              <td>The fully qualified class name or alias for the parameter that will be passed into this
                statement. This attribute is optional because MyBatis can calculate the TypeHandler to use out of
                the actual parameter passed to the statement. Default is <code>unset</code>.
              </td>
            </tr>
            <tr>
              <td>
                <strike><code>parameterMap</code></strike>
              </td>
              <td>
                <strike>This is a deprecated approach to referencing an external <code>parameterMap</code>. Use
                  inline parameter mappings and the <code>parameterType</code> attribute.
                </strike>
              </td>
            </tr>
            <tr>
              <td><code>resultType</code></td>
              <td>The fully qualified class name or alias for the expected type that will be returned from
                this statement. Note that in the case of collections, this should be the type that the
                collection contains, not the type of the collection itself. Use <code>resultType</code> OR
                <code>resultMap</code>, not both.
              </td>
            </tr>
            <tr>
              <td><code>resultMap</code></td>
              <td>A named reference to an external <code>resultMap</code>. Result maps are the most powerful feature of
                MyBatis, and with a good understanding of them, many difficult mapping cases can be
                solved. Use <code>resultMap</code> OR <code>resultType</code>, not both.
              </td>
            </tr>
            <tr>
              <td><code>flushCache</code></td>
              <td>Setting this to true will cause the local and 2nd level caches to be flushed whenever this statement is
                called. Default: <code>false</code> for select statements.
              </td>
            </tr>
            <tr>
              <td><code>useCache</code></td>
              <td>Setting this to true will cause the results of this statement to be cached in 2nd level cache. Default:
                <code>true</code> for select statements.
              </td>
            </tr>
            <tr>
              <td><code>timeout</code></td>
              <td>This sets the number of seconds the driver will wait for the database to return from a
                request, before throwing an exception. Default is <code>unset</code> (driver dependent).
              </td>
            </tr>
            <tr>
              <td><code>fetchSize</code></td>
              <td>This is a driver hint that will attempt to cause the driver to return results in batches
                of rows numbering in size equal to this setting. Default is <code>unset</code> (driver dependent).
              </td>
            </tr>
            <tr>
              <td><code>statementType</code></td>
              <td>Any one of <code>STATEMENT</code>, <code>PREPARED</code> or <code>CALLABLE</code>.
              This causes MyBatis to use <code>Statement</code>,
                <code>PreparedStatement</code> or <code>CallableStatement</code> respectively. Default: <code>PREPARED</code>.
              </td>
            </tr>
            <tr>
              <td><code>resultSetType</code></td>
              <td>Any one of <code>FORWARD_ONLY</code>|<code>SCROLL_SENSITIVE</code>|<code>SCROLL_INSENSITIVE</code>|<code>DEFAULT</code>(same as unset).
              Default is <code>unset</code> (driver dependent).
              </td>
            </tr>
            <tr>
              <td><code>databaseId</code></td>
              <td>In case there is a configured databaseIdProvider, MyBatis will load all statements with no <code>databaseId</code>
              attribute or with a <code>databaseId</code> that matches the current one. If case the same statement
              if found with and without the <code>databaseId</code> the latter will be discarded.
              </td>
            </tr>
            <tr>
              <td><code>resultOrdered</code></td>
              <td>This is only applicable for nested result select statements: If this is true, it
                is assumed that nested results are contained or grouped together such that when a
                new main result row is returned, no references to a previous result row will occur
                anymore. This allows nested results to be filled much more memory friendly. Default:
                <code>false</code>.
              </td>
            </tr>
            <tr>
              <td><code>resultSets</code></td>
              <td>This is only applicable for multiple result sets. It lists the result sets that will
                be returned by the statement and gives a name to each one. Names are separated by commas.
              </td>
            </tr>
          </tbody>
        </table>
      </subsection>

      <subsection name="insert, update and delete">
        <p>The data modification statements insert, update and delete are very similar in their implementation:
        </p>

        <source><![CDATA[<insert
  id="insertAuthor"
  parameterType="domain.blog.Author"
  flushCache="true"
  statementType="PREPARED"
  keyProperty=""
  keyColumn=""
  useGeneratedKeys=""
  timeout="20">

<update
  id="updateAuthor"
  parameterType="domain.blog.Author"
  flushCache="true"
  statementType="PREPARED"
  timeout="20">

<delete
  id="deleteAuthor"
  parameterType="domain.blog.Author"
  flushCache="true"
  statementType="PREPARED"
  timeout="20">]]></source>

        <table>
          <caption>Insert, Update and Delete Attributes</caption>
          <thead>
            <tr>
              <th>Attribute</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td><code>id</code></td>
              <td>A unique identifier in this namespace that can be used to reference this statement.</td>
            </tr>
            <tr>
              <td><code>parameterType</code></td>
              <td>The fully qualified class name or alias for the parameter that will be passed into this
                statement. This attribute is optional because MyBatis can calculate the TypeHandler to use out of
                the actual parameter passed to the statement. Default is <code>unset</code>.
              </td>
            </tr>
            <tr>
              <td>
                <strike><code>parameterMap</code></strike>
              </td>
              <td>
                <strike>This is a deprecated approach to referencing an external parameterMap. Use
                  inline parameter mappings and the parameterType attribute.
                </strike>
              </td>
            </tr>
            <tr>
              <td><code>flushCache</code></td>
              <td>Setting this to true will cause the 2nd level and local caches to be flushed whenever this statement is
                called. Default: <code>true</code> for insert, update and delete statements.
              </td>
            </tr>
            <tr>
              <td><code>timeout</code></td>
              <td>This sets the maximum number of seconds the driver will wait for the database to return from a
                request, before throwing an exception. Default is <code>unset</code> (driver dependent).
              </td>
            </tr>
            <tr>
              <td><code>statementType</code></td>
              <td>Any one of <code>STATEMENT</code>, <code>PREPARED</code> or <code>CALLABLE</code>.
              This causes MyBatis to use <code>Statement</code>,
                <code>PreparedStatement</code> or <code>CallableStatement</code> respectively. Default: <code>PREPARED</code>.
              </td>
            </tr>
            <tr>
              <td><code>useGeneratedKeys</code></td>
              <td>(insert and update only) This tells MyBatis to use the JDBC <code>getGeneratedKeys</code> method to retrieve
                keys generated internally by the database (e.g. auto increment fields in RDBMS like
                MySQL or SQL Server). Default: <code>false</code>.
              </td>
            </tr>
            <tr>
              <td><code>keyProperty</code></td>
              <td>(insert and update only) Identifies a property into which MyBatis will set the key value returned
                by <code>getGeneratedKeys</code>, or by a <code>selectKey</code> child element of the insert statement.
                Default: <code>unset</code>.  Can be a comma separated list of property names if multiple
                generated columns are expected.
              </td>
            </tr>
            <tr>
              <td><code>keyColumn</code></td>
              <td>(insert and update only) Sets the name of the column in the table with a generated key. This is
                only required in certain databases (like PostgreSQL) when the key column is not the
                first column in the table. Can be a comma separated list of columns names if multiple
                generated columns are expected.
              </td>
            </tr>
            <tr>
              <td><code>databaseId</code></td>
              <td>In case there is a configured databaseIdProvider, MyBatis will load all statements with no <code>databaseId</code>
              attribute or with a <code>databaseId</code> that matches the current one. If case the same statement
              if found with and without the <code>databaseId</code> the latter will be discarded.
              </td>
            </tr>
          </tbody>
        </table>

        <p>The following are some examples of insert, update and delete statements.</p>

        <source><![CDATA[<insert id="insertAuthor">
  insert into Author (id,username,password,email,bio)
  values (#{id},#{username},#{password},#{email},#{bio})
</insert>

<update id="updateAuthor">
  update Author set
    username = #{username},
    password = #{password},
    email = #{email},
    bio = #{bio}
  where id = #{id}
</update>

<delete id="deleteAuthor">
  delete from Author where id = #{id}
</delete>]]></source>

        <p>
          As mentioned, insert is a little bit more rich in that it has a few extra attributes and
          sub-elements that allow it to deal with key generation in a number of ways.
        </p>

        <p>
          First, if your database supports auto-generated key fields (e.g. MySQL and SQL Server),
          then you can simply set <code>useGeneratedKeys="true"</code> and set the <code>keyProperty</code> to the target property
          and you're done. For example, if the <code>Author</code> table above had used an auto-generated column type
          for the id, the statement would be modified as follows:
        </p>

        <source><![CDATA[<insert id="insertAuthor" useGeneratedKeys="true"
    keyProperty="id">
  insert into Author (username,password,email,bio)
  values (#{username},#{password},#{email},#{bio})
</insert>]]></source>

        <p>
          If your database also supports multi-row insert, you can pass a list or an array of <code>Author</code>s and retrieve the auto-generated keys.
        </p>

        <source><![CDATA[<insert id="insertAuthor" useGeneratedKeys="true"
    keyProperty="id">
  insert into Author (username, password, email, bio) values
  <foreach item="item" collection="list" separator=",">
    (#{item.username}, #{item.password}, #{item.email}, #{item.bio})
  </foreach>
</insert>]]></source>

        <p>
          MyBatis has another way to deal with key generation for databases that don't support auto-generated
          column types, or perhaps don't yet support the JDBC driver support for auto-generated keys.
        </p>

        <p>
          Here's a simple (silly) example that would generate a random ID (something you'd likely never do,
          but this demonstrates the flexibility and how MyBatis really doesn't mind):
        </p>
        <source><![CDATA[<insert id="insertAuthor">
  <selectKey keyProperty="id" resultType="int" order="BEFORE">
    select CAST(RANDOM()*1000000 as INTEGER) a from SYSIBM.SYSDUMMY1
  </selectKey>
  insert into Author
    (id, username, password, email,bio, favourite_section)
  values
    (#{id}, #{username}, #{password}, #{email}, #{bio}, #{favouriteSection,jdbcType=VARCHAR})
</insert>]]></source>
        <p>
          In the example above, the selectKey statement would be run first, the <code>Author</code> id property would be
          set, and then the insert statement would be called. This gives you a similar behavior to an
          auto-generated key in your database without complicating your Java code.
        </p>
        <p>
          The selectKey element is described as follows:
        </p>
        <source><![CDATA[<selectKey
  keyProperty="id"
  resultType="int"
  order="BEFORE"
  statementType="PREPARED">]]></source>

        <table>
          <caption>selectKey Attributes</caption>
          <thead>
            <tr>
              <th>Attribute</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td><code>keyProperty</code></td>
              <td>The target property where the result of the <code>selectKey</code> statement should be set.
                Can be a comma separated list of property names if multiple generated columns
                are expected.
              </td>
            </tr>
            <tr>
              <td><code>keyColumn</code></td>
              <td>The column name(s) in the returned result set that match the properties.
                Can be a comma separated list of column names if multiple generated columns
                are expected.
              </td>
            </tr>
            <tr>
              <td><code>resultType</code></td>
              <td>
                The type of the result. MyBatis can usually figure this out, but it doesn't hurt to
                add it to be sure. MyBatis allows any simple type to be used as the key,
                including Strings.  If you are expecting multiple generated columns, then
                you can use an Object that contains the expected properties, or a Map.
              </td>
            </tr>
            <tr>
              <td><code>order</code></td>
              <td>
                This can be set to <code>BEFORE</code> or <code>AFTER</code>. If set to <code>BEFORE</code>, then it will select the key
                first, set the <code>keyProperty</code> and then execute the insert statement. If set to <code>AFTER</code>,
                it runs the insert statement and then the <code>selectKey</code> statement – which is common with
                databases like Oracle that may have embedded sequence calls inside of insert statements.
              </td>
            </tr>
            <tr>
              <td><code>statementType</code></td>
              <td>
                Same as above, MyBatis supports <code>STATEMENT</code>, <code>PREPARED</code> and <code>CALLABLE</code> statement types that
                map to <code>Statement</code>, <code>PreparedStatement</code> and <code>CallableStatement</code> respectively.
              </td>
            </tr>
          </tbody>
        </table>
      </subsection>

      <subsection name="sql">
        <p>
          This element can be used to define a reusable fragment of SQL code that can be
          included in other statements. It can be statically (during load phase) parametrized. Different property values can
          vary in include instances. For example:
        </p>

        <source><![CDATA[<sql id="userColumns"> ${alias}.id,${alias}.username,${alias}.password </sql>]]></source>

        <p>
          The SQL fragment can then be included in another statement, for example:
        </p>

        <source><![CDATA[<select id="selectUsers" resultType="map">
  select
    <include refid="userColumns"><property name="alias" value="t1"/></include>,
    <include refid="userColumns"><property name="alias" value="t2"/></include>
  from some_table t1
    cross join some_table t2
</select>]]></source>

        <p>
          Property value can be also used in include refid attribute or property values inside include clause, for example:
        </p>

        <source><![CDATA[<sql id="sometable">
  ${prefix}Table
</sql>

<sql id="someinclude">
  from
    <include refid="${include_target}"/>
</sql>

<select id="select" resultType="map">
  select
    field1, field2, field3
  <include refid="someinclude">
    <property name="prefix" value="Some"/>
    <property name="include_target" value="sometable"/>
  </include>
</select>]]></source>
      </subsection>

      <subsection name="Parameters">
        <p>
          In all of the past statements, you've seen examples of simple parameters. Parameters are very
          powerful elements in MyBatis. For simple situations, probably 90% of the cases, there's not much
          to them, for example:
        </p>

        <source><![CDATA[<select id="selectUsers" resultType="User">
  select id, username, password
  from users
  where id = #{id}
</select>]]></source>

        <p>
          The example above demonstrates a very simple named parameter mapping. The parameterType is set to
          <code>int</code>, so therefore the parameter could be named anything. Primitive or simple data types such as
          <code>Integer</code> and <code>String</code> have no relevant properties, and thus will replace the full value of the
          parameter entirely. However, if you pass in a complex object, then the behavior is a little
          different. For example:
        </p>

        <source><![CDATA[<insert id="insertUser" parameterType="User">
  insert into users (id, username, password)
  values (#{id}, #{username}, #{password})
</insert>]]></source>

        <p>
          If a parameter object of type User was passed into that statement, the id, username and password
          property would be looked up and their values passed to a <code>PreparedStatement</code> parameter.
        </p>

        <p>
          That's nice and simple for passing parameters into statements. But there are a lot of other
          features of parameter maps.
        </p>

        <p>
          First, like other parts of MyBatis, parameters can specify a more specific data type.
        </p>

        <source><![CDATA[#{property,javaType=int,jdbcType=NUMERIC}]]></source>

        <p>
          Like the rest of MyBatis, the javaType can almost always be determined from the parameter object,
          unless that object is a <code>HashMap</code>. Then the <code>javaType</code> should be specified to ensure the correct
          <code>TypeHandler</code> is used.
        </p>

        <p>
          <span class="label important">NOTE</span> The JDBC Type is required by JDBC for all nullable
          columns, if <code>null</code> is passed as a value. You can investigate this yourself by reading the JavaDocs
          for the <code>PreparedStatement.setNull()</code> method.
        </p>

        <p>
          To further customize type handling, you can also specify a specific <code>TypeHandler</code>
          class (or alias), for example:
        </p>

        <source><![CDATA[#{age,javaType=int,jdbcType=NUMERIC,typeHandler=MyTypeHandler}]]></source>

        <p>
          So already it seems to be getting verbose, but the truth is that you'll rarely set any of these.
        </p>

        <p>
          For numeric types there's also a <code>numericScale</code> for determining how many decimal places are relevant.
        </p>

        <source><![CDATA[#{height,javaType=double,jdbcType=NUMERIC,numericScale=2}]]></source>

        <p>
          Finally, the mode attribute allows you to specify <code>IN</code>, <code>OUT</code> or <code>INOUT</code> parameters. If a parameter is
          <code>OUT</code> or <code>INOUT</code>, the actual value of the parameter object property will be changed, just as you would
          expect if you were calling for an output parameter. If the <code>mode=OUT</code> (or <code>INOUT</code>) and the
          <code>jdbcType=CURSOR</code> (i.e. Oracle REFCURSOR), you must specify a <code>resultMap</code> to map the <code>ResultSet</code> to the
          type of the parameter. Note that the <code>javaType</code> attribute is optional here, it will be automatically
          set to <code>ResultSet</code> if left blank with a <code>CURSOR</code> as the <code>jdbcType</code>.
        </p>

        <source><![CDATA[#{department, mode=OUT, jdbcType=CURSOR, javaType=ResultSet, resultMap=departmentResultMap}]]></source>

        <p>
          MyBatis also supports more advanced data types such as structs, but you must tell the statement
          the type name when registering the out parameter. For example (again, don't break lines like
          this in practice):
        </p>

        <source><![CDATA[#{middleInitial, mode=OUT, jdbcType=STRUCT, jdbcTypeName=MY_TYPE, resultMap=departmentResultMap}]]></source>

        <p>
          Despite all of these powerful options, most of the time you'll simply specify the property name,
          and MyBatis will figure out the rest. At most, you'll specify the <code>jdbcType</code> for nullable columns.
        </p>

        <source><![CDATA[#{firstName}
#{middleInitial,jdbcType=VARCHAR}
#{lastName}]]></source>

        <h4>
          String Substitution
        </h4>

        <p>
          By default, using the <code>#{}</code> syntax will cause MyBatis to generate <code>PreparedStatement</code> properties and
          set the values safely against the <code>PreparedStatement</code> parameters (e.g. ?). While this is safer,
          faster and almost always preferred, sometimes you just want to directly inject an unmodified string
          into the SQL Statement. For example, for ORDER BY, you might use something like this:
        </p>

        <source><![CDATA[ORDER BY ${columnName}]]></source>

        <p>
          Here MyBatis won't modify or escape the string.
        </p>

        <p>
          String Substitution can be very useful when the metadata(i.e. table name or column name) in the sql statement is dynamic,
          for example, if you want to <code>select</code> from a table by any one of its columns, instead of writing code like:
          <source><![CDATA[
@Select("select * from user where id = #{id}")
User findById(@Param("id") long id);

@Select("select * from user where name = #{name}")
User findByName(@Param("name") String name);

@Select("select * from user where email = #{email}")
User findByEmail(@Param("email") String email);

// and more "findByXxx" method
]]></source>
          you can just write:
          <source><![CDATA[
@Select("select * from user where ${column} = #{value}")
User findByColumn(@Param("column") String column, @Param("value") String value);
]]></source>
          in which the <code>${column}</code> will be substituted directly and the <code>#{value}</code> will be "prepared".
          Thus you can just do the same work by:
          <source><![CDATA[
User userOfId1 = userMapper.findByColumn("id", 1L);
User userOfNameKid = userMapper.findByColumn("name", "kid");
User userOfEmail = userMapper.findByColumn("email", "noone@nowhere.com");
]]></source>
        </p>

        <p>
          This idea can be applied to substitute the table name as well.
        </p>

        <p>
          <span class="label important">NOTE</span> It's not safe to accept input from a user and supply
          it to a statement unmodified in this way. This leads to potential SQL Injection attacks and
          therefore you should either disallow user input in these fields, or always perform your own escapes
          and checks.
        </p>
      </subsection>

      <subsection name="Result Maps">
        <p>
          The <code>resultMap</code> element is the most important and powerful element in MyBatis. It's what allows you to
          do away with 90% of the code that JDBC requires to retrieve data from <code>ResultSet</code>s, and in some cases
          allows you to do things that JDBC does not even support. In fact, to write the equivalent code for
          something like a join mapping for a complex statement could probably span thousands of lines of
          code. The design of the <code>ResultMap</code>s is such that simple statements don't require explicit result
          mappings at all, and more complex statements require no more than is absolutely necessary to
          describe the relationships.
        </p>

        <p>
          You've already seen examples of simple mapped statements that don't have an explicit <code>resultMap</code>. For
          example:
        </p>

        <source><![CDATA[<select id="selectUsers" resultType="map">
  select id, username, hashedPassword
  from some_table
  where id = #{id}
</select>]]></source>

        <p>
          Such a statement simply results in all columns being automatically mapped to the keys of a <code>HashMap</code>,
          as specified by the <code>resultType</code> attribute. While useful in many cases, a <code>HashMap</code> doesn't make a very
          good domain model. It's more likely that your application will use JavaBeans or POJOs (Plain Old
          Java Objects) for the domain model. MyBatis supports both. Consider the following JavaBean:
        </p>
        <source><![CDATA[package com.someapp.model;
public class User {
  private int id;
  private String username;
  private String hashedPassword;

  public int getId() {
    return id;
  }
  public void setId(int id) {
    this.id = id;
  }
  public String getUsername() {
    return username;
  }
  public void setUsername(String username) {
    this.username = username;
  }
  public String getHashedPassword() {
    return hashedPassword;
  }
  public void setHashedPassword(String hashedPassword) {
    this.hashedPassword = hashedPassword;
  }
}]]></source>

        <p>
          Based on the JavaBeans specification, the above class has 3 properties: id, username, and
          hashedPassword. These match up exactly with the column names in the select statement.
        </p>

        <p>
          Such a JavaBean could be mapped to a <code>ResultSet</code> just as easily as the <code>HashMap</code>.
        </p>

        <source><![CDATA[<select id="selectUsers" resultType="com.someapp.model.User">
  select id, username, hashedPassword
  from some_table
  where id = #{id}
</select>]]></source>

        <p>
          And remember that TypeAliases are your friends. Use them so that you don't have to keep typing the
          fully qualified path of your class out. For example:
        </p>

        <source><![CDATA[<!-- In Config XML file -->
<typeAlias type="com.someapp.model.User" alias="User"/>

<!-- In SQL Mapping XML file -->
<select id="selectUsers" resultType="User">
  select id, username, hashedPassword
  from some_table
  where id = #{id}
</select>]]></source>

        <p>
          In these cases MyBatis is automatically creating a <code>ResultMap</code> behind the scenes to auto-map the columns to
          the JavaBean properties based on name.
          If the column names did not match exactly, you could employ
          select clause aliases (a standard SQL feature) on the column names to make the labels match. For
          example:
        </p>

        <source><![CDATA[<select id="selectUsers" resultType="User">
  select
    user_id             as "id",
    user_name           as "userName",
    hashed_password     as "hashedPassword"
  from some_table
  where id = #{id}
</select>]]></source>

        <p>
          The great thing about <code>ResultMap</code>s is that you've already learned a lot about them, but you haven't
          even seen one yet! These simple cases don't require any more than you've seen here. Just for example
          sake, let's see what this last example would look like as an external <code>resultMap</code>, as that is another
          way to solve column name mismatches.
        </p>

        <source><![CDATA[<resultMap id="userResultMap" type="User">
  <id property="id" column="user_id" />
  <result property="username" column="user_name"/>
  <result property="password" column="hashed_password"/>
</resultMap>]]></source>

        <p>
          And the statement that references it uses the <code>resultMap</code> attribute to do so (notice we removed the
          <code>resultType</code> attribute). For example:
        </p>

        <source><![CDATA[<select id="selectUsers" resultMap="userResultMap">
  select user_id, user_name, hashed_password
  from some_table
  where id = #{id}
</select>]]></source>

        <p>
          Now if only the world was always that simple.
        </p>

	    <h4>Advanced Result Maps</h4>

        <p>
          MyBatis was created with one idea in mind: Databases aren't always what you want or need them to be.
          While we'd love every database to be perfect 3rd normal form or BCNF, they aren't. And it would be
          great if it was possible to have a single database map perfectly to all of the applications that use
          it, it's not. Result Maps are the answer that MyBatis provides to this problem.
        </p>

        <p>For example, how would we map this statement?</p>

        <source><![CDATA[<!-- Very Complex Statement -->
<select id="selectBlogDetails" resultMap="detailedBlogResultMap">
  select
       B.id as blog_id,
       B.title as blog_title,
       B.author_id as blog_author_id,
       A.id as author_id,
       A.username as author_username,
       A.password as author_password,
       A.email as author_email,
       A.bio as author_bio,
       A.favourite_section as author_favourite_section,
       P.id as post_id,
       P.blog_id as post_blog_id,
       P.author_id as post_author_id,
       P.created_on as post_created_on,
       P.section as post_section,
       P.subject as post_subject,
       P.draft as draft,
       P.body as post_body,
       C.id as comment_id,
       C.post_id as comment_post_id,
       C.name as comment_name,
       C.comment as comment_text,
       T.id as tag_id,
       T.name as tag_name
  from Blog B
       left outer join Author A on B.author_id = A.id
       left outer join Post P on B.id = P.blog_id
       left outer join Comment C on P.id = C.post_id
       left outer join Post_Tag PT on PT.post_id = P.id
       left outer join Tag T on PT.tag_id = T.id
  where B.id = #{id}
</select>]]></source>

        <p>
          You'd probably want to map it to an intelligent object model consisting of a Blog that was written
          by an Author, and has many Posts, each of which may have zero or many Comments and Tags. The
          following is a complete example of a complex ResultMap (assume Author, Blog, Post, Comments and Tags
          are all type aliases). Have a look at it, but don't worry, we're going to go through each step.
          While it may look daunting at first, it's actually very simple.
        </p>

        <source><![CDATA[<!-- Very Complex Result Map -->
<resultMap id="detailedBlogResultMap" type="Blog">
  <constructor>
    <idArg column="blog_id" javaType="int"/>
  </constructor>
  <result property="title" column="blog_title"/>
  <association property="author" javaType="Author">
    <id property="id" column="author_id"/>
    <result property="username" column="author_username"/>
    <result property="password" column="author_password"/>
    <result property="email" column="author_email"/>
    <result property="bio" column="author_bio"/>
    <result property="favouriteSection" column="author_favourite_section"/>
  </association>
  <collection property="posts" ofType="Post">
    <id property="id" column="post_id"/>
    <result property="subject" column="post_subject"/>
    <association property="author" javaType="Author"/>
    <collection property="comments" ofType="Comment">
      <id property="id" column="comment_id"/>
    </collection>
    <collection property="tags" ofType="Tag" >
      <id property="id" column="tag_id"/>
    </collection>
    <discriminator javaType="int" column="draft">
      <case value="1" resultType="DraftPost"/>
    </discriminator>
  </collection>
</resultMap>]]></source>

        <p>
          The <code>resultMap</code> element has a number of sub-elements and a structure worthy of some discussion. The
          following is a conceptual view of the <code>resultMap</code> element.
        </p>

        <h4>resultMap</h4>
        <ul>
          <li>
            <code>constructor</code> - used for injecting results into the constructor of a class upon instantiation
            <ul>
              <li><code>idArg</code> - ID argument; flagging results as ID will help improve overall performance</li>
              <li><code>arg</code> - a normal result injected into the constructor</li>
            </ul>
          </li>
          <li><code>id</code> – an ID result; flagging results as ID will help improve overall performance</li>
          <li><code>result</code> – a normal result injected into a field or JavaBean property</li>
          <li>
            <code>association</code> – a complex type association; many results will roll up into this type
            <ul>
              <li>nested result mappings – associations are <code>resultMap</code>s themselves, or can refer to one
              </li>
            </ul>
          </li>
          <li>
            <code>collection</code> – a collection of complex types
            <ul>
              <li>nested result mappings – collections are <code>resultMap</code>s themselves, or can refer to one</li>
            </ul>
          </li>
          <li>
            <code>discriminator</code> – uses a result value to determine which <code>resultMap</code> to use
            <ul>
              <li>
                <code>case</code> – a case is a result map based on some value
                <ul>
                  <li>nested result mappings – a case is also a result map itself, and thus can
                    contain many of these same elements, or it can refer to an external resultMap.
                  </li>
                </ul>
              </li>
            </ul>
          </li>
        </ul>

        <table>
          <caption>ResultMap Attributes</caption>
          <thead>
            <tr>
              <th>Attribute</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td><code>id</code></td>
              <td>A unique identifier in this namespace that can be used to reference this result map.</td>
            </tr>
            <tr>
              <td><code>type</code></td>
              <td>A fully qualified Java class name, or a type alias (see the table above for the list of built-in type aliases).
              </td>
            </tr>
            <tr>
              <td><code>autoMapping</code></td>
              <td>If present, MyBatis will enable or disable the automapping for this ResultMap.
                This attribute overrides the global autoMappingBehavior. Default: unset.
              </td>
            </tr>
          </tbody>
        </table>

        <p>
          <span class="label important">Best Practice</span> Always build ResultMaps incrementally. Unit
          tests really help out here. If you try to
          build a gigantic <code>resultMap</code> like the one above all at once, it's likely you'll get it wrong and it
          will be hard to work with. Start simple, and evolve it a step at a time. And unit test! The downside
          to using frameworks is that they are sometimes a bit of a black box (open source or not). Your best
          bet to ensure that you're achieving the behaviour that you intend, is to write unit tests. It also
          helps to have them when submitting bugs.
        </p>

        <p>
          The next sections will walk through each of the elements in more detail.
        </p>

        <h4>id &amp; result</h4>

        <source><![CDATA[<id property="id" column="post_id"/>
<result property="subject" column="post_subject"/>]]></source>

        <p>
          These are the most basic of result mappings. Both <i>id</i> and
          <i>result</i> map a single column value to a
          single property or field of a simple data type (String, int, double, Date, etc.).
        </p>

        <p>
          The only difference between the two is that <i>id</i>
          will flag the result as an identifier property to be
          used when comparing object instances. This helps to improve general performance, but especially
          performance of caching and nested result mapping (i.e. join mapping).
        </p>

        <p>
          Each has a number of attributes:
        </p>

        <table>
          <caption>Id and Result Attributes</caption>
          <thead>
            <tr>
              <th>Attribute</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td><code>property</code></td>
              <td>
                The field or property to map the column result to. If a matching JavaBeans property
                exists for
                the given name, then that will be used. Otherwise, MyBatis will look for a field of the
                given
                name. In both cases you can use complex property navigation using the usual dot
                notation. For
                example, you can map to something simple like: <code>username</code>, or to something more
                complicated
                like: <code>address.street.number</code>.
              </td>
            </tr>
            <tr>
              <td><code>column</code></td>
              <td>
                The column name from the database, or the aliased column label. This is the same string
                that
                would normally be passed to <code>resultSet.getString(columnName)</code>.
              </td>
            </tr>
            <tr>
              <td><code>javaType</code></td>
              <td>
                A fully qualified Java class name, or a type alias (see the table above for the list of
                built-in type aliases). MyBatis can usually figure out the type if you're mapping to a
                JavaBean. However, if you are mapping to a HashMap, then you should specify the javaType
                explicitly to ensure the desired behaviour.
              </td>
            </tr>
            <tr>
              <td><code>jdbcType</code></td>
              <td>
                The JDBC Type from the list of supported types that follows this table. The JDBC type is
                only required for nullable columns upon insert, update or delete. This is a JDBC
                requirement, not a MyBatis one. So even if you were coding JDBC directly, you'd need to
                specify this type – but only for nullable values.
              </td>
            </tr>
            <tr>
              <td><code>typeHandler</code></td>
              <td>
                We discussed default type handlers previously in this documentation. Using this property
                you can override the default type handler on a mapping-by-mapping basis. The value is
                either a fully qualified class name of a TypeHandler implementation, or a type alias.
              </td>
            </tr>
          </tbody>
        </table>

        <h4>Supported JDBC Types</h4>

        <p>
          For future reference, MyBatis supports the following JDBC Types via the included JdbcType
          enumeration.
        </p>

        <table>
          <tr>
            <td><code>BIT</code></td>
            <td><code>FLOAT</code></td>
            <td><code>CHAR</code></td>
            <td><code>TIMESTAMP</code></td>
            <td><code>OTHER</code></td>
            <td><code>UNDEFINED</code></td>
          </tr>
          <tr>
            <td><code>TINYINT</code></td>
            <td><code>REAL</code></td>
            <td><code>VARCHAR</code></td>
            <td><code>BINARY</code></td>
            <td><code>BLOB</code></td>
            <td><code>NVARCHAR</code></td>
          </tr>
          <tr>
            <td><code>SMALLINT</code></td>
            <td><code>DOUBLE</code></td>
            <td><code>LONGVARCHAR</code></td>
            <td><code>VARBINARY</code></td>
            <td><code>CLOB</code></td>
            <td><code>NCHAR</code></td>
          </tr>
          <tr>
            <td><code>INTEGER</code></td>
            <td><code>NUMERIC</code></td>
            <td><code>DATE</code></td>
            <td><code>LONGVARBINARY</code></td>
            <td><code>BOOLEAN</code></td>
            <td><code>NCLOB</code></td>
          </tr>
          <tr>
            <td><code>BIGINT</code></td>
            <td><code>DECIMAL</code></td>
            <td><code>TIME</code></td>
            <td><code>NULL</code></td>
            <td><code>CURSOR</code></td>
            <td><code>ARRAY</code></td>
          </tr>
        </table>

        <h4>constructor</h4>

        <p>
          While properties will work for most Data Transfer Object (DTO) type classes, and likely most of your
          domain model, there may be some cases where you want to use immutable classes. Often tables that
          contain reference or lookup data that rarely or never changes is suited to immutable classes.
          Constructor injection allows you to set values on a class upon instantiation, without exposing
          public methods. MyBatis also supports private properties and private JavaBeans properties to achieve
          this, but some people prefer Constructor injection. The
          <i>constructor</i>
          element enables this.
        </p>

        <p>
          Consider the following constructor:
        </p>

        <source><![CDATA[public class User {
   //...
   public User(Integer id, String username, int age) {
     //...
  }
//...
}]]></source>

        <p>
          In order to inject the results into the constructor, MyBatis needs to identify the constructor for somehow.
          In the following example, MyBatis searches a constructor declared with three parameters: <code>java.lang.Integer</code>, <code>java.lang.String</code> and <code>int</code> in this order.
        </p>

        <source><![CDATA[<constructor>
   <idArg column="id" javaType="int"/>
   <arg column="username" javaType="String"/>
   <arg column="age" javaType="_int"/>
</constructor>]]></source>

        <p>
          When you are dealing with a constructor with many parameters, maintaining the order of arg elements is error-prone.<br />
          Since 3.4.3, by specifying the name of each parameter, you can write arg elements in any order. To reference constructor parameters by their names, you can either add <code>@Param</code> annotation to them or compile the project with '-parameters' compiler option and enable <code>useActualParamName</code> (this option is enabled by default).
          The following example is valid for the same constructor even though the order of the second and the third parameters does not match with the declared order.
        </p>

        <source><![CDATA[<constructor>
   <idArg column="id" javaType="int" name="id" />
   <arg column="age" javaType="_int" name="age" />
   <arg column="username" javaType="String" name="username" />
</constructor>]]></source>

        <p>
          <code>javaType</code> can be omitted if there is a property with the same name and type.
        </p>

        <p>
          The rest of the attributes and rules are the same as for the regular id and result elements.
        </p>

        <table>
          <thead>
            <tr>
              <th>Attribute</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td><code>column</code></td>
              <td>
                The column name from the database, or the aliased column label. This is the same string
                that would normally be passed to <code>resultSet.getString(columnName)</code>.
              </td>
            </tr>
            <tr>
              <td><code>javaType</code></td>
              <td>
                A fully qualified Java class name, or a type alias (see the table above for the list of
                built-in type aliases). MyBatis can usually figure out the type if you're mapping to a
                JavaBean. However, if you are mapping to a HashMap, then you should specify the javaType
                explicitly to ensure the desired behaviour.
              </td>
            </tr>
            <tr>
              <td><code>jdbcType</code></td>
              <td>
                The JDBC Type from the list of supported types that follows this table. The JDBC type is
                only required for nullable columns upon insert, update or delete. This is a JDBC
                requirement, not an MyBatis one. So even if you were coding JDBC directly, you'd need to
                specify this type – but only for nullable values.
              </td>
            </tr>
            <tr>
              <td><code>typeHandler</code></td>
              <td>
                We discussed default type handlers previously in this documentation. Using this property
                you can override the default type handler on a mapping-by-mapping basis. The value is
                either a fully qualified class name of a <code>TypeHandler</code> implementation, or a type alias.
              </td>
            </tr>
            <tr>
              <td><code>select</code></td>
              <td>
                The ID of another mapped statement that will load the complex type required by this
                property mapping. The values retrieved from columns specified in the column attribute
                will be passed to the target select statement as parameters. See the Association element
                for more.
              </td>
            </tr>
            <tr>
              <td><code>resultMap</code></td>
              <td>
                This is the ID of a ResultMap that can map the nested results of this argument into an
                appropriate object graph. This is an alternative to using a call to another select
                statement. It allows you to join multiple tables together into a single <code>ResultSet</code>. Such
                a <code>ResultSet</code> will contain duplicated, repeating groups of data that needs to be
                decomposed and mapped properly to a nested object graph. To facilitate this, MyBatis
                lets you "chain" result maps together, to deal with the nested results. See the
                Association element below for more.
              </td>
            </tr>
            <tr>
              <td><code>name</code></td>
              <td>
                The name of the constructor parameter. Specifying name allows you to write arg elements in any order. See the above explanation. Since 3.4.3.
              </td>
            </tr>
          </tbody>
        </table>

        <h4>association</h4>

        <source><![CDATA[<association property="author" javaType="Author">
  <id property="id" column="author_id"/>
  <result property="username" column="author_username"/>
</association>]]></source>

        <p>
          The association element deals with a "has-one" type relationship. For example, in our example, a
          Blog has one Author. An association mapping works mostly like any other result. You specify the
          target property, the <code>javaType</code> of the property (which MyBatis
          can figure out most of the time), the jdbcType if necessary and a typeHandler if you want to
          override the retrieval of the result values.
        </p>

        <p>
          Where the association differs is that you need to tell MyBatis how to load the association. MyBatis
          can do so in two different ways:
        </p>

        <ul>
          <li>
            Nested Select: By executing another mapped SQL statement that returns the complex type desired.
          </li>
          <li>
            Nested Results: By using nested result mappings to deal with repeating subsets of joined
            results.
          </li>
        </ul>

        <p>
          First, let's examine the properties of the element. As you'll see, it differs from a normal result
          mapping only by the select and resultMap attributes.
        </p>

        <table>
          <thead>
            <tr>
              <th>Attribute</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td><code>property</code></td>
              <td>
                The field or property to map the column result to. If a matching JavaBeans property
                exists for the given name, then that will be used. Otherwise, MyBatis will look for a
                field of the given name. In both cases you can use complex property navigation using the
                usual dot notation. For example, you can map to something simple like: <code>username</code>, or to
                something more complicated like: <code>address.street.number</code>.
              </td>
            </tr>
            <tr>
              <td><code>javaType</code></td>
              <td>
                A fully qualified Java class name, or a type alias (see the table above for the list of
                built- in type aliases). MyBatis can usually figure out the type if you're mapping to a
                JavaBean. However, if you are mapping to a <code>HashMap</code>, then you should specify the javaType
                explicitly to ensure the desired behaviour.
              </td>
            </tr>
            <tr>
              <td><code>jdbcType</code></td>
              <td>
                The JDBC Type from the list of supported types that follows this table. The JDBC type is
                only required for nullable columns upon insert, update or delete. This is a JDBC
                requirement, not an MyBatis one. So even if you were coding JDBC directly, you'd need to
                specify this type – but only for nullable values.
              </td>
            </tr>
            <tr>
              <td><code>typeHandler</code></td>
              <td>
                We discussed default type handlers previously in this documentation. Using this property
                you can override the default type handler on a mapping-by-mapping basis. The value is
                either a fully qualified class name of a TypeHandler implementation, or a type alias.
              </td>
            </tr>
          </tbody>
        </table>

        <h4>Nested Select for Association</h4>

        <table>
          <thead>
            <tr>
              <th>Attribute</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td><code>column</code></td>
              <td>
                The column name from the database, or the aliased column label that holds the value that will be passed to the nested
                statement as an input parameter.
                This is the same string that would normally be passed to <code>resultSet.getString(columnName)</code>.
                Note: To deal with composite keys, you can specify multiple column names to pass to the
                nested select statement by using the syntax <code>column="{prop1=col1,prop2=col2}"</code>. This will
                cause <code>prop1</code> and <code>prop2</code> to be set against the parameter object for the target nested
                select statement.
              </td>
            </tr>
            <tr>
              <td><code>select</code></td>
              <td>
                The ID of another mapped statement that will load the complex type required by this
                property mapping. The values retrieved from columns specified in the column attribute
                will be passed to the target select statement as parameters. A detailed example follows
                this table.
                Note: To deal with composite keys, you can specify multiple column names to pass to the
                nested select statement by using the syntax <code>column="{prop1=col1,prop2=col2}"</code>. This will
                cause <code>prop1</code> and <code>prop2</code> to be set against the parameter object for the target nested
                select statement.
              </td>
            </tr>
            <tr>
              <td><code>fetchType</code></td>
              <td>
                Optional. Valid values are <code>lazy</code> and <code>eager</code>. If present, it supersedes
                the global configuration parameter <code>lazyLoadingEnabled</code> for this mapping.
              </td>
            </tr>
          </tbody>
        </table>

        <p>
          For example:
        </p>

        <source><![CDATA[<resultMap id="blogResult" type="Blog">
  <association property="author" column="author_id" javaType="Author" select="selectAuthor"/>
</resultMap>

<select id="selectBlog" resultMap="blogResult">
  SELECT * FROM BLOG WHERE ID = #{id}
</select>

<select id="selectAuthor" resultType="Author">
  SELECT * FROM AUTHOR WHERE ID = #{id}
</select>]]></source>

        <p>
          That's it. We have two select statements: one to load the Blog, the other to load the Author, and
          the Blog's resultMap describes that the <code>selectAuthor</code> statement should be used to load its author
          property.
        </p>

        <p>
          All other properties will be loaded automatically assuming their column and property names match.
        </p>

        <p>
          While this approach is simple, it will not perform well for large data sets or lists. This problem
          is known as the "N+1 Selects Problem". In a nutshell, the N+1 selects problem is caused like this:
        </p>

        <ul>
          <li>You execute a single SQL statement to retrieve a list of records (the "+1").</li>
          <li>For each record returned, you execute a select statement to load details for each (the "N").
          </li>
        </ul>

        <p>
          This problem could result in hundreds or thousands of SQL statements to be executed. This is not
          always desirable.
        </p>

        <p>
          The upside is that MyBatis can lazy load such queries, thus you might be spared the cost of these
          statements all at once. However, if you load such a list and then immediately iterate through it to
          access the nested data, you will invoke all of the lazy loads, and thus performance could be very
          bad.
        </p>

        <p>
          And so, there is another way.
        </p>

       <h4>Nested Results for Association</h4>

        <table>
          <thead>
            <tr>
              <th>Attribute</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td><code>resultMap</code></td>
              <td>
                This is the ID of a ResultMap that can map the nested results of this association into
                an appropriate object graph. This is an alternative to using a call to another select
                statement. It allows you to join multiple tables together into a single ResultSet. Such
                a ResultSet will contain duplicated, repeating groups of data that needs to be
                decomposed and mapped properly to a nested object graph. To facilitate this, MyBatis
                lets you "chain" result maps together, to deal with the nested results. An example will
                be far easier to follow, and one follows this table.
              </td>
            </tr>
            <tr>
              <td><code>columnPrefix</code></td>
              <td>
                When joining multiple tables, you would have to use column alias to avoid duplicated
                column names in the ResultSet. Specifying columnPrefix allows you to map such columns
                to an external resultMap. Please see the example explained later in this section.
              </td>
            </tr>
            <tr>
              <td><code>notNullColumn</code></td>
              <td>
                By default a child object is created only if at least one of the columns mapped to the child's properties
                is non null. With this attribute you can change this behaviour by specifiying which columns must have a value
                so MyBatis will create a child object only if any of those columns is not null. Multiple column names can be
                specified using a comma as a separator. Default value: unset.
              </td>
            </tr>
            <tr>
              <td><code>autoMapping</code></td>
              <td>If present, MyBatis will enable or disable automapping when mapping the result to this property.
                This attribute overrides the global autoMappingBehavior.
                Note that it has no effect on an external resultMap, so it is pointless to use it with <code>select</code> or <code>resultMap</code> attribute. Default value: unset.
              </td>
            </tr>
          </tbody>
        </table>

        <p>
          You've already seen a very complicated example of nested associations above. The following is a far
          simpler example to demonstrate how this works. Instead of executing a separate statement, we'll join
          the Blog and Author tables together, like so:
        </p>

        <source><![CDATA[<select id="selectBlog" resultMap="blogResult">
  select
    B.id            as blog_id,
    B.title         as blog_title,
    B.author_id     as blog_author_id,
    A.id            as author_id,
    A.username      as author_username,
    A.password      as author_password,
    A.email         as author_email,
    A.bio           as author_bio
  from Blog B left outer join Author A on B.author_id = A.id
  where B.id = #{id}
</select>]]></source>

        <p>
          Notice the join, as well as the care taken to ensure that all results are aliased with a unique and
          clear name. This makes mapping far easier. Now we can map the results:
        </p>

        <source><![CDATA[<resultMap id="blogResult" type="Blog">
  <id property="id" column="blog_id" />
  <result property="title" column="blog_title"/>
  <association property="author" resultMap="authorResult" />
</resultMap>

<resultMap id="authorResult" type="Author">
  <id property="id" column="author_id"/>
  <result property="username" column="author_username"/>
  <result property="password" column="author_password"/>
  <result property="email" column="author_email"/>
  <result property="bio" column="author_bio"/>
</resultMap>]]></source>

        <p>
          In the example above you can see at the Blog's "author" association delegates to the "authorResult"
          resultMap to load the Author instance.
        </p>

        <p>
          <span class="important">Very Important</span>: id elements play a very important role in Nested
          Result mapping. You should always
          specify one or more properties that can be used to uniquely identify the results. The truth is that
          MyBatis will still work if you leave it out, but at a severe performance cost. Choose as few
          properties as possible that can uniquely identify the result. The primary key is an obvious choice
          (even if composite).
        </p>

        <p>
          Now, the above example used an external resultMap element to map the association. This makes the
          Author resultMap reusable. However, if you have no need to reuse it, or if you simply prefer to
          co-locate your result mappings into a single descriptive resultMap, you can nest the association
          result mappings. Here's the same example using this approach:
        </p>

        <source><![CDATA[<resultMap id="blogResult" type="Blog">
  <id property="id" column="blog_id" />
  <result property="title" column="blog_title"/>
  <association property="author" javaType="Author">
    <id property="id" column="author_id"/>
    <result property="username" column="author_username"/>
    <result property="password" column="author_password"/>
    <result property="email" column="author_email"/>
    <result property="bio" column="author_bio"/>
  </association>
</resultMap>]]></source>

        <p>
          What if the blog has a co-author?
          The select statement would look like:
        </p>

        <source><![CDATA[<select id="selectBlog" resultMap="blogResult">
  select
    B.id            as blog_id,
    B.title         as blog_title,
    A.id            as author_id,
    A.username      as author_username,
    A.password      as author_password,
    A.email         as author_email,
    A.bio           as author_bio,
    CA.id           as co_author_id,
    CA.username     as co_author_username,
    CA.password     as co_author_password,
    CA.email        as co_author_email,
    CA.bio          as co_author_bio
  from Blog B
  left outer join Author A on B.author_id = A.id
  left outer join Author CA on B.co_author_id = CA.id
  where B.id = #{id}
</select>]]></source>

        <p>
          Recall that the resultMap for Author is defined as follows.
        </p>

        <source><![CDATA[<resultMap id="authorResult" type="Author">
  <id property="id" column="author_id"/>
  <result property="username" column="author_username"/>
  <result property="password" column="author_password"/>
  <result property="email" column="author_email"/>
  <result property="bio" column="author_bio"/>
</resultMap>]]></source>

        <p>
          Because the column names in the results differ from the columns defined in the resultMap,
          you need to specify <code>columnPrefix</code> to reuse the resultMap for mapping co-author results.
        </p>

        <source><![CDATA[<resultMap id="blogResult" type="Blog">
  <id property="id" column="blog_id" />
  <result property="title" column="blog_title"/>
  <association property="author"
    resultMap="authorResult" />
  <association property="coAuthor"
    resultMap="authorResult"
    columnPrefix="co_" />
</resultMap>]]></source>

        <h4>Multiple ResultSets for Association</h4>

        <table>
          <thead>
            <tr>
              <th>Attribute</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td><code>column</code></td>
              <td>
                When using multiple resultset this attribute specifies the columns (separated by commas) that will be correlated
                with the <code>foreignColumn</code> to identify the parent and the child of a relationship.
              </td>
            </tr>
            <tr>
              <td><code>foreignColumn</code></td>
              <td>
                Identifies the name of the columns that contains the foreign keys which values will be matched against the
                values of the columns specified in the <code>column</code> attibute of the parent type.
              </td>
            </tr>
            <tr>
              <td><code>resultSet</code></td>
              <td>
                Identifies the name of the result set where this complex type will be loaded from.
              </td>
            </tr>
          </tbody>
        </table>

        <p>Starting from version 3.2.3 MyBatis provides yet another way to solve the N+1 problem.</p>

        <p>Some databases allow stored procedures to return more than one resultset or execute more than one statement
         at once and return a resultset per each one. This can be used to hit the database just once
         and return related data without using a join.</p>

        <p>In the example, the stored procedure executes the following queries and returns two result sets.
          The first will contain Blogs and the second Authors.</p>

        <source><![CDATA[SELECT * FROM BLOG WHERE ID = #{id}

SELECT * FROM AUTHOR WHERE ID = #{id}]]></source>

        <p>A name must be given to each result set by adding a
        <code>resultSets</code> attribute to the mapped statement with a list of names separated by commas.</p>

        <source><![CDATA[<select id="selectBlog" resultSets="blogs,authors" resultMap="blogResult" statementType="CALLABLE">
  {call getBlogsAndAuthors(#{id,jdbcType=INTEGER,mode=IN})}
</select>
]]></source>

        <p>
        Now we can specify that the data to fill the "author" association comes in the "authors" result set:
        </p>

        <source><![CDATA[<resultMap id="blogResult" type="Blog">
  <id property="id" column="id" />
  <result property="title" column="title"/>
  <association property="author" javaType="Author" resultSet="authors" column="author_id" foreignColumn="id">
    <id property="id" column="id"/>
    <result property="username" column="username"/>
    <result property="password" column="password"/>
    <result property="email" column="email"/>
    <result property="bio" column="bio"/>
  </association>
</resultMap>]]></source>

        <p>
          You've seen above how to deal with a "has one" type association. But what about "has many"? That's
          the subject of the next section.
        </p>

        <h4>collection</h4>

        <source><![CDATA[<collection property="posts" ofType="domain.blog.Post">
  <id property="id" column="post_id"/>
  <result property="subject" column="post_subject"/>
  <result property="body" column="post_body"/>
</collection>]]></source>

        <p>
          The collection element works almost identically to the association. In fact, it's so similar, to
          document the similarities would be redundant. So let's focus on the differences.
        </p>

        <p>
          To continue with our example above, a Blog only had one Author. But a Blog has many Posts. On the
          blog class, this would be represented by something like:
        </p>

        <source><![CDATA[private List<Post> posts;]]></source>

        <p>
          To map a set of nested results to a List like this, we use the collection element. Just like the
          association element, we can use a nested select, or nested results from a join.
        </p>

        <h4>Nested Select for Collection</h4>

        <p>
          First, let's look at using a nested select to load the Posts for the Blog.
        </p>

        <source><![CDATA[<resultMap id="blogResult" type="Blog">
  <collection property="posts" javaType="ArrayList" column="id" ofType="Post" select="selectPostsForBlog"/>
</resultMap>

<select id="selectBlog" resultMap="blogResult">
  SELECT * FROM BLOG WHERE ID = #{id}
</select>

<select id="selectPostsForBlog" resultType="Post">
  SELECT * FROM POST WHERE BLOG_ID = #{id}
</select>]]></source>

        <p>
          There are a number things you'll notice immediately, but for the most part it looks very similar to
          the association element we learned about above. First, you'll notice that we're using the collection
          element. Then you'll notice that there's a new "ofType" attribute. This attribute is necessary to
          distinguish between the JavaBean (or field) property type and the type that the collection contains.
          So you could read the following mapping like this:
        </p>

        <source><![CDATA[<collection property="posts" javaType="ArrayList" column="id" ofType="Post" select="selectPostsForBlog"/>]]></source>

        <p>
          <span class="important">Read as</span>: "A collection of posts in an ArrayList of type Post."
        </p>

        <p>
          The <code>javaType</code> attribute is really unnecessary, as MyBatis will figure this out for you in most cases.
          So you can often shorten this down to simply:
        </p>

        <source><![CDATA[<collection property="posts" column="id" ofType="Post" select="selectPostsForBlog"/>]]></source>

        <h4>Nested Results for Collection</h4>

        <p>
          By this point, you can probably guess how nested results for a collection will work, because it's
          exactly the same as an association, but with the same addition of the <code>ofType</code> attribute applied.
        </p>

        <p>First, let's look at the SQL:</p>

        <source><![CDATA[<select id="selectBlog" resultMap="blogResult">
  select
  B.id as blog_id,
  B.title as blog_title,
  B.author_id as blog_author_id,
  P.id as post_id,
  P.subject as post_subject,
  P.body as post_body,
  from Blog B
  left outer join Post P on B.id = P.blog_id
  where B.id = #{id}
</select>]]></source>

        <p>
          Again, we've joined the Blog and Post tables, and have taken care to ensure quality result column
          labels for simple mapping. Now mapping a Blog with its collection of Post mappings is as simple as:
        </p>

        <source><![CDATA[<resultMap id="blogResult" type="Blog">
  <id property="id" column="blog_id" />
  <result property="title" column="blog_title"/>
  <collection property="posts" ofType="Post">
    <id property="id" column="post_id"/>
    <result property="subject" column="post_subject"/>
    <result property="body" column="post_body"/>
  </collection>
</resultMap>]]></source>

        <p>
          Again, remember the importance of the id elements here, or read the association section above if you
          haven't already.
        </p>

        <p>
          Also, if you prefer the longer form that allows for more reusability of your result maps, you can
          use the following alternative mapping:
        </p>
        <source><![CDATA[<resultMap id="blogResult" type="Blog">
  <id property="id" column="blog_id" />
  <result property="title" column="blog_title"/>
  <collection property="posts" ofType="Post" resultMap="blogPostResult" columnPrefix="post_"/>
</resultMap>

<resultMap id="blogPostResult" type="Post">
  <id property="id" column="id"/>
  <result property="subject" column="subject"/>
  <result property="body" column="body"/>
</resultMap>]]></source>

        <h4>Multiple ResultSets for Collection</h4>

        <p>
          As we did for the association, we can call a stored procedure that executes two queries and returns two result sets, one with Blogs
          and another with Posts:
        </p>

        <source><![CDATA[SELECT * FROM BLOG WHERE ID = #{id}

SELECT * FROM POST WHERE BLOG_ID = #{id}]]></source>

        <p>A name must be given to each result set by adding a
        <code>resultSets</code> attribute to the mapped statement with a list of names separated by commas.</p>

        <source><![CDATA[<select id="selectBlog" resultSets="blogs,posts" resultMap="blogResult">
  {call getBlogsAndPosts(#{id,jdbcType=INTEGER,mode=IN})}
</select>]]></source>

        <p>We specify that the "posts" collection will be filled out of data contained in the result set named "posts":</p>

        <source><![CDATA[<resultMap id="blogResult" type="Blog">
  <id property="id" column="id" />
  <result property="title" column="title"/>
  <collection property="posts" ofType="Post" resultSet="posts" column="id" foreignColumn="blog_id">
    <id property="id" column="id"/>
    <result property="subject" column="subject"/>
    <result property="body" column="body"/>
  </collection>
</resultMap>]]></source>

        <p>
          <span class="label important">NOTE</span> There's no limit to the depth, breadth or
          combinations of the associations and collections that you map.
          You should keep performance in mind when mapping them. Unit testing and performance
          testing of your application goes a long way toward discovering the best approach for your
          application. The nice thing is that MyBatis lets you change your mind later, with very little (if
          any) impact to your code.
        </p>

        <p>
          Advanced association and collection mapping is a deep subject. Documentation can only get you so
          far. With a little practice, it will all become clear very quickly.
        </p>

        <h4>discriminator</h4>

        <source><![CDATA[<discriminator javaType="int" column="draft">
  <case value="1" resultType="DraftPost"/>
</discriminator>]]></source>

        <p>
          Sometimes a single database query might return result sets of many different (but hopefully somewhat
          related) data types. The discriminator element was designed to deal with this situation, and others,
          including class inheritance hierarchies. The discriminator is pretty simple to understand, as it
          behaves much like a switch statement in Java.
        </p>

        <p>
          A discriminator definition specifies column and javaType attributes. The column is where MyBatis
          will look for the value to compare. The javaType is required to ensure the proper kind of equality
          test is performed (although String would probably work for almost any situation). For example:
        </p>

        <source><![CDATA[<resultMap id="vehicleResult" type="Vehicle">
  <id property="id" column="id" />
  <result property="vin" column="vin"/>
  <result property="year" column="year"/>
  <result property="make" column="make"/>
  <result property="model" column="model"/>
  <result property="color" column="color"/>
  <discriminator javaType="int" column="vehicle_type">
    <case value="1" resultMap="carResult"/>
    <case value="2" resultMap="truckResult"/>
    <case value="3" resultMap="vanResult"/>
    <case value="4" resultMap="suvResult"/>
  </discriminator>
</resultMap>]]></source>

        <p>
          In this example, MyBatis would retrieve each record from the result set and compare its vehicle type
          value. If it matches any of the discriminator cases, then it will use the <code>resultMap</code> specified by the
          case. This is done exclusively, so in other words, the rest of the resultMap is ignored (unless it
          is extended, which we talk about in a second). If none of the cases match, then MyBatis simply uses
          the resultMap as defined outside of the discriminator block. So, if the carResult was declared as
          follows:
        </p>


        <source><![CDATA[<resultMap id="carResult" type="Car">
  <result property="doorCount" column="door_count" />
</resultMap>]]></source>

        <p>
          Then ONLY the doorCount property would be loaded. This is done to allow completely independent
          groups of discriminator cases, even ones that have no relationship to the parent resultMap. In this
          case we do of course know that there's a relationship between cars and vehicles, as a Car is-a
          Vehicle. Therefore, we want the rest of the properties loaded too. One simple change to the
          resultMap and we're set to go.
        </p>

        <source><![CDATA[<resultMap id="carResult" type="Car" extends="vehicleResult">
  <result property="doorCount" column="door_count" />
</resultMap>]]></source>

        <p>
          Now all of the properties from both the vehicleResult and carResult will be loaded.
        </p>

        <p>
          Once again though, some may find this external definition of maps somewhat tedious. Therefore
          there's an alternative syntax for those that prefer a more concise mapping style. For example:
        </p>

        <source><![CDATA[<resultMap id="vehicleResult" type="Vehicle">
  <id property="id" column="id" />
  <result property="vin" column="vin"/>
  <result property="year" column="year"/>
  <result property="make" column="make"/>
  <result property="model" column="model"/>
  <result property="color" column="color"/>
  <discriminator javaType="int" column="vehicle_type">
    <case value="1" resultType="carResult">
      <result property="doorCount" column="door_count" />
    </case>
    <case value="2" resultType="truckResult">
      <result property="boxSize" column="box_size" />
      <result property="extendedCab" column="extended_cab" />
    </case>
    <case value="3" resultType="vanResult">
      <result property="powerSlidingDoor" column="power_sliding_door" />
    </case>
    <case value="4" resultType="suvResult">
      <result property="allWheelDrive" column="all_wheel_drive" />
    </case>
  </discriminator>
</resultMap>]]></source>

        <p>
          <span class="label important">NOTE</span> Remember
          that these are all Result Maps, and if you don't specify any results at all, then MyBatis will
          automatically match up columns and properties for you. So most of these examples are more verbose
          than they really need to be. That said, most databases are kind of complex and it's unlikely that
          we'll be able to depend on that for all cases.
        </p>

      </subsection>
      <subsection name="Auto-mapping">

        <p>
          As you have already seen in the previous sections, in simple cases MyBatis can auto-map the results for you
          and in others you will need to build a result map.
          But as you will see in this section you can also mix both strategies.
          Let's have a deeper look at how auto-mapping works.
        </p>

        <p>
          When auto-mapping results MyBatis will get the column name and look for a property with the same name ignoring case. That means that if
          a column named <i>ID</i> and property named <i>id</i> are found, MyBatis will set the <i>id</i> property with the <i>ID</i> column value.
        </p>

        <p>
          Usually database columns are named using uppercase letters and underscores between words and java properties often follow the camelcase
          naming covention. To enable the auto-mapping between them set the setting <code>mapUnderscoreToCamelCase</code> to true.
        </p>

        <p>
          Auto-mapping works even when there is an specific result map. When this happens, for each result map, all columns that are present in the
          ResultSet that have not a manual mapping will be auto-mapped, then manual mappings will be processed.
          In the following sample <i>id</i> and <i>userName</i> columns will be auto-mapped and <i>hashed_password</i> column will be mapped.</p>

        <source><![CDATA[<select id="selectUsers" resultMap="userResultMap">
  select
    user_id             as "id",
    user_name           as "userName",
    hashed_password
  from some_table
  where id = #{id}
</select>]]></source>

        <source><![CDATA[<resultMap id="userResultMap" type="User">
  <result property="password" column="hashed_password"/>
</resultMap>]]></source>

        <p>
          There are three auto-mapping levels:
        </p>

        <ul>
          <li>
            <code>NONE</code> - disables auto-mapping. Only manually mapped properties will be set.
          </li>
          <li>
            <code>PARTIAL</code> - will auto-map results except those that have nested result mappings defined inside (joins).
          </li>
          <li>
            <code>FULL</code> - auto-maps everything.
          </li>
        </ul>

        <p>
          The default value is <code>PARTIAL</code>, and it is so for a reason. When <code>FULL</code> is used auto-mapping will
          be performed when processing join results and joins retrieve data of several different entities in the same row
          hence this may result in undesired mappings. To understand the risk have a look at the following sample:
        </p>

        <source><![CDATA[<select id="selectBlog" resultMap="blogResult">
  select
    B.id,
    B.title,
    A.username,
  from Blog B left outer join Author A on B.author_id = A.id
  where B.id = #{id}
</select>]]></source>

        <source><![CDATA[<resultMap id="blogResult" type="Blog">
  <association property="author" resultMap="authorResult"/>
</resultMap>

<resultMap id="authorResult" type="Author">
  <result property="username" column="author_username"/>
</resultMap>]]></source>

        <p>
          With this result map both <i>Blog</i> and <i>Author</i> will be auto-mapped. But note that <i>Author</i> has an <i>id</i>
          property and there is a column named <i>id</i> in the ResultSet so Author's id will be filled with Blog's id, and that is not
          what you were expecting. So use the <code>FULL</code> option with caution.
        </p>

        <p>
          Regardless of the auto-mapping level configured you can enable or disable the automapping for an specific ResultMap
          by adding the attribute <code>autoMapping</code> to it:
        </p>

        <source><![CDATA[<resultMap id="userResultMap" type="User" autoMapping="false">
  <result property="password" column="hashed_password"/>
</resultMap>]]></source>

      </subsection>
      <subsection name="cache">
        <p>
          MyBatis includes a powerful transactional query caching feature which is very configurable and customizable.
          A lot of changes have been made in the MyBatis 3 cache implementation to make it both more powerful and far easier to configure.
        </p>

        <p>
          By default, just local session caching is enabled that is used solely to cache data for the duration of a session.
          To enable a global second level of caching you simply need to add one line to your SQL Mapping file:
        </p>

        <source><![CDATA[<cache/>]]></source>

        <p>
          Literally that's it. The effect of this one simple statement is as follows:
        </p>

        <ul>
          <li>All results from select statements in the mapped statement file will be cached.</li>
          <li>All insert, update and delete statements in the mapped statement file will flush the cache.</li>
          <li>The cache will use a Least Recently Used (LRU) algorithm for eviction.</li>
          <li>The cache will not flush on any sort of time based schedule (i.e. no Flush Interval).</li>
          <li>The cache will store 1024 references to lists or objects (whatever the query method returns).
          </li>
          <li>
            The cache will be treated as a read/write cache, meaning objects retrieved are not shared and
            can be safely modified by the caller, without interfering with other potential modifications by
            other callers or threads.
          </li>
        </ul>

        <p>
          <span class="label important">NOTE</span> The cache will only apply to statements declared in the mapping file
          where the cache tag is located. If you are using the Java API in conjunction with the XML mapping files, then
          statements declared in the companion interface will not be cached by default. You will need to refer to the
          cache region using the @CacheNamespaceRef annotation.
        </p>

        <p>
          All of these properties are modifiable through the attributes of the cache element. For example:
        </p>

        <source><![CDATA[<cache
  eviction="FIFO"
  flushInterval="60000"
  size="512"
  readOnly="true"/>]]></source>

        <p>
          This more advanced configuration creates a FIFO cache that flushes once every 60 seconds, stores up
          to 512 references to result objects or lists, and objects returned are considered read-only, thus
          modifying them could cause conflicts between callers in different threads.
        </p>

        <p>
          The available eviction policies available are:
        </p>

        <ul>
          <li>
            <code>LRU</code> – Least Recently Used: Removes objects that haven't been used for the longst period of
            time.
          </li>
          <li>
            <code>FIFO</code> – First In First Out: Removes objects in the order that they entered the cache.
          </li>
          <li>
            <code>SOFT</code> – Soft Reference: Removes objects based on the garbage collector state and the rules of
            Soft References.
          </li>
          <li>
            <code>WEAK</code> – Weak Reference: More aggressively removes objects based on the garbage collector state
            and rules of Weak References.
          </li>
        </ul>

        <p>The default is LRU.</p>

        <p>
          The flushInterval can be set to any positive integer and should represent a reasonable amount of
          time specified in milliseconds. The default is not set, thus no flush interval is used and the cache
          is only flushed by calls to statements.
        </p>

        <p>
          The size can be set to any positive integer, keep in mind the size of the objects your caching and
          the available memory resources of your environment. The default is 1024.
        </p>

        <p>
          The readOnly attribute can be set to true or false. A read-only cache will return the same instance
          of the cached object to all callers. Thus such objects should not be modified. This offers a
          significant performance advantage though. A read-write cache will return a copy (via serialization)
          of the cached object. This is slower, but safer, and thus the default is false.
        </p>

        <p>
          <span class="label important">NOTE</span> Second level cache is transactional. That means that it is updated
          when a SqlSession finishes with commit or when it finishes with rollback but no inserts/deletes/updates
          with flushCache=true where executed.
        </p>

        <h4>Using a Custom Cache</h4>

        <p>
          In addition to customizing the cache in these ways, you can also completely override the cache
          behavior by implementing your own cache, or creating an adapter to other 3rd party caching
          solutions.
        </p>

        <source><![CDATA[<cache type="com.domain.something.MyCustomCache"/>]]></source>

        <p>
          This example demonstrates how to use a custom cache implementation. The class specified in the type
          attribute must implement the org.apache.ibatis.cache.Cache interface and provide a constructor that gets
          an String id as an argument. This interface is one of the more complex in the MyBatis framework, but simple given what it does.
        </p>

        <source><![CDATA[public interface Cache {
  String getId();
  int getSize();
  void putObject(Object key, Object value);
  Object getObject(Object key);
  boolean hasKey(Object key);
  Object removeObject(Object key);
  void clear();
}]]></source>

        <p>
          To configure your cache, simply add public JavaBeans properties to your Cache implementation, and
          pass properties via the cache Element, for example, the following would call a method called
          <code>setCacheFile(String file)</code> on your Cache implementation:
        </p>

        <source><![CDATA[<cache type="com.domain.something.MyCustomCache">
  <property name="cacheFile" value="/tmp/my-custom-cache.tmp"/>
</cache>]]></source>

        <p>
          You can use JavaBeans properties of all simple types, MyBatis will do the conversion.
          And you can specify a placeholder(e.g. <code>${cache.file}</code>) to replace value defined at <a href="configuration.html#properties">configuration properties</a>.
        </p>

        <p>
          Since 3.4.2, the MyBatis has been supported to call an initialization method after it's set all properties.
          If you want to use this feature, please implements the <code>org.apache.ibatis.builder.InitializingObject</code>
          interface on your custom cache class.
        </p>

        <source><![CDATA[public interface InitializingObject {
  void initialize() throws Exception;
}]]></source>

        <p><span class="label important">NOTE</span>
          Settings of cache (like eviction strategy, read write..etc.) in section above are not applied
          when using Custom Cache.
        </p>

        <p>
          It's important to remember that a cache configuration and the cache instance are bound to the
          namespace of the SQL Map file. Thus, all statements in the same namespace as the cache are bound by
          it. Statements can modify how they interact with the cache, or exclude themselves completely by
          using two simple attributes on a statement-by-statement basis. By default, statements are configured
          like this:
        </p>

        <source><![CDATA[<select ... flushCache="false" useCache="true"/>
<insert ... flushCache="true"/>
<update ... flushCache="true"/>
<delete ... flushCache="true"/>]]></source>

        <p>
          Since that's the default, you obviously should never explicitly configure a statement that way.
          Instead, only set the flushCache and useCache attributes if you want to change the default behavior.
          For example, in some cases you may want to exclude the results of a particular select statement from
          the cache, or you might want a select statement to flush the cache. Similarly, you may have some
          update statements that don't need to flush the cache upon execution.
        </p>

          <h4>cache-ref</h4>
        <p>
          Recall from the previous section that only the cache for this particular namespace will be used or
          flushed for statements within the same namespace. There may come a time when you want to share the
          same cache configuration and instance between namespaces. In such cases you can reference another
          cache by using the cache-ref element.
        </p>

        <source><![CDATA[<cache-ref namespace="com.someone.application.data.SomeMapper"/>]]></source>
      </subsection>
    </section>
  </body>
</document>
