<?xml version="1.0" encoding="UTF-8"?>
<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
	<properties>
		<title>バッチ削除</title>
	</properties>
	<body>
		<section name="目次">
			<ul>
				<li><a href="#概要">概要</a></li>
				<li><a href="#SQLの自動生成によるバッチ削除">SQLの自動生成によるバッチ削除</a>
					<ul>
						<li><a href="#SQL自動生成におけるバージョン番号と楽観的排他制御">SQL自動生成におけるバージョン番号と楽観的排他制御</a></li>
					</ul>
				</li>
				<li><a href="#SQLファイルによるバッチ削除">SQLファイルによるバッチ削除</a>
					<ul>
						<li><a href="#SQLファイルにおけるバージョン番号と楽観的排他制御">SQLファイルにおけるバージョン番号と楽観的排他制御</a></li>
					</ul>
				</li>
				<li><a href="#クエリタイムアウト">クエリタイムアウト</a></li>
				<li><a href="#バッチサイズ">バッチサイズ</a></li>
			</ul>
		</section>
		<section name="概要">
			<p>
				バッチ削除を行うには、<a href="../../apidocs/org/seasar/doma/BatchDelete.html"><code>@BatchDelete</code></a>をDaoのメソッドに注釈します。
			</p>
<source><![CDATA[@Config(config = AppConfig.class)
public interface EmployeeDao {
    @BatchDelete
    int[] delete(List<Employee> employees);
    ...
}]]></source>
			<p>
				デフォルトでは、DELETE文が自動生成されます。
				<code>@BatchDelete</code>の<code>sqlFile</code>に<code>true</code>を設定することで、任意の<a href="../sqlfile.html">SQLファイル</a>にマッピングできます。
			</p>
			<p>
				パラメータの要素である<a href="../entity.html">エンティティクラス</a>に<a href="../entity.html#エンティティリスナー">エンティティリスナー</a>が指定されている場合、削除の実行前にエンティティリスナーの<code>preDelete</code>メソッドをエンティティごとに呼び出します。
				また、削除の実行後にエンティティリスナーの<code>postDelete</code>メソッドをエンティティごとに呼び出します。
			</p>
		</section>
		<section name="SQLの自動生成によるバッチ削除">
			<p>
				戻り値の型は<code>int[]</code>でなければいけません。
				パラメータの型は<a href="../entity.html">エンティティクラス</a>を要素とする<code>java.lang.Iterable</code>のサブタイプでなければいけません。
				指定できるパラメータの数は1つです。
				引数は<code>null</code>であってはいけません。
				戻り値の配列の要素の数はパラメータの<code>Iterable</code>の要素の数と等しくなります。
				配列のそれぞれの要素が更新された件数を返します。
			</p>
			<subsection name="SQL自動生成におけるバージョン番号と楽観的排他制御">
				<p>
					次の条件を満たす場合に、楽観的排他制御が行われます。
				</p>
				<ul>
					<li>パラメータの<code>java.lang.Iterable</code>のサブタイプの要素である<a href="../entity.html">エンティティクラス</a>に<code>@Version</code>が注釈されたプロパティがある</li>
					<li>@BatchDeleteの<code>ignoreVersion</code>要素が<code>false</code>である</li>
				</ul>
				<p>
					楽観的排他制御が有効であれば、バージョン番号は識別子とともに削除条件に含まれます。
					この場合、削除件数が0件であれば、楽観的排他制御の失敗を示す<a href="../../apidocs/org/seasar/doma/jdbc/BatchOptimisticLockException.html"><code>org.seasar.doma.jdbc.BatchOptimisticLockException</code></a>がスローされます。
				</p>
				<p>
					<code>@BatchDelete</code>の<code>ignoreVersion</code>要素が<code>true</code>の場合、
					バージョン番号は削除条件には含まれますが、
					削除件数が0件であっても<code>BatchOptimisticLockException</code>はスローされません。
				</p>
<source><![CDATA[@BatchDelete(ignoreVersion = true)
int[] delete(List<Employee> employees);]]></source>
				<p>
					<code>@BatchDelete</code>の<code>suppressOptimisticLockException</code>要素が<code>true</code>の場合、
					<code>@Version</code>が注釈されたプロパティがあればバージョン番号は削除条件に含まれません。
					この場合、削除件数が0件であっても<code>BatchOptimisticLockException</code>のスローされません。
				</p>
