はじめよう

このページについて

このガイドでは、開発環境の設定の概要と基本的な機能を紹介します。

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.EmployeeRepositoryCriteria 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);

次のステップ

他のサンプルプロジェクトを参照してください。