はじめよう
このページについて
このガイドでは、開発環境の設定の概要と基本的な機能を紹介します。
JDKのインストール
このガイドを実行するには JDK 17 が必要です。
注釈
DomaはJDK 8以降と互換性があります。サポートされているJDKのバージョンについては、該当するセクションを参照してください。DomaはどのバージョンのJDKをサポートしていますか?。
サンプルプロジェクトの入手
サンプルプロジェクトを入手するには、次のコマンドを使用して、getting-started リポジトリのクローンを作成し、新しいディレクトリに移動します。
$ git clone https://github.com/domaframework/getting-started.git
$ cd getting-started
次のコマンドが成功すれば、プロジェクトのセットアップは完了です。
$ ./gradlew build
注釈
Windowsユーザーは、./gradlew build
の代わりに gradlew build
を実行してください。
サンプルプロジェクトの構造
このガイドで扱うサンプルプロジェクトは、java-8 プロジェクトと java-17 プロジェクトから構成される Gradle のマルチプロジェクトです。2つのプロジェクトは似ていますが、 SQL ステートメントがどのように格納されるかに違いがあります。SQL ステートメントは、Java-8 ではファイルに、Java-17 ではテキストブロックの文字列に格納されます。
このガイドでは、java-17 プロジェクトに焦点を当てて説明を行います。
プロジェクトを IDE にインポートする
Eclipse
Eclipse 4.23.0でテストされています。./gradlew eclipse
を使用してEclipseプロジェクトファイルを生成し、java-8およびjava-17プロジェクトをワークスペースにインポートしてください。なお、その際、Gradleのプロジェクトとしてインポートするのではなく通常のプロジェクトとしてインポートしてください。
注釈
SQL文をファイルで管理する場合、Doma Tools が役立つかもしれません。
IntelliJ IDEA
IntelliJ IDEA Community 2023.3.4 でテストされています。プロジェクトを Gradle プロジェクトとしてインポートしてください。
注釈
IntelliJ IDEA Ultimate Edition を使用している場合、Doma Support が役立つかもしれません。
プログラミングスタイル
Doma は、DSL と DAO という 2 つのプログラミング スタイルをサポートしています。
DSL スタイルは、タイプ セーフな SQL ステートメントを構築するために Criteria API を利用します。Criteria API は、リフレクションを使わない、さまざまなタイプの関連付け (1 対多、多対 1、1 対 1) をサポートする、などいくつかの利点があります。
一方、DAO スタイルは、SQL ステートメントを Java インターフェイスのメソッドにマップします。こちらは、SQLの特長を最大限に活かす方法と言えます。
アプリケーションの特性に応じてスタイルを選択することをお勧めします。2つのスタイルは混在させることもできます。
DSL スタイル
DSL スタイルでは、 boilerplate.java17.repository.EmployeeRepository
と Criteria API の例を使用します。
SELECT
SELECT ステートメントを実行して Java オブジェクトの結果を取得するには、次の例に従います。
public Employee selectById(Integer id) {
var e = new Employee_();
return entityql.from(e).where(c -> c.eq(e.id, id)).fetchOne();
}
クエリを組み立てるために Employee
エンティティクラスのメタモデルクラスである Employee_
を使用します。メタモデルクラスは、アノテーション処理を通じて自動生成されるクラスです。
Entityql
クラスの entityql
インスタンスは、Criteria API の開始点として機能します。
上記のコードは次の SQL ステートメントを生成します。
select t0_.id, t0_.name, t0_.age, t0_.version from Employee t0_ where t0_.id = ?
DELETE
DELETE ステートメントを発行するには、次のように記述します。
public void delete(Employee employee) {
var e = new Employee_();
entityql.delete(e, employee).execute();
}
INSERT
INSERT ステートメントを発行するには、次のように記述します。
public void insert(Employee employee) {
var e = new Employee_();
entityql.insert(e, employee).execute();
}
UPDATE
UPDATE ステートメントを発行するには、次のように記述します。
public void update(Employee employee) {
var e = new Employee_();
entityql.update(e, employee).execute();
}
DAO スタイル
いくつかの例は boilerplate.java17.dao.EmployeeDao
にあります。詳細については、DAOインタフェース および SQLテンプレート を参照してください。
SELECT (DAO)
DAO スタイルで SELECT ステートメントを発行して Java オブジェクトを取得するには、SQL テンプレートのテキストブロックで @Sql
アノテーションを使用します。
@Sql("""
select
/*%expand*/*
from
employee
where
id = /* id */0
""")
@Select
Employee selectById(Integer id);
このSQLテンプレートには、/*%expand*/
と /* id */
の二つの特別な表現が含まれています。SQLテンプレートの処理中に、/*%expand*/
とその後の *
はカラムリストに置き換えられます。そして、/* id */
とその後の 0
はバインド変数 ?
に置き換えられます。バインドされる値は selectById
メソッドの id
パラメータです。
上記のコードは次の SQL ステートメントを生成します。
select
id, name, age, version
from
employee
where
id = ?
DELETE (DAO)
DELETE ステートメントを発行するには、次のように記述します。
@Delete
int delete(Employee employee);
INSERT (DAO)
INSERT ステートメントを発行するには、次のように記述します。
@Insert
int insert(Employee employee);
UPDATE (DAO)
UPDATE ステートメントを発行するには、次のように記述します。
@Update
int update(Employee employee);
次のステップ
他のサンプルプロジェクトを参照してください。