ステートメントを実行するメソッド

これらは、SQL Mapper で定義されている SELECT, INSERT, UPDATE, DELETE の各メソッドを実行するためのメソッドです。ほとんど自明ですが、それぞれ引数としてステートメントの ID とステートメントの引数オブジェクト（プリミティブ、JavaBean、POJO、Map のいずれか）を取ります。

<T> T selectOne(String statement, Object parameter)
<E> List<E> selectList(String statement, Object parameter)
<T> Cursor<T> selectCursor(String statement, Object parameter)
<K,V> Map<K,V> selectMap(String statement, Object parameter, String mapKey)
int insert(String statement, Object parameter)
int update(String statement, Object parameter)
int delete(String statement, Object parameter)

selectOne と selectList の違いは、selectOne は１つのオブジェクトまたは null を返さなくてはならないということです。複数のオブジェクトが返されると例外が発生します。結果のオブジェクト数が未知の場合は selectList を使用してください。オブジェクトが存在するかどうかを確認したいのなら、カウント結果（0 or 1）を返すようにした方が良いでしょう。selectMap は、結果のリストを mapKey で指定したプロパティに基づいたマップに格納して返す特殊なメソッドです。
ステートメントの引数は不要な場合もあるので、parameter オブジェクトの引数を持たないオーバーロードメソッドも用意されています。

insert, update, delete の各メソッドは、ステートメントの実行によって影響を受けた行数を返します。

<T> T selectOne(String statement)
<E> List<E> selectList(String statement)
<T> Cursor<T> selectCursor(String statement)
<K,V> Map<K,V> selectMap(String statement, String mapKey)
int insert(String statement)
int update(String statement)
int delete(String statement)

A Cursor offers the same results as a List, except it fetches data lazily using an Iterator.

try (Cursor<MyEntity> entities = session.selectCursor(statement, param)) {
   for (MyEntity entity:entities) {
      // process one entity
   }
}

最後に、高度な処理を行うための select メソッドがあります。これらは主に非常に大きなデータセットを扱う場合に、返される行の範囲を限定したり、カスタムの ResultHandler を使って独自に結果処理を行うことができるようになっています。

<E> List<E> selectList (String statement, Object parameter, RowBounds rowBounds)
<T> Cursor<T> selectCursor(String statement, Object parameter, RowBounds rowBounds)
<K,V> Map<K,V> selectMap(String statement, Object parameter, String mapKey, RowBounds rowbounds)
void select (String statement, Object parameter, ResultHandler<T> handler)
void select (String statement, Object parameter, RowBounds rowBounds, ResultHandler<T> handler)

RowBounds 引数を渡すことによって、指定された数のレコードをスキップし、結果として返される行の数を制限することができます。RowBounds クラスはイミュータブルで、コンストラクタ引数として offset と limit を取ります。

int offset = 100;
int limit = 25;
RowBounds rowBounds = new RowBounds(offset, limit);

ドライバーによって得られる効果は異なります。SCROLL_SENSITIVE または SCROLL_INSENSITIVE （つまり FORWARD_ONLY 以外）の結果セットタイプを使った時、最も良いパフォーマンスが得られます。

ResultHandler を渡すと、各行を自由に処理することができます。List に追加したり、Map や Set を作成することもできますし、結果を捨てて合計値のみを返すこともできます。ResultHandler を使えば好きな処理を行うことも可能で、MyBatis 自身も内部的に結果リストを構築するために ResultHandler を利用しています。

3.4.6 以降では、CALLABLE ステートメントに渡された ResultHandler は、指定されたストアド・プロシージャで宣言されている REFCURSOR 型の OUT 引数全てに対して適用されます。

ResultHandler インターフェイスは非常にシンプルです。

package org.mybatis.executor.result;
public interface ResultHandler<T> {
  void handleResult(ResultContext<? extends T> context);
}

引数 ResultContext を介して結果オブジェクトにアクセスすることができます。ResultContext#getResultCount() メソッドは作成された結果オブジェクトの数を返します。ResultContext#stop() メソッドを呼び出すと、それ以上結果を読み込まないよう MyBatis に指示します。

ResultHandler を使用する場合に注意すべき点が２つあります。

