<?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>GenTestタスク</title>
	</properties>
	<body>
		<section name="目次">
			<ul>
				<li><a href="#概要">概要</a></li>
				<li><a href="#パラメータ">パラメータ</a>
					<ul>
						<li><a href="#トップレベルパラメータ">トップレベルパラメータ</a></li>
						<li><a href="#ネストした要素として指定されるパラメータ">ネストした要素として指定されるパラメータ</a>
							<ul>
								<li><a href="#SqlTestConfig">SqlTestConfig</a></li>
								<li><a href="#SqlTestConfigにネストした要素として指定されるパラメータ">SqlTestConfigにネストした要素として指定されるパラメータ</a></li>
							</ul>
						</li>
					</ul>
				</li>
				<li><a href="#使用例">使用例</a>
					<ul>
						<li><a href="#独自のテンプレートファイルを使用する">独自のテンプレートファイルを使用する</a></li>
						<li><a href="#生成するJavaファイルに共通のヘッダーとしてコピーライトを含める">生成するJavaファイルに共通のヘッダーとしてコピーライトを含める</a></li>
						<li><a href="#生成するJavaファイルにauthorを指定する">生成するJavaファイルにauthorを指定する</a></li>
					</ul>
				</li>
			</ul>
		</section>
		<section name="概要">
			<p>
				GenTestタスクは、テストクラスのコードを生成します。
				現在のバージョンでは、SQLファイルに書かれたSQLを実行してSQLが正しいことを確認するテストコードを生成します。
			</p>
			<p>
				GenTestタスクを利用するには、次のようにtaskdefタグとtypedefタグを使ってタスクとデータ型を定義する必要があります。
			</p>
<source><![CDATA[<taskdef name="gen" classname="org.seasar.doma.extension.gen.task.Gen" classpathref="classpath" loaderref="loader"/>
<typedef name="sqlTestConfig" classname="org.seasar.doma.extension.gen.task.SqlTestConfig" loaderref="loader"/>
]]></source>
			<p>
				taskdefのclasspathref属性には、Doma-Gen、FreeMarkerのjarファイルが参照されるように設定してください（Doma本体のjarファイルは不要です）。
			</p>
			<p>
				定義したタスクとデータ型は次のように使用します。
			</p>
<source><![CDATA[<target name="genTest">
    <genTest
        dialectName="${dialectName}"
        driverClassName="${driverClassName}"
        url="${url}"
        user="${user}"
        password="${password}">
        <sqlTestConfig
            destdir="${javaDestDir}"
            testClassName="${sqlTestClassName}">
            <fileset dir="${sqlDestDir}">
                <include name="${sqlFilePattern}"/>
            </fileset>
        </sqlTestConfig>
    </genTest>
</target>]]></source>
			<p>
				生成されるJavaコードは次のようになります。
			</p>
