<?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>
					<ul>
						<li><a href="#Configインタフェースを直接実装する場合">Configインタフェースを直接実装する場合</a></li>
						<li><a href="#DomaAbstractConfigを継承する場合">DomaAbstractConfigを継承する場合</a></li>
						<li><a href="#JDBCドライバの設定">JDBCドライバの設定</a></li>
					</ul>
				</li>
				<li><a href="#設定クラスの利用">設定クラスの利用</a></li>
				<li><a href="#DIコンテナを利用する場合の設定例">DIコンテナを利用する場合の設定例</a>
					<ul>
						<li><a href="#設定クラスのインスタンスのインジェクション">設定クラスのインスタンスのインジェクション</a></li>
						<li><a href="#aptにより生成されるソースコードに対するアノテーションの注釈">aptにより生成されるソースコードに対するアノテーションの注釈</a></li>
					</ul>
				</li>
			</ul>
		</section>
		<section name="概要">
			<p>
				Domaに対する設定は、<a href ="../apidocs/org/seasar/doma/jdbc/Config.html"><code>Config</code></a>インタフェースの実装クラスで表現します。
				<code>Config</code>の実装クラスは<code>@Dao</code>の<code>config</code>要素に指定します。
			</p>
			<p>
				次の事柄を設定で変更できます。
			</p>
			<ul>
				<li>データソース</li>
				<li>データソースの名前</li>
				<li>データベースの方言</li>
				<li>JDBC関連のログ出力に使用するロギングフレームワークへのアダプタ</li>
				<li>SQLファイルのキャッシュ戦略</li>
				<li>トランザクション属性がREQUIRES_NEWであるトランザクションとの連動方法</li>
				<li>使用するアプリケーションサーバやフレームワークに依存した仕方でのクラスの取得</li>
				<li>例外メッセージに含めるSQLのタイプ</li>
				<li>クエリ時に使用するパラメータ（タイムアウト、最大件数、フェッチ件数、バッチサイズ）</li>
			</ul>
		</section>
		<section name="設定クラスの作成">
			<subsection name="Configインタフェースを直接実装する場合">
				<p>
					<code>Config</code>インタフェースの実装クラスは、publicなデフォルトコンストラクタ（引数なしのコンストラクタ）を持たねばいけません。
					また、どのメソッドも <code>null</code>を返してはいけません。
				</p>
				<p>
					ここでは、代表的な設定項目について説明します。
				</p>
				<h4>データソースの設定</h4>
				<p>
					<code>javax.sql.DataSource</code>を、<code>getDataSource</code>メソッドで返します。
					学習等でごく簡易的なデータアクセスを行うだけであれば、
					<a href ="../apidocs/org/seasar/doma/jdbc/SimpleDataSource.html"><code>SimpleDataSource</code></a>
					を使用できます。
				</p>
				<h4>データソース名の設定</h4>
				<p>
					データソース名をあらわす<code>String</code>を、<code>getDataSourceName</code>メソッドで返します。
					データソース名は、複数のデータソースを利用する環境で重要です。
					データソース名はデータソースごとに自動生成される識別子を認識するために使用されます。
					複数データソースを利用する場合は、それぞれ異なる名前を返すようにしてください。
				</p>
				<h4>RDBMS方言の設定</h4>
				<p>
					<a href ="../apidocs/org/seasar/doma/jdbc/dialect/Dialect.html"><code>org.seasar.doma.jdbc.dialect.Dialect</code></a>を、<code>getDialect</code>メソッドで返します。
					<code>Dialect</code>はRDBMSの方言をあらわすインタフェースです。
					実装クラスには次のものがあります。
				</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>H2 Database Engine 1.2.126で稼動実績あり</td>
					</tr>
					<tr>
						<td>H2 Database Engine</td>
						<td><code>org.seasar.doma.jdbc.dialect.H2Dialect</code></td>
						<td>H2 Database Engine 1.3.171以降に対応</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>Microsoft SQL Server 2008に対応</td>
					</tr>
					<tr>
						<td>Microsoft SQL Server</td>
						<td><code>org.seasar.doma.jdbc.dialect.MssqlDialect</code></td>
						<td>Microsoft SQL Server 2012以降に対応</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>
					接続先のRDBMSにあわせて、実装クラスを選んでください。
				</p>
				<h4>ロガーの設定</h4>
				<p>
					<a href ="../apidocs/org/seasar/doma/jdbc/JdbcLogger.html"><code>org.seasar.doma.jdbc.JdbcLogger</code></a>を、<code>getJdbcLogger</code>メソッドで返します。
					<code>JdbcLogger</code>はデータベースアクセスに関するログを扱うインタフェースです。
					実装クラスには次のものがあります。
				</p>
				<ul>
					<li><a href ="../apidocs/org/seasar/doma/jdbc/UtilLoggingJdbcLogger.html"><code>org.seasar.doma.jdbc.UtilLoggingJdbcLogger</code></a></li>
				</ul>
				<p>
					<code>UtilLoggingJdbcLogger</code>は、<code>java.util.logging</code>のロガーを使用してログ出力する実装です。
					多くの場合、アプリケーションで使用するcommons-loggingなどのロガーに出力する実装クラスを別途作ったほうがよいでしょう。
				</p>
				<h4>SQLファイルのリポジトリの設定</h4>
				<p>
					<a href ="../apidocs/org/seasar/doma/jdbc/SqlFileRepository.html"><code>org.seasar.doma.jdbc.SqlFileRepository</code></a>を、<code>getSqlFileRepository</code>メソッドで返します。
					<code>SqlFileRepository</code>はSQLファイルのリポジトリを扱うインタフェースです。
					実装クラスには次のものがあります。
				</p>
				<ul>
					<li><a href ="../apidocs/org/seasar/doma/jdbc/GreedyCacheSqlFileRepository.html"><code>org.seasar.doma.jdbc.GreedyCacheSqlFileRepository</code></a></li>
					<li><a href ="../apidocs/org/seasar/doma/jdbc/NoCacheSqlFileRepository.html"><code>org.seasar.doma.jdbc.NoCacheSqlFileRepository</code></a></li>
				</ul>
				<p>
					<code>GreedyCacheSqlFileRepository</code>は、読み込んだSQLファイルの内容をパースし、その結果をメモリが許す限り最大限にキャッシュします。
					<code>NoCacheSqlFileRepository</code>は、一切キャッシュを行いません。毎回、SQLファイルからSQLを読み取りパースします。
				</p>
				<p>
					メモリの利用に厳しい制限がある環境や、扱うSQLファイルが膨大にある環境では、適切なキャッシュアルゴリズムをもった実装クラスを作成し使用してください。
				</p>
				<h4>REQUIRES_NEWの属性をもつトランザクションを制御するための設定</h4>
				<p>
					<a href ="../apidocs/org/seasar/doma/jdbc/RequiresNewController.html"><code>org.seasar.doma.jdbc.RequiresNewController</code></a>を、<code>getRequiresNewController</code>メソッドで返します。
					<code>RequiresNewController</code>はREQUIRES_NEW の属性をもつトランザクションを制御するインタフェースです。
					実装クラスには次のものがあります。
				</p>
				<ul>
					<li><a href ="../apidocs/org/seasar/doma/jdbc/NullRequiresNewController.html"><code>org.seasar.doma.jdbc.NullRequiresNewController</code></a></li>
				</ul>
				<p>
					<code>NullRequiresNewController</code>は、実質的になにも行いません。
				</p>
				<p>
					REQUIRES_NEWの属性をもつトランザクションの最適な制御方法は、環境ごとに異なるため、適切な実装クラスを作成し使用してください。
					ただし、このインタフェースは、<code>@TableGenerator</code>で、識別子を自動生成する際にしか使われません。
					<code>@TableGenerator</code>を利用しない場合は、<code>NullRequiresNewController</code>を使用してもかまいません。
					また、<code>@TableGenerator</code>を利用する場合であっても、識別子を採番するための更新ロックが問題にならない程度のトランザクション数であれば、<code>NullRequiresNewController</code>を使用してもかまいません。
				</p>
				<h4>クラスの扱いに関する設定</h4>
				<p>
					<a href ="../apidocs/org/seasar/doma/jdbc/ClassHelper.html"><code>org.seasar.doma.jdbc.ClassHelper</code></a>を、<code>getClassHelper</code>メソッドで返します。
					<code>ClassHelper</code>はクラスの扱いに関してアプリケーションサーバやフレームワークの差異を抽象化するインタフェースです。
					実装クラスには次のものがあります。
				</p>
				<ul>
					<li><a href ="../apidocs/org/seasar/doma/jdbc/DefaultClassHelper.html"><code>org.seasar.doma.jdbc.DefaultClassHelper</code></a></li>
				</ul>
				<p>
					<code>DefaultClassHelper</code>は、<code>java.lang.Class.forName(name)</code> を用いてクラスをロードします。
				</p>
				<h4>例外メッセージに含めるSQLのタイプの設定</h4>
				<p>
					例外メッセージに含めるSQLのタイプをあらわす、<a href ="../apidocs/org/seasar/doma/jdbc/ExceptionSqlLogType.html"><code>org.seasar.doma.jdbc.ExceptionSqlLogType</code></a>を<code>getExceptionSqlLogType</code>メソッドで返します。
					この値は、<a href ="../apidocs/org/seasar/doma/jdbc/UniqueConstraintException.html"><code>UniqueConstraintException</code></a>などの例外にどのような形式のSQLを含めるかを決定します。
				</p>
				<h4>クエリタイムアウト（秒）の設定</h4>
				<p>
					クエリタイムアウト（秒）をあらわす、<code>int</code>を<code>getQueryTimeout</code>メソッドで返します。
					この値は、Daoインタフェースの<code>@Delegate</code>以外の問い合わせで使用されます。
					クエリタイムアウト（秒）は<code>java.sql.Statement.setQueryTimeout(int)</code>に渡されます。
				</p>
				<h4>SELECT時のフェッチサイズの設定</h4>
				<p>
					SELECT時のフェッチサイズをあらわす、<code>int</code>を<code>getFetchSize</code>メソッドで返します。
					この値は、Daoインタフェースの<code>@Select</code>が注釈されたメソッドの実行で使用されます。
					フェッチサイズは<code>java.sql.Statement.setFetchSize(int)</code>に渡されます。
				</p>
				<h4>SELECT時の最大行数の設定</h4>
				<p>
					SELECT時の最大行数をあらわす、<code>int</code>を<code>getMaxRows</code>メソッドで返します。
					この値は、Daoインタフェースの<code>@Select</code>が注釈されたメソッドの実行で使用されます。
					最大行数は<code>java.sql.Statement.setMaxRows(int)</code>に渡されます。
				</p>
				<h4>バッチ更新のバッチサイズの設定</h4>
				<p>
					バッチサイズをあらわす、<code>int</code>を<code>getBatchSize</code>メソッドで返します。
					この値は、Daoインタフェースの<code>@BatchUpdate</code>などが注釈されたバッチ系のメソッドの実行に使用されます。
				</p>
			</subsection>
			<subsection name="DomaAbstractConfigを継承する場合">
				<p>
					<code>Config</code>インタフェースを直接実装してもかまいませんが、
					いくつかのデフォルトの設定をもつ <a href ="../apidocs/org/seasar/doma/jdbc/DomaAbstractConfig.html"><code>DomaAbstractConfig</code></a>を継承するのが簡単です。
					最初は、このクラスを使い、慣れてきたら<code>Config</code>インタフェースを直接実装するのがよいでしょう。
				</p>