• ResultHandler を引数に取るメソッドから返されるデータはキャッシュされません。
• 複雑な ResultMap では複数行のデータがひとつのオブジェクトにマッピングされることもあります。こうした ResultMap を ResultHandler と併用する際、association や collection のデータがマッピングされる前の状態のオブジェクトが渡される場合があります。

バッチ更新ステートメントをフラッシュするメソッド

バッチ更新用に JDBC ドライバ内に蓄積されたステートメントを任意のタイミングでデータベースへフラッシュ(実行)するメソッドがあります。このメソッドは、 ExecutorType として ExecutorType.BATCH を使用している場合に使用することができます。

List<BatchResult> flushStatements()

トランザクションを制御するメソッド

トランザクションのスコープを制御するメソッドは４つあります。当然ですが、auto-commit を使用する場合や、外部のトランザクションマネージャーを使っている場合、これらのメソッドは効果がありません。しかし、Connection のインスタンスによって管理されている JDBC トランザクションマネージャーを利用している場合は便利なメソッドです。

void commit()
void commit(boolean force)
void rollback()
void rollback(boolean force)

デフォルトでは、データベースの変更を伴うメソッド insert, update, delete, affectData を有効化した select が実行されない限り MyBatis は commit を実行しません。何らかの理由でこれらのメソッドを使わずにデータを変更した場合は確実にコミットされるように commit メソッドに引数 true を渡してください（ただし、auto-commit モードのセッションや外部のトランザクションマネージャーを使っている場合は true を渡してもコミットされません）。commit が実行されない場合、MyBatis がロールバックを実行するので、通常明示的に rollback() メソッドを呼び出す必要はありません。しかし、一つのセッションの中で複数のコミットやロールバックが必要とされるようなケースでは、rollback() メソッドを使ってより細かい制御を行うことが可能です。

NOTE Mybatis-Spring と MyBatis-Guice では宣言的トランザクションがサポートされています。詳細は各サブプロジェクトのドキュメントを参照してください。

ローカルキャッシュ

MyBatis は２種類の内部キャッシュを使用します。

新しいセッションが生成される際、同時にローカルキャッシュが作成され、セッションにアタッチされます。このセッション内で実行されるクエリは全てローカルキャッシュに保存され、同一パラメーターで再度呼び出された場合はデータベースに問い合わせずに結果を返します。ローカルキャッシュは update, commit, rollback, close が実行されるとクリアされるようになっています。

デフォルトでは、ローカルキャッシュはセッションが破棄されるまで保持されます。ローカルキャッシュは ResultMap の循環参照の解決やネストされたクエリの効率化にも使用されているため、完全に無効化することはできませんが、localCacheScope に STATEMENT を設定することで保持期間をステートメント単位に変更することができます。

localCacheScope に SESSION が設定されている場合、MyBatis は同一オブジェクトへの参照を返すという点に注意してください。返されたオブジェクトやリストなどに変更を加えた場合、ローカルキャッシュの内容が変更されることになるので、セッションが有効な間に同じクエリを発行すると意図しない結果が戻ることになります。同一セッション内で同じクエリを繰り返し発行するようなケースでは、結果として返されたオブジェクトを変更しないほうが無難です。

また、次のメソッドを呼び出すことにより任意のタイミングでローカルキャッシュをクリアすることも可能です。

void clearCache()

確実に SqlSession をクローズする

void close()

最も重要なのは、オープンした session は必ずクローズする必要があるということです。そのためには次のようなパターンでコードを書くのが最も確実です。

try (SqlSession session = sqlSessionFactory.openSession()) {
    // following 3 lines pseudocode for "doing some work"
    session.insert(...);
    session.update(...);
    session.delete(...);
    session.commit();
}

NOTE SqlSessionFactory と同様、getConfiguration() メソッドを呼び出すことで使用中の Configuration のインスタンスを取得することができます。

Configuration getConfiguration()

Mapper を使う

<T> T getMapper(Class<T> type)

SqlSession に用意されている insert, update, delete, select などのメソッドは確かに強力ですが、かなり冗長で、型に安全でないため IDE やユニットテストの機能をフルに活用することができません。既にスタートガイドの章で Mapper を使う例が出てきました。

