Apache Maven を使用した Red Hat build of Quarkus アプリケーションの開発とコンパイル

手順

1. コマンドターミナルで以下のコマンドを入力して、Maven が OpenJDK 17 または 21 を使用していること、および Maven のバージョンが 3.8.6 以降であることを確認します。

   mvn --version

   Copy to Clipboard Toggle word wrap
2. 前のコマンドで OpenJDK 17 または 21 が返されない場合は、OpenJDK 17 または 21 へのパスを PATH 環境変数に追加し、前のコマンドを再度入力します。

3. プロジェクトを作成するには、次のいずれかの方法を使用します。

   • Quarkus Maven プラグインを使用します。以下のコマンドを実行します。

     mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.15.7.redhat-00001:create \
         -DprojectGroupId=<project_group_id> \
         -DprojectArtifactId=<project_artifact_id> \
         -DplatformGroupId=com.redhat.quarkus.platform \
         -DplatformArtifactId=quarkus-bom \
         -DplatformVersion=3.15.7.redhat-00001
         -DpackageName=getting.started

     Copy to Clipboard Toggle word wrap

     このコマンドでは、以下の値を置き換えてください。

     • <project_group_id>: プロジェクトの一意識別子
     • <project_artifact_id>: プロジェクトおよびプロジェクトディレクトリーの名前

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

     mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.15.7.redhat-00001:create

     Copy to Clipboard Toggle word wrap

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

     注記

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

     mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.15.7.redhat-00001:create -B

   • Quarkus CLI を使用します。以下のコマンドを実行します。

     quarkus create app my-groupId:my-artifactId --package-name=getting.started

     Copy to Clipboard Toggle word wrap

     • 次のコマンドを使用して、利用可能なオプションのリストを取得することもできます。

       quarkus create app --help

       Copy to Clipboard Toggle word wrap

手順

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

2. 次の項目を含む設定プロパティーを追加します。

   • Maven Compiler プラグインのバージョン
   • Quarkus BOM の groupID、artifactID、および version
   • Maven Surefire プラグインのバージョン
   • skipITs プロパティー

   <properties>
       <compiler-plugin.version>3.11.0</compiler-plugin.version>
       <quarkus.platform.group-id>com.redhat.quarkus.platform</quarkus.platform.group-id>
       <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
       <quarkus.platform.version>3.15.7.redhat-00001</quarkus.platform.version>
       <surefire-plugin.version>3.1.2</surefire-plugin.version>
       <skipITs>true</skipITs>
   </properties>

   Copy to Clipboard Toggle word wrap

3. Quarkus GAV (グループ、アーティファクト、バージョン) を追加し、quarkus-bom ファイルを使用して、さまざまな Quarkus 依存関係のバージョンを省略します。

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

   Copy to Clipboard Toggle word wrap

4. Quarkus Maven プラグイン、Maven Compiler プラグイン、Maven Surefire プラグインを追加します。

   <build>
       <plugins>
           <plugin>
               <groupId>${quarkus.platform.group-id}</groupId>
               <artifactId>quarkus-maven-plugin</artifactId>
               <version>${quarkus.platform.version}</version>
               <extensions>true</extensions>
               <executions>
                   <execution>
                       <goals>
                           <goal>build</goal>
                           <goal>generate-code</goal>
                           <goal>generate-code-tests</goal>
                       </goals>
                   </execution>
               </executions>
           </plugin>
           <plugin>
               <artifactId>maven-compiler-plugin</artifactId>
               <version>${compiler-plugin.version}</version>
               <configuration>
                   <compilerArgs>
                       <arg>-parameters</arg>
                   </compilerArgs>
               </configuration>
           </plugin>
           <plugin>
               <artifactId>maven-surefire-plugin</artifactId>
               <version>${surefire-plugin.version}</version>
               <configuration>
                   <systemPropertyVariables>
                       <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
                       <maven.home>${maven.home}</maven.home>
                   </systemPropertyVariables>
               </configuration>
           </plugin>
       </plugins>
   </build>

   Copy to Clipboard Toggle word wrap
   注記

   maven-surefire-plugin は、アプリケーションのユニットテストを実行します。

