第二戒: 入信の儀 〜 神殿を建立せよ

「まず Maven の呪文を唱えよ。さすれば神殿の礎が築かれるであろう」 ーー Wicket 聖典 第二戒より

Apache Wicket 10 の開発環境をゼロから構築する手順を解説します。Maven アーキタイプを使えば、わずか数分で動作するプロジェクトのひな型が手に入ります。本章では、JDK の確認からプロジェクト作成、Eclipse へのインポート、そしてアプリケーションの起動確認までを順を追って説明します。

前提条件

Wicket 10 で開発を始めるにあたり、以下のソフトウェアが必要です。まだインストールしていない場合は、先に準備してください。

ソフトウェア 必須バージョン 備考
JDK 17 以上 Eclipse Temurin、Oracle JDK、Amazon Corretto など任意のディストリビューション。LTS バージョン(17 または 21)を推奨。
Apache Maven 3.8 以上 3.9.x を推奨。Gradle は公式にはサポートされていません。
Eclipse IDE 2023-03 以降 Eclipse IDE for Enterprise Java and Web Developers を推奨。IntelliJ IDEA でも可。

javax から jakarta への移行に注意

Wicket 10 は Jakarta EE 9+ に完全移行しています。従来の javax.servlet パッケージは jakarta.servlet に変更されました。Wicket 9.x 以前のコードをそのまま使うとコンパイルエラーになります。

JDK 自体にはこの変更は影響しませんが、使用する IDE やアプリケーションサーバーが Jakarta EE に対応しているか確認してください。Eclipse の場合、2023-03 以降のバージョンであれば Jakarta EE 9/10 をサポートしています。

JDK のインストール確認

まず、JDK が正しくインストールされているか確認しましょう。ターミナル(コマンドプロンプト)を開いて以下のコマンドを実行します。

JDK バージョンの確認
$ java -version
openjdk version "21.0.2" 2024-01-16
OpenJDK Runtime Environment Temurin-21.0.2+13 (build 21.0.2+13)
OpenJDK 64-Bit Server VM Temurin-21.0.2+13 (build 21.0.2+13, mixed mode, sharing)

バージョン番号が 17 以上であることを確認してください。コマンドが見つからない場合は、JAVA_HOME 環境変数と PATH の設定を見直しましょう。

Maven バージョンの確認
$ mvn -version
Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3cd08dcc295161ae)
Maven home: /opt/maven
Java version: 21.0.2, vendor: Eclipse Adoptium
Default locale: ja_JP, platform encoding: UTF-8
OS name: "linux", version: "6.5.0", arch: "amd64", family: "unix"

Maven のバージョンが 3.8 以上であること、そして Maven が使用している Java のバージョンが 17 以上であることを合わせて確認してください。

JAVA_HOME の設定

Maven が参照する JDK は JAVA_HOME 環境変数で決まります。複数の JDK をインストールしている場合は、JAVA_HOME が正しい JDK を指しているか確認しましょう。

Maven でプロジェクトを作成

Wicket プロジェクトを手動で構成するのは手間がかかりますが、公式の Maven アーキタイプを使えば、必要なファイルがすべて揃った状態のプロジェクトを一発で生成できます。

アーキタイプコマンド

任意のディレクトリで以下のコマンドを実行してください。

Wicket クイックスタートプロジェクトの生成
mvn archetype:generate \
  -DarchetypeGroupId=org.apache.wicket \
  -DarchetypeArtifactId=wicket-archetype-quickstart \
  -DarchetypeVersion=10.8.0 \
  -DgroupId=com.example \
  -DartifactId=mywicketapp \
  -DinteractiveMode=false

Windows の場合