<source>public class AppConfig extends DomaAbstractConfig {
    ...
}</source>
				<p>
					<code>DomaAbstractConfig</code>を利用する場合、必要な設定は次の3つです。
				</p>
				<ul>
					<li>データソースの設定</li>
					<li>データソース名の設定</li>
					<li>RDBMS方言の設定</li>
				</ul>
				<p>
					上記以外の設定については、デフォルトの実装やデフォルトの値が使用されます。
				</p>
				<table>
					<tr>
						<th>設定項目</th>
						<th>デフォルトの実装クラス/値</th>
					</tr>
					<tr>
						<td>ロガーの設定</td>
						<td><code>org.seasar.doma.jdbc.UtilLoggingJdbcLogger</code></td>
					</tr>
					<tr>
						<td>SQLファイルのリポジトリの設定</td>
						<td><code>org.seasar.doma.jdbc.GreedyCacheSqlFileRepository</code></td>
					</tr>
					<tr>
						<td>REQUIRES_NEWの属性をもつトランザクションを制御するための設定</td>
						<td><code>org.seasar.doma.jdbc.NullRequiresNewController</code></td>
					</tr>
					<tr>
						<td>クラスの扱いに関する設定</td>
						<td><code>org.seasar.doma.jdbc.DefaultClassHelper</code></td>
					</tr>
					<tr>
						<td>例外メッセージに含めるSQLのタイプの設定</td>
						<td><code>org.seasar.doma.jdbc.ExceptionSqlLogType.FORMATTED_SQL</code></td>
					</tr>
					<tr>
						<td>クエリタイムアウト（秒）の設定</td>
						<td><code>0 （0以下の値は明示的に設定しないことをあらわします）</code></td>
					</tr>
					<tr>
						<td>SELECT時のフェッチサイズの設定</td>
						<td><code>0 （0以下の値は明示的に設定しないことをあらわします）</code></td>
					</tr>
					<tr>
						<td>SELECT時の最大行数の設定</td>
						<td><code>0 （0以下の値は明示的に設定しないことをあらわします）</code></td>
					</tr>
					<tr>
						<td>バッチ更新のバッチサイズの設定</td>
						<td><code>10</code></td>
					</tr>
				</table>
			</subsection>
			<subsection name="JDBCドライバの設定">
				<p>
					通常、クラスパスが通っていれば、JDBC 4.0 ドライバは<a href="http://docs.oracle.com/javase/6/docs/technotes/guides/jar/jar.html#Service%20Provider">サービスプロバイダ</a>メカニズムにより自動でロードされます。
				</p>
				<p>
					しかし、たとえばTomcatでは、<a href="http://tomcat.apache.org/tomcat-7.0-doc/jndi-datasource-examples-howto.html#DriverManager, the service provider mechanism and memory leaks">WEB-INF/libの下のJDBCドライバを自動でロードしません</a>。
					自動でロードされない条件下では、Class.forNameを使ってJDBCドライバをロードしてください。
				</p>
				<p>
					Class.forNameを実行する場所は、設定クラスのstatic初期化子が1つの候補です。
					たとえば、H2 DatabaseのJDBCドライバを明示的にロードする場合には次のようにします。
				</p>