5. オプション: ネイティブアプリケーションをビルドするには、maven-failsafe-plugin を含むネイティブプロファイルを追加します。

   <build>
       <plugins>
           ...
           <plugin>
               <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>
       </plugins>
   </build>
   ...
   <profiles>
       <profile>
           <id>native</id>
           <activation>
               <property>
                   <name>native</name>
               </property>
           </activation>
           <properties>
               <skipITs>false</skipITs>
               <quarkus.package.type>native</quarkus.package.type>
           </properties>
       </profile>
   </profiles>

   Copy to Clipboard Toggle word wrap
   • 名前に IT が含まれ、@QuarkusIntegrationTest アノテーションを含むテストは、ネイティブ実行可能ファイルに対して実行します。
   • ネイティブモードと Java 仮想マシン (JVM) モードの違いの詳細は、「Red Hat build of Quarkus の使用開始」ガイドの JVM およびネイティブビルドモード を参照してください。

手順

1. Web ブラウザーで、https://code.quarkus.redhat.com に移動します。

2. 利用可能なバージョンのリストから、必要な Red Hat build of Quarkus のバージョンを選択します。

   注記

   code.quarkus.redhat.com アプリケーションは、自動的に Red Hat build of Quarkus の最新リリースを使用します。これは優先されるオプションです。ただし、必要に応じて、プロジェクト生成後に pom.xml ファイル内の以前の BOM バージョンに手動で変更することもできますが、これは推奨されません。

3. プロジェクトの基本情報を指定します。

   

   View larger image

   
   1. プロジェクトのグループ名を入力します。名前の形式は、Java パッケージ命名規則に従います (例: org.acme)。
   2. プロジェクトによって生成される Maven アーティファクトの名前 (code-with-quarkus など) を入力します。

   3. アプリケーションのコンパイルおよび起動に使用するビルドツールを選択します。選択したビルドツールにより、次の設定が決まります。

      • 生成されるプロジェクトのディレクトリー構造
      • 生成したプロジェクトで使用される設定ファイルのフォーマット

      • プロジェクトの生成後に code.quarkus.redhat.com に表示される、アプリケーションのコンパイルと起動のためのカスタムビルドスクリプトおよびコマンド

        注記

        Red Hat は、Quarkus Maven プロジェクトを作成する場合にのみ code.quarkus.redhat.com の使用をサポートします。

4. アプリケーションプロジェクトに関する追加情報を指定します。

   1. アプリケーションの詳細を含むフィールドを表示するには、More options を選択します。

      

      View larger image

      
   2. プロジェクトによって生成されたアーティファクトに使用するバージョンを入力します。このフィールドのデフォルト値は 1.0.0-SNAPSHOT です。semantic versioning の使用が推奨されます。ただし、別のタイプのバージョン管理を指定することもできます。
   3. code.quarkus.redhat.com がスターターコードをプロジェクトに追加するかどうかを選択します。"STARTER-CODE" でマークされたエクステンションをプロジェクトに追加する場合、このオプションを有効にして、プロジェクト生成時にそのエクステンションのサンプルクラスとリソースファイルを自動的に作成できます。ただし、サンプルコードを提供するエクステンションを追加しない場合、このオプションは生成されたプロジェクトには影響しません。

   image::additional-app-details-project-generator.png[code.quarkus.redhat.com サイトのアプリケーション詳細セクションのスクリーンショット。追加のアプリケーションの詳細を含む展開されたフォームが表示されています。]

5. 使用するエクステンションを選択します。Quarkus アプリケーションには、依存関係として選択したエクステンションが含まれます。Quarkus プラットフォームにより、これらのエクステンションは今後のバージョンとの互換性も確保されます。

   重要

   同じプロジェクトで RESTEasy と Quarkus REST 拡張機能を使用しないでください。どちらも同様の機能を提供しますが、動作方法は非常に異なります。Quarkus REST の使用が推奨されます。

   エクステンションの横にある quark アイコン ( ) は、そのエクステンションが Red Hat build of Quarkus プラットフォームリリースの一部であることを示します。Red Hat は、同じプラットフォームのエクステンションを使用することを推奨します。これは、エクステンションは一緒にテストおよび検証され、使用とアップグレードが容易になるためです。

   "STARTER-CODE" でマークされたエクステンションのスターターコードを自動生成するオプションを有効にできます。

   

6. 選択を確認するには、Generate your application を選択します。表示されるダイアログボックスには、次の項目が表示されます。

   • 生成されたプロジェクトを含むアーカイブをダウンロードするためのリンク
   • アプリケーションをコンパイルして起動するために使用できるコマンド
7. 生成されたプロジェクトファイルを含むアーカイブをマシンに保存するには、Download the ZIP を選択します。
8. アーカイブの内容をデプロイメントします。

9. 展開したプロジェクトファイルが含まれるディレクトリーに移動します。

   cd <directory_name>

   Copy to Clipboard Toggle word wrap

