Apache Maven を使用した Quarkus アプリケーションの開発およびコンパイル

手順

1. コマンドターミナルで以下のコマンドを入力し、Maven が JDK 11 を使用していること、そして Maven のバージョンが 3.6.3 以上であることを確認します。

   mvn --version

2. 上記のコマンドで JDK 11 が返されない場合は、JDK 11 へのパスを PATH 環境変数に追加し、上記のコマンドを再度入力します。

3. Quarkus Maven プラグインを使用して新規プロジェクトを作成するには、以下のいずれかの方法を使用します。

   • 以下のコマンドを入力します。

     mvn io.quarkus:quarkus-maven-plugin:1.7.6.Final-redhat-00014:create \
         -DprojectGroupId=<project_group_id> \
         -DprojectArtifactId=<project_artifact_id> \
         -DplatformGroupId=com.redhat.quarkus \
         -DplatformArtifactId=quarkus-universe-bom \
         -DplatformVersion=1.7.6.Final-redhat-00014 \
         -DclassName="<classname>"

     このコマンドで、以下の値を置き換えます。

     • <project_group_id>: プロジェクトの一意の識別子。
     • <project_artifact_id>: プロジェクトおよびプロジェクトディレクトリーの名前。
     • <classname>: 生成されたリソースの完全修飾名 (例: org.acme.quarkus.sample.HelloResource)。

   • インタラクティブモードでプロジェクトを作成します。

     mvn io.quarkus:quarkus-maven-plugin:1.7.6.Final-redhat-00014:create

     プロンプトが表示されたら、必要な属性値を入力します。

     注記

     以下のコマンドを入力し、プロジェクト属性のデフォルト値を使用してプロジェクトを作成することもできます。

     mvn io.quarkus:quarkus-maven-plugin:1.7.6.Final-redhat-00014:create -B

     以下の表は、create コマンドで定義できる属性を一覧表示しています。

     Expand

     属性	デフォルト値	説明
     projectGroupId	org.acme.sample	プロジェクトの一意識別子。
     projectArtifactId	なし	プロジェクトおよびプロジェクトディレクトリーの名前。projectArtifactId を指定しないと、Maven プラグインはインタラクティブモードを起動します。ディレクトリーがすでに存在する場合、生成は失敗します。
     projectVersion	1.0-SNAPSHOT	プロジェクトのバージョン。
     platformGroupId	io.quarkus	プラットフォームのグループ ID。既存のプラットフォームのデフォルト値はすべて、io.quarkus です。ただし、デフォルト値は変更することができます。
     platformArtifactId	quarkus-universe-bom	プラットフォーム BOM のアーティファクト ID。ローカルにビルドされた Quarkus を使用するには、quarkus-universe-bom を pom.xml ファイルに追加します。
     platformVersion	プラットフォームの最新バージョン	プロジェクトに使用するプラットフォームのバージョン。バージョン範囲を指定でき、Maven プラグインは最新バージョンを使用します。
     className	なし	生成されたリソースの完全修飾名。アプリケーションの作成後、REST エンドポイントは以下の URL で公開されます。 http://localhost:8080/$path デフォルトの path を使用する場合、URL は http://localhost:8080/hello になります。
     path	/hello	リソースパス (className を設定した場合のみ)。
     extensions	[]	プロジェクトに追加するエクステンションのコンマ区切りリスト。

     Show more

手順

1. テキストエディターで pom.xml ファイルを開きます。

2. Quarkus GAV (Group、Artifact、Version) を追加し、quarkus-universe-bom ファイルを使用して、Quarkus の異なる依存関係のバージョンを省略します。

   <dependencyManagement>
       <dependencies>
         <dependency>
           <groupId>${quarkus.platform.group-id}</groupId>
           <artifactId>${quarkus.platform.artifact-id}</artifactId>
           <version>${quarkus-plugin.version}</version>
           <type>pom</type>
           <scope>import</scope>
         </dependency>
       </dependencies>
     </dependencyManagement>

3. Quarkus Maven プラグインを追加します。

   <build>
       <plugins>
           <plugin>
               <groupId>io.quarkus</groupId>
               <artifactId>quarkus-maven-plugin</artifactId>
               <version>${quarkus-plugin.version}</version>
               <executions>
                   <execution>
                       <goals>
                           <goal>build</goal>
                       </goals>
                   </execution>
               </executions>
           </plugin>
       </plugins>
   </build>

