<?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>
						<li><a href="#更新対象プロパティ">更新対象プロパティ</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/Update.html"><code>@Update</code></a>をDaoのメソッドに注釈します。
			</p>
<source><![CDATA[@Config(config = AppConfig.class)
public interface EmployeeDao {
    @Update
    int update(Employee employee);
    ...
}]]></source>
			<p>
				デフォルトでは、UPDATE文が自動生成されます。
				<code>@Update</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>preUpdate</code>メソッドを呼び出します。
				また、更新の実行後にエンティティリスナーの<code>postUpdate</code>メソッドを呼び出します。
			</p>
		</section>
		<section name="SQLの自動生成による更新">
			<p>
				戻り値の型は<code>int</code>でなければいけません。
				戻り値は更新件数を返します。
				パラメータの型は<a href="../entity.html">エンティティクラス</a>でなければいけません。
				指定できるパラメータの数は1つです。
				引数は<code>null</code>であってはいけません。
			</p>
<source><![CDATA[@Update
int update(Employee employee);]]></source>
			<subsection name="SQL自動生成におけるバージョン番号と楽観的排他制御">
				<p>
					次の条件を満たす場合に、楽観的排他制御が行われます。
				</p>
				<ul>
					<li>パラメータの<a href="../entity.html">エンティティクラス</a>に<code>@Version</code>が注釈されたプロパティがある</li>
					<li>@Updateの<code>ignoreVersion</code>要素が<code>false</code>である</li>
				</ul>
				<p>
					楽観的排他制御が有効であれば、バージョン番号は識別子とともに更新条件に含まれ、1増分して更新されます。
					このときの更新件数が0件の場合、楽観的排他制御の失敗を示す<a href="../../apidocs/org/seasar/doma/jdbc/OptimisticLockException.html"><code>org.seasar.doma.jdbc.OptimisticLockException</code></a>がスローされます。
					また、更新件数が0件でない場合、<code>OptimisticLockException</code>はスローされず、エンティティのバージョンプロパティの値が1増分されます。
				</p>
				<p>
					<code>@Update</code>の<code>ignoreVersion</code>要素が<code>true</code>の場合、
					バージョン番号は更新条件には含まれず、UPDATE文のSET句に含まれます。バージョン番号はアプリケーションで設定した値で更新されます。
					この場合、更新件数が0件であっても、<code>OptimisticLockException</code>はスローされません。
				</p>
<source><![CDATA[@Update(ignoreVersion = true)
int update(Employee employee);]]></source>
				<p>
					<code>@Update</code>の<code>suppressOptimisticLockException</code>要素が<code>true</code>の場合、
					<code>@Version</code>が注釈されたプロパティがあればバージョン番号は更新条件に含まれ増分もされますが、
					更新件数が0件であっても<code>OptimisticLockException</code>はスローされません。
					ただし、エンティティのバージョンプロパティの値は1増分されます。
				</p>
<source><![CDATA[@Update(suppressOptimisticLockException = true)
int update(Employee employee);]]></source>
			</subsection>
			<subsection name="更新対象プロパティ">
				<h4><code>@Column</code>の<code>updatable</code>要素</h4>
				<p>
					<a href="../entity.html">エンティティクラス</a>に<code>@Column</code>が注釈されたプロパティがある場合、
					<code>@Column</code>の<code>updatable</code>要素が<code>false</code>のものは更新対象外です。
				</p>
				<h4><code>@Update</code>の<code>exclude</code>要素</h4>
				<p>
					<code>@Update</code>の<code>exclude</code>要素に指定されたプロパティを更新対象外とします。
					プロパティがこの要素に指定されていれば、<code>@Column</code>の<code>updatable</code>要素が<code>true</code>であっても更新対象外です。
				</p>
<source><![CDATA[@Update(exclude = {"name", "salary"})
int update(Employee employee);]]></source>
				<h4><code>@Update</code>の<code>include</code>要素</h4>
				<p>
					<code>@Update</code>の<code>include</code>要素に指定されたプロパティのみを削除対象とします。
					<code>@Update</code>の<code>include</code>要素と<code>exclude</code>要素の両方に
					同じプロパティが指定された場合、そのプロパティは更新対象外になります。
					プロパティがこの要素に指定されていても、<code>@Column</code>の<code>updatable</code>要素が<code>false</code>であれば更新対象外です。
				</p>
<source><![CDATA[@Update(include = {"name", "salary"})
int update(Employee employee);]]></source>
				<h4><code>@Update</code>の<code>excludeNull</code>要素</h4>
				<p>
					<code>@Update</code>の<code>excludeNull</code>要素が<code>true</code>の場合、
					値が<code>null</code>のプロパティを削除対象外とします。
					この要素が<code>true</code>の場合、<code>@Column</code>の<code>updatable</code>要素が<code>true</code>であったり、
					<code>@Update</code>の<code>include</code>要素にプロパティが指定されていても、値が<code>null</code>であれば更新対象外です。
				</p>