<source>public class AppConfig extends DomaAbstractConfig {
    static {
        try {
            Class.forName("org.h2.Driver");
        } catch (ClassNotFoundException e) {
            throw new RuntimeException(e);
        }
    }
    ...
}</source>
			</subsection>
		</section>
		<section name="設定クラスの利用">
			<p>
				設定クラスは<code>@Dao</code>の<code>config</code>要素で指定します。
				設定クラスを<code>AppConfig</code>という名前で作成した場合、次のようになります。
			</p>
<source><![CDATA[@Dao(config = AppConfig.class)
public interface EmployeeDao {
    ...
}]]></source>
		</section>
		<section name="DIコンテナを利用する場合の設定例">
			<p>
				DIコンテナを利用する場合、<code>Dao</code>の実装クラスや設定クラスのインスタンスをDIコンテナに管理させるとよいでしょう。
			</p>
			<subsection name="設定クラスのインスタンスのインジェクション">
				<p>
					<code>Dao</code>の実装クラスのインスタンスに設定クラスのインスタンスをインジェクションするには、
					<code>@Dao</code>の<code>config</code>要素に何も指定しないでください。
					この場合、<code>Config</code>型のインスタンスを受け取るコンストラクタが<code>Dao</code>の実装クラスに生成されます。
					コンストラクタインジェクションをサポートするDIコンテナであれば、設定ファイルなどによりインジェクションが可能です。
				</p>
