select

select ステートメントは、MyBatis で最も頻繁に使われる要素のひとつです。 データを取り出すことができてはじめてデータベースにデータを追加する意味があるので、ほとんどのアプリケーションではデータを変更するよりも検索する回数の方が多くなります。 insert, update, delete のそれぞれに対して、多くの select があるはずです。 これは MyBatis の大原則の一つであり、クエリ発行と結果のマッピングに注力している理由でもあります。 シンプルなケースでは、select 要素は非常に簡単です。１つ例を挙げましょう。

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

これは selectPerson というステートメントで、int （または Integer）型の引数を取り、列名を key、値を value として保持する HashMap を返します。

パラメーターは次のように記述されています。

#{id}

このように記述すると、MyBatis は PreparedStatement のパラメーターを作成します。 JDBC では PreparedStatement を作成する場合の '?' に相当します。

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

JDBC 単体で select 結果を展開してオブジェクトのインスタンスにマップするためにはもっと多くのコードが必要ですが、MyBatis を使えばそうしたコードは書かずに済みます。 パラメーターと結果のマッピングについては他にも知っておくべきことが数多くあります。 これらについては、後ほどそれぞれに独立した章を用意して説明します。

ステートメントに関して細かい設定ができるように、select 要素には多くの属性があります。

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

insert, update and delete

データを変更するステートメントである insert, update, delete は、非常によく似た実装となっています。

<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">

以下、insert, update, delete ステートメントの例をいくつか挙げておきます。

<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>

前述のように、insert は自動生成されたキーを扱うため、追加の属性や子要素を持つことができるようになっています。

お使いのデータベースがキーの自動生成に対応しているなら（MySQL や SQL Server は対応しています）、単純に useGeneratedKeys に true を設定し、keyPropoerty でキーが格納されるプロパティを指定するだけです。 例えば上記の Author テーブルで id 列に自動生成が設定されていた場合、ステートメントは次のように書くことができます。

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

複数行の一括挿入に対応したデータベースなら、 Author のリストまたは配列を引数として渡して自動生成された id の値を一括取得することも可能です。

<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>

主にキーの自動生成に対応していないデータベースやドライバーのため、MyBatis はもうひとつ別の方法を提供しています。

全く実用的ではありませんが、MyBatis の柔軟さを示す意味も込めて、ID をランダムに生成する例を挙げておきます。

<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>

上記の例では、最初に selectKey ステートメントが実行され、Author オブジェクトの id プロパティに生成された乱数がセットされます。 次に、insert ステートメントが実行されます。 こうすることで、Java 側でややこしいコードを書かなくても自動生成と同様の結果を得ることができるようになっています。

selectKey 要素は次の属性を持っています。

<selectKey
  keyProperty="id"
  resultType="int"
  order="BEFORE"
  statementType="PREPARED">

例外として、INSERT, UPDATE, DELETE 文から ResultSet を返す SQL 文（PostgreSQL, MariaDB の RETURNING , MS SQL Server の OUTPUT など）で結果をマップするためには <select /> を使用する必要があります。

