<?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="#プロシージャー名">プロシージャー名</a></li>
				<li><a href="#パラメータ">パラメータ</a>
					<ul>
						<li><a href="#INパラメータ">INパラメータ</a></li>
						<li><a href="#INOUTパラメータ">INOUTパラメータ</a></li>
						<li><a href="#OUTパラメータ">OUTパラメータ</a></li>
						<li><a href="#カーソルのOUTパラメータもしくは結果セット">カーソルのOUTパラメータもしくは結果セット</a></li>
					</ul>
				</li>
				<li><a href="#マップのキーのネーミング規約">マップのキーのネーミング規約</a></li>
			</ul>
		</section>
		<section name="概要">
			<p>
				ストアドプロシージャーを呼び出すには、<a href="../../apidocs/org/seasar/doma/Procedure.html"><code>@Procedure</code></a>をDaoのメソッドに注釈します。
			</p>
<source><![CDATA[@Config(config = AppConfig.class)
public interface EmployeeDao {
    @Procedure
    void execute(@In Integer id, @InOut Reference<BigDecimal> salary);
    ...
}]]></source>
			<p>
				パラメータには、パラメータの種別を示す<a href="../../apidocs/org/seasar/doma/In.html"><code>@In</code></a>、
				<a href="../../apidocs/org/seasar/doma/InOut.html"><code>@InOut</code></a>、
				<a href="../../apidocs/org/seasar/doma/Out.html"><code>@Out</code></a>、
				<a href="../../apidocs/org/seasar/doma/ResultSet.html"><code>@ResultSet</code></a>のいずれかのアノテーションが必須です。
				パラメータは複数指定できます。
				戻り値は<code>void</code>でなければいけません。
			</p>
		</section>
		<section name="プロシージャー名">
			<p>
				デフォルトではメソッド名がプロシージャー名になります。
				<code>@Procedure</code>の<code>name</code>要素に値を指定した場合は、その値がプロシージャー名になります。
			</p>
<source><![CDATA[@Procedure(name = "calculateSalary")
void execute(@In Integer id, @InOut Reference<BigDecimal> salary);]]></source>
			<p>
				<code>@Procedure</code>の<code>catalog</code>要素や<code>schema</code>要素にカタログ名やスキーマ名を指定できます。
				このときプロシージャーの名前は<code>catalog</code>要素、<code>schema</code>要素、<code>name</code>要素（指定されていなければメソッド名）をピリオドで連結したものになります。
			</p>
<source><![CDATA[@Procedure(catlog = "CATALOG", schema ="SCHEMA", name = "calculateSalary")
void execute(@In Integer id, @InOut Reference<BigDecimal> salary);]]></source>
		</section>
		<section name="パラメータ">
			<p>
				ストアドプロシージャーのパラメータとDaoメソッドのパラメータの並び順は合わせなければいけません。
			</p>
			<subsection name="INパラメータ">
				<p>
					INパラメータは、<code>@In</code>をメソッドのパラメータに注釈して示します。
					パラメータの型が基本型もしくはドメインクラスの場合、引数を<code>null</code>にできます。
					それ以外の型の場合、引数は<code>null</code>であってはいけません。
				</p>
<source><![CDATA[@Procedure
void execute(@In Integer id);]]></source>
				<p>
					次のように使用します。
				</p>
<source><![CDATA[EmployeeDao dao = new EmployeeDaoImpl();
dao.execute(1);]]></source>
			</subsection>
			<subsection name="INOUTパラメータ">
				<p>
					INOUTパラメータは、<code>@InOut</code>をメソッドのパラメータに注釈して示します。
					注釈されるパラメータの型は<a href="../../apidocs/org/seasar/doma/jdbc/Reference.html"><code>org.seasar.doma.jdbc.Reference</code></a>
					でなければいけません。
					<code>Reference</code>の型パラメータは<a href="../basic.html">基本型</a>もしくは<a href="../domain.html">ドメインクラス</a>でなければいけません。
					引数は<code>null</code>であってはいけません。
				</p>
