概要
バッチ更新を行うには、@BatchUpdateをDaoのメソッドに注釈します。
@Config(config = AppConfig.class)
public interface EmployeeDao {
@BatchUpdate
int[] update(List<Employee> employees);
...
}
デフォルトでは、UPDATE文が自動生成されます。
@BatchUpdateのsqlFileにtrueを設定することで、任意のSQLファイルにマッピングできます。
パラメータの要素のエンティティクラスにエンティティリスナーが指定されている場合、更新の実行前にエンティティリスナーのpreUpdateメソッドをエンティティごとに呼び出します。
また、更新の実行後にエンティティリスナーのpostUpdateメソッドをエンティティごとに呼び出します。
SQLの自動生成によるバッチ更新
戻り値の型はint[]でなければいけません。
パラメータの型はエンティティクラスを要素とするjava.lang.Iterableのサブタイプでなければいけません。
指定できるパラメータの数は1つです。
引数はnullであってはいけません。
戻り値の配列の要素の数はパラメータのIterableの要素の数と等しくなります。
配列のそれぞれの要素が更新された件数を返します。
SQL自動生成におけるバージョン番号と楽観的排他制御
次の条件を満たす場合に、楽観的排他制御が行われます。
- パラメータの
java.lang.Iterableのサブタイプの要素であるエンティティクラスに@Versionが注釈されたプロパティがある - @BatchUpdateの
ignoreVersion要素がfalseである
楽観的排他制御が有効であれば、バージョン番号は識別子とともに更新条件に含まれ、1増分して更新されます。
このときの更新件数が0件の場合、楽観的排他制御の失敗を示すorg.seasar.doma.jdbc.BatchOptimisticLockExceptionがスローされます。
また、更新件数が0件でない場合、BatchOptimisticLockExceptionはスローされず、エンティティのバージョンプロパティの値が1増分されます。
@BatchUpdateのignoreVersion要素がtrueの場合、
バージョン番号は更新条件には含まれず、UPDATE文のSET句に含まれます。バージョン番号はアプリケーションで設定した値で更新されます。
この場合、更新件数が0件であっても、BatchOptimisticLockExceptionはスローされません。
@BatchUpdate(ignoreVersion = true) int[] update(List<Employee> employees);
@BatchUpdateのsuppressOptimisticLockException要素がtrueの場合、
@Versionが注釈されたプロパティがあればバージョン番号は更新条件に含まれ増分もされますが、
更新件数が0件であってもBatchOptimisticLockExceptionはスローされません。
ただし、エンティティのバージョンプロパティの値は1増分されます。
@BatchUpdate(suppressOptimisticLockException = true) int[] update(List<Employee> employees);
更新対象プロパティ
@Columnのupdatable要素
エンティティクラスに@Columnが注釈されたプロパティがある場合、
@Columnのupdatable要素がfalseのものは更新対象外です。
@BatchUpdateのexclude要素
@BatchUpdateのexclude要素に指定されたプロパティを更新対象外とします。
プロパティがこの要素に指定されていれば、@Columnのupdatable要素がtrueであっても削除対象外です。
@BatchUpdate(exclude = {"name", "salary"})
int[] update(List<Employee> employees);
@BatchUpdateのinclude要素
@BatchUpdateのinclude要素に指定されたプロパティのみを削除対象とします。
@BatchUpdateのinclude要素とexclude要素の両方に
同じプロパティが指定された場合、そのプロパティは更新対象外になります。
プロパティがこの要素に指定されていても、@Columnのupdatable要素がfalseであれば更新対象外です。
@BatchUpdate(include = {"name", "salary"})
int[] update(List<Employee> employees);
SQLファイルによるバッチ更新
SQLファイルによるバッチ更新を行うには、@BatchUpdateのsqlFile要素にtrueを設定し、
メソッドに対応するSQLファイルを用意します。
@BatchUpdate(sqlFile = true) int[] update(List<Employee> employees);
戻り値の型はint[]でなければいけません。
パラメータは任意の型を要素とするjava.lang.Iterableのサブタイプでなければいけません。
指定できるパラメータの数は1つです。
引数はnullであってはいけません。
戻り値の配列の要素の数はパラメータのIterableの要素の数と等しくなります。
配列のそれぞれの要素が更新された件数を返します。
たとえば、上記のメソッドに対応するSQLは次のように記述します。
update employee set name = /* employees.name */'hoge', salary = /* employees.salary */100 where id = /* employees.id */0
SQLファイル上では、パラメータの名前はjava.lang.Iterableのサブタイプの要素を指します。
SQLファイルによるバッチ更新では、バージョン番号の自動更新は行われません。
また、@BatchUpdateのexclude要素、include要素は参照されません。
SQLファイルにおけるバージョン番号と楽観的排他制御
次の条件を満たす場合に、楽観的排他制御が行われます。
- パラメータの
java.lang.Iterableのサブタイプの要素がエンティティクラスであり、エンティティクラスに@Versionが注釈されたプロパティがある - @BatchUpdateの
ignoreVersion要素がfalseである
ただし、SQLファイルに楽観的排他制御用のSQLを記述するのは、アプリケーション開発者の責任です。 たとえば、下記のSQLのように、WHERE句でバージョンを番号を指定しSET句でバージョン番号を1だけ増分しなければいけません。
update EMPLOYEE set DELETE_FLAG = 1, VERSION = /* employees.version */1 + 1 where ID = /* employees.id */1 and VERSION = /* employees.version */1
このSQLの更新件数が0件の場合、楽観的排他制御の失敗を示すorg.seasar.doma.jdbc.BatchOptimisticLockExceptionがスローされます。
更新件数が0件でない場合、BatchOptimisticLockExceptionはスローされず、エンティティのバージョンプロパティの値が1増分されます。
楽観的排他制御が有効であれば、バージョン番号は識別子とともに更新条件に含まれ、1増分して更新されます。
このときの更新件数が0件の場合、楽観的排他制御の失敗を示すorg.seasar.doma.jdbc.BatchOptimisticLockExceptionがスローされます。
一方、更新件数が0件でない場合、BatchOptimisticLockExceptionはスローされず、エンティティのバージョンプロパティの値が1増分されます。
@BatchUpdateのignoreVersion要素がtrueの場合、
更新件数が0件であっても、BatchOptimisticLockExceptionはスローされません。
また、エンティティのバージョンプロパティの値は変更されません。
@BatchUpdate(sqlFile = true, ignoreVersion = true) int[] update(List<Employee> employees);
@BatchUpdateのsuppressOptimisticLockException要素がtrueの場合、
更新件数が0件であってもBatchOptimisticLockExceptionはスローされません。
ただし、エンティティのバージョンプロパティの値は1増分されます。
@BatchUpdate(sqlFile = true, suppressOptimisticLockException = true) int[] update(List<Employee> employees);
一意制約違反
一意制約違反が発生した場合は、SQLファイルの使用の有無に関係なくorg.seasar.doma.jdbc.UniqueConstraintExceptionがスローされます。
クエリタイムアウト
@BatchUpdateのqueryTimeout要素にクエリタイムアウトの秒数を指定できます。
@BatchUpdate(queryTimeout = 10) int[] update(List<Employee> employees);
この設定は、SQLファイルの使用の有無に関係なく適用されます。
queryTimeout要素に値を指定しない場合、
設定クラスに指定されたクエリタイムアウトが使用されます。
バッチサイズ
@BatchUpdateのbatchSize要素にバッチサイズを指定できます。
@BatchUpdate(batchSize = 10) int[] update(List<Employee> employees);
この設定は、SQLファイルの使用の有無に関係なく適用されます。
batchSize要素に値を指定しない場合、
設定クラスに指定されたバッチサイズが使用されます。