10. 次のいずれかの方法でアプリケーションを開発モードでコンパイルして起動します。

    • Maven を使用する場合:

      ./mvnw quarkus:dev

      Copy to Clipboard Toggle word wrap

    • Quarkus CLI を使用:

      quarkus dev

      Copy to Clipboard Toggle word wrap

手順

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

2. 次のいずれかの方法で、使用可能なすべてのエクステンションをリスト表示します。

   • Maven を使用する場合:

     ./mvnw quarkus:list-extensions

     Copy to Clipboard Toggle word wrap

   • Quarkus CLI を使用する場合:

     quarkus extension --installable

     Copy to Clipboard Toggle word wrap

3. 次のいずれかの方法を使用して、プロジェクトにエクステンションを追加します。

   • Maven を使用して、次のコマンドを入力します。この場合の <extension> は、追加するエクステンションのグループ、アーティファクト、バージョン (GAV) です。

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

     Copy to Clipboard Toggle word wrap

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

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

     Copy to Clipboard Toggle word wrap

   • Quarkus CLI を使用して、次のコマンドを入力します。この場合の <extension> は、追加するエクステンションのグループ、アーティファクト、バージョン (GAV) です。

     quarkus extension add '<extension>'

     Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

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

   [SUCCESS] ✅  Extension io.quarkus:quarkus-agroal has been installed

   Copy to Clipboard Toggle word wrap

   同様に、Quarkus CLI では次のように入力できます。

   quarkus extension add 'agroal'

   Copy to Clipboard Toggle word wrap

CodeReady Studio または Eclipse

1. CodeReady Studio または Eclipse で、File> Import をクリックします。
2. Maven → Existing Maven Project を選択します。
3. 次に、プロジェクトのルートの場所を選択します。利用可能なモジュールがリストされます。
4. 生成されたプロジェクトを選択し、Finish をクリックします。

5. 次のいずれかの方法でアプリケーションをコンパイルして起動します。

   • Maven を使用する場合:

     ./mvnw quarkus:dev

     Copy to Clipboard Toggle word wrap

   • Quarkus CLI を使用する場合:

     quarkus dev

     Copy to Clipboard Toggle word wrap

IntelliJ

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

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

6. 次のいずれかの方法でアプリケーションをコンパイルして起動します。

   • Maven を使用する場合:

     ./mvnw quarkus:dev

     Copy to Clipboard Toggle word wrap

   • Quarkus CLI を使用する場合:

     quarkus dev

     Copy to Clipboard Toggle word wrap

Apache NetBeans

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

4. 次のいずれかの方法でアプリケーションをコンパイルして起動します。

   • Maven を使用する場合:

     ./mvnw quarkus:dev

     Copy to Clipboard Toggle word wrap

   • Quarkus CLI を使用する場合:

     quarkus dev

     Copy to Clipboard Toggle word wrap

Visual Studio Code

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

手順

1. {project}/src/main/resources フォルダーに移動し、テキストエディターで application.properties ファイルを開きます。

2. 変更するプロパティーを追加し、ファイルを保存します。

   Expand

   表1.1 変更できるプロパティー

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

   Show more

1. 次のコマンドを実行してアプリケーションをテストします。

手順

1. pom.xml ファイルを開き、build セクションに次の要素が含まれていることを確認します。

   <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>

   Copy to Clipboard Toggle word wrap
   • Maven Failsafe プラグイン (maven-failsafe-plugin) は結合テストを実行し、生成されたネイティブ実行可能ファイルの場所を示します。

