<?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="#H2_Database_Engineのダウンロード">H2 Database Engineのダウンロード</a></li>
						<li><a href="#JDBCドライバの設定">JDBCドライバの設定</a></li>
						<li><a href="#サンプルテーブルとデータの作成">サンプルテーブルとデータの作成</a></li>
						<li><a href="#エンティティクラスの作成">エンティティクラスの作成</a></li>
						<li><a href="#設定クラスの作成">設定クラスの作成</a></li>
						<li><a href="#Daoインタフェースの作成">Daoインタフェースの作成</a></li>
						<li><a href="#SQLファイルの作成">SQLファイルの作成</a></li>
						<li><a href="#起動クラスの作成">起動クラスの作成</a></li>
						<li><a href="#実行結果">実行結果</a></li>
						<li><a href="#プロジェクト構成">プロジェクト構成</a></li>
					</ul>
				</li>
				<li><a href="#次へのステップ">次へのステップ</a></li>
			</ul>
		</section>
		<section name="概要">
			<p>
				このページでは、Domaを使用したデータベースアクセスに最低限必要な手順のみを説明します。
			</p>
		</section>
		<section name="クイックスタート">
			<p>
				あらかじめ<a href="setup.html">セットアップ</a>を完了させてください。
			</p>
			<p>
				このクイックスタートでは、<a href="http://www.h2database.com/html/main.html">H2 Database Engine</a>（以下H2）にサンプルテーブルとデータを用意し、取得と更新を行います。
			</p>
			<p>
				DDL、データベースの接続情報、方言（Dialect）の実装を書き換えれば他のRDBMSでも動作します。
				（現在、サポートしているデータベースは、DB2、H2 Database Engine、HSQLDB、Microsoft SQL Server 2008、MySQL、Oracle Database、PostgreSQL、SQLiteです。）
			</p>
			<subsection name="H2 Database Engineのダウンロード">
				<p>
					H2は次のサイトからダウンロードできます。
				</p>
				<ul>
					<li><a href="http://www.h2database.com/html/main.html">http://www.h2database.com/html/main.html</a></li>
				</ul>
				<p>
					以下、All Platformsのリンクで示されるzipファイルをダウンロードするものとして説明します。
					zipファイルをダウンロードしたら解凍しbinディレクトリを開いてください。
				</p>
			</subsection>
			<subsection name="JDBCドライバの設定">
				<p>
					binディレクトリにあるjarファイルをEclipseなど開発環境のクラスパスに追加してください。
				</p>
				<p>
					通常、クラスパスが通っていれば、JDBC 4.0 ドライバはサービスプロバイダメカニズムにより自動でロードされます。
					詳細は、<a href="reference/config.html#JDBCドライバの設定">設定クラスのリファレンス</a>を参照ください。
				</p>
			</subsection>
			<subsection name="サンプルテーブルとデータの作成">
				<p>
					binディレクトリにあるh2.batもしくはh2.shを実行してください。
					ブラウザが立ち上がり、H2コンソールへのログイン画面が開きます。
				</p>
				<img src="images/h2_console_login.png" width="454" height="152" alt="H2コンソール ログイン" />
				<p>
					保存済み設定を「Generic H2 (Server)」とし接続ボタンを押してください。
					H2コンソールが開いたら、H2コンソールに以下のSQLを入力してください
				</p>
<source>create table EMPLOYEE (
  EMPLOYEE_ID integer not null primary key, 
  EMPLOYEE_NAME varchar(20), 
  HIREDATE date,
  SALARY numeric(7,2),
  VERSION_NO integer
);

insert into EMPLOYEE values(1, 'SMITH', '1980-12-17', 800, 1);
insert into EMPLOYEE values(2, 'ALLEN', '1981-02-20', 1600, 1);
insert into EMPLOYEE values(3, 'WARD', '1981-02-22', 1250, 1);</source>
				<img src="images/h2_console_setup.png" width="454" height="152" alt="H2コンソール セットアップ" />
				<p>
					実行ボタンを押すと、H2のデータベースにテーブルとデータが作成されます。
					作成されたことを確認するために、次のSQLを実行してください。
				</p>