<source><![CDATA[public class SqlTest extends TestCase {
    ...
    public void test0() throws Exception {
        SqlFile sqlFile = repository.getSqlFile("META-INF/example/dao/AddressDao/selectById.sql", dialect);
        execute(sqlFile);
    }

    public void test1() throws Exception {
        SqlFile sqlFile = repository.getSqlFile("META-INF/example/dao/AddressDao/selectByIdAndVersion.sql", dialect);
        execute(sqlFile);
    }

    public void test2() throws Exception {
        SqlFile sqlFile = repository.getSqlFile("META-INF/example/dao/CategoryDao/selectById.sql", dialect);
        execute(sqlFile);
    }
    ...
}]]></source>
			<p>
				対象とするSQLファイルの数だけテストメソッドが生成されます。
			</p>
		</section>
		<section name="パラメータ">
			<subsection name="トップレベルパラメータ">
				<p>
					トップレベルパラメータの定義は次の通りです。
				</p>
				<table border="1" cellpadding="2" cellspacing="0">
					<tr><th>属性</th><th>説明</th><th>デフォルト値</th><th>必須</th></tr>
					<tr><td>dialectName</td><td>接続するRDBMSの方言名です。次のうちのどれかを指定できます。"h2"、"hsqldb"、"mysql"、"postgres"、"oracle"、"db2"、"mssql2008"、"mssql"。この名前に対応するクラスは、GenTestタスクを実行するクラスパスに通されている必要があります。</td><td>-</td><td><b>dialectClassNameが指定されていない場合YES</b></td></tr>
					<tr><td>dialectClassName</td><td>接続するRDBMSの方言クラス名です。<code>org.seasar.doma.jdbc.dialect.Dialect</code>の実装クラスでなければいけません。dialectNameの指定により利用できる組み込みの方言クラス以外を利用する場合に指定します。指定するクラスは、GenTestタスクを実行するクラスパスに通されている必要があります。</td><td>-</td><td><b>dialectNameが指定されていない場合YES</b></td></tr>
					<tr><td>driverClassName</td><td>JDBCドライバクラス名です。<code>java.sql.Driver</code>の実装クラスでなければいけません。</td><td>-</td><td><b><b>YES</b></b></td></tr>
					<tr><td>url</td><td>JDBC接続URLです。</td><td>-</td><td><b>YES</b></td></tr>
					<tr><td>user</td><td>JDBC接続ユーザーです。</td><td>-</td><td><b>YES</b></td></tr>
					<tr><td>password</td><td>JDBC接続パスワードです。</td><td>-</td><td><b>YES</b></td></tr>
					<tr><td>templateEncoding</td><td>テンプレートファイルのエンコーディングです。</td><td>"UTF-8"</td><td>NO</td></tr>
					<tr><td>templatePrimaryDir</td><td>テンプレートファイルを検索する際の優先ディレクトリです。独自テンプレートファイルを使用する場合に指定します。</td><td>-</td><td>NO</td></tr>
					<tr><td>globalFactoryClassName</td><td>このタスクで使用されるインスタンスを生成するファクトリの完全修飾名です。<code>org.seasar.doma.extension.gen.GlobalFactory</code>の実装クラスでなければいけません。このタスクの振る舞いをカスタマイズする場合に指定します。</td><td>"org.seasar.doma.extension.gen.GlobalFactory"</td><td>NO</td></tr>
				</table>
			</subsection>
			<subsection name="ネストした要素として指定されるパラメータ">
				<h4><a name="SqlTestConfig"></a>SqlTestConfig</h4>
				<p>
					SQLのテストコードの生成に関する設定を表すデータ型です。
				</p>
				<p>
					このデータ型を使用するとSQLのテストを行うJavaコードを生成できます。
					生成されるテストコードは、JUnitとDomaに依存します。
					このテストコードでは、SQLファイルに記述されたSQLをそのまま実行することでSQLが正しいことを確認します。
					SQLの実行により変更されたデータはコミットせず、ロールバックします。
				</p>
				<p>
					SqlTestConfigのパラメータ定義は次のとおりです。
				</p>
				<table border="1" cellpadding="2" cellspacing="0">
					<tr><th>属性</th><th>説明</th><th>デフォルト値</th><th>必須</th></tr>
					<tr><td>generate</td><td>"true"の場合、Javaコードを生成します。</td><td>"true"</td><td>NO</td></tr>
					<tr><td>destDir</td><td>Javaコードの出力先ディレクトリです。</td><td>"src"</td><td>NO</td></tr>
					<tr><td>overwrite</td><td>"true"の場合、Javaコードを上書きします。</td><td>"true"</td><td>NO</td></tr>
					<tr><td>testClassName</td><td>生成するテストクラスの名前です。</td><td>"example.SqlTest"</td><td>NO</td></tr>
					<tr><td>abstrct</td><td>"true"の場合、テストクラスを抽象クラスとして生成します。継承によってデータベースアクセス処理をカスタマイズしたい場合に"true"を指定してください。この名前は、「abstract」ではなく「abstrct」であることに注意してください。</td><td>"false"</td><td>NO</td></tr>
				</table>
				<h4><a name="SqlTestConfigにネストした要素として指定されるパラメータ"></a>SqlTestConfigにネストした要素として指定されるパラメータ</h4>
				<h5>FileSet</h5>
				<p>
					テスト対象のSQLファイルを指定するためにFileSetを使用します。
					SQLファイルは次の条件を満たしていなければいけません。
				</p>
				<ul>
					<li>拡張子がsqlである。</li>
					<li>META-INFディレクトリ以下に配置される。</li>
				</ul>
			</subsection>
		</section>
		<section name="使用例">
			<subsection name="独自のテンプレートファイルを使用する">
				<p>
					Doma-Genのテンプレートは、配布ファイルのresources/templateディレクトリ以下にあります。
					SQLをテストするクラスのテンプレートはsqlTest.ftlです。
					これをコピーして、修正を加えるのが良いでしょう。
					テンプレートの記述方法については<a href="http://freemarker.org/">FreeMarker</a>のドキュメントを参照してください。
				</p>
				<p>
					修正したテンプレートファイルは、ファイル名を変更せずにtemplateFilePrimaryDir属性に指定するディレクトリに配置します。
					mytemplateディレクトリに配置する場合、templatePrimaryDir属性にmytemplateを指定します。
				</p>