2. src/test/java/org/acme/GreetingResourceIT.java ファイルを開き、次のコンテンツが含まれていることを確認します。

   package org.acme;
   
   import io.quarkus.test.junit.QuarkusIntegrationTest;
   
   @QuarkusIntegrationTest 

   1

   
   public class GreetingResourceIT extends GreetingResourceTest { 

   2

   
   
       // Execute the same tests but in native mode.
   }

   Copy to Clipboard Toggle word wrap

   1

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

   2

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

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

   ./mvnw verify -Dnative

   Copy to Clipboard Toggle word wrap

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

   ./mvnw verify -Dnative
   ....
   
   GraalVM Native Image: Generating 'getting-started-1.0.0-SNAPSHOT-runner' (executable)...
   ========================================================================================================================
   [1/8] Initializing...                                                                                    (6.6s @ 0.22GB)
    Java version: 21.0.4+7-LTS, vendor version: Mandrel-23.1.4.0-1b1
    Graal compiler: optimization level: 2, target machine: x86-64-v3
    C compiler: gcc (redhat, x86_64, 13.2.1)
    Garbage collector: Serial GC (max heap size: 80% of RAM)
    2 user-specific feature(s)
    - io.quarkus.runner.Feature: Auto-generated class by Red Hat build of Quarkus from the existing extensions
    - io.quarkus.runtime.graal.DisableLoggingFeature: Disables INFO logging during the analysis phase
   [2/8] Performing analysis...  [******]                                                                  (40.0s @ 2.05GB)
     10,318 (86.40%) of 11,942 types reachable
     15,064 (57.36%) of 26,260 fields reachable
     52,128 (55.75%) of 93,501 methods reachable
      3,298 types,   109 fields, and 2,698 methods registered for reflection
         63 types,    68 fields, and    55 methods registered for JNI access
          4 native libraries: dl, pthread, rt, z
   [3/8] Building universe...                                                                               (5.9s @ 1.31GB)
   [4/8] Parsing methods...      [**]                                                                       (3.7s @ 2.08GB)
   [5/8] Inlining methods...     [***]                                                                      (2.0s @ 1.92GB)
   [6/8] Compiling methods...    [******]                                                                  (34.4s @ 3.25GB)
   [7/8] Layouting methods...    [**]                                                                       (4.1s @ 1.78GB)
   [8/8] Creating image...       [**]                                                                       (4.5s @ 2.31GB)
     20.93MB (48.43%) for code area:    33,233 compilation units
     21.95MB (50.80%) for image heap:  285,664 objects and 8 resources
    337.06kB ( 0.76%) for other data
     43.20MB in total
   
   ....
   
   
   [INFO]
   [INFO] --- maven-failsafe-plugin:3.0.0-M7:integration-test (default) @ getting-started ---
   [INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
   [INFO]
   [INFO] -------------------------------------------------------
   [INFO]  T E S T S
   [INFO] -------------------------------------------------------
   [INFO] Running org.acme.GreetingResourceIT
   __  ____  __  _____   ___  __ ____  ______
    --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
    -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
   --\___\_\____/_/ |_/_/|_/_/|_|\____/___/
   2024-09-27 14:04:52,681 INFO  [io.quarkus] (main) getting-started 1.0.0-SNAPSHOT native (powered by Quarkus 3.15.7.redhat-00001) started in 0.038s. Listening on: http://0.0.0.0:8081
   2024-09-27 14:04:52,682 INFO  [io.quarkus] (main) Profile prod activated.
   2024-09-27 14:04:52,682 INFO  [io.quarkus] (main) Installed features: [cdi, rest, smallrye-context-propagation, vertx]
   [INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 4.696 s - in org.acme.GreetingResourceIT
   [INFO]
   [INFO] Results:
   [INFO]
   [INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
   [INFO]
   [INFO]
   [INFO] --- maven-failsafe-plugin:3.0.0-M7:verify (default) @ getting-started ---

   Copy to Clipboard Toggle word wrap
   注記

   Quarkus は、ネイティブイメージが起動するのを 60 秒間待機してから、自動的にネイティブテストに失敗します。この期間は、quarkus.test.wait-time システムプロパティーを設定することで変更できます。

   以下のコマンドを使用して、待機時間を延長できます。この場合の <duration> は待機時間 (秒単位) です。

   ./mvnw verify -Dnative -Dquarkus.test.wait-time=<duration>

   Copy to Clipboard Toggle word wrap
   注記
   • デフォルトでは、quarkus.test.native-image-profile プロパティーで変更されていない限り、ネイティブテストは prod プロファイルを使用して実行されます。

手順

1. Quarkus アプリケーションの pom.xml ファイルが含まれるディレクトリーに切り替えます。

2. Quarkus アプリケーションを開発モードでコンパイルして起動するには、次のいずれかの方法を使用します。

   • Maven を使用する場合:

     ./mvnw quarkus:dev

     Copy to Clipboard Toggle word wrap

   • Quarkus CLI を使用する場合:

     quarkus dev

     Copy to Clipboard Toggle word wrap
3. アプリケーションに変更を加え、ファイルを保存します。

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

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

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

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

   ./mvnw quarkus:dev -Dsuspend

   Copy to Clipboard Toggle word wrap

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

   ./mvnw quarkus:dev -Ddebug=false

   Copy to Clipboard Toggle word wrap

システムプロパティーを設定してデバッガーを制御する

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

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

2. デバッグモードでの実行中に JVM を一時停止するには、suspend システムプロパティーの値を次のいずれかの値に設定します。

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