はじめに (対象読者・この記事でわかること)

この記事は、JavaでDomaを利用したデータアクセス層の実装に取り組んでいるエンジニア、特に初心者から中級者を対象としています。DomaのImplクラスを生成・実装する際に出くわす「SQL文が見つからない」「コンパイルエラー」「Springとの連携エラー」など、代表的な例外や警告メッセージの意味と対処法を体系的に解説します。この記事を読むことで、エラーメッセージの読み解き方から、設定ファイルの見直し、コードの修正方法までを具体的に学び、Domaプロジェクトをスムーズに進められるようになるでしょう。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。 - Javaの基本的な文法とビルドツール（Maven/Gradle）の操作 - Domaの概要とアノテーション（@Dao, @Select, @Insert など）の意味 - Spring Framework（特にSpring Boot）でのDI概念

Doma Implでよく見られるエラーの概要

Domaはコンパイル時にSQLを検証し、Implクラスを自動生成する仕組みを持っています。そのため、設定ミスやSQLの書き方、クラスパスの問題が直接コンパイルエラーとして現れることがあります。代表的なエラーは次の通りです。

  1. @Daoインタフェースに対する実装クラスが生成されない
    - 原因: doma.compile が有効になっていない、または doma のアノテーションプロセッサがビルドパスに含まれていない。
  2. SQLファイルが見つからない (SQL file not found)
    - 原因: SQLファイルの配置場所が resources 以下の規約に合っていない、またはファイル名に誤りがある。
  3. パラメータ型が合わない (parameter type mismatch)
    - 原因: メソッド引数の型とSQLファイル内のプレースホルダーの型が一致していない。
  4. Springとの統合時に NoSuchBeanDefinitionException が発生
    - 原因: @Dao インタフェースが Spring のコンテナに登録されていない、または @Repository が付与されていない。

これらのエラーは、開発初期に「なぜコンパイルが通らないのか？」と戸惑うことが多いですが、原因を特定すれば数行の設定変更で解決できることがほとんどです。以下では、実際に遭遇したケースを元に、段階的な解決手順を示します。

具体的な手順と実装例

ステップ1：ビルド環境の整備

まずは Doma のアノテーションプロセッサが正しく有効化されているか確認します。Maven を例にすると pom.xml に次の依存関係とプラグイン設定が必要です。

Xml

<dependency>
    <groupId>org.seasar.doma</groupId>
    <artifactId>doma</artifactId>
    <version>2.53.0</version>
</dependency>
<dependency>
    <groupId>org.seasar.doma</groupId>
    <artifactId>doma-slf4j</artifactId>
    <version>2.53.0</version>
</dependency>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.11.0</version>
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.seasar.doma</groupId>
                        <artifactId>doma</artifactId>
                        <version>2.53.0</version>
                    </path>
                </annotationProcessorPaths>
                <parameters>true</parameters>
            </configuration>
        </plugin>
    </plugins>
</build>

Gradleの場合は次のように記述します。

Gradle

plugins {
    id 'java'
}

dependencies {
    implementation 'org.seasar.doma:doma:2.53.0'
    implementation 'org.seasar.doma:doma-slf4j:2.53.0'
    annotationProcessor 'org.seasar.doma:doma:2.53.0'
}

ポイント
- annotationProcessor（Maven では annotationProcessorPaths）が欠落すると Impl クラスが生成されず、cannot find symbol エラーになる。
- -parameters オプションはリフレクションで引数名を取得できるようにするため必須です。

ステップ2：SQL ファイルの配置と命名規則

Doma はデフォルトで resources 配下に META-INF フォルダを作り、その中に DAO の完全修飾クラス名と同名の .sql ファイルを配置します。例として com.example.dao.EmployeeDao の selectAll メソッドがある場合、SQLファイルは次のようになります。

src/main/resources/META-INF/com/example/dao/EmployeeDao/selectAll.sql

SQL の内容例:

Sql