<select id="insertAndGetAuthor" resultType="domain.blog.Author"
      affectData="true" flushCache="true">
  insert into Author (username, password, email, bio)
  values (#{username}, #{password}, #{email}, #{bio})
  returning id, username, password, email, bio
</select>

sql

この要素を使うと、再利用可能な SQL コードのスニペットを定義しておいて、他のステートメントにインクルードすることができます。このときパラメータを指定することもできますが、インクルードの解決はロード時に行われるので、静的な文字列のみ指定可能です。
例：

<sql id="userColumns"> ${alias}.id,${alias}.username,${alias}.password </sql>

上記の SQL スニペットを他のステートメントにインクルードするには、次のように記述します。

<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>

呼び出し側の property 要素で指定された値を、sql 要素に内包された include 要素の refid 属性や property 要素の value 属性として指定することも可能です。
例：

<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>

Parameters

これまでのステートメントの例では、すべて単純なパラメーターを利用していました。パラメーターは非常に強力な要素です。単純な用途（たぶん全用途の９割くらい）については、特筆すべきことはありません。
例：

<select id="selectUsers" resultType="User">
  select id, username, password
  from users
  where id = #{id}
</select>

上記は、名前を指定してパラメーターを参照するごく簡単な例です。parameterType が int と指定されていますので、好きな名前を使って参照することができます。プリミティブ型や Integer, String などの単純型はプロパティを持たないので、引数の参照はパラメーターの値そのものに置き換えられます。
パラメーターとして複合型を渡した場合はもう少し複雑です。次の例を見てください。

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

User 型のオブジェクトがパラメーターとしてステートメントに渡されると、id, username, password の各プロパティが参照され、その値が PreparedStatement の引数として渡されます。

このように、ステートメントにパラメーターを渡すだけならとても簡単です。しかし、パラメーターマップには更にいろいろな機能があります。

まず、他と同じ様に、より具体的に型を指定することができます。

#{property,javaType=int,jdbcType=NUMERIC}

他と同様、ほとんどの場合 javaType は自動的に検出されますが、例外は HashMap です。パラメーターとして HashMap を使う場合は、正しい TypeHandler が使用されるよう javaType を指定してください。

重要 JDBC の仕様上、値として null を設定する場合は JDBC タイプが必須となります。 詳しくは PreparedStatement.setNull() メソッドの javadoc を参照してください。

タイプハンドラーの完全修飾クラス名またはエイリアスを指定して、特定のタイプハンドラーを割り当てることもできます。

#{age,javaType=int,jdbcType=NUMERIC,typeHandler=MyTypeHandler}

だんだんゴチャゴチャしてきましたが、実際のところ、これらの属性を指定することは滅多にないと思います。

数値型に関しては、有効桁数を指定するための numericScale という属性もあります。

#{height,javaType=double,jdbcType=NUMERIC,numericScale=2}

最後になりますが、mode 属性で IN, OUT, INOUT パラメーターを指定することができます。 OUT または INOUT の場合は、パラメーターオブジェクトのプロパティの値が変更されます。 mode が OUT または INOUT で jdbcType が CURSOR（Oracle の REFCURSOR）の場合は、ResultSet とパラメーターの型をマッピングする resultMap を指定する必要があります。ただし jdbcType として CURSOR を指定した場合 javaType には自動的に ResultSet が設定されますので、javaType の指定は省略可能です。

#{department, mode=OUT, jdbcType=CURSOR, javaType=ResultSet, resultMap=departmentResultMap}

MyBatis ではより高度な struct のようなデータ型もサポートされていますが、OUT パラメーターを登録するときに型名を指定する必要があります。

#{middleInitial, mode=OUT, jdbcType=STRUCT, jdbcTypeName=MY_TYPE, resultMap=departmentResultMap}

このように多くの強力なオプションがあるわけですが、ほとんどの場合、単純にプロパティ名を指定すれば、後は MyBatis がよきに計らってくれるはずです。 あとは、null が設定可能な列に対して jdbcType を指定するくらいでしょう。

#{firstName}
#{middleInitial,jdbcType=VARCHAR}
#{lastName}

文字列代入

デフォルトでは、#{} という表記を使うと PreparedStatement のプロパティが生成され、PreparedStatement の引数（? の部分）に対して安全な値が設定されるようになっています。 これは安全かつ高速なので、ほとんどすべてのケースで推奨される方法ですが、時には文字列をそのまま SQL 文に挿入した方が都合が良い場合があります。例えば ORDER BY 句は以下のように記述できます。

ORDER BY ${columnName}

この場合、MyBatis は引数として渡された文字列を変更したりエスケープしたりしません。

文字列代入は、メタ情報(例：テーブル名やカラム名など)をSQLステートメントへ動的に埋め込みたい場合に非常に便利な仕組みです。 例えば、任意のカラム値に一致するレコードを取得する場合に、以下のようにカラム毎にメソッドを用意するのではなく、

@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

@Select("select * from user where ${column} = #{value}")
User findByColumn(@Param("column") String column, @Param("value") String value);

User userOfId1 = userMapper.findByColumn("id", 1L);
User userOfNameKid = userMapper.findByColumn("name", "kid");
User userOfEmail = userMapper.findByColumn("email", "noone@nowhere.com");

この考え方はテーブル名にも適用することができます。

重要 この方法を使って、ユーザーが入力した文字列を直接 SQL 文に代入するのは危険です。SQL インジェクションの原因となる可能性がありますので、ユーザーによる入力を受け付けないようにしておくか、常にプログラム側で独自にエスケープやチェックの処理を行うようにしてください。

Result Maps

MyBatis の中で最も重要かつ強力なのが resultMap 要素です。resultMap のおかげで、JDBC を使って ResultSet からデータを取得する場合に書かなくてはならないコードの９割を省くことができ、またときには JDBC がサポートすらしていないことも可能となるのです。 実際、複雑なクエリの結果を結合してマッピングするコードを書く場合、数千行ものコードになってしまう場合もあります。 ResultMap は、簡単なステートメントなら明示的にマッピングな記述を省略でき、複雑なステートメントの場合でもオブジェクト同士の関連付けを行うための必要最小限のコードのみを記述すれば良いように設計されています。

明示的な resultMap を必要としない、簡単な Mapped Statement については既に例として出てきました。
例：

<select id="selectUsers" resultType="map">
  select id, username, hashedPassword
  from some_table
  where id = #{id}
</select>

この例の場合、resultType で指定された通り、すべての列が自動的に HashMap のキーとしてマップされます。 便利な時もありますが、HashMap は良いドメインモデルとは言えません。 ほとんどのアプリケーションではドメインモデルとして JavaBeans や POJO (Plain Old Java Objects) を使っていると思います。MyBatis はどちらもサポートしています。
次のような JavaBean があったとします。

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;
  }
}

