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