4. 任意手順: ネイティブアプリケーションをビルドするには、Maven Surefire および Maven Failsafe プラグインを含む特定のネイティブプロファイルを追加し、native パッケージタイプを有効化します。

   <profiles>
       <profile>
           <id>native</id>
           <properties>
               <quarkus.package.type>native</quarkus.package.type>
           </properties>
           <build>
               <plugins>
                   <plugin>
                       <groupId>org.apache.maven.plugins</groupId>
                       <artifactId>maven-failsafe-plugin</artifactId>
                       <version>${surefire-plugin.version}</version>
                       <executions>
                           <execution>
                               <goals>
                                   <goal>integration-test</goal>
                                   <goal>verify</goal>
                               </goals>
                               <configuration>
                                   <systemProperties>
                                       <native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
                                   </systemProperties>
                               </configuration>
                           </execution>
                       </executions>
                   </plugin>
               </plugins>
           </build>
       </profile>
   </profiles>

   名前に IT が含まれるテストは、@NativeImageTest アノテーションが付けられ、ネイティブ実行可能ファイルに対して実行されます。

手順

1. Quarkus プロジェクトディレクトリーに移動します。

2. 利用可能なエクステンションを一覧表示するには、以下のコマンドを入力します。

   ./mvnw quarkus:list-extensions

3. プロジェクトにエクステンションを追加するには、以下のコマンドを入力します。ここで、<extension> は、追加するエクステンションの Group、Artifact、Version (GAV) に置き換えます。

   ./mvnw quarkus:add-extension -Dextensions="<extension>"

   たとえば、Agroal エクステンションを追加するには、以下のコマンドを入力します。

   ./mvnw quarkus:add-extension -Dextensions="io.quarkus:quarkus-agroal"

4. 特定のエクステンションを検索するには、-Dextensions= の後にエクステンション名または名前の一部を入力します。以下の例では、名前に、jdbc、agroal、および non-exist-ent のテキストが含まれるエクステンションを検索します。

   ./mvnw quarkus:add-extension -Dextensions=jdbc,agroal,non-exist-ent

   このコマンドは、以下の結果を返します。

   ❌ Multiple extensions matching 'jdbc'
       * io.quarkus:quarkus-jdbc-h2
       * io.quarkus:quarkus-jdbc-mariadb
       * io.quarkus:quarkus-jdbc-postgresql
       Be more specific e.g using the exact name or the full gav.
   ✅ Adding extension io.quarkus:quarkus-agroal
   ❌ Cannot find a dependency matching 'non-exist-ent', maybe a typo?
   [...]

5. 特定のテキスト文字列が返すすべてのエクステンションをインストールするには、-Dextensions= の後にエクステンション名または名前の一部を入力します。以下の例では、hibernate- で始まるすべてのエクステンションを検索し、インストールします。

   ./mvnw quarkus:add-extension -Dextensions="hibernate-*"

CodeReady Studio または Eclipse

1. CodeReady Studio または Eclipse で、File → Import とクリックします。
2. Maven → Existing Maven Project と選択します。
3. 次の画面で、プロジェクトのルートロケーションを選択します。見つかったモジュールの一覧が表示されます。
4. 生成されたプロジェクトを選択し、Finish をクリックします。

5. アプリケーションを起動するには、新しいターミナルウィンドウに以下のコマンドを入力します。

   ./mvnw compile quarkus:dev

IntelliJ

1. IntelliJ で、以下のタスクのいずれかを実行します。

   • File → New → Project From Existing Sources と選択します。
   • Welcome ページで Import project を選択します。
2. プロジェクトの root ディレクトリーを選択します。
3. Import project from external model を選択してから、Maven を選択します。
4. オプションを確認して Next をクリックします。
5. Finish をクリックします。

6. アプリケーションを起動するには、新しいターミナルウィンドウに以下のコマンドを入力します。

   ./mvnw compile quarkus:dev

Apache NetBeans

1. File → Open Project と選択します。
2. プロジェクトの root ディレクトリーを選択します。
3. Open Project クリックします。

4. アプリケーションを起動するには、新しいターミナルウィンドウに以下のコマンドを入力します。

   ./mvnw compile quarkus:dev

Visual Studio Code

1. Java Extension Pack をインストールします。
2. Visual Studio Code でプロジェクトディレクトリーを開きます。プロジェクトは Maven プロジェクトとしてロードされます。

手順

1. テキストエディターで application.properties ファイルを開きます。