<source><![CDATA[@Dao
public interface EmployeeDao {
    ...
}]]></source>
				<p>
					上のインタフェースに対する実装クラスのソースコードは、aptにより次のように生成されます。
				</p>
<source><![CDATA[public class EmployeeDaoImpl extends org.seasar.doma.jdbc.DomaAbstractDao implements example.EmployeeDao {
    public EmployeeDaoImpl(org.seasar.doma.jdbc.Config config) {
        super(config);
    }
    ...
}]]></source>
			</subsection>
			<subsection name="aptにより生成されるソースコードに対するアノテーションの注釈">
				<p>
					<code>@AnnotateWith</code>を使用することで、インジェクションのためのアノテーションを<code>Dao</code>の実装クラスのソースコードに注釈できます。
					これにより、DIコンテナがサポートしていれば、アノテーションによるインジェクションも可能になります。
				</p>
				<p>
					たとえば、  <a href="http://code.google.com/p/google-guice/">Guice</a>のアノテーションを注釈するには次のように記述します。
				</p>
<source><![CDATA[@Dao
@AnnotateWith(annotations = {
        @Annotation(target = AnnotationTarget.CONSTRUCTOR, type = Inject.class),
        @Annotation(target = AnnotationTarget.CONSTRUCTOR_PARAMETER, type = Named.class, elements = "\"sales\"") })
public interface EmployeeDao {
    ...
}]]></source>
				<p>
					上のインタフェースに対する実装クラスのソースコードは、aptにより次のように生成されます。
					コンストラクタとコンストラクタのパラメータにアノテーションが注釈されていることに注目してください。
				</p>