JavaBeans の仕様によれば、上記のクラスは３つのプロパティ id, username, hashedPassword を持っているということになります。 これらのプロパティは、先に挙げた select ステートメントの中で指定されている列名と一致しています。

このような条件を満たす JavaBean であれば、HashMap のときと同じように ResultSet にマップすることができます。

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

タイプエイリアスを使えば何度も完全修飾クラス名を入力しなくて済む、ということも思い出してください。

<!-- 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>

こうしたケースでは、名前に基づいて列を JavaBean にマップするための ResultMap が MyBatis によって自動的に作成されます。 もし列名が一致しない場合、select 文で列に別名をつけることで対応可能です（列の別名は標準 SQL の機能です）。

<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>

ResultMap の素晴らしいところは、まだ一つの例も挙げていないにも関わらず、あなたは既にその多くを学んでいるということです。 これらのシンプルなケースでは既に見てきた以上のことは何も必要ありません。 列名の不一致を解消するもう一つの方法でもありますが、この最後のサンプルで resultMap を明示的に定義したらどうなるか見てみましょう。

<resultMap id="userResultMap" type="User">
  <id property="id" column="user_id" />
  <result property="username" column="user_name"/>
  <result property="password" column="hashed_password"/>
</resultMap>

そして、resultMap 属性を使って定義した ResultMap を参照するステートメントは以下のようになります（resultType 属性は削除しています）。

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

全てがこんなに簡単なら良いのでしょうが、そう甘くはありません。

高度な結果マッピング

MyBatis は「データベースは必ずしも希望通りに定義されている訳ではない」という思想に基づいて設計されています。 すべてのデータベースが完全な第三正規形あるいは BCNF なら最高ですが、実際はそうではありません。 また、たったひとつで全てのアプリケーションに適合できるようなデータベースを作ることができたら素晴らしいですが、これも現実とは異なります。 こうした問題に対する MyBatis の答えが Result Map です。

例えば、こんなステートメントをどうやってマップすれば良いのでしょう？

<!-- 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>

あなたはおそらく、Author によって書かれた、たくさんの Post を持つ Blog といったようなオブジェクトモデルにマップしたいと考えるでしょう。 次に上げるのは、複雑な ResultMap の完全な例です（Author, Blog, Post, Comments, Tags はすべてタイプエイリアスとします）。 後ほどひとつずつ説明しますが、とりあえず目を通してみてください。 最初は難解に思えるかも知れませんが、実際は非常にシンプルです。

