先生と生徒の会話形式で理解しよう

生徒

「Jakarta EEのプロジェクトをMavenでビルドしようとしたら、依存関係のエラーが出ました…。どうすれば直るんですか？」

先生

「それはよくある悩みですね。Jakarta EEはモジュールが多いため、依存関係の設定ミスや衝突が原因でビルドエラーが発生しやすいです。」

生徒

「初心者には難しく感じます…。何を確認すれば良いのか、順を追って教えてください！」

先生

「わかりました。今回はJakarta EEの依存トラブルの原因と、その解決方法について丁寧に解説していきましょう。」

1. Jakarta EEと依存関係の基本知識

Jakarta EEでは、サーブレット・JSP・JAX-RS・JSFなど複数の仕様をサポートするライブラリがあり、プロジェクトではそれらをビルドツール（MavenやGradle）で管理します。依存関係の記述を間違えると、クラスが見つからない、ライブラリのバージョンが衝突するといったエラーが発生します。

特に、Jakarta EE 8からJakarta EE 9への移行でjavaxパッケージがjakartaに変更されたことが、多くの依存関係トラブルの原因になっています。

2. Mavenでの依存関係トラブルと対処法

MavenでJakarta EEのプロジェクトをビルドする際によく発生するエラーには以下のようなものがあります。

依存ライブラリが解決できない
同じクラスが複数のJarに存在して競合
Jakarta EE 8と9のクラス名衝突

以下は正しい依存設定の例です（Jakarta EE 10でServlet APIを使用する場合）。


<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <version>6.0.0</version>
    <scope>provided</scope>
</dependency>

ポイントは、scopeをprovidedにすること。サーバー側（例：PayaraやWildFly）がライブラリを提供するため、重複するとエラーになります。

3. Gradleでの依存エラーの回避法

GradleではMavenと同様に依存を管理しますが、記述方法が異なります。以下はServlet APIを導入する例です。


dependencies {
    providedCompile 'jakarta.servlet:jakarta.servlet-api:6.0.0'
}

GradleではprovidedCompileのようなスコープ指定がデフォルトで存在しないため、warプラグインの導入が必要な場合もあります。


apply plugin: 'war'

Gradleでの依存解決エラーの対処には、バージョンの明記、不要な依存の排除、dependencyInsightの活用が有効です。

4. Jakarta EEの依存衝突のよくある原因

Jakarta EEでは以下のような依存トラブルが特に頻出します。

旧javaxと新jakartaの混在
重複した依存（例：jakarta.servlet-apiとjavax.servlet-apiの併用）
サーバーが提供するライブラリをローカルでも指定している
Transitive Dependencies（間接的な依存）によるバージョン競合

このような問題を避けるには、以下のチェックが有効です。

mvn dependency:tree や gradle dependencies で依存構成を確認
Jakarta EEのバージョンを統一して管理する（Bill of Materialsの活用）

5. Jakarta EEにおけるBOM（Bill of Materials）の活用

Jakarta EEの各ライブラリは個別にバージョン管理されていますが、それを一元化するのがBOMです。以下はMavenの例です。


<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>jakarta.platform</groupId>
      <artifactId>jakarta.jakartaee-bom</artifactId>
      <version>10.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

この設定により、他のJakarta EEモジュールを個別にバージョン指定せずに利用できます。

6. Jakarta EEの依存解決エラーの実例とデバッグ手順

例えば、以下のようなエラーが表示されたとします。


java.lang.ClassNotFoundException: jakarta.servlet.http.HttpServlet

この場合は、Servlet APIの依存が設定されていない、あるいはprovidedスコープを忘れてruntimeなどにしてしまったことが原因です。

また、エラー文中に「javax.servlet」と出ているなら、古い依存が混入している可能性もあります。dependency:treeで親ライブラリからの伝播を確認しましょう。

7. Jakarta EEと依存の相性をよくする設計のポイント

Jakarta EEのプロジェクトでは、以下のような設計の工夫も重要です。

Jakarta EEのバージョンをプロジェクト開始時に明確にする
依存の追加時には毎回dependency:treeで構成を確認する
IDEのビルドキャッシュやローカルリポジトリを定期的にクリアする
サーバー（Payara, WildFly）と依存ライブラリの対応表を確認する

特に初心者は、手動でライブラリを追加せず、スターターの雛形を活用するのがおすすめです。

Jakarta EEと依存解決のトラブル対処法｜Maven・Gradleでのエラーを完全攻略