<source><![CDATA[public class EmployeeDaoImpl extends org.seasar.doma.jdbc.DomaAbstractDao implements example.EmployeeDao {
    @com.google.inject.Inject()
    public EmployeeDaoImpl(@com.google.inject.name.Named("sales") org.seasar.doma.jdbc.Config config) {
        super(config);
    }
    ...
}]]></source>
				<p>
					<code>@AnnotateWith</code>を任意のアノテーションに注釈し、そのアノテーションをDaoインタフェースに注釈することも可能です。
					たとえば、<code>@InjectConfig</code>というアノテーションに<code>@AnnotateWith</code>を注釈するとします。
				</p>
<source><![CDATA[@AnnotateWith(annotations = {
        @Annotation(target = AnnotationTarget.CONSTRUCTOR, type = Inject.class),
        @Annotation(target = AnnotationTarget.CONSTRUCTOR_PARAMETER, type = Named.class, elements = "\"sales\"") })
public @interface InjectConfig {
    ...
}]]></source>
				<p>
					<code>@InjectConfig</code>をDaoインタフェースに注釈すれば、<code>@AnnotateWith</code>を直接Daoインタフェースに注釈しているのと同じ効果が得られます。
				</p>
<source><![CDATA[@Dao
@InjectConfig
public interface EmployeeDao {
    ...
}]]></source>
			</subsection>
		</section>
	</body>
</document>