Quarkus スタートガイド

手順

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

   mvn --version

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

3. プロジェクトをビルドするには、以下のコマンドのいずれか 1 つを実行します。

   注記

   Apple macOS および Microsoft Windows は、実稼働環境ではサポートされません。

   • Linux または Apple macOS を使用している場合は、以下のコマンドを入力します。

     mvn io.quarkus:quarkus-maven-plugin:1.11.7.Final-redhat-00009:create \
         -DprojectGroupId=org.acme \
         -DprojectArtifactId=getting-started \
         -DplatformGroupId=com.redhat.quarkus \
         -DplatformVersion=1.11.7.Final-redhat-00009 \
         -DclassName="org.acme.quickstart.GreetingResource" \
         -Dpath="/hello"
     cd getting-started

   • Microsoft Windows のコマンドラインを使用している場合は、以下のコマンドを入力します。

     mvn io.quarkus:quarkus-maven-plugin:1.11.7.Final-redhat-00009:create -DprojectGroupId=org.acme -DprojectArtifactId=getting-started -DplatformGroupId=com.redhat.quarkus -DplatformVersion=1.11.7.Final-redhat-00009 -DclassName="org.acme.quickstart.GreetingResource" -Dpath="/hello"

   • Microsoft Windows Powershell を使用している場合は、以下のコマンドを入力します。

     mvn io.quarkus:quarkus-maven-plugin:1.11.7.Final-redhat-00009:create "-DprojectGroupId=org.acme" "-DprojectArtifactId=getting-started" "-DplatformVersion=1.11.7.Final-redhat-00009" "-DplatformGroupId=com.redhat.quarkus" "-DclassName=org.acme.quickstart.GreetingResource" "-Dpath=/hello"

     これらのコマンドにより、./getting-started ディレクトリーに以下の要素が作成されます。

     • Maven プロジェクトディレクトリー構造
     • /hello で公開される org.acme.quickstart.GreetingResource リソース
     • ネイティブモードおよび JVM モードでアプリケーションをテストするための関連するユニットテスト
     • アプリケーションの起動後に http://localhost:8080 でアクセス可能なランディングページ
     • src/main/docker ディレクトリーの Dockerfile.jvm、Dockerfile.native、および Dockerfile.fast-jar ファイルの例
     • アプリケーションの設定ファイル

4. ディレクトリー構造が作成されたら、テキストエディターで pom.xml ファイルを開き、ファイルの内容を確認します。

   <dependencyManagement>
       <dependencies>
           <dependency>
               <groupId>com.redhat.quarkus</groupId>
               <artifactId>quarkus-universe-bom</artifactId>
               <version>${quarkus.version}</version>
               <type>pom</type>
               <scope>import</scope>
           </dependency>
       </dependencies>
   </dependencyManagement>
   
   <build>
     <plugins>
       <plugin>
         <groupId>io.quarkus</groupId>
         <artifactId>quarkus-maven-plugin</artifactId>
         <version>${quarkus-plugin.version}</version>
         <executions>
           <execution>
             <goals>
               <goal>build</goal>
               <goal>generate-code</goal>
               <goal>generate-code-tests</goal>
             </goals>
           </execution>
         </executions>
       </plugin>
    </plugins>
   </build>

   Quarkus BOM は pom.xml ファイルの <dependencyManagement> セクションに含まれます。そのため、pom.xml ファイルに個別の Quarkus 依存関係のバージョンを記述する必要はありません。さらに、アプリケーションをパッケージ化し、開発モードを提供する quarkus-maven-plugin プラグインがあることを確認できます。

5. pom.xml ファイルで、quarkus-resteasy の依存関係を確認します。この依存関係により、REST アプリケーションを開発できます。

       <dependency>
           <groupId>io.quarkus</groupId>
           <artifactId>quarkus-resteasy</artifactId>
       </dependency>

