チュートリアル

チュートリアルは、JUnitを使用したコンソール形式のアプリケーションです。

このページでは、チュートリアルのセットアップ方法と構成について説明します。

チュートリアルのプロジェクトをダウンロードし、環境を整えます。 JavaやEclipseのインストールがまだ完了していない場合は、先にそれらのセットアップを済ませてください。

バージョン6以上のJDKをインストールします。 JREではなくJDKが必要であることに注意してください。 JDK 6 は以下のURLのサイトからダウンロードできます。

http://www.oracle.com/technetwork/java/javase/downloads/index.html

バージョン3.5以上のEclipseをインストールします。 Pluggable Annotation Processing API をサポートしていれば、Eclipse以外のIDEであってもかまいませんが、 このドキュメントではEclipseを使うことを前提に説明を進めます。 Eclipseは以下のURLのサイトからダウンロードできます。

http://www.eclipse.org/downloads/

Eclipseは、バージョン6以上のJDKに含まれるJREで起動されるようにしてください。 明示的にJREを指定するには、-vm オプションを使用します。 

-vm %JAVA_HOME%\bin\javaw.exe

ダウンロードのページからdoma-tutorial-x.x.x.zipをダウンロードし、 Eclipseへインポートしてください。インポートの具体的な手順は次のとおりです。2つの方法を説明します。

通常の方法

  • Eclipseのメニューから「File」 - 「Import」を選択します。
  • 「Existing Projects to Workspace」を選択し、「Next」ボタンを押します。
  • 「Select archive file」のラジオボタンをチェックし、ダウンロードしたdoma-tutorial-x.x.x.zipを選択します。
  • 「Projects」の項目に表示される「doma-tutorial」のチェックボックスをチェックし、「Finish」ボタンを押します。

インポートが完了したら、doma-tutorialプロジェクトを右クリックし、コンテキストメニューから「Run As」 - 「JUnit Test」 を実行してください。 すべてのテストが成功したらセットアップが正しく完了しています。

