<?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></li>
			</ul>
		</section>
		<section name="概要">
			<p>
				SQLスクリプトの実行を行うには、 <a href="../../apidocs/org/seasar/doma/Script.html"><code>@Script</code></a>をDaoのメソッドに注釈します。
			</p>
<source><![CDATA[@Config(config = AppConfig.class)
public interface EmployeeDao {
    @Script
    void createTable();
    ...
}]]></source>
			<p>
				メソッドの戻り値の型はvoidでなければいけません。パラメータの数は0でなければいけません。
			</p>
			<p>
				また、メソッドに対応するスクリプトファイルが必須です。
			</p>
		</section>
		<section name="スクリプトファイル">
			<subsection name="配置場所">
				<p>
					スクリプトファイルはクラスパスが通った  <code>META-INF</code> ディレクトリ以下に配置しなければいけません。
				</p>
			</subsection>
			<subsection name="ファイル名の形式">
				<p>
					ファイル名は、次の形式でなければいけません。
				</p>
<source>META-INF/Daoのクラスの完全修飾名をディレクトリに変換したもの/Daoのメソッド名.script</source>
				<p>
					例えば、 Daoのクラスが <code>aaa.bbb.EmployeeDao</code>で
					マッピングしたいメソッドが <code>createTable</code> の場合、パス名は次のようになります。
				</p>
<source>META-INF/aaa/bbb/EmployeeDao/createTable.script</source>
				<p>
					複数のRDBMSに対応する必要があり特定のRDBMSでは別のスクリプトファイルを使いたい場合、
					<code>.script</code> の前にハイフン区切りでRDBMS名を入れることで、優先的に使用するファイルを指示できます。
					たとえば、PostgreSQL専用のSQLファイルは次の名前にします。
				</p>
<source>META-INF/aaa/bbb/EmployeeDao/createTables-postgres.script</source>
				<p>
					この場合、PostgreSQLを使用している場合に限り、<code>META-INF/aaa/bbb/EmployeeDao/createTable.script</code> よりも
					<code>META-INF/aaa/bbb/EmployeeDao/createTable-postgres.script</code> が優先的に使用されます。
				</p>
				<p>
					RDBMS名は、 <code>org.seasar.doma.jdbc.dialect.Dialect</code>の <code>getName</code>メソッドの値が使用されます。
					あらかじめ用意されたDialectについてそれぞれのRDBMS名を以下の表に示します。
				</p>
				<table>
					<tr>
						<th>データベース</th>
						<th>方言クラスの名前</th>
						<th>RDBMS名</th>
					</tr>
					<tr>
						<td>DB2</td>
						<td><code>org.seasar.doma.jdbc.dialect.Db2Dialect</code></td>
						<td><code>db2</code></td>
					</tr>
					<tr>
						<td>H2 Database Engine 1.2.126</td>
						<td><code>org.seasar.doma.jdbc.dialect.H212126Dialect</code></td>
						<td><code>h2</code></td>
					</tr>
					<tr>
						<td>H2 Database Engine</td>
						<td><code>org.seasar.doma.jdbc.dialect.H2Dialect</code></td>
						<td><code>h2</code></td>
					</tr>
					<tr>
						<td>HSQLDB</td>
						<td><code>org.seasar.doma.jdbc.dialect.HsqldbDialect</code></td>
						<td><code>hsqldb</code></td>
					</tr>
					<tr>
						<td>Microsoft SQL Server 2008</td>
						<td><code>org.seasar.doma.jdbc.dialect.Mssql2008Dialect</code></td>
						<td><code>mssql2008</code></td>
					</tr>
					<tr>
						<td>Microsoft SQL Server</td>
						<td><code>org.seasar.doma.jdbc.dialect.MssqlDialect</code></td>
						<td><code>mssql</code></td>
					</tr>
					<tr>
						<td>MySQL</td>
						<td><code>org.seasar.doma.jdbc.dialect.MySqlDialect</code></td>
						<td><code>mysql</code></td>
					</tr>
					<tr>
						<td>Oracle Database</td>
						<td><code>org.seasar.doma.jdbc.dialect.OracleDialect</code></td>
						<td><code>oracle</code></td>
					</tr>
					<tr>
						<td>PostgreSQL</td>
						<td><code>org.seasar.doma.jdbc.dialect.PostgresDialect</code></td>
						<td><code>postgres</code></td>
					</tr>
					<tr>
						<td>SQLite</td>
						<td><code>org.seasar.doma.jdbc.dialect.SqliteDialect</code></td>
						<td><code>sqlite</code></td>
					</tr>
				</table>
			</subsection>
			<subsection name="エンコーディング">
				<p>
					スクリプトファイルのエンコーディングはUTF-8でなければいけません。
				</p>
			</subsection>
			<subsection name="区切り文字">
				<p>
					スクリプトファイルの区切り文字には、ステートメントの区切り文字とブロックの区切り文字の2種類があります。
				</p>
				<p>
					ステートメントの区切り文字はセミコロン(;)です。
				</p>
				<p>
					ブロックの区切り文字は、方言クラスのデフォルトの値が使用されます。
				</p>
				<table>
					<tr>
						<th>データベース</th>
						<th>方言クラスの名前</th>
						<th>ブロックの区切り文字</th>
					</tr>
					<tr>
						<td>DB2</td>
						<td><code>org.seasar.doma.jdbc.dialect.Db2Dialect</code></td>
						<td>@</td>
					</tr>
					<tr>
						<td>H2 Database Engine 1.2.126</td>
						<td><code>org.seasar.doma.jdbc.dialect.H212126Dialect</code></td>
						<td>なし</td>
					</tr>
					<tr>
						<td>H2 Database Engine</td>
						<td><code>org.seasar.doma.jdbc.dialect.H2Dialect</code></td>
						<td>なし</td>
					</tr>
					<tr>
						<td>HSQLDB</td>
						<td><code>org.seasar.doma.jdbc.dialect.HsqldbDialect</code></td>
						<td>なし</td>
					</tr>
					<tr>
						<td>Microsoft SQL Server 2008</td>
						<td><code>org.seasar.doma.jdbc.dialect.Mssql2008Dialect</code></td>
						<td>GO</td>
					</tr>
					<tr>
						<td>Microsoft SQL Server</td>
						<td><code>org.seasar.doma.jdbc.dialect.MssqlDialect</code></td>
						<td>GO</td>
					</tr>
					<tr>
						<td>MySQL</td>
						<td><code>org.seasar.doma.jdbc.dialect.MySqlDialect</code></td>
						<td>/</td>
					</tr>
					<tr>
						<td>Oracle Database</td>
						<td><code>org.seasar.doma.jdbc.dialect.OracleDialect</code></td>
						<td>/</td>
					</tr>
					<tr>
						<td>PostgreSQL</td>
						<td><code>org.seasar.doma.jdbc.dialect.PostgresDialect</code></td>
						<td>$$</td>
					</tr>
					<tr>
						<td>SQLite</td>
						<td><code>org.seasar.doma.jdbc.dialect.SqliteDialect</code></td>
						<td>なし</td>
					</tr>
				</table>
				<p>
					ブロックの区切り文字は、アノテーションの<code>blockDelimiter</code>要素で明示することもできます。アノテーションで指定した場合、方言クラスのデフォルトの値よりも優先されます。
				</p>