<source>select * from EMPLOYEE</source>
				<p>
					データが存在することを確認できます。
				</p>
				<img src="images/h2_console_before.png" width="454" height="152" alt="H2コンソール データ確認" />
				<p>
					以上でサンプルテーブルとデータの作成は終わりです。
				</p>
			</subsection>
			<subsection name="エンティティクラスの作成">
				<p>
					テーブルにマッピングするエンティティクラスを作成します。
					エンティティであることを示すために@Entityを注釈します。
					@Entityのnaming要素には、テーブルやカラムの名前とエンティティクラスやプロパティの名前をマッピングするための規約を指定します。
					ここで使用するNamingType.SNAKE_UPPER_CASEは、employeeIdというプロパティ名をEMPLOYEE_IDと対応づけます。
				</p>
				<p>
					主キーには@Id、楽観的排他制御で使用するバージョン番号には@Versionを注釈します。
				</p>
				<p>
					プロパティのフィールドは、<code>public</code>にします。
				</p>
<source>package quickstart;

import java.math.BigDecimal;
import java.sql.Date;

import org.seasar.doma.Entity;
import org.seasar.doma.Id;
import org.seasar.doma.Version;
import org.seasar.doma.jdbc.entity.NamingType;

@Entity(naming = NamingType.SNAKE_UPPER_CASE)
public class Employee {

    @Id
    public Integer employeeId;

    public String employeeName;

    public Date hiredate;

    public BigDecimal salary;

    @Version
    public Integer versionNo;

}</source>
				<p>
					エンティティクラスを作成すると、メタ情報を表すクラス（この場合、_Employee）が「.apt_generated」ディレクトリに生成されます。
					「.apt_generated」はデフォルトではPackage Explorerビューに表示されないので注意してください。
					詳細は、よくある質問のページを参照してください。
				</p>
				<ul>
					<li><a href="faq.html#development-environment-6">aptで生成されたコードはどこに出力されますか？</a></li>
					<li><a href="faq.html#development-environment-7">Eclipseを使用していますが、「.apt_generated」ディレクトリが見つかりません。どうしてですか？</a></li>
				</ul>
			</subsection>
			<subsection name="設定クラスの作成">
				<p>
					データベースアクセスに関する設定情報を提供するクラスを作成します。
					ここでは、H2のデータソースと方言を利用することを示します。
				</p>
				<p>
					<code>DomaAbstractConfig</code> を継承して作成できます。
				</p>
<source>package quickstart;

import javax.sql.DataSource;

import org.seasar.doma.jdbc.DomaAbstractConfig;
import org.seasar.doma.jdbc.SimpleDataSource;
import org.seasar.doma.jdbc.dialect.Dialect;
import org.seasar.doma.jdbc.dialect.H2Dialect;
import org.seasar.doma.jdbc.tx.LocalTransaction;
import org.seasar.doma.jdbc.tx.LocalTransactionalDataSource;

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:tcp://localhost/~/test");
        dataSource.setUser("sa");
        return new LocalTransactionalDataSource(dataSource);
    }

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

}</source>
			</subsection>
			<subsection name="Daoインタフェースの作成">
				<p>
					データアクセスを行うためのData Access Object（Dao）インタフェースを作成します。
					Daoであることを示すために@Daoを注釈します。
					@Daoのconfig要素には、先ほど作成したAppConfigクラスを指定します。
				</p>
				<p>
					検索のメソッドには@Select、更新のメソッドには@Updateを注釈します。
				</p>
<source>package quickstart;

import org.seasar.doma.Dao;
import org.seasar.doma.Select;
import org.seasar.doma.Update;

@Dao(config = AppConfig.class)
public interface EmployeeDao {

    @Select
    Employee selectById(Integer employeeId);

    @Update
    int update(Employee employee);
}</source>
				<p>
					selectByIdメソッドに、対応するSQLファイルが存在しないことを示すエラーが表示されることを確認します。
				</p>
			</subsection>
			<subsection name="SQLファイルの作成">
				<p>
					まずは、selectByIdメソッドに対応するSQLを考えます。
					selectByIdメソッドで実行したいSQLは次のものです。
				</p>