マップドステートメントを実行する際は Mapper クラスを使った方法がより一般的です。Mapper クラスは SqlSession のメソッドに対応したメソッド定義を持つインターフェイスです。次の例は、Mapper クラスで定義されているメソッドが SqlSession のメソッドとどのように対応しているかを表しています。

public interface AuthorMapper {
  // (Author) selectOne("selectAuthor",5);
  Author selectAuthor(int id);
  // (List<Author>) selectList(“selectAuthors”)
  List<Author> selectAuthors();
  // (Map<Integer,Author>) selectMap("selectAuthors", "id")
  @MapKey("id")
  Map<Integer, Author> selectAuthors();
  // insert("insertAuthor", author)
  int insertAuthor(Author author);
  // updateAuthor("updateAuthor", author)
  int updateAuthor(Author author);
  // delete("deleteAuthor",5)
  int deleteAuthor(int id);
}

基本的に、それぞれの Mapper メソッドのシグネチャは、対応する SqlSession のメソッドのシグネチャからステートメントの ID を指定する String 型の引数を除いたものになっています。ステートメントの ID は引数で指定するのではなくメソッド名から取得されます。

戻り値の型について補足しておくと、クエリの結果が単一オブジェクトの場合はその型と一致している必要があり、複数の場合は配列またはコレクションになります。プリミティブ、Map, POJO, JavaBean など通常の型は一通り指定可能です。

NOTE Mapper インターフェイスは、他のインターフェイスを実装したり、他のクラスを継承する必要はありません。定義されているメソッドのシグネチャから対応するステートメントを識別できるようになっていれば OK です。

NOTE Mapper インターフェイスは他のインターフェイスを継承することができます。Mapper インターフェイスを XML と組み合わせて使う場合は、ステートメントが正しいネームスペースに含まれるように注意してください。また唯一の制限として、継承関係にある複数のインターフェイスに同じシグネチャを持つメソッドを定義することはできません（そもそも良い考えではありません）。

Mapper メソッドに複数の引数を渡すこともできます。ステートメントの中では #{param1}, #{param2} のように引数の順番を変数名として使用することができます。数字ではなく分かりやすい名前で引数を参照したい場合は、アノテーションを使って @Param("paramName") のように指定することもできます（引数が複数存在する場合のみ）。

引数として RowBounds のインスタンスを渡すとクエリ結果の行数を制限することができます。

Mapper アノテーション

MyBatis は当初から XML 駆動型のフレームワークでした。設定ファイルは XML でしたし、マップドステートメントも XML で定義されています。MyBatis 3 からは新しいオプションが追加されました。MyBatis 3 は包括的で強力な Java ベースの Configuration API の上に構築されています。この Configuration API が、XML による設定とアノテーションによる設定の基礎となっています。アノテーションを使うと、シンプルなマップドステートメントを無駄なく実装することができます。

NOTE 残念ながら、アノテーションの表現力と柔軟性には制限があります。調査や試行錯誤に多くの時間を費やしたにも関わらず、複雑なマッピングをアノテーションで実現することはできません。（例えば）C# の Attributes にはこのような制限が無いので、MyBatis.NET では XML の代わりに Attributes を活用することができます。とは言っても、Java のアノテーションにも利点が無いわけではありません。

アノテーション一覧：

Mapper アノテーションのサンプル

次のコードは @SelectKey アノテーションを使って insert 前にシーケンスの値を取得する例です。

@Insert("insert into table3 (id, name) values(#{nameId}, #{name})")
@SelectKey(statement="call next value for TestSequence", keyProperty="nameId", before=true, resultType=int.class)
int insertTable3(Name name);

次のコードは @SelectKey アノテーションを使って insert 後に identity の値を取得する例です。

@Insert("insert into table2 (name) values(#{name})")
@SelectKey(statement="call identity()", keyProperty="nameId", before=false, resultType=int.class)
int insertTable2(Name name);

次のコードは @Flush アノテーションを使って SqlSession#flushStatements()メソッドを呼び出す例です。

@Flush
List<BatchResult> flush();

次のコードは @Results アノテーションの id 属性で名前を指定する例です。

@Results(id = "userResult", value = {
  @Result(property = "id", column = "uid", id = true),
  @Result(property = "firstName", column = "first_name"),
  @Result(property = "lastName", column = "last_name")
})
@Select("select * from users where id = #{id}")
User getUserById(Integer id);