Windows のコマンドプロンプトでは、行末の \(バックスラッシュ)を ^(キャレット)に置き換えるか、すべてを1行にまとめて実行してください。PowerShell の場合はバッククォート ` を使います。

パラメータの解説

パラメータ 説明
archetypeGroupId org.apache.wicket Wicket 公式のアーキタイプが属するグループ ID。
archetypeArtifactId wicket-archetype-quickstart クイックスタート用のアーキタイプ。最小限の構成でプロジェクトを生成します。
archetypeVersion 10.8.0 使用する Wicket のバージョン。最新の安定版を指定してください。
groupId com.example 生成するプロジェクトのグループ ID。自社のドメインを逆にしたものを使います。
artifactId mywicketapp 生成するプロジェクトのアーティファクト ID。プロジェクト名として使われます。
interactiveMode false 対話モードを無効にし、すべての値をコマンドラインで指定します。

生成されるプロジェクト構成

コマンドの実行が成功すると、以下のようなディレクトリ構造が生成されます。

プロジェクト構成
mywicketapp/
├── pom.xml
└── src/
    ├── main/
    │   ├── java/com/example/
    │   │   ├── WicketApplication.java
    │   │   └── HomePage.java
    │   ├── resources/com/example/
    │   │   └── HomePage.html
    │   └── webapp/WEB-INF/web.xml
    └── test/java/com/example/
        └── TestHomePage.java

各ファイルの役割を確認しておきましょう。

ファイル 役割
pom.xml Maven プロジェクトの設定ファイル。Wicket の依存関係やビルド設定が記述されています。
WicketApplication.java アプリケーションのエントリポイント。WebApplication を継承し、ホームページの設定などを行います。
HomePage.java ホームページの Java クラス。画面のロジック(コンポーネントの配置やイベント処理)を記述します。
HomePage.html ホームページの HTML テンプレート。Java クラスと同じパッケージ内に配置するのが Wicket のルールです。
web.xml サーブレットの設定ファイル。Wicket のフィルタを登録しています。
TestHomePage.java ホームページのユニットテスト。WicketTester を使った画面テストのサンプルです。

HTML とJava クラスの配置ルール

Wicket では、HTML テンプレートファイルを対応する Java クラスと同じパッケージに配置する必要があります。HomePage.javacom.example パッケージにある場合、HomePage.htmlsrc/main/resources/com/example/ ディレクトリに置きます。このルールを守らないと、実行時に MarkupNotFoundException が発生します。

pom.xml の解説

生成された pom.xml には、Wicket アプリケーションの開発に必要な設定がすべて含まれています。ここでは特に重要な部分を抜粋して解説します。

主要な依存関係

Wicket のコアライブラリは以下のように定義されています。

pom.xml - Wicket コア依存関係
<properties>
    <wicket.version>10.8.0</wicket.version>
    <jetty.version>12.0.7</jetty.version>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
</properties>

<dependencies>
    <!-- Wicket コアライブラリ -->
    <dependency>
        <groupId>org.apache.wicket</groupId>
        <artifactId>wicket-core</artifactId>
        <version>${wicket.version}</version>
    </dependency>

    <!-- SLF4J ログ実装 -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-simple</artifactId>
        <version>2.0.12</version>
    </dependency>
</dependencies>

wicket-core が Wicket の中心となるモジュールです。Wicket 10 では内部的に jakarta.servlet API に依存しているため、javax.servlet 系のライブラリとの混在には注意が必要です。

Jetty プラグイン

開発時にアプリケーションを簡単に起動するために、Jetty Maven プラグインが設定されています。

pom.xml - Jetty Maven プラグイン
<build>
    <plugins>
        <plugin>
            <groupId>org.eclipse.jetty.ee10</groupId>
            <artifactId>jetty-ee10-maven-plugin</artifactId>
            <version>${jetty.version}</version>
            <configuration>
                <webApp>
                    <contextPath>/</contextPath>
                </webApp>
                <httpConnector>
                    <port>8080</port>
                </httpConnector>
            </configuration>
        </plugin>
    </plugins>
</build>

Jetty 12 と EE10 名前空間

Wicket 10 は Jakarta EE 10 に準拠しているため、Jetty プラグインも jetty-ee10-maven-plugin を使用します。従来の jetty-maven-plugin を指定すると正しく動作しない場合があるので注意してください。Jetty 12 からは EE バージョンごとにモジュールが分かれています。

テスト依存関係

Wicket 10 では、テスト用のユーティリティ WicketTester独立したモジュールとして提供されるようになりました。これは Wicket 9.x からの重要な変更点です。

pom.xml - テスト用依存関係
<!-- Wicket テストユーティリティ(10.x で独立モジュール化) -->
<dependency>
    <groupId>org.apache.wicket</groupId>
    <artifactId>wicket-tester</artifactId>
    <version>${wicket.version}</version>
    <scope>test</scope>
</dependency>

<!-- JUnit 5 -->
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-api</artifactId>
    <version>5.10.2</version>
    <scope>test</scope>
</dependency>

wicket-tester の独立化について

Wicket 9.x 以前では WicketTesterwicket-core に含まれていましたが、Wicket 10 では wicket-tester として独立モジュールになりました。テストを書く際には、この依存関係を pom.xml に明示的に追加する必要があります。これにより、本番環境のデプロイサイズが削減されるメリットがあります。

Eclipse へのインポート

Maven で生成したプロジェクトを Eclipse にインポートします。Eclipse には Maven 連携プラグイン(m2e)が標準で搭載されているため、追加のプラグインは不要です。

インポート手順

  1. Eclipse を起動し、ワークスペースを選択します。
  2. メニューから File > Import... を選択します。
  3. インポートウィザードで Maven > Existing Maven Projects を選択し、Next をクリックします。
  4. Root DirectoryBrowse... ボタンをクリックし、先ほど生成した mywicketapp ディレクトリを選択します。
  5. Projects 欄に pom.xml が表示されていることを確認し、チェックが入った状態で Finish をクリックします。
  6. Eclipse がプロジェクトを読み込み、Maven の依存関係を自動的にダウンロードします。右下のプログレスバーが完了するまで待ちましょう。初回はダウンロードに数分かかる場合があります。

インポートが完了すると、Package Explorer にプロジェクトが表示されます。src/main/java 配下に WicketApplication.javaHomePage.java があることを確認してください。

トラブルシューティング

Jakarta EE 関連のエラーが出る場合

Eclipse のバージョンが古い場合、jakarta.servlet パッケージが解決できずエラーが表示されることがあります。以下を確認してください。

  • Eclipse のバージョン: 2023-03 以降であることを確認
  • JRE の設定: Window > Preferences > Java > Installed JREs で JDK 17 以上が設定されているか確認
  • プロジェクトの更新: プロジェクトを右クリック > Maven > Update Project... を実行
  • コンパイラ準拠レベル: プロジェクトの Properties > Java Compiler で Compiler compliance level が 17 以上になっているか確認

m2e コネクタの問題

pom.xml にエラーマーカーが表示され「Plugin execution not covered by lifecycle configuration」というメッセージが出る場合は、Eclipse の m2e プラグインが一部の Maven プラグインを認識できていません。エラー箇所にカーソルを置き、Quick Fix から "Mark goal as ignored in Eclipse build" を選択するか、m2e の設定ファイル(.settings/org.eclipse.m2e.core.prefs)で除外設定を行ってください。

アプリケーションの起動

プロジェクトの準備ができたら、実際にアプリケーションを起動してみましょう。起動方法はコマンドラインと Eclipse の2つがあります。

コマンドラインから起動

プロジェクトのルートディレクトリで以下のコマンドを実行します。

Jetty で起動
$ cd mywicketapp
$ mvn jetty:run

初回起動時は依存関係のダウンロードに時間がかかりますが、以下のようなログが表示されれば起動成功です。

起動成功時のログ出力
[INFO] Started oeje10s.ServletContextHandler@xxxxxxxx{/,file:///...mywicketapp/src/main/webapp/,AVAILABLE}
[INFO] Started ServerConnector@xxxxxxxx{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}
[INFO] Started Server@xxxxxxxx{STARTING}[12.0.7,sto=0] @xxxxxms

ブラウザで http://localhost:8080 にアクセスしてください。停止するには、ターミナルで Ctrl+C を押します。

Eclipse から起動

クイックスタートプロジェクトには、組み込み Jetty サーバーを起動するための Start.java クラスが含まれています。Eclipse から直接起動する手順は以下のとおりです。

  1. Package Explorer で src/test/java 配下にある Start.java を見つけます。
  2. Start.java を右クリックし、Run As > Java Application を選択します。
  3. Console ビューにログが出力され、サーバーが起動します。
  4. ブラウザで http://localhost:8080 にアクセスします。

Run Configuration の作成

毎回右クリックメニューから起動するのが面倒な場合は、Run Configuration を作成しておくと便利です。

  1. Run > Run Configurations... を開く
  2. 左側の Java Application を右クリックして New Configuration を選択
  3. Name に「Wicket Start」など分かりやすい名前を付ける
  4. Projectmywicketapp を指定
  5. Main classcom.example.Start を指定
  6. Apply > Run で起動

次回以降はツールバーの実行ボタンからワンクリックで起動できます。

ホットリロードについて

Wicket は開発モードで起動すると、HTML テンプレートの変更を自動的に検出して反映します。Java コードの変更には再起動が必要ですが、HTML やプロパティファイルの修正はブラウザをリロードするだけで確認できるため、開発効率が良くなります。開発モードは WicketApplication クラスの getConfigurationType() メソッドで RuntimeConfigurationType.DEVELOPMENT を返すことで有効になります(クイックスタートではデフォルトで有効です)。

動作確認

アプリケーションが正常に起動したら、ブラウザで http://localhost:8080 にアクセスします。

以下のような Wicket クイックスタートのデフォルトページが表示されれば、環境構築は成功です。

期待される表示内容
Congratulations!

If you see this message, it means that your Apache Wicket
quickstart application is running successfully.

You can now start building your application.

このページは HomePage.javaHomePage.html によって生成されています。試しに HomePage.html を編集して、ブラウザをリロードしてみてください。変更が即座に反映されるのを確認できるはずです。

ページが表示されない場合

  • ポート競合: 他のアプリケーションが 8080 ポートを使用していないか確認してください。netstat -an | grep 8080lsof -i :8080 で調べられます。
  • ファイアウォール: ローカルのファイアウォールがポート 8080 をブロックしていないか確認してください。
  • コンソールのエラー: ターミナルまたは Eclipse の Console ビューにエラーメッセージが表示されていないか確認してください。

Wicket 10 の主要な依存関係

クイックスタートでは最小限の依存関係のみが含まれていますが、実際の開発ではプロジェクトの要件に応じて追加のモジュールが必要になります。Wicket 10 で利用可能な主要モジュールを以下にまとめます。

モジュール(artifactId) 説明 用途
wicket-core コアライブラリ Wicket の基本機能。すべての Wicket アプリケーションで必須。ページ、コンポーネント、モデルなどの基本 API を提供します。
wicket-extensions 拡張コンポーネント DataTable、DatePicker、ModalWindow、Wizard など、よく使われる高機能コンポーネントを提供します。多くのプロジェクトで利用されます。
wicket-spring Spring 連携 Spring Framework の DI コンテナと Wicket を統合します。@SpringBean アノテーションによる依存性注入を可能にします。
wicket-auth-roles 認証・認可 ロールベースのアクセス制御を実装するためのフレームワーク。ページやコンポーネント単位での権限チェックが可能です。
wicket-tester テストユーティリティ WicketTester によるページ・コンポーネントのユニットテストを提供します。10.x で wicket-core から独立したモジュールになりました。
wicket-bean-validation Bean Validation 連携 Jakarta Bean Validation(旧 Hibernate Validator)のアノテーションを Wicket フォームのバリデーションに利用できるようにします。
wicket-devutils 開発ユーティリティ 開発時に便利なデバッグツール群。DebugBar、PageStore ビューア、InspectorPage などを提供します。本番環境では無効にしてください。

モジュールを追加するには、pom.xml<dependencies> セクションに以下のような記述を追加します。

pom.xml - モジュール追加の例(wicket-extensions)
<dependency>
    <groupId>org.apache.wicket</groupId>
    <artifactId>wicket-extensions</artifactId>
    <version>${wicket.version}</version>
</dependency>

バージョンの統一

すべての Wicket モジュールは同じバージョンを使用してください。バージョンが異なるとクラスの不整合が発生し、予期しないエラーの原因になります。${wicket.version} プロパティを使って一元管理することを強く推奨します。

次のステップ

環境構築が完了したら、次の章では Wicket のアーキテクチャと設計思想を学びます。Wicket がどのように HTML と Java を結び付けているのか、コンポーネントツリーやモデルの仕組みを理解することで、効率的な開発が可能になります。

実務でハマりやすい注意点

  • 問題
    HTML を直したのに、ブラウザでは修正前の画面のまま表示される。レイアウト調整中に「保存したのに変わらない」という状態になりやすい。
    原因
    アプリが Deployment モードで動作していると、テンプレートの変更検知が抑制される。結果として、修正したHTMLが即時に再読み込みされない。
    対策
    開発中は Development モードで起動する。あわせて、反映されない場合は再デプロイやブラウザキャッシュのクリアを実施して切り分ける。