<source>select * from EMPLOYEE where EMPLOYEE_ID = /* employeeId */99</source>
				<p>
					SQLコメント/* employeeId */は、DaoメソッドのemployeeIdパラメータSQLにバインディングすることを示します。
					その直後の数値である99はテスト用のデータです。
					プログラムからSQLを発行する際には使用されません。
				</p>
				<p>
					このSQLをH2コンソール上で実行しSQLの構文に誤りがないことを確認します。
				</p>
				<img src="images/h2_console_sql.png" width="454" height="152" alt="H2コンソール SQL確認" />
				<p>
					EMPLOYEE_IDが99のデータは存在しないので結果は0件ですが、SQLの構文には誤りがないことが確認できました。
				</p>
				<p>
					次に、上記のSQLを格納するSQLファイルを作成します。
					SQLファイルのパスは「META-INF/quickstart/EmployeeDao/selectById.sql」にします。
					このパスはクラスパスに通っていなければいけません。
					<a href="extension/doma_tools.html">Doma Tools</a>をインストールしていれば、
					selectByIdメソッドを右クリックして開くメニューから「Doma」 - 「Jump to SQL File」と選択することで適切な場所にファイルを作成できます。
					ファイルを作成したら、上記のSQLをファイルに記述します。
				</p>
				<p>
					SQLファイルが完成したら、<code>EmployeeDao</code>を再度ビルドしてください。
					Doma Toolsを利用している場合は、SQLファイルの保存時に自動でビルドが行われます。
					ビルドが行われるとSQLファイルの存在チェックが再度行われエラーが消えます。
				</p>
				<p>
					また、ビルドが成功すると、インタフェースと同じパッケージに<code>EmployeeDaoImpl</code>という実装クラスが自動生成されます。
					データベースアクセスは、この実装クラスをインスタンス化しておこないます。
				</p>
				<p>
					EmployeeDaoImplは「.apt_generated」ディレクトリに生成されます。
					「.apt_generated」はデフォルトではPackage Explorerビューに表示されないので注意してください。
					詳細は、よくある質問のページを参照してください。
				</p>
				<ul>
					<li><a href="faq.html#development-environment-6">aptで生成されたコードはどこに出力されますか？</a></li>
					<li><a href="faq.html#development-environment-7">Eclipseを使用していますが、「.apt_generated」ディレクトリが見つかりません。どうしてですか？</a></li>
				</ul>
			</subsection>
			<subsection name="起動クラスの作成">
				<p>
					エンティティやDaoを利用してデータベースアクセスを行います。
					次のクラスを作成してください。
				</p>
<source>package quickstart;

import java.math.BigDecimal;

import org.seasar.doma.jdbc.tx.LocalTransaction;

public class Main {

    public static void main(String[] args) {
        // トランザクションの取得
        LocalTransaction tx = AppConfig.getLocalTransaction();
        try {
            // トランザクションの開始
            tx.begin();

            // aptで生成されたDaoの実装クラスを生成
            EmployeeDao dao = new EmployeeDaoImpl();

            // 主キーでエンティティを検索
            Employee employee = dao.selectById(1);

            // エンティティのプロパティを変更
            employee.employeeName = "KING";
            employee.salary = employee.salary.add(new BigDecimal(1000));

            // エンティティを更新
            dao.update(employee);

            // トランザクションのコミット
            tx.commit();
        } finally {
            // トランザクションのロールバック
            tx.rollback();
        }
    }
}</source>
				<p>
					ここでは、従業員テーブルから1件を主キーで検索し、従業員名を更新しています。
				</p>
			</subsection>
			<subsection name="実行結果">
				<p>
					<code>Main</code>クラスを実行すると、データの更新が行われます。
					このとき、コンソールにはいくつかのログが出力されます。
					ここに例外が出力されていなければ実行は成功です。
				</p>
				<p>
					H2コンソールから次のSQLを実行し、実行結果を確認してください。
				</p>
<source>select * from EMPLOYEE</source>
				<p>
					EMPLOYEE_IDが1のレコードのEMPLOYEE_NAMEとSALARYとVERSION_NOが更新されているはずです。
				</p>
				<img src="images/h2_console_after.png" width="454" height="152" alt="H2コンソール 実行結果確認" />
			</subsection>
			<subsection name="プロジェクト構成">
				<p>
					Eclipseの場合、Package Explorer上のプロジェクト構成は最終的には次のようになります。
				</p>
				<img src="images/quick_start_project.png" width="454" height="152" alt="プロジェクト構成" />
			</subsection>
		</section>
		<section name="次へのステップ">
			<p>
				Domaが提供するより詳細な機能については<a href="tutorial/index.html">チュートリアル</a>や<a href="reference/index.html">リファレンス</a>を参照してください。
			</p>
		</section>
	</body>
</document>
