<?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="#JDKのインストール">JDKのインストール</a></li>
						<li><a href="#Eclipseのインストール">Eclipseのインストール</a></li>
						<li><a href="#プロジェクトのインポート">プロジェクトのインポート</a></li>
						<li><a href="#Doma_Toolsのインストール">Doma Toolsのインストール</a></li>
					</ul>
				</li>
				<li><a href="#チュートリアルの構成">チュートリアルの構成</a>
					<ul>
						<li><a href="#フォルダ構成">フォルダ構成</a></li>
						<li><a href="#データベース">データベース</a></li>
						<li><a href="#JDBCドライバのプロバイダ構成ファイル">JDBCドライバのプロバイダ構成ファイル</a></li>
						<li><a href="#主要なクラス">主要なクラス</a>
							<ul>
								<li><a href="#設定クラス">設定クラス</a></li>
								<li><a href="#エンティティクラス">エンティティクラス</a></li>
								<li><a href="#エンティティリスナークラス">エンティティリスナークラス</a></li>
								<li><a href="#ドメインクラス">ドメインクラス</a></li>
								<li><a href="#Daoインタフェース">Daoインタフェース</a></li>
							</ul>
						</li>
						<li><a href="#SQLファイル">SQLファイル</a></li>
					</ul>
				</li>
				<li><a href="#実行方法">実行方法</a></li>
				<li><a href="#機能の解説">機能の解説</a></li>
			</ul>
		</section>
		<section name="概要">
			<p>
				チュートリアルは、JUnitを使用したコンソール形式のアプリケーションです。
			</p>
			<p>
				このページでは、チュートリアルのセットアップ方法と構成について説明します。
			</p>
		</section>
		<section name="セットアップ">
			<p>
				チュートリアルのプロジェクトをダウンロードし、環境を整えます。
				JavaやEclipseのインストールがまだ完了していない場合は、先にそれらのセットアップを済ませてください。
			</p>
			<subsection name="JDKのインストール">
				<p>
					バージョン6以上のJDKをインストールします。
					JREではなくJDKが必要であることに注意してください。
					JDK 6 は以下のURLのサイトからダウンロードできます。
				</p>
				<p>
					<a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">http://www.oracle.com/technetwork/java/javase/downloads/index.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="プロジェクトのインポート">
				<p>
					<a href="../downloads.html">ダウンロード</a>のページからdoma-tutorial-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-tutorial-x.x.x.zipを選択します。</li>
					<li>「Projects」の項目に表示される「doma-tutorial」のチェックボックスをチェックし、「Finish」ボタンを押します。</li>
				</ul>
				<p>
					インポートが完了したら、doma-tutorialプロジェクトを右クリックし、コンテキストメニューから「Run As」 - 「JUnit Test」 を実行してください。
					すべてのテストが成功したらセットアップが正しく完了しています。
				</p>
				<h4>m2eclipseを使ってMaven Projectとしてインポートする方法</h4>
				<ul>
					<li>doma-tutorial-x.x.x.zipを解凍します。</li>
					<li>Eclipseのメニューから「File」 - 「Import」を選択します。</li>
					<li>「Existing Maven Projects」を選択し、「Next」ボタンを押します。</li>
					<li>Root Directoryの入力欄にdoma-tutorial-x.x.x.zipを解凍したディレクトリを指定します。</li>
					<li>「Projects」の項目に表示されるpom.xmlのチェックボックスをチェックし、「Finish」ボタンを押します。</li>
					<li>インポートが完了した時点ではビルドエラーが発生します。</li>
					<li>エラーを解消するために、プロジェクトのプロパティからJavaのビルドパスのダイアログを開きます。</li>
					<li>Javaのビルドパスのダイアログでは、src/main/resourcesとsrc/test/resourcesのソースフォルダの「Exclude:**/*」となっている項目を選択して「Remove」を押します（「Exclude:(None)」に変わります）。</li>
					<li>また、同じJavaのビルドパスのダイアログで「Add Folder...」を押し、プロジェクト直下の.apt_generatedをソースフォルダとして登録します。</li>
				</ul>
				<p>
					以上の手順を実行し終えるとビルドエラーは解消されます。
					最後に、doma-tutorialプロジェクトを右クリックし、コンテキストメニューから「Run As」 - 「JUnit Test」 を実行してください。
					すべてのテストが成功したらセットアップが正しく完了しています。
				</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>
		</section>
		<section name="チュートリアルの構成">
			<p>
				チュートリアルの構成を説明します。
			</p>
			<subsection name="フォルダ構成">
				<p>
					プロジェクトのフォルダ構成は以下の通りです。主要なものを中心に説明します。
				</p>
				<table>
					<tr>
						<th>フォルダ</th>
						<th>説明</th>
					</tr>
					<tr>
						<td>src/main/java</td>
						<td>
							設定クラス、Daoインタフェース、エンティティクラス等のソースフォルダです。
						</td>
					</tr>
					<tr>
						<td>src/main/resources</td>
						<td>
							SQLファイル等のソースフォルダです。
							SQLファイルは、Domaの規約に則ってMETA-INFフォルダ以下に配置されます。
							また、JDBCドライバのプロバイダ構成ファイルがMETA-INF/servicesフォルダ以下にjava.sql.Driverという名前で配置されます。
						</td>
					</tr>
					<tr>
						<td>src/test/java</td>
						<td>
							Daoを利用するコードのためのソースフォルダです。
							Daoを利用するコードはすべてJUnitのテストクラスとして記述されています。
						</td>
					</tr>
					<tr>
						<td>src/test/resources</td>
						<td>
							使用していません。
						</td>
					</tr>
					<tr>
						<td>.apt_generated</td>
						<td>
							apt（Annotation Processing Tool）によって生成されたコードを格納するソースフォルダです。
							Package Explorerビューでは、フィルタリングされるため表示されません（フィルタリングは解除可能です）。
							Nivigatorビューで確認できます。
						</td>
					</tr>
					<tr>
						<td>lib</td>
						<td>
							このチュートリアルで利用するjarファイルを格納するフォルダです。
							JUnit、H2、Domaのjarが格納されます。
							これらのjarはすべてビルドパスに通っていなければいけません。
						</td>
					</tr>
					<tr>
						<td>libsrc</td>
						<td>このチュートリアルで利用するjarファイルのソースコードを格納するフォルダです。</td>
					</tr>
				</table>
				<p>
					プロジェクト直下には次のファイルがあります。主要なものを説明します。
				</p>
				<table>
					<tr>
						<th>ファイル</th>
						<th>説明</th>
					</tr>
					<tr>
						<td>build.xml</td>
						<td>
							チュートリアルプロジェクトをAntでビルドするためのビルドファイルです。
							詳しくは、<a href="../reference/app_build.html#Antによるビルド">Antによるビルド</a>を参照してください。
						</td>
					</tr>
					<tr>
						<td>pom.xml</td>
						<td>
							チュートリアルプロジェクトをMavenでビルドするためのプロジェクト記述ファイルです。
							詳しくは、<a href="../reference/app_build.html#Mavenによるビルド">Mavenによるビルド</a>を参照してください。
						</td>
					</tr>
				</table>
			</subsection>
			<subsection name="データベース">
				<p>
					このチュートリアルでは、データベースに<a href="http://www.h2database.com/html/main.html">H2 Database Engine</a>を利用します。
				</p>
				<p>
					使用するスキーマの定義は次のとおりです。
					1つのシーケンスと2つのテーブルを使用します。
				</p>
	<source><![CDATA[create sequence employee_seq start with 100 increment by 1;]]></source>
<source><![CDATA[create table employee (
  id integer not null primary key,
  name varchar(255) not null,
  age integer not null,
  salary integer,
  job_type varchar(20),
  hiredate timestamp, 
  department_id integer, 
  version integer not null, 
  insertTimestamp timestamp, 
  updateTimestamp timestamp
);]]></source>
<source><![CDATA[create table department (
  id integer not null primary key,
  name varchar(255) not null,
  version integer not null
);]]></source>
				<p>
					H2はin-memoryモードで起動し、テスト用のスキーマとデータは各テストの実行前に作成し、テスト終了後に破棄します。
					スキーマとデータの作成と破棄は、共通のテストクラスで行っています。
					Javaのコードは、<a href="https://www.seasar.org/svn/doma/trunk/doma-tutorial/src/test/java/tutorial/TutorialTestCase.java">src/test/java/tutorial/TutorialTestCase.java</a>になります。
				</p>
			</subsection>
			<subsection name="JDBCドライバのプロバイダ構成ファイル">
				<p>
					H2のJDBCドライバを登録するためのプロバイダ構成ファイルがsrc/main/resources/META-INF/servicesに必要です。
					ファイルの名称は<a href="https://www.seasar.org/svn/doma/trunk/doma-tutorial/src/main/resources/META-INF/services/java.sql.Driver">java.sql.Driver</a>で、中身は次のように記述されます。
				</p>
<source><![CDATA[org.h2.Driver]]></source>
				<p>
					プロバイダ構成ファイルの詳細については、<a href="http://java.sun.com/javase/ja/6/docs/ja/technotes/guides/jar/jar.html#Service%20Provider">JAR ファイルの仕様</a>
					を参照してください。
				</p>
			</subsection>
			<subsection name="主要なクラス">
				<p>
					チュートリアル中の主要なクラスについて説明します。
				</p>
				<h4><a name="設定クラス"></a>設定クラス</h4>
				<p>
					<a href="../reference/config.html">設定クラス</a>とは、Domaに関する各種設定を持つクラスです。
					このチュートリアルで使用する設定クラスのソースコードは、<a href="https://www.seasar.org/svn/doma/trunk/doma-tutorial/src/main/java/tutorial/AppConfig.java">src/main/java/tutorial/AppConfig.java</a>になります。
				</p>
				<p>
					このクラスでは、H2のデータソースの作成とH2の方言の設定を行っています。
					それ以外の設定については親クラスの<a href="https://www.seasar.org/svn/doma/trunk/doma/src/main/java/org/seasar/doma/jdbc/DomaAbstractConfig.java">DomaAbstractConfig</a>のものを利用しています。
					設定クラスはDaoインタフェースから利用されます。
				</p>
<source><![CDATA[public class AppConfig extends DomaAbstractConfig {

    protected static final LocalTransactionalDataSource dataSource = createDataSource();

    protected static final Dialect dialect = new H2Dialect();

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

    @Override
    public Dialect getDialect() {
        return dialect;
    }

    protected static LocalTransactionalDataSource createDataSource() {
        SimpleDataSource dataSource = new SimpleDataSource();
        dataSource.setUrl("jdbc:h2:mem:tutorial;DB_CLOSE_DELAY=-1");
        dataSource.setUser("sa");
        return new LocalTransactionalDataSource(dataSource);
    }

    public static LocalTransaction getLocalTransaction() {
        return dataSource.getLocalTransaction(defaultJdbcLogger);
    }

}]]></source>
				<h4><a name="エンティティクラス"></a>エンティティクラス</h4>
				<p>
					<a href="../reference/entity.html">エンティティクラス</a>とは、テーブルやSQLの結果セットにマッピングされたクラスです。
					エンティティクラスは、@Entityを注釈して示します。
					このチュートリアルで使用するエンティティクラスのソースコードは、
					<a href="https://www.seasar.org/svn/doma/trunk/doma-tutorial/src/main/java/tutorial/entity/Employee.java">src/main/java/tutorial/entity/Employee.java</a>
					と
					<a href="https://www.seasar.org/svn/doma/trunk/doma-tutorial/src/main/java/tutorial/entity/EmployeeDepartment.java">src/main/java/tutorial/entity/EmployeeDepartment.java</a>
					になります。
				</p>
				<p>
					Employeeクラスは、EMPLOYEEテーブルに対応します。
				</p>
				<p>
					識別子（テーブルの主キー）には@Idを注釈します。
					識別子を自動生成する場合は、さらに@GeneratedValueを注釈し、自動生成の方法を示します。
					ここではEMPLOYEE_SEQシーケンスを使って採番することを示しています。
				</p>
				<p>
					プロパティ名がマッピングするカラム名と異なる場合は@Columnのname要素を使って示します。
				</p>
				<p>
					更新や削除時の楽観的排他制御に使用するカラムとマッピングされたプロパティには@Versionを注釈します。
				</p>
				<p>
					@Entityのlistener要素にはEmployeeListenerクラスを指定しています。
				</p>
<source><![CDATA[@Entity(listener = EmployeeListener.class)
public class Employee {

    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE)
    @SequenceGenerator(sequence = "EMPLOYEE_SEQ")
    Integer id;

    String name;

    int age;

    Salary salary;

    @Column(name = "JOB_TYPE")
    JobType jobType;

    Date hiredate;

    @Column(name = "DEPARTMENT_ID")
    Integer departmentId;

    @Version
    @Column(name = "VERSION")
    Integer version;

    Timestamp insertTimestamp;

    Timestamp updateTimestamp;

    @OriginalStates
    Employee originalStates;

    ...
}]]></source>
				<p>
					EmployeeDepartmentクラスは、EMPLOYEEテーブルとDEPARTMENTテーブルを結合した結果セットに対応します。
				</p>
				<p>
					このクラスは、Employeeクラスを継承し、DEPARTMENTテーブルのNAMEカラムに対応するプロパティを持ちます。
					@Columnのname要素に指定されている「DEPARTMENT_NAME」はSQL上でDEPARTMENTテーブルのNAMEカラムの別名になります。
				</p>
<source><![CDATA[@Entity
public class EmployeeDepartment extends Employee {

    @Column(name = "DEPARTMENT_NAME")
    String departmentName;

    ...
}]]></source>
				<h4><a name="エンティティリスナークラス"></a>エンティティリスナークラス</h4>
				<p>
					エンティティリスナークラスのインスタンスは、エンティティがデータベースに挿入、更新、削除される前後に呼び出されます。
					このチュートリアルで使用するエンティティリスナークラスはEmployeeListenerです。
					ソースコードは、<a href="https://www.seasar.org/svn/doma/trunk/doma-tutorial/src/main/java/tutorial/entity/EmployeeListener.java">src/main/java/tutorial/entity/EmployeeListener.java</a>になります。
				</p>
<source><![CDATA[public class EmployeeListener implements EntityListener<Employee> {

    @Override
    public void preDelete(Employee employee, PreDeleteContext context) {
    }

    @Override
    public void preInsert(Employee employee, PreInsertContext context) {
        Timestamp timestamp = new Timestamp(System.currentTimeMillis());
        employee.setInsertTimestamp(timestamp);
    }

    @Override
    public void preUpdate(Employee employee, PreUpdateContext context) {
        if (context.isEntityChanged()) {
            Timestamp timestamp = new Timestamp(System.currentTimeMillis());
            employee.setUpdateTimestamp(timestamp);
        }
    }

    @Override
    public void postInsert(Employee entity, PostInsertContext context) {
    }

    @Override
    public void postUpdate(Employee entity, PostUpdateContext context) {
    }

    @Override
    public void postDelete(Employee entity, PostDeleteContext context) {
    }
}]]></source>
				<h4><a name="ドメインクラス"></a>ドメインクラス</h4>
				<p>
					<a href="../reference/domain.html">ドメインクラス</a>は、データベースのカラムにマッピング可能なアプリケーション固有の値型です。
					ドメインクラスは@Domainを注釈して示します。
					このチュートリアルで使用するドメインクラスは、給料を表すSalaryクラスです。
					ソースコードは、<a href="https://www.seasar.org/svn/doma/trunk/doma-tutorial/src/main/java/tutorial/domain/Salary.java">src/main/java/tutorial/domain/Salary.java</a>になります。
				</p>
<source><![CDATA[@Domain(valueType = Integer.class)
public class Salary {

    private final Integer value;

    public Salary(Integer value) {
        this.value = value;
    }

    public Integer getValue() {
        return value;
    }

    public Salary add(Salary salary) {
        if (salary == null) {
            throw new NullPointerException("The salary parameter is null.");
        }
        if (this.value == null || salary.value == null) {
            return new Salary(null);
        }
        return new Salary(this.value + salary.value);
    }

    ...

}]]></source>
				<h4><a name="Daoインタフェース"></a>Daoインタフェース</h4>
				<p>
					<a href="../reference/dao.html">Daoインタフェース</a>とは、データベースアクセスの境界となるインタフェースです。
					Daoインタフェースは@Daoを注釈して示します。
					@Daoのconfig要素には設定クラスであるAppConfigクラスを指定します。
					このチュートリアルで使用するDaoインタフェースのソースコードは、<a href="https://www.seasar.org/svn/doma/trunk/doma-tutorial/src/main/java/tutorial/dao/EmployeeDao.java">src/main/java/tutorial/dao/EmployeeDao.java</a>になります。
				</p>
				<p>
					Daoインタフェースの実装クラスはDomaにより自動生成されます。
				</p>
				<p>
					すべてのメソッドは、@Selectや@Updateなど問い合わせの種別を示すアノテーションが注釈されなければいけません。
				</p>
<source><![CDATA[@Dao(config = AppConfig.class)
public interface EmployeeDao {

    @Select
    Employee selectById(Integer id);

    @Select
    List<Employee> selectByAgeRange(Integer min, Integer max);

    @Select
    List<Employee> selectByAges(List<Integer> ages);

    @Select
    List<Employee> selectByNames(List<String> names);

    ...

    @Insert
    int insert(Employee employee);

    @Insert(sqlFile = true)
    int insertWithSqlFile(Employee employee);

    @Update
    int update(Employee employee);

    @Update(sqlFile = true)
    int updateWithSqlFile(Employee employee);

    @Delete
    int delete(Employee employee);

    @Delete(sqlFile = true)
    int deleteWithSqlFile(Employee employee);

    ...

}]]></source>
			</subsection>
			<subsection name="SQLファイル">
				<p>
					<a href="../reference/sqlfile.html">SQLファイル</a>は、src/main/resources/META-INF/tutorial/EmployeeDaoフォルダ以下に配置されます。
					フォルダの名前はDaoインタフェースと対応づけられます。
				</p>
				<p>
					SQLファイルは、名前から拡張子を除いたものがDaoインタフェースのメソッドに一致します。
					たとえば、<a href="https://www.seasar.org/svn/doma/trunk/doma-tutorial/src/main/resources/META-INF/tutorial/dao/EmployeeDao/selectById.sql">selectById.sql</a>はDaoインタフェースのselectByIdメソッドに対応します。
					selectById.sqlの中身は次のようなテキストです。
				</p> 
<source><![CDATA[select * from employee where id = /* id */0]]></source>
			</subsection>
			<subsection name="実行方法">
				<p>
					Eclipseの場合、src/test/java/tutorial以下のJavaファイルを開き、メニューから「Run」 - 「Run as」 - 「JUnit Test」を選択します。
				</p>
			</subsection>
			<subsection name="機能の解説">
				<ul>
					<li><a href="select.html">検索</a>
						<ul>
							<li><a href="select.html#概要">概要</a></li>
							<li><a href="select.html#単純な検索">単純な検索</a></li>
							<li><a href="select.html#条件分岐を用いた検索">条件分岐を用いた検索</a></li>
							<li><a href="select.html#条件分岐でelseを用いた検索">条件分岐でelseを用いた検索</a></li>
							<li><a href="select.html#繰り返しを用いた検索">繰り返しを用いた検索</a></li>
							<li><a href="select.html#IN述語による検索">IN述語による検索</a></li>
							<li><a href="select.html#LIKE述語による検索">LIKE述語による検索</a></li>
							<li><a href="select.html#日付による範囲検索">日付による範囲検索</a></li>
							<li><a href="select.html#文字シーケンスを組み込み関数で判定する検索">文字シーケンスを組み込み関数で判定する検索</a></li>
							<li><a href="select.html#ドメインによる検索">ドメインによる検索</a></li>
							<li><a href="select.html#エンティティによる検索">エンティティによる検索</a></li>
							<li><a href="select.html#ページングを行う検索">ページングを行う検索</a></li>
							<li><a href="select.html#ページングと集計を同時に行う検索">ページングと集計を同時に行う検索</a></li>
							<li><a href="select.html#イテレーション検索">イテレーション検索</a></li>
							<li><a href="select.html#結合した結果を取得する検索">結合した結果を取得する検索</a></li>
						</ul>
					</li>
					<li><a href="insert.html">挿入</a>
						<ul>
							<li><a href="insert.html#概要">概要</a></li>
							<li><a href="insert.html#SQLの自動生成による挿入">SQLの自動生成による挿入</a></li>
							<li><a href="insert.html#SQLファイルによる挿入">SQLファイルによる挿入</a></li>
						</ul>
					</li>
					<li><a href="update.html">更新</a>
						<ul>
							<li><a href="update.html#概要">概要</a></li>
							<li><a href="update.html#SQLの自動生成による更新">SQLの自動生成による更新</a></li>
							<li><a href="update.html#SQLファイルによる更新">SQLファイルによる更新</a></li>
						</ul>
					</li>
					<li><a  href="delete.html">削除</a>
						<ul>
							<li><a href="delete.html#概要">概要</a></li>
							<li><a href="delete.html#SQLの自動生成による削除">SQLの自動生成による削除</a></li>
							<li><a href="delete.html#SQLファイルによる削除">SQLファイルによる削除</a></li>
						</ul>
					</li>
				</ul>
			</subsection>
		</section>
	</body>
</document>