SELECT employee_id, name, department
FROM employee
ORDER BY employee_id

よくあるミス
- パスに余計なディレクトリが入っている（例: resources/sql/...）
- ファイル名が selectAll.sql ではなく SelectAll.sql など大文字小文字が一致しない（Windows では問題になりにくいが、Linux 環境では致命的）。

ステップ3：メソッドシグネチャとパラメータ型の合わせ込み

SQL ファイル内のバインド変数は /*# param */ で記述します。Java 側のメソッド引数の名前と型は、SQL 側と完全に一致させる必要があります。

Java

@Select
List<Employee> selectByDept(@Param("deptId") int deptId);

対応する SQL:

Sql

SELECT employee_id, name, department
FROM employee
WHERE department_id = /*# deptId */

エラー例
parameter type mismatch が出た場合、以下を確認してください。

  1. @Param の名前が正しいか。
  2. 引数の型（int, Integer, long, Long, String 等）がSQL側の期待型と合っているか。
  3. java.time 系の型を使う場合は Doma が提供する LocalDate などの変換が必要。

ハマった点やエラー解決

1. Impl クラスが生成されない（cannot find symbol）

症状
EmployeeDaoImpl が見つからず、コンパイルエラーになる。

原因
Maven の maven-compiler-plugin で annotationProcessorPaths が正しく設定されていない、または clean 後に target ディレクトリが残っている。

解決策
- pom.xml に上記の annotationProcessorPaths を追加。
- mvn clean compile を実行し、生成ログに Doma annotation processor が表示されることを確認。

2. SQL file not found エラー

症状
org.seasar.doma.DomaNullPointerException: SQL file not found: META-INF/com/example/dao/EmployeeDao/selectAll.sql

原因
SQL ファイルのパスが規約に合っていない、または resources がビルドに含まれていない。

解決策
- src/main/resources/META-INF/com/example/dao/EmployeeDao/selectAll.sql が正しい場所にあるか確認。
- pom.xml の <resources> 設定がデフォルトで src/main/resources を含んでいるかチェック。
- IntelliJ 等の IDE でリソースフォルダが Resources Root として認識されているか確認。

3. Spring Boot で Bean が取得できない

症状
org.springframework.beans.factory.NoSuchBeanDefinitionException: No qualifying bean of type 'com.example.dao.EmployeeDao' available

原因
@Dao インタフェースに @Repository が付与されていない、もしくは @ComponentScan の対象外。

解決策 

Java

@Dao
@Repository
public interface EmployeeDao {
    // ...
}

または、@EnableDomaRepositories（※Doma が提供するアノテーションは無いが、カスタム設定で対応）を利用し、@Configuration で Dao インタフェースを Bean として登録する。

解決策まとめ

エラー 主な原因 解決のポイント
Impl が生成されない アノテーションプロセッサ未設定 annotationProcessor を追加し clean compile
SQL ファイルが見つからない パス・命名規則違反 META-INF/<package>/<Dao>/<method>.sql を遵守
パラメータ型不一致 @Param 名・型の相違 メソッド引数と SQL のバインド変数を一致
Spring で Bean が無い @Repository 未付与 or スキャン外 @Repository を付与、または明示的に Bean 定義

まとめ

本記事では、Java の ORM フレームワーク Doma における Impl クラス生成時に頻出するエラーを、原因別に整理し、具体的な設定例・コード例を交えて解決手順を提示しました。

  • ビルド環境：アノテーションプロセッサの正しい設定が最重要
  • SQL 配置：規約通りのパスとファイル名でリソースを管理
  • 型合わせ：メソッドシグネチャと SQL バインド変数の整合性を保つ
  • Spring 連携：@Repository で Bean 登録を忘れずに

これらを実践すれば、Doma を使ったデータアクセス層の開発がスムーズになり、エラー解決に費やす時間を大幅に削減できます。次回は Doma の高度な機能（SQL ファイルのインクルードやカスタム型ハンドラ）について掘り下げる予定です。

参考資料