バッチ追加

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.

追加対象プロパティ

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

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ファイルによるバッチ追加では、ID の自動設定、バージョン番号の自動設定は実行されません。また、 @BatchInsert 内の exclude プロパティおよび include プロパティは参照されません。

一意制約違反

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 をログ出力することを表します。