複数行追加 

複数行の追加を実行するために @MultiInsert を使用して DAO メソッドに注釈を付けます。

@Dao
public interface EmployeeDao {
    @MultiInsert
    int insert(List<Employee> employees);

    @MultiInsert
    MultiResult<ImmutableEmployee> insert(List<ImmutableEmployee> employees);
}

複数行の追加を使用すると、次のような SQL ステートメントを発行できます。

insert into EMPLOYEE (EMPLOYEE_ID, EMPLOYEE_NO, EMPLOYEE_NAME, AGE, VERSION)
values (?, ?, ?, ?, ?), (?, ?, ?, ?, ?)

エンティティクラスにエンティティリスナーが指定されている場合、preInsert メソッドは挿入操作を実行する前にそれぞれのエンティティに対して呼び出されます。同様に、挿入操作が完了した後に、それぞれのエンティティに対して postInsert メソッドが呼び出されます。

注釈

この機能をサポートするデータベースは次のとおりです。

H2
MySQL
PostgreSQL
SQL Server
Oracle Database

ただし、SQL Server および Oracle の場合、この機能はauto incrementなプライマリキーを持つテーブルでは実行できません。

戻り値の型 

returning プロパティを使用する場合 

returning

returning プロパティを使用しない場合 

Iterable パラメータの型引数が immutable なエンティティクラスの場合、戻り値の型はそのエンティティクラスを要素とする org easar.doma.jdbc.MultiResult でなければいけません。

Iterable パラメータの型引数が変更可能なエンティティクラスの場合、戻り値の型は更新された件数を表す int でなければなりません。

パラメータの型 

パラメータの型はエンティティクラスを要素とする java.lang.Iterable のサブタイプでなければなりません。

パラメータは null であってはいけません。

自動生成される値 

複数行追加の実行時に、自動生成された値がエンティティプロパティに設定されます。

識別子 

IDの生成を参照してください。

バージョン番号 

アプリケーションがバージョンプロパティに値を設定しない場合や 0 より小さい値を設定する場合、1 が最終的にそのプロパティに設定されます。

アプリケーションが 0 より大きい値を明示的にバージョンプロパティに設定した場合、自動生成は行われません。

バージョン) も参照してください。

@MultiInsert のプロパティ 

exclude 

@MultiInsert の exclude プロパティで指定されたエンティティプロパティは、追加の対象から除外されます。たとえそれらが @Column 注釈で insertable に設定されていたとしてもです。

@MultiInsert(exclude = {"name", "salary"})
int insert(List<Employee> employees);

include 

@MultiInsert の include プロパティに指定されたエンティティプロパティのみが追加の対象に含まれます。

exclude と include の両方のプロパティに同じエンティティプロパティが指定されている場合、そのエンティティプロパティは追加の対象には含まれません。

@Column 注釈で insertable が false に設定されたエンティティプロパティは追加対象には含まれません。 include プロパティで指定されていたとしても含まれません。

@MultiInsert(include = {"name", "salary"})
int insert(List<Employee> employees);

duplicateKeyType 

このプロパティは、追加操作時に重複したキーを処理するための戦略を定義します。

次の3つの値のいずれかを取ることができます:

DuplicateKeyType.UPDATE: 重複したキーが見つかった場合、テーブル内の既存の行が更新されます。
DuplicateKeyType.IGNORE: 重複したキーが見つかった場合、挿入操作は無視され、テーブルに変更は加えられません。
DuplicateKeyType.EXCEPTION: 重複したキーが発生した場合、例外が投げられます。

@MultiInsert(duplicateKeyType = DuplicateKeyType.UPDATE)
int insert(List<Employee> employees);

duplicateKeys 

このプロパティは、重複キーが存在するかどうかを判断するために使用するキーを表します。重複キーが存在する場合、重複キーを処理するために duplicateKeyType ストラテジーを使用します。

@MultiInsert(duplicateKeyType = DuplicateKeyType.UPDATE, duplicateKeys = {"employeeNo"})
int insert(List<Employee> employees);

注釈

このプロパティは、duplicateKeyType ストラテジーが DuplicateKeyType.UPDATE または DuplicateKeyType.IGNORE のいずれかである場合にのみ使用されます。

注釈

MySQLの方言はこのプロパティを利用しません。

returning 

returning プロパティで @Returning を指定することで、SQL の INSERT .. RETURNING 句に相当するコードを生成できます。

@Dao
public interface EmployeeDao {
    @MultiInsert(returning = @Returning)
    List<Employee> insert(List<Employee> employees);

    @MultiInsert(returning = @Returning(include = { "employeeId", "version" }))
    List<Employee> insertReturningIdAndVersion(List<Employee> employees);

    @MultiInsert(returning = @Returning(exclude = { "password" }))
    List<Employee> insertReturningExceptPassword(List<Employee> employees);
}

@Returning の include 要素を使用して、RETURNING 句によって返されるエンティティのプロパティ（データベース列に対応）を指定できます。また、exclude 要素を使用して、返されるべきでないプロパティを指定することもできます。同じエンティティのプロパティが include と exclude の両方の要素に含まれている場合、それは返されません。

戻り値の型はエンティティインスタンスの List でなければなりません。

注釈

この機能は、H2 Database、PostgreSQL、SQL Server、およびSQLiteのダイアレクトのみがサポートしています。

一意制約違反 

一意制約違反が発生した場合、org.seasar.doma.jdbc.UniqueConstraintException がスローされます。

クエリタイムアウト 

@MultiInsert アノテーション内の queryTimeout プロパティにクエリタイムアウトの秒数を指定できます。

@MultiInsert(queryTimeout = 10)
int insert(List<Employee> employees);

queryTimeout プロパティに値が設定されていない場合、設定クラスで指定されたクエリタイムアウトが使用されます。

SQLログの出力形式 

@MultiInsert アノテーション内の sqlLog プロパティに SQL ログの出力形式を指定できます。

@MultiInsert(sqlLog = SqlLogType.RAW)
int insert(List<Employee> employees);

SqlLogType.RAW は、SQLステートメントとそのバインドパラメータをログに出力します。