@Results(id = "companyResults")
@ConstructorArgs({
  @Arg(column = "cid", javaType = Integer.class, id = true),
  @Arg(column = "name", javaType = String.class)
})
@Select("select * from company where id = #{id}")
Company getCompanyById(Integer id);

次のコードは SQLプロバイダー用のアノテーションを使用して、パラメータをひとつ受け取る例です。

@SelectProvider(type = UserSqlBuilder.class, method = "buildGetUsersByName")
List<User> getUsersByName(String name);

class UserSqlBuilder {
  public static String buildGetUsersByName(final String name) {
    return new SQL(){{
      SELECT("*");
      FROM("users");
      if (name != null) {
        WHERE("name like #{value} || '%'");
      }
      ORDER_BY("id");
    }}.toString();
  }
}

次のコードは SQLプロバイダー用のアノテーションを使用して、複数パラメータをひとつ受け取る例です。

@SelectProvider(type = UserSqlBuilder.class, method = "buildGetUsersByName")
List<User> getUsersByName(
    @Param("name") String name, @Param("orderByColumn") String orderByColumn);

class UserSqlBuilder {

  // @Paramを使わない場合は, Mapperメソッドと同じ引数で定義する必要があります。
  public static String buildGetUsersByName(
      final String name, final String orderByColumn) {
    return new SQL(){{
      SELECT("*");
      FROM("users");
      WHERE("name like #{name} || '%'");
      ORDER_BY(orderByColumn);
    }}.toString();
  }

  // @Paramを使う場合は, 必要な引数のみ定義することができます。
  public static String buildGetUsersByName(@Param("orderByColumn") final String orderByColumn) {
    return new SQL(){{
      SELECT("*");
      FROM("users");
      WHERE("name like #{name} || '%'");
      ORDER_BY(orderByColumn);
    }}.toString();
  }
}

次のコードは、グローバル設定を利用して全てのマッパーメソッドで同じSQLプロバイダクラスを利用する例です。(3.5.6以降で利用可能)

Configuration configuration = new Configuration();
configuration.setDefaultSqlProviderType(TemplateFilePathProvider.class); // 全てのマッパーメソッドで利用するSQLプロバイダクラスを指定する
// ...

// 各メソッドのSQLプロバイダアノテーションの type または value 属性は省略することができ、
// 省略した場合はMyBaitsはグローバル設定の defaultSqlProviderType に指定されているクラスを適用する
public interface UserMapper {

  @SelectProvider // @SelectProvider(TemplateFilePathProvider.class) と同義
  User findUser(int id);

  @InsertProvider // @InsertProvider(TemplateFilePathProvider.class) と同義
  void createUser(User user);

  @UpdateProvider // @UpdateProvider(TemplateFilePathProvider.class) と同義
  void updateUser(User user);

  @DeleteProvider // @DeleteProvider(TemplateFilePathProvider.class) と同義
  void deleteUser(int id);
}

次のコードは、ProviderMethodResolver(MyBatis 3.5.1以降で利用可能)のデフォルト実装の利用例です。

@SelectProvider(UserSqlProvider.class)
List<User> getUsersByName(String name);

// SQLプロバイダクラスにProviderMethodResolverを実装する
class UserSqlProvider implements ProviderMethodResolver {

  // デフォルト実装では、マッパーメソッドと同名のメソッドが対象メソッドとして扱われます。
  public static String getUsersByName(final String name) {
    return new SQL(){{
      SELECT("*");
      FROM("users");
      if (name != null) {
        WHERE("name like #{value} || '%'");
      }
      ORDER_BY("id");
    }}.toString();
  }

}

次のコードは、databaseId属性(3.5.5以降で利用可能)の利用例です。

@Select(value = "SELECT SYS_GUID() FROM dual", databaseId = "oracle") // DatabaseIdProviderが提供する値が "oracle" の時にこのステートメントを利用する
@Select(value = "SELECT uuid_generate_v4()", databaseId = "postgres") // DatabaseIdProviderが提供する値が "postgres" の時にこのステートメントを利用する
@Select("SELECT RANDOM_UUID()") // DatabaseIdProviderの設定がないまたはDatabaseIdProviderが提供する値に一致しない時にこのステートメントを利用する
String generateId();