resultMap

• constructor - クエリ結果をコンストラクタに渡してクラスのインスタンスを作成する場合に使用します。
  • idArg - このコンストラクタ引数が ID であることを明示します。ID 列を明示することによって全体のパフォーマンスが向上します。
  • arg - 通常のコンストラクタ引数です。
• id – このフィールドまたはプロパティが ID であることを明示します。ID を明示することによって全体のパフォーマンスが向上します。
• result – フィールドまたは JavaBean のプロパティにセットされる通常のデータです。
• association – 複雑型のアソシエーションを定義します。多くのマッピングはこのタイプに当てはまります。
  • ネストされた Result Map – アソシエーション自身も resultMap として記述します。他で定義されている resultMap を参照することもできます。
• collection – 複雑型のコレクションを定義します。
  • ネストされた Result Map – コレクション自身も resultMap として記述します。他で定義されている resultMap を参照することもできます。
• discriminator – 結果の値を使ってどの resultMap を使用するか決定します。
  • case – case は Result Map の一種で、値が一致した場合に使用されます。
    • ネストされた Result Map – case も Result Map なので、resultMap とほぼ同じ要素を持つことができます。また、別の場所で定義された resultMap を参照することもできます。

ベストプラクティス ResultMap は段階的に実装するようにしましょう。ユニットテストも効果的です。 上で見たような巨大な resultMap を一度に実装しようとするとミスが発生しやすく、作業も困難です。 シンプルなところからスタートして、ユニットテストを書きながら徐々に拡張しましょう。 フレームワークの欠点でもありますが、ソースが公開されているかどうかに関わらず、フレームワークはある種のブラックボックスとなり得ます。期待通りに動作していることを確かめるにはユニットテストが一番です。 ユニットテストはバグを報告する場合も役に立ちます。

次の章ではそれぞれの要素について詳しく見ていきます。

id と result

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

id と result は結果マッピングの基本となる要素です。 どちらも、ある列の値を単純型（String, int, double, Date など）のプロパティまたはフィールドにマップするときに使用します。

両者の違いは、id は、その結果が識別子プロパティ（オブジェクトのインスタンスを比較する際に使われます）であることを表すという点のみです。 これによって全体的なパフォーマンスが向上しますが、特に恩恵をうけるのはキャッシュとネストされた結果マッピング（＝JOIN マッピング）の処理を行うときです。

どちらも多くの属性を持っています。

サポートされている JDBC データ型

参考として、MyBatis に含まれている JdbcType 列挙型によってサポートされている JDBC データ型を以下に挙げておきます。

constructor

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

ほとんどの DTO (Data Transfer Object) やドメインモデルではプロパティを使って値を設定することができますが、時にはイミュータブルなクラスを使いたい場合もあるかも知れません。 通常更新されることのない参照用データを含むテーブルなどはイミュータブルクラスに向いています。 コンストラクタインジェクションを使うとインスタンス化の際に値を設定することができるので、カプセル化の妨げとなる public メソッドの定義が不要となります。 MyBatis は private として定義されているプロパティやフィールドもサポートしていますが、コンストラクタインジェクションを好む人もいると思います。 constructor 要素を使うとコンストラクタインジェクションによって値をマップすることが可能となります。

次のようなコンストラクタを考えてみます。

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

このコンストラクタに結果をインジェクトするためには、パラメーターの型によってコンストラクタを識別する必要があります。 Java では引数の名前を取得する方法がありませんので、constructor 要素を定義する場合は引数を正しい順番に並べ、適切なデータ型を指定するようにしてください。

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

それ以外の属性とルールについては通常の id, result 要素と同じです。

association

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

association 要素は "has-one" タイプのリレーションシップを扱います。 例えば、上で出てきたサンプルの Blog は１つの Author を持っています。 アソシエーションは、他の result とほぼ同じように動作します。 値を設定するプロパティ、値の取得元となる列、プロパティの javaType （ほとんどの場合自動で検出可能）、必要なら jdbcType、またデフォルトのタイプハンドラーをオーバーライドしたい場合は typeHandler を指定します。

