<?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>Doma JPetStore</title>
	</properties>
	<body>
		<section name="目次">
			<ul>
				<li><a href="#概要">概要</a></li>
				<li><a href="#セットアップ">セットアップ</a>
					<ul>
						<li><a href="#JDKのインストール">JDKのインストール</a></li>
						<li><a href="#Eclipseのインストール">Eclipseのインストール</a></li>
						<li><a href="#Tomcatのインストール">Tomcatのインストール</a></li>
						<li><a href="#SysdeoSQLI_Tomcat_Launcherのインストール">Sysdeo/SQLI Tomcat Launcherのインストール</a></li>
						<li><a href="#Doma_Toolsのインストール">Doma Toolsのインストール</a></li>
						<li><a href="#プロジェクトのインポート">プロジェクトのインポート</a></li>
					</ul>
				</li>
				<li><a href="#アプリケーションの起動">アプリケーションの起動</a>
					<ul>
						<li><a href="#制限事項">制限事項</a></li>
					</ul>
				</li>
				<li><a href="#Seasar2との連携">Seasar2との連携</a>
					<ul>
						<li><a href="#Seasar2で管理されたデータソースを利用する">Seasar2で管理されたデータソースを利用する</a></li>
						<li><a href="#Seasar2で管理されたトランザクションマネジャーを利用する">Seasar2で管理されたトランザクションマネジャーを利用する</a></li>
						<li><a href="#ログ管理を統合する">ログ管理を統合する</a></li>
						<li><a href="#HOT_deploy環境下でSQLファイルの変更を即座に認識させる">HOT deploy環境下でSQLファイルの変更を即座に認識させる</a></li>
						<li><a href="#DomaのDaoをSMART_deployする">DomaのDaoをSMART deployする</a></li>
					</ul>
				</li>
				<li><a href="#JPetStoreを他プロジェクトの雛形として使用する際の注意点">JPetStoreを他プロジェクトの雛形として使用する際の注意点</a>
					<ul>
						<li><a href="#convention.dicon">convention.dicon</a></li>
						<li><a href="#jdbc.dicon">jdbc.dicon</a></li>
						<li><a href="#struts-config.xml">struts-config.xml</a></li>
					</ul>
				</li>
			</ul>
		</section>
		<section name="概要">
			<p>
				Doma JPetStoreは、<a href="http://sastruts.seasar.org/">SAStruts</a>との連携方法を示すデモ用Webアプリケーションです。
				他のプロジェクトの雛形として使用されることも想定しています。
			</p>
			<p>
				このアプリケーションは、<a href="http://ibatis.apache.org/java.cgi">iBATIS</a>が提供する JPetStore 5.0 Example Application をベースに作成されています。
			</p>
		</section>
		<section name="セットアップ">
			<subsection name="JDKのインストール">
				<p>
					バージョン6以上のJDKをインストールします。
					JREではなくJDKが必要であることに注意してください。
					JDK 6 は以下のURLのサイトからダウンロードできます。
				</p>
				<p>
					<a href="http://java.sun.com/javase/ja/6/download.html">http://java.sun.com/javase/ja/6/download.html</a>
				</p>
			</subsection>
			<subsection name="Eclipseのインストール">
				<p>
					バージョン3.5以上のEclipseをインストールします。
					<a href="http://jcp.org/en/jsr/detail?id=269">Pluggable Annotation Processing API</a>
					をサポートしていれば、Eclipse以外のIDEであってもかまいませんが、
					このドキュメントではEclipseを使うことを前提に説明を進めます。
					Eclipseは以下のURLのサイトからダウンロードできます。
				</p>
				<p>
					<a href="http://www.eclipse.org/downloads/">http://www.eclipse.org/downloads/</a>
				</p>
				<p>
					Eclipseは、バージョン6以上のJDKに含まれるJREで起動されるようにしてください。
					明示的にJREを指定するには、-vm オプションを使用します。
				</p>
				<pre>-vm %JAVA_HOME%\bin\javaw.exe</pre>
			</subsection>
			<subsection name="Tomcatのインストール">
				<p>
					Tomcatのバージョン6.xをインストールします。 
					Tomcatは以下のURLのサイトからダウンロードできます。
				</p>
				<p>
					<a href="http://tomcat.apache.org/download-60.cgi">http://tomcat.apache.org/download-60.cgi</a>
				</p>
			</subsection>
			<subsection name="Sysdeo/SQLI Tomcat Launcherのインストール">
				<p>
					アプリケーションをEclipseから動作させるには、EclipseプラグインのSysdeo/SQLI Tomcat Launcher をインストールｓます。
					Sysdeo/SQLI Tomcat Launcher は以下の更新サイトからインストールできます。
				</p>
				<p>
					<a href="http://eclipse.seasar.org/updates/3.2/">http://eclipse.seasar.org/updates/3.2/</a>
				</p>
				<p>
					Sysdeo/SQLI Tomcat Launcher をインストールしたら、メニューの「Window」 - 「Preference」 ー「Tomcat」 よりTomcatのバージョンとホームを指定してください。
				</p>
			</subsection>
			<subsection name="Doma Toolsのインストール">
				<p>
					<a href="extension/doma_tools.html">Doma Tools</a>をインストールします。
				</p>
				<p>
					Doma Toolsは、以下の更新サイトからインストールできます。
				</p>
				<ul>
					<li><a href="http://eclipse.seasar.org/updates/3.5/">http://eclipse.seasar.org/updates/3.5/</a></li>
				</ul>
			</subsection>
			<subsection name="プロジェクトのインポート">
				<p>
					<a href="../downloads.html">ダウンロード</a>のページからdoma-jpetstore-x.x.x.zipをダウンロードし、
					Eclipseへインポートしてください。インポートの具体的な手順は次のとおりです。2つの方法を説明します。
				</p>
				<h4>通常の方法</h4>
				<ul>
					<li>Eclipseのメニューから「File」 - 「Import」を選択します。</li>
					<li>「Existing Projects to Workspace」を選択し、「Next」ボタンを押します。</li>
					<li>「Select archive file」のラジオボタンをチェックし、ダウンロードしたdoma-jpetstore-x.x.x.zipを選択します。</li>
					<li>「Projects」の項目に表示される「doma-jpetstore」のチェックボックスをチェックし、「Finish」ボタンを押します。</li>
				</ul>
				<h4>m2eclipseを使ってMaven Projectとしてインポートする方法</h4>
				<ul>
					<li>doma-jpetstore-x.x.x.zipを解凍します。</li>
					<li>Eclipseのメニューから「File」 - 「Import」を選択します。</li>
					<li>「Existing Maven Projects」を選択し、「Next」ボタンを押します。</li>
					<li>Root Directoryの入力欄にdoma-jpetstore-x.x.x.zipを解凍したディレクトリを指定します。</li>
					<li>「Projects」の項目に表示されるpom.xmlのチェックボックスをチェックし、「Finish」ボタンを押します。</li>
					<li>インポートが完了した時点ではビルドエラーが発生します。</li>
					<li>エラーを解消するために、プロジェクトのプロパティからJavaのビルドパスのダイアログを開きます。</li>
					<li>Javaのビルドパスのダイアログでは、src/main/resourcesのソースフォルダの「Exclude:**/*」となっている項目を選択して「Remove」を押します（「Exclude:(None)」に変わります）。</li>
					<li>また、同じJavaのビルドパスのダイアログで「Add Folder...」を押し、プロジェクト直下の.apt_generatedをソースフォルダとして登録します。</li>
				</ul>
				<p>
					以上の手順を実行し終えるとビルドエラーは解消されます。
				</p>
			</subsection>
		</section>
		<section name="アプリケーションの起動">
			<p>
				プロジェクトを右クリックし、コンテキストメニューから「Tomcatプロジェクト」 - 「コンテキスト定義を更新」 を実行します。
				そして、メニューの「Tomcat」 - 「Tomcat起動」 を実行します。
			</p>
			<p>
				Tomcatの起動が完了したことを確認し、<a href="http://localhost:8080/doma-jpetstore/">http://localhost:8080/doma-jpetstore/</a> にアクセスしてください。
			</p>
			<subsection name="制限事項">
				<p>
					Internet Explorerで表示すると画面レイアウトが崩れます。
					オリジナルのJPetStore 5.0 Example ApplicationのCSSがInternet Explorerに対応できていないようです。
					Internet Explorerでもレイアウトが崩れないように直してくれる方がいたら歓迎いたします。
				</p>
			</subsection>
		</section>
		<section name="Seasar2との連携">
			<p>
				DomaとSeasar2を連携させるためのTipsを説明します。
			</p>
			<subsection name="Seasar2で管理されたデータソースを利用する">
				<p>
					<a href="reference/config.html">設定クラス</a>のgetDataSourceメソッドで、
					S2Containerからデータソースを取り出し返します。
					src/main/java/demo/config/AppConfig.javaを参照してください。
				</p>
<source><![CDATA[public class AppConfig implements Config {

    ...

    @Override
    public DataSource getDataSource() {
        return getDataSourceInternal();
    }

    protected DataSource getDataSourceInternal() {
        S2Container container = SingletonS2ContainerFactory.getContainer();
        return (DataSource) container.getComponent(DataSource.class);
    }
    
    ...
}]]></source>
				<p>
					別の方法としては、設定クラスのコンポーネントをS2Containerで管理してデータソースをDIし、それから設定クラスのコンポーネントをDaoにDIするという戦略もあります。
					こちら方法を使用したい場合は、<a href="reference/config.html#DIコンテナを利用する場合の設定例">DIコンテナを利用する場合の設定例</a>を参照してください。
				</p>
			</subsection>
			<subsection name="Seasar2で管理されたトランザクションマネジャーを利用する">
				<p>
					Seasar2で管理されたデータソースを利用していれば、ほとんど意識することなくSeasar2で管理されたトランザクションマネジャーと連携できます。
					Doma JPetStoreアプリケーションでは、Actionがトランザクション境界になっているため、Action呼び出し以降であれば
					Daoで行われるデータアクセスはSeasar2で管理されたトランザクションマネジャーの配下で行われます。
				</p>
				<p>
					通常、Domaがトランザクションマネジャーを意識する必要はないのですが、テーブルを使った採番で行ロックを極力短くするために局所的にトランザクションマネジャーと連携したいことがあります。
					そのために用意されているのが、<code>org.seasar.doma.jdbc.RequiresNewController</code>というインタフェースです。
					Seasar2用の実装例としては、src/main/java/demo/config/S2RequiresNewController.javaを参照してください。
				</p>
<source><![CDATA[public class S2RequiresNewController implements RequiresNewController {

    @SuppressWarnings("unchecked")
    @Override
    public <R> R requiresNew(final Callback<R> callback) throws Throwable {
        S2Container container = SingletonS2ContainerFactory.getContainer();
        TransactionManagerAdapter txAdapter = (TransactionManagerAdapter) container
                .getComponent(TransactionManagerAdapter.class);
        Object result = txAdapter.requiresNew(new TransactionCallback() {

            public Object execute(final TransactionManagerAdapter adapter)
                    throws Throwable {
                return callback.execute();
            }

        });
        return (R) result;
    }
}]]></source>
				<p>
					<a href="reference/config.html">設定クラス</a>（src/main/java/demo/config/AppConfig.java）のgetRequiresNewControllerメソッドでは、上記のS2RequiresNewControllerのインスタンスを返すようにします。
				</p>
			</subsection>
			<subsection name="ログ管理を統合する">
				<p>
					Seasar2では、ログ管理にCommons Loggingを使用しています。
					DomaはデフォルトではJDKのLogging APIを使用していますが、Seasar2に合わせてCommons Loggingに出力したほうが管理しやすいでしょう。
				</p>
				<p>
					Domaのログ出力の実装を切り替えるには、<code>org.seasar.doma.jdbc.JdbcLogger</code>というインタフェースの実装を用意します。
					実装例としては、src/main/java/demo/config/CommonsJdbcLogger.javaを参照してください。
				</p>
<source><![CDATA[public class CommonsJdbcLogger implements JdbcLogger {

    ...

    @Override
    public void logDaoMethodEntering(String callerClassName,
            String callerMethodName, Object... parameters) {
        Log log = LogFactory.getLog(callerClassName);
        log.info("START " + callerClassName + "#" + callerMethodName);
    }

    @Override
    public void logDaoMethodExiting(String callerClassName,
            String callerMethodName, Object result) {
        Log log = LogFactory.getLog(callerClassName);
        log.info("END   " + callerClassName + "#" + callerMethodName);
    }

    ...

    @Override
    public void logSql(String callerClassName, String callerMethodName,
            Sql<?> sql) {
        Log log = LogFactory.getLog(callerClassName);
        String message = String.format("SQL log. sqlFilePath=[%s],%n%s", sql
                .getSqlFilePath(), sql.getFormattedSql());
        log.info(message);
    }

}]]></source>
				<p>
					<a href="reference/config.html">設定クラス</a>（src/main/java/demo/config/AppConfig.java）のgetJdbcLoggerメソッドでは、上記のCommonsJdbcLoggerのインスタンスを返すようにします。
				</p>
			</subsection>
			<subsection name="HOT deploy環境下でSQLファイルの変更を即座に認識させる">
				<p>
					Seasar2が提供するHotdeployUtilというユーティリティクラスを使用し、
					HOT deployの場合にはSQLファイルをキャッシュしないようにします。
					実装例としてはsrc/main/java/demo/config/SqlFileRepositoryProxy.javaを参照してください。
				</p>
<source><![CDATA[public class SqlFileRepositoryProxy extends AbstractSqlFileRepository {

    private final SqlFileRepository greedyCacheSqlFileRepository = new GreedyCacheSqlFileRepository();

    private final SqlFileRepository noCacheSqlFileRepository = new NoCacheSqlFileRepository();

    @Override
    protected SqlFile getSqlFileWithCacheControl(String path, Dialect dialect) {
        if (HotdeployUtil.isHotdeploy()) {
            return noCacheSqlFileRepository.getSqlFile(path, dialect);
        }
        return greedyCacheSqlFileRepository.getSqlFile(path, dialect);
    }

}]]></source>
				<p>
					<a href="reference/config.html">設定クラス</a>（src/main/java/demo/config/AppConfig.java）のgetSqlFileRepositoryメソッドでは、上記のSqlFileRepositoryProxyのインスタンスを返すようにします。
				</p>
			</subsection>
			<subsection name="DomaのDaoをSMART deployする">
				<p>
					Domaのaptが生成するクラスは、デフォルトでは、Seasar2のSMART deployの命名規約に即していません。
					SMART deployに対応させるには、aptで生成されるDao実装クラスの名前を調整する必要があります。
				</p>
				<p>
					たとえば、Daoインタフェースが<code>demo.smart.dao.ProductDao</code>という名前の場合、
					生成されるDao実装クラスが<code>demo.smart.dao.impl.ProductDaoImpl</code>となるようにします（前提としてdemo.smartがルートパッケージでなければいけません）。
				</p>
				<p>
					このような名前の調整は<a href="reference/apt.html">注釈処理</a>のオプション指定で行います。
					具体的には、「dao.subpackage」には「impl」を、「dao.suffix」には「Impl」を指定します。
					Eclipseの場合、プロジェクトのプロパティの「Annotation Processing」の項目で次のように指定します。
				</p>
				<img src="images/eclipse_apt_options.png" width="454" height="152" alt="Eclipseでのオプション指定" />
			</subsection>
		</section>
		<section name="JPetStoreを他プロジェクトの雛形として使用する際の注意点">
			<p>
				JPetStoreを他プロジェクトの雛形として使用する際の注意点を述べます。
			</p>
			<subsection name="convention.dicon">
				<p>
					src/main/resources/convention.diconには、ルートパッケージを指定します。
					JPetStoreでは、「demo.smart」と「demo」の2つを指定していますが、このパッケージ名を新しいプロジェクトのパッケージ構成に合わせて変更してください。
				</p>
<source><![CDATA[<components>
	<component class="org.seasar.framework.convention.impl.NamingConventionImpl">
		<initMethod name="addRootPackageName">
			<arg>"demo.smart"</arg>
		</initMethod>
		<initMethod name="addRootPackageName">
			<arg>"demo"</arg>
			<arg>false</arg>
		</initMethod>
	</component>
	<component class="org.seasar.framework.convention.impl.PersistenceConventionImpl"/>
</components>]]></source>
			</subsection>
			<subsection name="jdbc.dicon">
				<p>
					src/main/resources/jdbc.diconには、JDBCの接続情報を記述します。
					JPetStoreでは、H2 Database Engineを使用していますが、新しいプロジェクトで使用するデータベースに合わせて変更してください。
				</p>
<source><![CDATA[<components namespace="jdbc">
	<include path="jta.dicon"/>

	<!-- for H2 -->
	<component name="xaDataSource"
		class="org.seasar.extension.dbcp.impl.XADataSourceImpl">
		<property name="driverClassName">
			"org.h2.Driver"
		</property>
		<property name="URL">
			"jdbc:h2:file:"
				+ @org.seasar.framework.util.ResourceUtil@getBuildDir("jdbc.dicon").getCanonicalPath()
				+ "/data-h2/demo;DB_CLOSE_ON_EXIT=FALSE"
		</property>
		<property name="user">"sa"</property>
		<property name="password">""</property>
	</component>
	．．．
</components>]]></source>
			</subsection>
			<subsection name="struts-config.xml">
				<p>
					JPetStoreでは、独自のRequestProcessorを使用しています。
					SAStrutsのRequestProcessorを使用するには、
					src/main/webapp/WEB-INF/struts-config.xml内のcontroller要素のprocessorClass属性で<code>demo.action.JPetStoreRequestProcessor</code>のかわりに<code>org.seasar.struts.action.S2RequestProcessor</code>を指定してください。
				</p>
<source><![CDATA[<struts-config>
	．．．
	<controller
		maxFileSize="1024K"
		bufferSize="1024"
		processorClass="demo.action.JPetStoreRequestProcessor"
		multipartClass="org.seasar.struts.upload.S2MultipartRequestHandler"/>
	．．．
</struts-config>]]></source>
			</subsection>
		</section>
	</body>
</document>