2. 変更するプロパティーの値を編集し、ファイルを保存します。

   以下の表は、変更可能なプロパティーをまとめたものです。

   Expand

   プロパティー	説明	タイプ	デフォルト
   quarkus.package.main-class	アプリケーションのエントリーポイント。ほとんどの場合、この値は変更する必要があります。	string	io.quarkus.runner.GeneratedMain
   quarkus.package.type	要求された出力タイプ。	string	jar
   quarkus.package.uber-jar	Java ランナーを uber-JAR としてパックすべきかどうか。	boolean	false
   quarkus.package.manifest.add-implementation-entries	実装情報をランナー JAR ファイルの MANIFEST.MF ファイルに含めるかどうか。	boolean	true
   quarkus.package.user-configured-ignored-entries	出力アーティファクトにコピーしてはならないファイル。	string (list)
   quarkus.package.runner-suffix	ランナー JAR ファイルに適用される接尾辞。	string	-runner
   quarkus.package.output-directory	アプリケーションビルドの出力フォルダー。これは、ビルドシステムのターゲットディレクトリーと相対的に解決されます。	string
   quarkus.package.output-name	最終的なアーティファクトの名前。	string

   Show more

手順

1. プラグイン設定を pom.xml ファイルに追加します。

   <project>
       [...]
         <plugin>
             <groupId>io.quarkus</groupId>
             <artifactId>quarkus-bootstrap-maven-plugin</artifactId>
             <version>${quarkus-plugin.version}</version>
         </plugin>
       [...]
   </project>

2. アプリケーションのビルド依存関係ツリーを一覧表示するには、以下のコマンドを入力します。

   ./mvnw quarkus-bootstrap:build-tree

3. このコマンドの出力は、以下のようになります。

   [INFO] --- quarkus-bootstrap-maven-plugin:1.7:build-tree (default-cli) @ getting-started ---
   [INFO] org.acme:getting-started:jar:1.0-SNAPSHOT
   [INFO] └─ io.quarkus:quarkus-resteasy-deployment:jar:1.7 (compile)
   [INFO]    ├─ io.quarkus:quarkus-resteasy-server-common-deployment:jar:1.7 (compile)
   [INFO]    │  ├─ io.quarkus:quarkus-core-deployment:jar:1.7 (compile)
   [INFO]    │  │  ├─ commons-beanutils:commons-beanutils:jar:1.9.3 (compile)
   [INFO]    │  │  │  ├─ commons-logging:commons-logging:jar:1.2 (compile)
   [INFO]    │  │  │  └─ commons-collections:commons-collections:jar:3.2.2 (compile)
   ...

手順

1. Getting Started プロジェクトのpom.xml ファイルを開き、native プロファイルが含まれていることを確認します。

   <profiles>
       <profile>
           <id>native</id>
           <properties>
               <quarkus.package.type>native</quarkus.package.type>
           </properties>
       </profile>
   </profiles>

   注記

   Quarkus native プロファイルを使用すると、ネイティブ実行可能ファイルおよびネイティブイメージテストの両方を実行することができます。

2. 以下のいずれかの方法を使用して、ネイティブ実行可能ファイルをビルドします。

   1. Docker を使用してネイティブ実行可能ファイルをビルドします。

      ./mvnw package -Pnative -Dquarkus.native.container-build=true

   2. Podman を使用してネイティブ実行可能ファイルをビルドします。

      ./mvnw package -Pnative -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman

      これらのコマンドは、target ディレクトリーに getting-started-*-runner バイナリーを作成します。

      重要

      Quarkus アプリケーションをネイティブ実行可能ファイルにコンパイルすると、分析および最適化の際にメモリーを大量に消費します。quarkus.native.native-image-xmx 設定プロパティーを設定することで、ネイティブコンパイル時に使用されるメモリーの量を制限することができます。メモリー制限を低く設定すると、ビルド時間が長くなる可能性があります。

3. ネイティブ実行可能ファイルを実行します。

   ./target/getting-started-*-runner

   ネイティブ実行可能ファイルをビルドする場合、prod プロファイルが有効化され、Quarkus ネイティブテストは、prod プロファイルを使用して実行されます。これは、quarkus.test.native-image-profile プロパティーを使用して変更することができます。

手順

1. pom.xml ファイルを開き、native プロファイルに以下の要素が含まれていることを確認します。

   <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-failsafe-plugin</artifactId>
       <version>${surefire-plugin.version}</version>
       <executions>
           <execution>
               <goals>
                   <goal>integration-test</goal>
                   <goal>verify</goal>
               </goals>
               <configuration>
                   <systemPropertyVariables>
                       <native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
                       <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
                       <maven.home>${maven.home}</maven.home>
                   </systemPropertyVariables>
               </configuration>
           </execution>
       </executions>
   </plugin>

   failsafe-maven-plugin はインテグレーションテストを実行し、作成されたネイティブ実行可能ファイルの場所を示します。