6. src/main/java/org/acme/quickstart/GreetingResource.java ファイルを確認します。

   package org.acme.quickstart;
   
   import javax.ws.rs.GET;
   import javax.ws.rs.Path;
   import javax.ws.rs.Produces;
   import javax.ws.rs.core.MediaType;
   
   @Path("/hello")
   public class GreetingResource {
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return "hello";
       }
   }

   このファイルには、/hello エンドポイントに送信するリクエストへの応答として hello を返す単純な REST エンドポイントが含まれます。

   注記

   Quarkus では、JAX-RS の Application クラスはサポートされますが、必須ではありません。さらに、リクエストごとに 1 つのインスタンスが作成されるのではなく、GreetingResource クラスのインスタンスが 1 つだけ作成されます。これは、別の *Scoped アノテーションを使用して設定できます。たとえば、ApplicationScoped、RequestScoped などを使用できます。

手順

1. 開発モードで Quarkus Hello アプリケーションをコンパイルするには、プロジェクトディレクトリーから以下のコマンドを入力します。

   ./mvnw compile quarkus:dev

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

   [INFO] --------------------< org.acme:getting-started >---------------------
   [INFO] Building getting-started 1.0.0-SNAPSHOT
   [INFO] --------------------------------[ jar ]---------------------------------
   [INFO]
   [INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ getting-started ---
   [INFO] Using 'UTF-8' encoding to copy filtered resources.
   [INFO] skip non existing resourceDirectory /Users/starksm/Dev/JBoss/Quarkus/starksm64-quarkus-quickstarts/getting-started/src/main/resources
   [INFO]
   [INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ getting-started ---
   [INFO] Changes detected - recompiling the module!
   [INFO] Compiling 2 source files to /Users/starksm/Dev/JBoss/Quarkus/starksm64-quarkus-quickstarts/getting-started/target/classes
   [INFO]
   [INFO] --- quarkus-maven-plugin:<version>:dev (default-cli) @ getting-started ---
   Listening for transport dt_socket at address: 5005
   2019-02-28 17:05:22,347 INFO  [io.qua.dep.QuarkusAugmentor] (main) Beginning quarkus augmentation
   2019-02-28 17:05:22,635 INFO  [io.qua.dep.QuarkusAugmentor] (main) Quarkus augmentation completed in 288ms
   2019-02-28 17:05:22,770 INFO  [io.quarkus] (main) Quarkus started in 0.668s. Listening on: http://localhost:8080
   2019-02-28 17:05:22,771 INFO  [io.quarkus] (main) Installed features: [cdi, resteasy]

2. 新しいターミナルウィンドウに以下のコマンドを入力し、アプリケーションによって提供されるエンドポイントにリクエストを送信します。

   curl -w "\n" http://localhost:8080/hello
   hello

   注記

   この例では、"\n" 属性を使用して、コマンドの出力の前に新しい行を自動的に追加します。これにより、ターミナルで '%' 文字が出力されたり、出力結果と次のコマンドプロンプトが同じ行に表示されたりすることを防ぎます。

3. アプリケーションを停止するには、CTRL+C を押します。

手順

1. アプリケーションを変更し、コンパニオン Bean を追加するには、以下の内容で src/main/java/org/acme/quickstart/GreetingService.java ファイルを作成します。

   package org.acme.quickstart;
   
   import javax.enterprise.context.ApplicationScoped;
   
   @ApplicationScoped
   public class GreetingService {
   
       public String greeting(String name) {
           return "hello " + name;
       }
   
   }

2. src/main/java/org/acme/quickstart/GreetingResource.java を編集して GreetingService をインジェクトし、これを使用して新しいエンドポイントを作成します。

   package org.acme.quickstart;
   
   import javax.inject.Inject;
   import javax.ws.rs.GET;
   import javax.ws.rs.Path;
   import javax.ws.rs.Produces;
   import javax.ws.rs.core.MediaType;
   
   import org.jboss.resteasy.annotations.jaxrs.PathParam;
   
   @Path("/hello")
   public class GreetingResource {
   
       @Inject
       GreetingService service;
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       @Path("/greeting/{name}")
       public String greeting(@PathParam String name) {
           return service.greeting(name);
       }
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return "hello";
       }
   }

3. アプリケーションを停止した場合は、以下のコマンドを入力して再起動します。

   ./mvnw compile quarkus:dev

4. エンドポイントが hello quarkus を返すことを確認するには、新しいターミナルウィンドウに以下のコマンドを入力します。

   curl -w "\n" http://localhost:8080/hello/greeting/quarkus
   hello quarkus

手順

1. 生成された pom.xml ファイルを開き、コンテンツを確認します。

   <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>
          </systemPropertyVariable>
       </configuration>
   </plugin>

   注記:

   • アプリケーションがテスト用に正しいログマネージャーを使用するように、java.util.logging.manager システムプロパティーが設定されます。
   • maven.home プロパティーは、プロジェクトに適用するカスタム Maven 設定を保存できる settings.xml ファイルの場所を参照します。

2. src/test/java/org/acme/quickstart/GreetingResourceTest.java ファイルを以下の内容に一致するように編集します。

   package org.acme.quickstart;
   
   import io.quarkus.test.junit.QuarkusTest;
   import org.junit.jupiter.api.Test;
   
   import java.util.UUID;
   
   import static io.restassured.RestAssured.given;
   import static org.hamcrest.CoreMatchers.is;
   
   @QuarkusTest
   public class GreetingResourceTest {
   
       @Test
       public void testHelloEndpoint() {
           given()
             .when().get("/hello")
             .then()
                .statusCode(200)
                .body(is("hello"));
       }
   
       @Test
       public void testGreetingEndpoint() {
           String uuid = UUID.randomUUID().toString();
           given()
             .pathParam("name", uuid)
             .when().get("/hello/greeting/{name}")
             .then()
               .statusCode(200)
               .body(is("hello " + uuid));
       }
   
   }

   注記

   QuarkusTest ランナーを使用することで、テストを開始する前に JUnit にアプリケーションを起動するよう指示します。

3. Maven からこれらのテストを実行するには、以下のコマンドを入力します。

   ./mvnw test

   注記

   IDE からテストを実行することもできます。その場合は、最初にアプリケーションを停止してください。

   デフォルトでは、テストはポート 8081 で実行されるため、実行中のアプリケーションと競合しません。Quarkus では、RestAssured 依存関係はこのポートを使用するように設定されています。別のクライアントを使用する場合は、@TestHTTPResource アノテーションを使用して、テスト済みアプリケーションの URL を Test クラスのフィールドに直接インジェクトします。このフィールドには、タイプ String、URL、または URI を使用できます。このアノテーションにテストパスを指定することもできます。たとえば、/myservlet にマップされたサーブレットをテストするには、以下の行をテストに追加します。

   @TestHTTPResource("/myservlet")
   URL testUrl;

4. 必要な場合は、quarkus.http.test-port 設定プロパティーにテストポートを指定します。

手順

1. Quarkus Getting Started プロジェクトをパッケージ化するには、root ディレクトリーで以下のコマンドを入力します。

   ./mvnw package

   このコマンドは、以下の JAR ファイルを /target ディレクトリーに生成します。

   • getting-started-1.0-0-SNAPSHOT.jar: プロジェクトのクラスおよびリソースが含まれます。これは、Maven ビルドで生成される通常のアーティファクトです。

   • getting-started-1.0-0-SNAPSHOT-runner.jar: 実行可能な JAR ファイルです。依存関係は target/lib ディレクトリーにコピーされるため、このファイルは uber-JAR ファイルではない点に注意してください。

     警告

     お使いのアプリケーションが開発モードで実行中の場合は、CTRL+C を押してアプリケーションを停止する必要があります。開発モードが有効な場合にアプリケーションをパッケージ化しようとすると、ポートの競合が発生します。

2. 以下のコマンドを入力してアプリケーションを起動します。

   java -jar target/getting-started-1.0-0-SNAPSHOT-runner.jar

   注記

   runner JAR ファイルからの MANIFEST.MF ファイルの Class-Path エントリーは、lib ディレクトリーからの JAR ファイルを明示的に記述します。別の場所からアプリケーションをデプロイする場合は、runner JAR ファイルと lib ディレクトリーをコピーする必要があります。

手順

1. Web ブラウザーを使用して https://code.quarkus.redhat.com に移動します。

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

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

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

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

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

        注記

        Red Hat は、code.quarkus.redhat.com を使用して Quarkus Maven プロジェクトのみを作成する際にサポートを提供します。Red Hat では、Gradle プロジェクトの生成はサポートしていません。

        

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

   1. Configure more options を選択し、追加のアプリケーションの詳細が含まれるフィールドを表示します。
   2. プロジェクトから生成されたアーティファクトで使用されるバージョンを入力します。このフィールドのデフォルト値は 1.0.0-SNAPSHOT です。semantic versioning の使用が推奨されますが、必要に応じて、別のタイプのバージョンを使用できます。

   3. code.quarkus.redhat.com がサンプルコードをプロジェクトに追加するかどうかを選択します。エクステンションの一覧から アイコンでマーク付けされたエクステンションをプロジェクトに追加する場合は、このオプションを有効にして、プロジェクトの生成時にこれらのエクステンションのクラスファイルおよびリソースファイルのサンプルを自動的に作成できます。サンプルコードを提供するエクステンションを追加しない場合、このオプションは生成されたプロジェクトには影響しません。

      
      注記

      code.quarkus.redhat.com は、Red Hat ビルドの Quarkus の最新リリースを自動的に使用します。プロジェクトの生成後に、pom.xml ファイルで BOM バージョンを手動で変更できます。

4. エクステンションの一覧から、アプリケーションで使用するエクステンションを選択します。選択したエクステンションは、Quarkus アプリケーションの依存関係として含まれ、それらのバージョンは互換性を確保するために Quarkus プラットフォームによって管理されます。

   このオプションを有効にすると、 アイコンでマーク付けされたエクステンションのサンプルコードを自動的に生成できます。

   

   Red Hat は、一覧にある個別のエクステンションに対して さまざまなレベル のサポートを提供します。レベルは、各エクステンション名の横にあるラベルで示されています。

   • SUPPORTED エクステンション: Red Hat は、実稼働環境でのエンタープライズアプリケーションでの使用に対して完全にサポートしています。
   • TECH-PREVIEW 拡張: Red Hat は、テクノロジープレビュー機能のサポート範囲 に基づき、限定的に、実稼働環境でのサポートを提供します。
   • DEV-SUPPORT エクステンション: Red Hat は、実稼働環境での使用をサポートしていません。ただし、新規アプリケーションの開発での使用に対しては、Red Hat 開発者がこれらのコア機能をサポートしています。
   • Red Hat は、ラベル付けされていないエクステンションの実稼働環境での使用をサポートしていません。

   • DEPRECATED エクステンション: 同じ機能を提供する新しいテクノロジーまたは実装に置き換えられる予定です。

     各エクステンションの横にあるオーバーフローメニュー (⋮) を展開して、以下を実行する追加オプションにアクセスできます。

     • エクステンションを既存プロジェクトに追加する (コマンドラインで Quarkus Maven プラグインを使用)。
     • プロジェクトの pom.xml ファイルへエクステンションを追加するための XML スニペットをコピーする。
     • 各エクステンションの groupId、artifactId、および version を取得する。

     • エクステンションガイドを開く。

       

5. Generate your application を選択して選択内容を確認し、生成されたプロジェクトを含むアーカイブのダウンロードリンクのオーバーレイ画面を表示します。オーバーレイ画面には、アプリケーションのコンパイルおよび起動に使用できるカスタムコマンドも表示されます。
6. Download the ZIP を選択して、生成されたプロジェクトファイルを含むアーカイブをマシンに保存します。
7. アーカイブの内容を展開します。

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

   cd <directory_name>

9. 開発モードでアプリケーションをコンパイルして起動します。

   ./mvnw compile quarkus:dev