association が他と異なるのは、アソシエーションを読み込む方法を MyBatis に伝える必要があるという点です。これには２つの方法があります。

• select をネストする：別のマップドステートメントを実行してその結果を読み込む方法です。
• 結果をネストする：ネストした Result Map を使って結合（Join）した結果を読み込む方法です。

まずは要素の属性を調べてみましょう。 select, resultMap 以外の属性は result 要素と同じです。

ネストされた select を使って 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 ステートメントが二つありますが、一つは Blog、もう一つは Author を読み込むための selct です。 Blog の resultMap を見ると、author プロパティを読み込むために "selectAuthor" ステートメントを使うように指示されています。

他のプロパティは自動的に読み込まれます（列名とプロパティ名が一致していることが前提となります）。

この方法は簡単ですが、大量のデータやリストを扱うのには向いていません。 この問題は "N+1 セレクト問題" として知られています。 要約すると、"N+1 セレクト問題" が発生する仕組みは下記のようなものです。

• レコードのリストを取得するために SQL ステートメントを一つ実行します（これが "+1" です）。
• 結果に含まれる各レコードに対して、その詳細を取得するための select 文が一回ずつ実行されます（これが "N" です）。

場合によっては数百、数千もの SQL ステートメントが実行されることになるので、あまり良い方法とは言えません。

幸い MyBatis ではこのようなクエリに対して遅延読み込み（Lazy load）を設定することができるので、すべてのクエリが同時に実行されるような状況を避けることも可能です。 ただし、リストを読み込んだ直後に各要素を反復処理してネストされたデータにアクセスするような処理を行うと、すべての遅延読み込みが実行されるのでパフォーマンスが極端に悪化します。

では、もう一つの方法について説明しましょう。

ネストされた結果を使って association を読み込む

ネストされたアソシエーションについては、既にとても複雑な例を見ていただきました。次のサンプルは、それと比べるとずっと理解しやすいと思います。ここでは、独立した select を実行する代わりに Blog と Author のテーブルを結合するクエリを実行します。

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

この例では、Blog の "author" を読み込むためのアソシエーションで、別の resultMap "authorResult" を指定しています。

超重要 ネストされた Result Map では、id 要素が重要な役割を果たします。常に、結果の固有性を判定できる一つ以上のプロパティを id として指定するようにしてください。指定がなくても動作はしますが、パフォーマンスに著しい悪影響を与えます。また、結果の固有性を判定するために必要な最小限のプロパティを指定するようにしてください。主キー（複合キーでも可）は良い選択肢です。

上の例では、別の場所で定義した resultMap 要素を指定してアソシエーションを読み込んでいますが、こうすると Author の resultMap を再利用することができます。再利用する必要がない場合や、単に一つの resultMap にマッピングの情報をまとめておきたい場合には、アソシエーションの Result Map をネストすることもできます。この方法で書き直したのが次の例です。

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

もしこの Blog に共著者 co-author が設定されていたらどうなるでしょうか。 select ステートメントは下記のようになります。

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

Author に対する 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 で指定されている列名と異なるので、この resultMap を再利用するためには columnPrefix を指定する必要があります。

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

複数の ResultSet を association にマッピングする

バージョン 3.2.3 から、N+1 セレクト問題を解決する新しい方法が追加されました。

データベースによってはストアドプロシージャから複数の ResultSet を返すことができます。この機能を利用すると、テーブルの結合（Join）を使わず一度の問い合わせで互いに関連する複数のデータを取得することができます。

以下の例では、ストアドプロシージャが２つの ResultSet を返します。１つめの ResultSet には複数の Blog のデータが含まれており、２つめの ResultSet には複数の Author のデータが含まれています。

SELECT * FROM BLOG WHERE ID = #{id}

SELECT * FROM AUTHOR WHERE ID = #{id}

ストアドプロシージャを実行する select 要素の resultSets 属性で、それぞれの ResultSet に名前を付けておく必要があります（カンマ区切り）。ここでは、それぞれ blogs, authors としています。

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