<!-- 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>

resultMap 要素には多くの子要素や階層構造があり、それぞれについて多少説明が必要です。 以下は resultMap 要素の構成要素です。

<id property="id" column="post_id"/>
<result property="subject" column="post_subject"/>

public class User {
   //...
   public User(Integer id, String username, int age) {
  //...
  }
//...
}

<constructor>
   <idArg column="id" javaType="int"/>
   <arg column="username" javaType="String"/>
   <arg column="arg" javaType="_int"/>
</constructor>

<constructor>
   <idArg column="id" javaType="int" name="id" />
   <arg column="age" javaType="_int" name="age" />
   <arg column="username" javaType="String" name="username" />
</constructor>

<association property="author" column="blog_author_id" javaType="Author">
  <id property="id" column="author_id"/>
  <result property="username" column="author_username"/>
</association>

<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>

<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>

<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>

<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>

<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>

<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>

<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>

SELECT * FROM BLOG WHERE ID = #{id}

SELECT * FROM AUTHOR WHERE ID = #{id}

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

<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>

<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>

private List<Post> posts;

<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>

<collection property="posts" javaType="ArrayList" column="id" ofType="Post" select="selectPostsForBlog"/>

<collection property="posts" column="id" ofType="Post" select="selectPostsForBlog"/>

<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>

<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>

<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>

SELECT * FROM BLOG WHERE ID = #{id}

SELECT * FROM POST WHERE BLOG_ID = #{id}

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

<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>

<discriminator javaType="int" column="draft">
  <case value="1" resultType="DraftPost"/>
</discriminator>

<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>

<resultMap id="carResult" type="Car">
  <result property="doorCount" column="door_count" />
</resultMap>

<resultMap id="carResult" type="Car" extends="vehicleResult">
  <result property="doorCount" column="door_count" />
</resultMap>

<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>

自動マッピング

前章では、シンプルなケースでは MyBatis の自動マッピングが利用できるということと、複雑なケースではあなた自身で Result Map を記述する必要があるということを説明しました。 この章では更に、この２つの方法を同時に利用する方法を説明していきます。 まず、自動マッピングの動作について詳しく見て行きましょう。

結果を自動マッピングする際、MyBatis は列名と同じ名前を持つプロパティを探します（大文字と小文字は区別しません）。 例えば ID という名前の列と id という名前のプロパティが見つかった場合、MyBatis は id プロパティに ID 列の値をセットします。

通常、データベースの列名は英数字と単語を区切るアンダースコアで定義され、Java のプロパティはキャメルケースで定義されるのが一般的です。 mapUnderscoreToCamelCase に true に設定すると、この一般的な命名規則に基づいて自動マッピングを適用することができます。

Result Map が指定されている場合でも自動マッピングは動作します。この場合、ResultSet に含まれる列のうち、各 Result Map で明示的にマッピングが指定されていない列が自動マッピングの対象となります。 次の例では、hashed_password 列が password プロパティにマップされ、id と userName 列が自動マッピングの対象となります。

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

<resultMap id="userResultMap" type="User">
  <result property="password" column="hashed_password"/>
</resultMap>

自動マッピングには３つのレベルがあります。

• NONE - 自動マッピングを無効化します。明示的にマッピングが指定されたプロパティにのみ値がセットされます。
• PARTIAL - ネストされた Result Map を持たない Result Map のみが自動マッピングの対象となります。
• FULL - 全ての Result Map が自動マッピングの対象となります。

デフォルト値は PARTIAL で、それには理由があります。 FULL が指定されていると、JOIN 句によって複数のエンティティに対する結果が一行に結合されているような場合に自動マッピングによって意図しないマッピングが実行されてしまう場合があります。 次の例を見てください。

<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>

<resultMap id="blogResult" type="Blog">
  <association property="author" resultMap="authorResult"/>
</resultMap>

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

この Result Map では、Blog と Author の両方が自動マッピングの対象となりますが、Author に id というプロパティがあり、ResultSet に id という列が含まれているため、Author の id に Blog の id がセットされることになります。 自動マッピングで FULL を指定する場合は、こうした意図しないマッピングが行われないように注意する必要があります。