<source><![CDATA[@Update(excludeNull = true)
int update(Employee employee);]]></source>
				<h4><code>@Update</code>の<code>includeUnchanged</code>要素</h4>
				<p>
					この要素は、更新対象の<a href="../entity.html">エンティティクラス</a>に<code>@OriginalStates</code>が注釈されたプロパティがある場合にのみ有効です。
				</p>
				<p>
					この要素が<code>true</code>の場合、エンティティの全プロパティが更新対象となります。
					つまり、全プロパティに対応するカラムがUPDATE文のSET句に含まれます。
				</p>
				<p>
					この要素が<code>false</code>の場合、エンティティが取得されてから実際に変更されたプロパティのみが更新対象になります。
					つまり、変更されたプロパティに対応するカラムのみがUPDATE文のSET句に含まれます。
				</p>
<source><![CDATA[@Update(includeUnchanged = true)
int update(Employee employee);]]></source>
			</subsection>
		</section>
		<section name="SQLファイルによる更新">
			<p>
				SQLファイルによる更新を行うには、<code>@Update</code>の<code>sqlFile</code>要素に<code>true</code>を設定し、
				メソッドに対応する<a href="../sqlfile.html">SQLファイル</a>を用意します。
			</p>
			<p>
				戻り値の型は<code>int</code>でなければいけません。
				戻り値は更新件数を返します。
				パラメータには任意の型が使用できます。
				指定できるパラメータの数に制限はありません。
				パラメータの型が基本型もしくはドメインクラスの場合、引数を<code>null</code>にできます。
				それ以外の型の場合、引数は<code>null</code>であってはいけません。
			</p>
<source><![CDATA[@Update(sqlFile = true)
int update(Employee employee);]]></source>
			<p>
				たとえば、上記のメソッドに対応するSQLは次のように記述します。
			</p>
<source><![CDATA[update employee set name = /* employee.name */'hoge', salary = /* employee.salary */100 where id = /* employee.id */0]]></source>
			<p>
				SQLファイルによる更新では、<code>@Update</code>の<code>exclude</code>要素、<code>include</code>要素、
				<code>excludeNull</code>要素、<code>includeUnchanged</code>要素は参照されません。
			</p>
			<subsection name="SQLファイルにおけるバージョン番号と楽観的排他制御">
				<p>
					次の条件を満たす場合に、楽観的排他制御が行われます。
				</p>
				<ul>
					<li>パラメータに<a href="../entity.html">エンティティクラス</a>を含む</li>
					<li>パラメータの内、左から数えて最初に登場するエンティティクラスに<code>@Version</code>が注釈されたプロパティがある</li>
					<li>@Updateの<code>ignoreVersion</code>要素が<code>false</code>である</li>
				</ul>
				<p>
					ただし、SQLファイルに楽観的排他制御用のSQLを記述するのは、アプリケーション開発者の責任です。
					たとえば、下記のSQLのように、WHERE句でバージョンを番号を指定しSET句でバージョン番号を1だけ増分しなければいけません。
				</p>
<source><![CDATA[update EMPLOYEE set DELETE_FLAG = 1, VERSION = /* employee.version */1 + 1 where ID = /* employee.id */1 and VERSION = /* employee.version */1]]></source>
				<p>
					このSQLの更新件数が0件の場合、楽観的排他制御の失敗を示す<a href="../../apidocs/org/seasar/doma/jdbc/OptimisticLockException.html"><code>org.seasar.doma.jdbc.OptimisticLockException</code></a>がスローされます。
					更新件数が0件でない場合、<code>OptimisticLockException</code>はスローされず、エンティティのバージョンプロパティの値が1増分されます。
				</p>
				<p>
					<code>@Update</code>の<code>ignoreVersion</code>要素が<code>true</code>の場合、
					更新件数が0件であっても、<code>OptimisticLockException</code>はスローされません。
					また、エンティティのバージョンプロパティの値は変更されません。
				</p>
<source><![CDATA[@Update(sqlFile = true, ignoreVersion = true)
int update(Employee employee);]]></source>
				<p>
					<code>@Update</code>の<code>suppressOptimisticLockException</code>要素が<code>true</code>の場合、
					更新件数が0件であっても、<code>OptimisticLockException</code>はスローされません。
					ただし、エンティティのバージョンプロパティの値は1増分されます。
				</p>
<source><![CDATA[@Update(sqlFile = true, suppressOptimisticLockException = true)
int update(Employee employee);]]></source>
			</subsection>
		</section>
		<section name="一意制約違反">
			<p>
				一意制約違反が発生した場合は、SQLファイルの使用の有無に関係なく<a href="../../apidocs/org/seasar/doma/jdbc/UniqueConstraintException.html"><code>org.seasar.doma.jdbc.UniqueConstraintException</code></a>がスローされます。
			</p>
		</section>
		<section name="クエリタイムアウト">
			<p>
				<code>@Update</code>の<code>queryTimeout</code>要素にクエリタイムアウトの秒数を指定できます。
			</p>
<source><![CDATA[@Update(queryTimeout = 10)
int update(Employee employee);]]></source>
			<p>
				この設定は、SQLファイルの使用の有無に関係なく適用されます。
				<code>queryTimeout</code>要素に値を指定しない場合、
				<a href="../config.html">設定クラス</a>に指定されたクエリタイムアウトが使用されます。
			</p>
		</section>
	</body>
</document>