下記の resultMap では、authors 内の各 Author が、それぞれ対応する Blog にマッピングされます。

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

ここまで "has one" タイプのリレーションシップを扱う方法を見て来ましたが、"has many" の場合はどうしたら良いのでしょうか？これは次の章で説明します。

collection

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

collection 要素の働きは association とほとんど同じです。同じ説明の繰り返しを省くため、association との違いにフォーカスして見て行きます。

引き続き上記のサンプルを使います。Blog に対する Author は一人だけですが、Post は複数存在します。この関係を Blog クラスで表現すると、次のようになると思います。

private List<Post> posts;

collection 要素を使ってこのような List 型のプロパティにネストされた結果セットをマップする場合、select をネストする方法と、結果をネストする方法があります。

ネストされた select を使って collection を読み込む

まずは、ネストされた select を使って Blog に関連した Post を読み込む例を見てみましょう。

<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="Blog">
  SELECT * FROM POST WHERE BLOG_ID = #{id}
</select>

いろいろ気づいたことがあると思いますが、上で見た association 要素と似た部分が多いと思います。 まず眼を引くのは collection 要素を使っていることでしょう。次に "ofType" という新しい属性があることに気づくでしょう。 この属性は、JavaBean のプロパティ（またはフィールド）の型と、コレクションに含まれている型を区別するために必要です。 したがって、このマッピングは次のように読むことができます。

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

このように読めます: "投稿のリストは、Post クラスを要素とする ArrayList に格納される。"

ほとんどの場合、javaType 属性はMyBatis によって推測されるため省略可能です。 ということで、大抵は下記のように短く書くことができます。

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

ネストされた結果を使って collection を読み込む

ここまで来れば、ネストされた結果を collection に読み込む方法について想像できるのではないでしょうか。 なぜなら、association と全く同じだからです（ただし、ネストされた select と同様、"ofType" 属性の指定が必要です）。

まずは SQL を見てみましょう。

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

Blog と Post テーブルを結合した上で、マッピングを簡単にするため各列に別名を付けています。 ここまでくれば、次に挙げたシンプルな ResultMap で、Post のリストも含めて Blog のデータを読み込むことができます。

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

id 要素の重要さはここでも変わりません。まだ読んでいなければ、上の association 要素についての説明を参照してください。

もし、Post のマッピングを再利用したいのであれば、次のように２つの 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>

複数の ResultSets を collection にマッピングする

association で説明したのと同様に、２つの ResultSet を返すストアドプロシージャを呼び出すことができます。１つ目の ResultSet には Blog のリスト、２つ目の ResultSet には Post のリストが含まれているものとします。

SELECT * FROM BLOG WHERE ID = #{id}

SELECT * FROM POST WHERE BLOG_ID = #{id}

ストアドプロシージャを実行する select 要素の resultSets 属性で、それぞれの ResultSet に名前を付けておく必要があります（カンマ区切り）。ここでは、それぞれ blogs, posts としています。

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

以下の resultMap では、posts に含まれる Post が、対応する Blog にマッピングされます。

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

Note collection と association のマッピングに関して、階層の深さやオブジェクトの大きさに制限はありませんし、両者を組み合わせることも可能です。 ただ、パフォーマンスのことは忘れないようにしてください。 ユニットテストと負荷テストを怠らなければ、あなたのアプリケーションにとっての最適なアプローチを見つけることができます。 幸いなことに、後で別のアプローチに切り替える場合でも、MyBatis ならコードの変更は最小限（あるいはゼロ）で済みます。

association と collection を使った高度なマッピングはかなり深いテーマです。 ドキュメントで全てを網羅することはできませんが、少し練習すればすぐに全体がクリアになるはずです。

discriminator

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

データベースに対して実行した１回のクエリによって、複数の異なる（何らかの関係を持った）データ型を含む結果が戻ってくることがあります。 discriminator 要素は、こうしたケースをはじめとして、クラスの継承関係を再現する場合など様々な用途を想定して作られています。 discriminator は、Java における switch 文と同じように働くので理解するのはそれほど難しくないはずです。

