バッチ追加 

DAO メソッドに @BatchInsert アノテーションを付けてバッチ追加を実行します。

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

    @BatchInsert
    BatchResult<ImmutableEmployee> insert(List<ImmutableEmployee> employees);
}

デフォルトでは、INSERT ステートメントが自動生成されます。 @BatchInsert アノテーション内の sqlFile プロパティに true を指定することで、任意の SQL ファイルをマッピングできます。

エンティティリスナーの preInsert メソッドは、パラメータのエンティティクラスでエンティティリスナーが指定されている場合、追加の実行前に各エンティティごとに呼び出されます。また、エンティティリスナーメソッドの postInsert メソッドは、追加の実行後に各エンティティごとに呼び出されます。

戻り値 

パラメータである Iterable の要素が不変エンティティクラスの場合、戻り値はエンティティクラスを要素として持つ org.seasar.doma.jdbc.BatchResult でなければなりません。

上記の条件が満たされない場合、戻り値は各追加処理の追加件数を表す int[] でなければなりません。

自動生成されたSQLによるバッチ追加 

パラメータの型は要素としてエンティティクラスを持つ java.lang.Iterable のサブタイプでなければなりません。指定できるパラメータは 1 つだけです。パラメータは null であってはなりません。戻り値の配列要素数は、 Iterable の要素数と等しくなります。配列のそれぞれの要素が追加された件数を表します。

ID 

エンティティクラスの ID プロパティに @GeneratedValue の注釈が付けられている場合、IDは自動生成されてプロパティに設定されます。

注意点については IDの生成を参照してください。

アプリケーションで自動生成された ID を使用しない場合は、ingoreGeneratedKeys フラグを有効にすることができます。このフラグによりパフォーマンスが向上する可能性があります。

@BatchInsert(ignoreGeneratedKeys = true)
int[] insert(List<Employee> entities);

If value that explicitly set is over 0 then use the value if エンティティクラス has property that is annotated with @Version. If the value is not set or is less than 0 the value is set 1 automatically.

@BatchInsert のプロパティ 

insertable

エンティティクラスに @Column アノテーションが付けられたプロパティがある場合、 @Column アノテーション内の false が指定された insertable プロパティは追加対象から除外されます。

exclude

@BatchInsert アノテーション内の exclude プロパティで指定されたプロパティは追加対象から除外されます。 @Column アノテーション内の insertable プロパティに true が指定されていても、この要素でプロパティが指定されている場合、そのプロパティは追加対象から除外されます。

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

include

@BatchInsert アノテーション内の include プロパティで指定されたプロパティのみが追加対象となります。 @BatchInsert 内の include プロパティと exclude プロパティの両方で同じプロパティを指定した場合、そのプロパティは追加対象から除外されます。この要素でプロパティを指定しても、 @Column アノテーション内の inserttable プロパティが false の場合、そのプロパティは挿入対象から除外されます。

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

duplicateKeyType

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

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

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

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

duplicateKeys

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

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

注釈

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

注釈

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

SQLファイルによるバッチ追加 

SQLファイルによるバッチ追加を実行するには、 @BatchInsert アノテーション内の sqlFile プロパティに true を設定し、メソッドに対応したSQLファイルを用意します。

@BatchInsert(sqlFile = true)
int[] insert(List<Employee> employees);

@BatchInsert(sqlFile = true)
BatchResult<ImmutableEmployee> insert(List<ImmutableEmployee> employees);

パラメータの型は要素としてエンティティクラスを持つ java.lang.Iterable のサブタイプでなければなりません。指定できるパラメータは 1 つだけです。パラメータは null であってはなりません。戻り値の配列要素数は、 Iterable の要素数と等しくなります。配列のそれぞれの要素が追加された件数を表します。

エンティティリスナーがエンティティクラスで指定されている場合、エンティティリスナーのメソッドは呼び出されません。

例えば、上記のメソッドに対応するには以下のようなSQLを記述します。

insert into employee (id, name, salary, version)
values (/* employees.id */0, /* employees.name */'hoge', /* employees.salary */100, /* employees.version */0)

SQL ファイル内では、メソッドのパラメータ名は java.lang.Iterable の要素を示します。

識別子の自動設定およびバージョン番号の自動設定は、SQLファイルによるバッチ挿入では実行されません。

また、以下の @BatchInsert のプロパティは使用されません。

exclude
include
duplicateKeyType
duplicateKeys

一意制約違反 

SQLファイルの使用の有無に関わらず、一意性制約違反が発生した場合は UniqueConstraintException がスローされます。

クエリタイムアウト 

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

@BatchInsert(queryTimeout = 10)
int[] insert(List<Employee> employees);

この指定はSQLファイルの使用の有無に関わらず適用されます。 queryTimeout プロパティに値が設定されていない場合は、設定クラスで指定されたクエリタイムアウトが使用されます。

バッチサイズ 

バッチサイズは @BatchInsert アノテーション内の batchSize プロパティに指定できます。

@BatchInsert(batchSize = 10)
int[] insert(List<Employee> employees);

この指定はSQLファイルの使用有無に関わらず適用されます。 batchSize プロパティに値を指定しない場合は、設定クラスで指定されたバッチサイズが適用されます。

SQLログの出力形式 

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

@BatchInsert(sqlLog = SqlLogType.RAW)
int insert(Employee employee);

SqlLogType.RAW はバインドパラメータ付きの SQL をログ出力することを表します。