尚、グローバルな自動マッピング設定とは別に、autoMapping 属性を指定することで特定のステートメントでの自動マッピング動作を有効／無効化することもできます。

<resultMap id="userResultMap" type="User" autoMapping="false">
  <result property="password" column="hashed_password"/>
</resultMap>

cache

MyBatis には非常に柔軟なトランザクション対応のクエリキャッシング機能が用意されています。 MyBatis 3 では、より強力で、かつ簡単に設定できるよう、キャッシュの実装に多くの改良が加えられています。

デフォルトでは、セッション生存期間中のデータを保持するローカルセッションキャッシュのみが有効です。 グローバルな２次キャッシュを有効にするためには、Mapper XML ファイルに次の一行を追加するだけです。

<cache/>

文字通りこれだけです。この行の効果は次の通りです。

• この SQL マップファイルに含まれる select ステートメントの結果は全てキャッシュされます。
• この SQL マップファイルに含まれる insert, update, delete ステートメントを実行するとキャッシュがフラッシュされます。
• このキャッシュは LRU アルゴリズムに基づいて置き換えられます。
• このキャッシュは経過時間によってフラッシュされることはありません（つまり Flush Interval は設定されていないということです）。
• このキャッシュはクエリ結果のリストまたはオブジェクトへの参照を 1024 個格納します。
• このキャッシュは読み書き可能なキャッシュとして扱われます。これはつまり、取得したオブジェクトは共有されず、呼び出した側で安全に変更することができる（別の呼び出し元や他スレッドでの変更の影響を受けない）ということを意味しています。

重要 対応する Java マッパーのステートメントをキャッシュの適用対象に含めるためには @CacheNamespaceRef アノテーションで XML マッパーのネームスペースを指定する必要があります。

これらのプロパティは cache 要素の属性で変更することができます。

<cache
  eviction="FIFO"
  flushInterval="60000"
  size="512"
  readOnly="true"/>

この設定では、以下のようなキャッシュが作成されます。

• FIFO アルゴリズムに基づいて置き換えられる。
• 60 秒ごとにフラッシュされる。
• 結果オブジェクトまたはリストへの参照を 512 個まで格納できる。
• 返されるオブジェクトは読み取り専用（read-only）（変更した場合、他の呼び出し元や別スレッドからの変更とコンフリクトする可能性がある）。

指定可能な置換（eviction）ポリシーは以下の通りです。

• LRU – Least Recently Used: 最も長いこと使われていないオブジェクトを優先的に削除します。
• FIFO – First In First Out: 最初に登録されたオブジェクトから順番に削除します。
• SOFT – Soft Reference: ガベージコレクターの状態と Soft Reference の規則に基づいてオブジェクトを削除します。
• WEAK – Weak Reference: ガベージコレクターの状態と Weak Reference の規則に基づいて、より積極的にオブジェクトを削除します。

デフォルト値は LRU です。

flushInterval には、適切な時間（ミリ秒）を表す正の整数を指定することができます。 デフォルト値は指定なしで、キャッシュがフラッシュされるのはステートメント（insert, update, delete または flushCache が設定された select）が実行された場合のみです。

size には任意の正の整数を指定することができますが、実行環境で利用可能なメモリリソースとキャッシュされるオブジェクトのサイズに配慮してください。デフォルト値は 1024 です。

readOnly 属性には true または false を設定することができます。読み取り専用キャッシュはキャッシュされたオブジェクトのインスタンスをそのまま呼び出し元に返しますので、このオブジェクトを変更すべきではありません。 読み取り専用キャッシュの利点は非常に高速だということです。 読み書き可能なキャッシュは、キャッシュされたオブジェクトを複製して（シリアライゼーションを使います）返しますので読み取り専用と比較すると遅いですが安全です。 デフォルト値は false です。

NOTE ２次レベルキャッシュはトランザクションに対応しています。SqlSession が (1) commit された場合、あるいは (2) flushCache=true が指定された insert/delete/update が実行されずに rollback された場合に２次レベルキャッシュが更新されます。