m2eclipseを使ってMaven Projectとしてインポートする方法

  • doma-tutorial-x.x.x.zipを解凍します。
  • Eclipseのメニューから「File」 - 「Import」を選択します。
  • 「Existing Maven Projects」を選択し、「Next」ボタンを押します。
  • Root Directoryの入力欄にdoma-tutorial-x.x.x.zipを解凍したディレクトリを指定します。
  • 「Projects」の項目に表示されるpom.xmlのチェックボックスをチェックし、「Finish」ボタンを押します。
  • インポートが完了した時点ではビルドエラーが発生します。
  • エラーを解消するために、プロジェクトのプロパティからJavaのビルドパスのダイアログを開きます。
  • Javaのビルドパスのダイアログでは、src/main/resourcesとsrc/test/resourcesのソースフォルダの「Exclude:**/*」となっている項目を選択して「Remove」を押します（「Exclude:(None)」に変わります）。
  • また、同じJavaのビルドパスのダイアログで「Add Folder...」を押し、プロジェクト直下の.apt_generatedをソースフォルダとして登録します。

以上の手順を実行し終えるとビルドエラーは解消されます。 最後に、doma-tutorialプロジェクトを右クリックし、コンテキストメニューから「Run As」 - 「JUnit Test」 を実行してください。 すべてのテストが成功したらセットアップが正しく完了しています。

Doma Toolsをインストールします。

Doma Toolsは、以下の更新サイトからインストールできます。

チュートリアルの構成を説明します。

プロジェクトのフォルダ構成は以下の通りです。主要なものを中心に説明します。

フォルダ 説明
src/main/java 設定クラス、Daoインタフェース、エンティティクラス等のソースフォルダです。
src/main/resources SQLファイル等のソースフォルダです。 SQLファイルは、Domaの規約に則ってMETA-INFフォルダ以下に配置されます。 また、JDBCドライバのプロバイダ構成ファイルがMETA-INF/servicesフォルダ以下にjava.sql.Driverという名前で配置されます。
src/test/java Daoを利用するコードのためのソースフォルダです。 Daoを利用するコードはすべてJUnitのテストクラスとして記述されています。
src/test/resources 使用していません。
.apt_generated apt（Annotation Processing Tool）によって生成されたコードを格納するソースフォルダです。 Package Explorerビューでは、フィルタリングされるため表示されません（フィルタリングは解除可能です）。 Nivigatorビューで確認できます。
lib このチュートリアルで利用するjarファイルを格納するフォルダです。 JUnit、H2、Domaのjarが格納されます。 これらのjarはすべてビルドパスに通っていなければいけません。
libsrc このチュートリアルで利用するjarファイルのソースコードを格納するフォルダです。

プロジェクト直下には次のファイルがあります。主要なものを説明します。

ファイル 説明
build.xml チュートリアルプロジェクトをAntでビルドするためのビルドファイルです。 詳しくは、Antによるビルドを参照してください。
pom.xml チュートリアルプロジェクトをMavenでビルドするためのプロジェクト記述ファイルです。 詳しくは、Mavenによるビルドを参照してください。

このチュートリアルでは、データベースにH2 Database Engineを利用します。

使用するスキーマの定義は次のとおりです。 1つのシーケンスと2つのテーブルを使用します。

H2はin-memoryモードで起動し、テスト用のスキーマとデータは各テストの実行前に作成し、テスト終了後に破棄します。 スキーマとデータの作成と破棄は、共通のテストクラスで行っています。 Javaのコードは、src/test/java/tutorial/TutorialTestCase.javaになります。

H2のJDBCドライバを登録するためのプロバイダ構成ファイルがsrc/main/resources/META-INF/servicesに必要です。 ファイルの名称はjava.sql.Driverで、中身は次のように記述されます。

プロバイダ構成ファイルの詳細については、JAR ファイルの仕様 を参照してください。

チュートリアル中の主要なクラスについて説明します。

設定クラス

設定クラスとは、Domaに関する各種設定を持つクラスです。 このチュートリアルで使用する設定クラスのソースコードは、src/main/java/tutorial/AppConfig.javaになります。

このクラスでは、H2のデータソースの作成とH2の方言の設定を行っています。 それ以外の設定については親クラスのDomaAbstractConfigのものを利用しています。 設定クラスはDaoインタフェースから利用されます。

エンティティクラス

エンティティクラスとは、テーブルやSQLの結果セットにマッピングされたクラスです。 エンティティクラスは、@Entityを注釈して示します。 このチュートリアルで使用するエンティティクラスのソースコードは、 src/main/java/tutorial/entity/Employee.java と src/main/java/tutorial/entity/EmployeeDepartment.java になります。

Employeeクラスは、EMPLOYEEテーブルに対応します。

識別子（テーブルの主キー）には@Idを注釈します。 識別子を自動生成する場合は、さらに@GeneratedValueを注釈し、自動生成の方法を示します。 ここではEMPLOYEE_SEQシーケンスを使って採番することを示しています。

プロパティ名がマッピングするカラム名と異なる場合は@Columnのname要素を使って示します。

更新や削除時の楽観的排他制御に使用するカラムとマッピングされたプロパティには@Versionを注釈します。

@Entityのlistener要素にはEmployeeListenerクラスを指定しています。

EmployeeDepartmentクラスは、EMPLOYEEテーブルとDEPARTMENTテーブルを結合した結果セットに対応します。

このクラスは、Employeeクラスを継承し、DEPARTMENTテーブルのNAMEカラムに対応するプロパティを持ちます。 @Columnのname要素に指定されている「DEPARTMENT_NAME」はSQL上でDEPARTMENTテーブルのNAMEカラムの別名になります。

エンティティリスナークラス

エンティティリスナークラスのインスタンスは、エンティティがデータベースに挿入、更新、削除される前後に呼び出されます。 このチュートリアルで使用するエンティティリスナークラスはEmployeeListenerです。 ソースコードは、src/main/java/tutorial/entity/EmployeeListener.javaになります。

{ @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) { } }]]>

ドメインクラス

ドメインクラスは、データベースのカラムにマッピング可能なアプリケーション固有の値型です。 ドメインクラスは@Domainを注釈して示します。 このチュートリアルで使用するドメインクラスは、給料を表すSalaryクラスです。 ソースコードは、src/main/java/tutorial/domain/Salary.javaになります。

Daoインタフェース

Daoインタフェースとは、データベースアクセスの境界となるインタフェースです。 Daoインタフェースは@Daoを注釈して示します。 @Daoのconfig要素には設定クラスであるAppConfigクラスを指定します。 このチュートリアルで使用するDaoインタフェースのソースコードは、src/main/java/tutorial/dao/EmployeeDao.javaになります。

Daoインタフェースの実装クラスはDomaにより自動生成されます。

すべてのメソッドは、@Selectや@Updateなど問い合わせの種別を示すアノテーションが注釈されなければいけません。

selectByAgeRange(Integer min, Integer max); @Select List selectByAges(List ages); @Select List selectByNames(List 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); ... }]]>

SQLファイルは、src/main/resources/META-INF/tutorial/EmployeeDaoフォルダ以下に配置されます。 フォルダの名前はDaoインタフェースと対応づけられます。

SQLファイルは、名前から拡張子を除いたものがDaoインタフェースのメソッドに一致します。 たとえば、selectById.sqlはDaoインタフェースのselectByIdメソッドに対応します。 selectById.sqlの中身は次のようなテキストです。

Eclipseの場合、src/test/java/tutorial以下のJavaファイルを開き、メニューから「Run」 - 「Run as」 - 「JUnit Test」を選択します。