discriminator を定義する場合は column と javaType 属性を指定します。 ここで指定した column は、MyBatis が比較対象の値を参照する際に使用されます。 javaType は、値が等しいかどうかを調べる際、確実に正しい比較が行われるように指定します（ですが、ほとんどのケースでは String を指定すれば期待通りに動作するはずです）。 使用例を見てみましょう。

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

この例では、MyBatis は結果セットのレコードをひとつずつ取り出して vehicle_type の値を比較します。 もし、vehicle_type の値が case で指定した条件のいずれかに一致した場合、その case 要素で指定されている resultMap を使って結果のマッピングを行います。 この処理は排他的に行われます。言い換えると、使われなかった resultMap は無視されるということです（ただし resultMap が継承されている場合は別です。これについてはすぐ後で説明します）。 一致する case が見つからない場合は、discriminator ブロックの外側で定義されている resultMap だけが適用されます。 仮に、carResult が次のように定義されていたとします。

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

この場合、doorCount プロパティのみが読み込まれることになります。 これによって、完全に独立した discriminator case のグループを定義することができます。親の resultMap と全く関連性のない resultMap であっても構いません。 今回のケースでは車は乗り物の一種（Car is-a Vehicle）なので、car と vehicle の間に関連性があることは明らかです。 当然、doorCount 以外のプロパティも読み込んで欲しいと思うでしょう。 resultMap を一箇所変更すれば、希望通りの動作になります。

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

これで、vehicleResult と carResult の両方で定義されているすべてのプロパティが読み込まれるようになります。

繰り返しになりますが、別々の 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>

思い出してください これらは全て Result Map なので、もし result が全く指定されていなければ、MyBatis が自動的に列名と一致する名前を持つプロパティに値を設定します。 ですから、上で挙げた例の多くは必要以上に冗長になっているといえます。 ただ、データベースは複雑ですから全てのケースで自動マッピングが使えるということもないでしょう。

カスタムキャッシュを使う

上記のプロパティを使ってキャッシュをカスタマイズする方法の他に、自作のキャッシュ実装や 3rd パーティのキャッシュソリューションのアダプタを作成してキャッシュの挙動を完全にオーバーライドしてしまうこともできます。

<cache type="com.domain.something.MyCustomCache"/>

上記は、カスタムキャッシュの実装を使用するための設定例です。 type 属性で指定されているクラスは org.mybatis.cache.Cache インターフェイスを実装している必要があります。 このインターフェイスは MyBatis の中では複雑な方ですが、その役割を考えればシンプルです。

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

あなたが作成したキャッシュを設定するには、キャッシュの実装クラスに public な JavaBean プロパティを追加し、cache 要素でプロパティを渡しします。 例えば次のように設定すると、あなたが作成したキャッシュの実装クラスの "setCacheFile(String file)" というメソッドが呼び出されます。

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

設定対象のプロパティは、単純型であれば String 以外でも使用可能です。

ここで重要なのは、キャッシュの設定とキャッシュのインスタンスは Mapper XML ファイルのネームスペースに関連付けられているということです。 あるネームスペースに対して定義されているキャッシュは、同じネームスペース内で定義されている全てのステートメントに関連付けられます。 ステートメントごとにキャッシュとの関連性を変更したり無効化することができるように、二つの簡単な属性が用意されています。 デフォルトでは、各ステートメントは下記のように設定されています。

<select ... flushCache="false" useCache="true"/>
<insert ... flushCache="true"/>
<update ... flushCache="true"/>
<delete ... flushCache="true"/>

上記の設定はデフォルトですので、明示的に上記のように設定する必要はありません。 デフォルトの動作を変更したい場合に限り、flushCache と useCache 属性を設定するようにしてください。 例えば、特定の select ステートメントの結果をキャッシュの対象から除外したり、ある select ステートメントを実行する際にキャッシュをフラッシュしたい、といった場合です。 同様に、キャッシュのフラッシュを伴わない update ステートメントを定義したいと思う時があるかも知れません。