<source><![CDATA[    @Script(blockDelimiter = "GO")
    void createTable();
]]></source>
			</subsection>
			<subsection name="エラー発生時の継続実行">
				<p>
					デフォルトでは、スクリプト中のどれかのSQLの実行が失敗すれば、処理はそこで止まります。
					しかし、アノテーションの<code>haltOnError</code>要素に<code>false</code>を指定することで、エラー発生時に処理を継続させることができます。
				</p>
<source><![CDATA[    @Script(haltOnError = false)
    void createTable();
]]></source>
			</subsection>
		</section>
		<section name="スクリプトの記述例">
			<p>
				スクリプトはスクリプトファイルに次のように記述できます。
				この例は、Oracle Databaseに有効なスクリプトです。
			</p>
<source><![CDATA[/*
 * テーブル定義(SQLステートメント)
 */
create table EMPLOYEE (
  ID numeric(5) primary key,  -- 識別子
  NAME varchar2(20)           -- 名前
);

/*
 * データの追加(SQLステートメント)
 */
insert into EMPLOYEE (ID, NAME) values (1, 'SMITH');

/*
 * プロシージャー定義(SQLブロック)
 */
create or replace procedure proc 
( cur out sys_refcursor, 
  employeeid in numeric
) as
begin
  open cur for select * from employee where id > employeeid order by id; 
end proc_resultset;
/

/*
 * プロシージャー定義2(SQLブロック)
 */
create or replace procedure proc2
( cur out sys_refcursor, 
  employeeid in numeric
) as
begin
  open cur for select * from employee where id > employeeid order by id; 
end proc_resultset;
/
]]></source>
			<p>
 				コメントは1行コメント(--)とブロックコメント(/* */)の2種類が使用できます。 
 				コメントは取り除かれてデータベースへ発行されます。
			</p>
			<p>
				1つのSQLステートメントは複数行に分けて記述できます。 
				ステートメントはセミコロン(;)で区切らなければいけません。
				 改行はステートメントの区切りとはみなされません。
			</p>
			<p>
				ストアドプロシージャーなどのブロックの区切りは、方言クラスのデフォルトの値か、@Scriptの<code>blockDelimiter</code>要素に指定した値を使用して示せます。
				 この例では、Oracle Database用の方言クラスのデフォルトの区切り文字であるスラッシュ(/)を使用しています。
				ブロックの 区切り文字は行頭に記述し、区切り文字の後ろには何も記述しないようにしてください。 
				つまり、区切り文字だけの行としなければいけません。 
			</p>
		</section>
	</body>
</document>