<source><![CDATA[@Procedure
void execute(@InOut Reference<BigDecimal> salary);]]></source>
				<p>
					次のように使用します。
				</p>
<source><![CDATA[EmployeeDao dao = new EmployeeDaoImpl();
BigDecimal in = new BigDecimal(100);
Reference<BigDecimal> ref = new Reference<BigDecimal>(in);
dao.execute(ref);
BigDecimal out = ref.get();]]></source>
			</subsection>
			<subsection name="OUTパラメータ">
				<p>
					OUTパラメータは、<code>@Out</code>をメソッドのパラメータに注釈して示します。
					注釈されるパラメータの型は<a href="../../apidocs/org/seasar/doma/jdbc/Reference.html"><code>org.seasar.doma.jdbc.Reference</code></a>
					でなければいけません。
					<code>Reference</code>の型パラメータは<a href="../basic.html">基本型</a>もしくは<a href="../domain.html">ドメインクラス</a>でなければいけません。
					引数は<code>null</code>であってはいけません。
				</p>
<source><![CDATA[@Procedure
void execute(@Out Reference<BigDecimal> salary);]]></source>
				<p>
					次のように使用します。
				</p>
<source><![CDATA[EmployeeDao dao = new EmployeeDaoImpl();
Reference<BigDecimal> ref = new Reference<BigDecimal>();
dao.execute(ref);
BigDecimal out = ref.get();]]></source>
			</subsection>
			<subsection name="カーソルのOUTパラメータもしくは結果セット">
				<p>
					カーソルのOUTパラメータ、もしくはストアドファンクションが返す結果セットは、<code>@ResultSet</code>をメソッドのパラメータに注釈して示します。
					注釈されるパラメータの型は、<a href="../basic.html">基本型</a>、<a href="../domain.html">ドメインクラス</a>、
					<a href="../entity.html">エンティティクラス</a>、<code><![CDATA[java.util.Map<String, Object>]]></code>のいずれかを要素とする<code>java.util.List</code>でなければいけません。
					引数は<code>null</code>であってはいけません。
				</p>
<source><![CDATA[@Procedure
void execute(@ResultSet List<Employee> employees);]]></source>
				<p>
					次のように使用します。
				</p>
<source><![CDATA[EmployeeDao dao = new EmployeeDaoImpl();
List<Employee> employees = new ArrayList<Employee>();
dao.execute(employees);
for (Employee e : employees) {
    ...
}]]></source>
			<p>
				検索結果を受ける型がエンティティクラスやエンティティクラスを要素とする<code>java.util.List</code>の場合において、エンティティのプロパティすべてに対して漏れなく結果セットのカラムをマッピングすることを保証したい場合は、<code>@ResultSet</code>の<code>ensureResultMapping</code>要素に<code>true</code>を指定します。
			</p>
<source><![CDATA[@Procedure
void execute(@ResultSet(ensureResultMapping = true) List<Employee> employee);]]></source>
			<p>
				結果セットのカラムにマッピングされないプロパティが存在する場合<code>org.seasar.doma.jdbc.ResultMappingException</code>がスローされます。
			</p>
			</subsection>
		</section>
		<section name="マップのキーのネーミング規約">
			<p>
				結果セットを<code><![CDATA[java.util.Map<String, Object>]]></code>にマッピングする場合、
				<code>@Procedure</code>の<code>mapKeyNaming</code>要素にマップのキーのネーミング規約を指定できます。
			</p>
<source><![CDATA[@Procedure(mapKeyNaming = MapKeyNamingType.CAMEL_CASE)
void execute(@ResultSet List<Map<String, Object>> employees);]]></source>
			<p>
				<code>MapKeyNamingType.CAMEL_CASE</code>は、カラム名をキャメルケースに変換することを示します。
				そのほかに、カラム名をを大文字や小文字に変換する規約があります。
				指定しない場合、変換は行われません。
			</p>
		</section>
	</body>
</document>