<source><![CDATA[@BatchDelete(suppressOptimisticLockException = true)
int[] delete(List<Employee> employees);]]></source>
			</subsection>
		</section>
		<section name="SQLファイルによるバッチ削除">
			<p>
				SQLファイルによるバッチ削除を行うには、<code>@BatchDelete</code>の<code>sqlFile</code>要素に<code>true</code>を設定し、
				メソッドに対応する<a href="../sqlfile.html">SQLファイル</a>を用意します。
			</p>
<source><![CDATA[@BatchDelete(sqlFile = true)
int[] delete(List<Employee> employees);]]></source>
			<p>
				戻り値の型は<code>int[]</code>でなければいけません。
				パラメータは任意の型を要素とする<code>java.lang.Iterable</code>のサブタイプでなければいけません。
				指定できるパラメータの数は1つです。
				引数は<code>null</code>であってはいけません。
				戻り値の配列の要素の数はパラメータの<code>Iterable</code>の要素の数と等しくなります。
				配列のそれぞれの要素が更新された件数を返します。
			</p>
			<p>
				たとえば、上記のメソッドに対応するSQLは次のように記述します。
			</p>
<source><![CDATA[delete from employee where name = /* employees.name */'hoge']]></source>
			<p>
				SQLファイル上では、パラメータの名前は<code>java.lang.Iterable</code>のサブタイプの要素を指します。
			</p>
			<subsection name="SQLファイルにおけるバージョン番号と楽観的排他制御">
				<p>
					次の条件を満たす場合に、楽観的排他制御が行われます。
				</p>
				<ul>
					<li>パラメータの<code>java.lang.Iterable</code>のサブタイプの要素が<a href="../entity.html">エンティティクラス</a>であり、エンティティクラスに<code>@Version</code>が注釈されたプロパティがある</li>
					<li>@BatchDeleteの<code>ignoreVersion</code>要素が<code>false</code>である</li>
					<li>@BatchDeleteの<code>suppressOptimisticLockException</code>要素が<code>false</code>である</li>
				</ul>
				<p>
					ただし、SQLファイルに楽観的排他制御用のSQLを記述するのは、アプリケーション開発者の責任です。
					たとえば、下記のSQLのように、WHERE句でバージョンを番号を指定しなければいけません。
				</p>
<source><![CDATA[delete from EMPLOYEE where ID = /* employees.id */1 and VERSION = /* employees.version */1]]></source>
				<p>
					このSQLの削除件数が0件の場合、楽観的排他制御の失敗を示す<a href="../../apidocs/org/seasar/doma/jdbc/BatchOptimisticLockException.html"><code>org.seasar.doma.jdbc.BatchOptimisticLockException</code></a>がスローされます。
					削除件数が0件でない場合、<code>BatchOptimisticLockException</code>はスローされません。
				</p>
				<p>
					<code>@BatchDelete</code>の<code>ignoreVersion</code>要素、または<code>suppressOptimisticLockException</code>要素が<code>true</code>の場合、
					削除件数が0件であっても<code>BatchOptimisticLockException</code>はスローされません。
				</p>
<source><![CDATA[@BatchDelete(sqlFile = true, ignoreVersion = true)
int[] delete(List<Employee> employees);]]></source>
<source><![CDATA[@BatchDelete(sqlFile = true, suppressOptimisticLockException = true)
int[] delete(List<Employee> employees);]]></source>
			</subsection>
		</section>
		<section name="クエリタイムアウト">
			<p>
				<code>@BatchDelete</code>の<code>queryTimeout</code>要素にクエリタイムアウトの秒数を指定できます。
			</p>
<source><![CDATA[@BatchDelete(queryTimeout = 10)
int[] delete(List<Employee> employees);]]></source>
			<p>
				この設定は、SQLファイルの使用の有無に関係なく適用されます。
				<code>queryTimeout</code>要素に値を指定しない場合、
				<a href="../config.html">設定クラス</a>に指定されたクエリタイムアウトが使用されます。
			</p>
		</section>
		<section name="バッチサイズ">
			<p>
				<code>@BatchDelete</code>の<code>batchSize</code>要素にバッチサイズを指定できます。
			</p>
<source><![CDATA[@BatchDelete(batchSize = 10)
int[] delete(List<Employee> employees);]]></source>
			<p>
				この設定は、SQLファイルの使用の有無に関係なく適用されます。
				<code>batchSize</code>要素に値を指定しない場合、
				<a href="../config.html">設定クラス</a>に指定されたバッチサイズが使用されます。
			</p>
		</section>
	</body>
</document>