2. src/test/java/org/acme/quickstart/NativeGreetingResourceIT.java ファイルを開き、以下の内容が含まれていることを確認します。

   package org.acme.quickstart;
   
   
   import io.quarkus.test.junit.NativeImageTest;
   
   @NativeImageTest 

   1

   
   public class NativeGreetingResourceIT extends GreetingResourceTest { 

   2

   
   
       // Run the same tests
   
   }

   1

   テストの前に、ネイティブファイルからアプリケーションを開始する別のテストランナーを使用します。実行可能ファイルは、Failsafe Maven Plugin に設定された native.image.path システムプロパティーを使用して取得されます。

   2

   この例は、GreetingResourceTest を拡張しますが、新しいテストを作成することも可能です。

3. テストを実行します。

   ./mvnw verify -Pnative

   以下の例は、このコマンドの出力を示しています。

   ./mvnw verify -Pnative
   ...
   [getting-started-1.0-SNAPSHOT-runner:18820]     universe:     587.26 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]      (parse):   2,247.59 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]     (inline):   1,985.70 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]    (compile):  14,922.77 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]      compile:  20,361.28 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]        image:   2,228.30 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]        write:     364.35 ms
   [getting-started-1.0-SNAPSHOT-runner:18820]      [total]:  52,777.76 ms
   [INFO]
   [INFO] --- maven-failsafe-plugin:2.22.1:integration-test (default) @ getting-started ---
   [INFO]
   [INFO] -------------------------------------------------------
   [INFO]  T E S T S
   [INFO] -------------------------------------------------------
   [INFO] Running org.acme.quickstart.NativeGreetingResourceIT
   Executing [/data/home/gsmet/git/quarkus-quickstarts/getting-started/target/getting-started-1.0-SNAPSHOT-runner, -Dquarkus.http.port=8081, -Dtest.url=http://localhost:8081, -Dquarkus.log.file.path=build/quarkus.log]
   2019-04-15 11:33:20,348 INFO  [io.quarkus] (main) Quarkus 999-SNAPSHOT started in 0.002s. Listening on: http://[::]:8081
   2019-04-15 11:33:20,348 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy]
   [INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.387 s - in org.acme.quickstart.NativeGreetingResourceIT
   ...

   注記

   Quarkus は、ネイティブイメージの開始まで 60 秒間待機し、その後ネイティブテストに自動的に失敗します。この待機時間は、quarkus.test.native-image-wait-time システムプロパティーを使用して変更可能です。

   以下のコマンドを使用して、待機時間を延長することができます。<duration> は、秒単位の待機時間になります。

   ./mvnw verify -Pnative -Dquarkus.test.native-image-wait-time=<duration>

手順

1. 開発モードで Quarkus を起動するには、Quarkus アプリケーションの pom.xml ファイルが含まれるディレクトリーで以下のコマンドを入力します。

   ./mvnw quarkus:dev

2. アプリケーションに変更を加え、ファイルを保存します。

3. ブラウザーを更新して、ワークスペースのスキャンをトリガーします。

   変更が検出されると、Java ファイルが再コンパイルされ、アプリケーションが再デプロイされます。その後、要求は再デプロイされたアプリケーションによって処理されます。コンパイルまたはデプロイメントに問題がある場合には、エラーページが表示されます。

   開発モードでは、デバッガーがアクティベートされ、ポート 5005 をリッスンします。

4. 任意手順: アプリケーションの実行前にデバッガーが割り当てられるのを待つには、-Dsuspend を追加します。

   ./mvnw quarkus:dev -Dsuspend

5. 任意手順: デバッガーが実行されないようにするには、-Ddebug=false を追加します。

   ./mvnw quarkus:dev -Ddebug=false

システムプロパティーを使用したデバッガーの制御

1. 以下の debug システムプロパティーの値の 1 つを変更します。ここで、PORT はデバッガーがリッスンするポートです。

   • false: JVM はデバッグモードを無効にして開始します。
   • true: JVM はデバッグモードで開始され、ポート 5005 でリッスンしています。
   • client: JVM はクライアントモードで起動され、localhost:5005 への接続を試みます。
   • PORT: JVM はデバッグモードで開始され、PORT をリッスンしています。

2. suspend システムプロパティーの値を変更します。このプロパティーは、Quarkus がデバッグモードで開始する際に使用されます。

   • y または true: デバッグモードの JVM の起動が一時停止します。
   • n または false: デバッグモードの JVM は一時停止せずに起動します。

コマンドラインからのデバッガーの制御

1. デバッグモードの JVM で Quarkus アプリケーションを起動するには、以下のコマンドを入力します。

   ./mvnw compile quarkus:dev -Ddebug

2. localhost:5005 にデバッガーを割り当てます。