<source><![CDATA[<genTest
    dialectName="${dialectName}"
    driverClassName="${driverClassName}"
    url="${url}"
    user="${user}"
    password="${password}"
    templatePrimaryDir="mytemplate">
    <sqlTestConfig
        ...
    />
<genTest/>]]></source>
				<p>
					テンプレートは、特定のデータモデルを参照します。
					テンプレートとデータモデルクラスの対応付けを以下に示します。
				</p>
				<table border="1" cellpadding="2" cellspacing="0">
					<tr><th>テンプレート</th><th>データモデルクラス</th><th>生成物</th></tr>
					<tr><td>sqlTest.ftl</td><td><a href="doma-gen/apidocs/org/seasar/doma/extension/gen/SqlTestDesc.html">org.seasar.doma.extension.gen.SqlTestDesc</a></td><td>SQLテストクラスのJavaファイル</td></tr>
				</table>
			</subsection>	
			<subsection name="生成するJavaファイルに共通のヘッダーとしてコピーライトを含める">
				<p>
					lib.ftlというファイルを作成し、これをtemplatePrimaryDir属性に指定するディレクトリに配置します。
					lib.ftlには次のようにcopyrightの定義をします。
<source><![CDATA[<#assign copyright>
/*
 * Copyright 2008-2009 ...
 * All rights reserved.
 */
</#assign>]]></source>
					mytemplate/lib.ftlと配置する場合、タスクの定義は次のようになります。
				</p>
<source><![CDATA[<genTest
    dialectName="${dialectName}"
    driverClassName="${driverClassName}"
    url="${url}"
    user="${user}"
    password="${password}"
    templatePrimaryDir="mytemplate">
    <sqlTestConfig
        ...
    />
<genTest/>]]></source>
			</subsection>
			<subsection name="生成するJavaファイルにauthorを指定する">
				<p>
					lib.ftlというファイルを作成し、これをtemplatePrimaryDir属性に指定するディレクトリに配置します。
					lib.ftlには次のようにauthorの定義をします。
<source><![CDATA[<#assign author="Nakamura">]]></source>
					mytemplate/lib.ftlと配置する場合、タスクの定義は次のようになります。
				</p>
<source><![CDATA[<genTest
    dialectName="${dialectName}"
    driverClassName="${driverClassName}"
    url="${url}"
    user="${user}"
    password="${password}"
    templatePrimaryDir="mytemplate">
    <sqlTestConfig
        ...
    />
<genTest/>]]></source>
			</subsection>
		</section>
	</body>
</document>