プロパティーファイルを使用して Red Hat build of Quarkus アプリケーションを設定する

手順

1. Maven が OpenJDK 17 または 21 を使用していること、および Maven のバージョンが 3.8.6 以降であることを確認します。

   mvn --version

   Copy to Clipboard Toggle word wrap

2. mvn コマンドが OpenJDK 17 または 21 を返さない場合は、システム上で OpenJDK 17 または 21 がインストールされているディレクトリーが PATH 環境変数に含まれていることを確認します。

   export PATH=$PATH:<path_to_JDK>

   Copy to Clipboard Toggle word wrap

3. プロジェクトを生成するには、以下のコマンドを入力します。

   mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.8.6.SP3-redhat-00002:create \
       -DprojectGroupId=org.acme \
       -DprojectArtifactId=config-quickstart \
       -DplatformGroupId=com.redhat.quarkus.platform \
       -DplatformVersion=3.8.6.SP3-redhat-00002 \
       -DclassName="org.acme.config.GreetingResource" \
       -Dpath="/greeting"
   cd config-quickstart

   Copy to Clipboard Toggle word wrap

手順

1. src/main/resources/application.properties ファイルを開きます。

2. 設定プロパティーを設定ファイルに追加します。<property_name> はプロパティー名に、<value> はプロパティーの値に置き換えます。

   <property_name>=<value>

   Copy to Clipboard Toggle word wrap

   以下の例は、Quarkus config-quickstart プロジェクトで greeting.message プロパティーおよび greeting.name プロパティーの値を設定する方法を示しています。

   application.properties ファイルの例

   greeting.message=hello
   greeting.name=quarkus

   Copy to Clipboard Toggle word wrap

   重要

   アプリケーションを設定する際に、アプリケーション固有プロパティーの前に quarkus の文字列を付けないでください。quarkus の接頭辞は、フレームワークレベルで Quarkus を設定するために予約されています。quarkus をアプリケーション固有プロパティーの接頭辞として使用すると、アプリケーションの実行時に予期しない結果が生じる可能性があります。

3. プロジェクトの GreetingResource.java ファイルを確認します。このファイルには、/greeting エンドポイントで HTTP リクエストを送信した場合にメッセージを返す hello() メソッドが含まれる GreetingResource クラスがあります。

   GreetingResource.java ファイルの例

   package org.acme.config;
   
   import java.util.Optional;
   
   import jakarta.ws.rs.GET;
   import jakarta.ws.rs.Path;
   import jakarta.ws.rs.Produces;
   import jakarta.ws.rs.core.MediaType;
   
   import org.eclipse.microprofile.config.inject.ConfigProperty;
   
   @Path("/greeting")
   public class GreetingResource {
   
       String message;
       Optional<String> name;
       String suffix;
   
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return message + " " + name.orElse("world") + suffix;
       }
   }

   Copy to Clipboard Toggle word wrap

   ここで示した例では、hello() メソッドの message および name 文字列の値は初期化されていません。エンドポイントが呼び出され、この状態で正常に開始されると、アプリケーションは NullPointerException をスローします。

4. message、name、および suffix フィールドを定義し、アノテーション @ConfigProperty を付け、greeting.message および greeting.name プロパティーに定義した値と一致させます。アノテーション @ConfigProperty を使用して、各文字列の設定値を注入します。以下に例を示します。

   GreetingResource.java ファイルの例

   package org.acme.config;
   
   import java.util.Optional;
   
   import jakarta.ws.rs.GET;
   import jakarta.ws.rs.Path;
   import jakarta.ws.rs.Produces;
   import jakarta.ws.rs.core.MediaType;
   
   import org.eclipse.microprofile.config.inject.ConfigProperty;
   
   @Path("/greeting")
   public class GreetingResource {
   
     @ConfigProperty(name = "greeting.message") 

   1

   
     String message;
   
     @ConfigProperty(name = "greeting.suffix", defaultValue="!") 

   2

   
     String suffix;
   
     @ConfigProperty(name = "greeting.name")
     Optional<String> name; 

   3

   
   
     @GET
     @Produces(MediaType.TEXT_PLAIN)
     public String hello() {
         return message + " " + name.orElse("world") + suffix;
      }
   }

   Copy to Clipboard Toggle word wrap

   1

   greeting.message 文字列の値を設定しない場合、アプリケーションは失敗し、jakarta.enterprise.inject.spi.DeploymentException: io.quarkus.runtime.configuration.ConfigurationException: Failed to load config value of type class java.lang.String for: greeting.message の例外をスローします。

   2

   greeting.suffix の値を設定しないと、Quarkus はその値をデフォルト値に解決します。

   3

   greeting.name プロパティーを定義しない場合、name の値は使用できません。name に Optional パラメーターを設定しているため、この値が使用できない場合でもアプリケーションは実行されます。

   注記

   設定した値を注入するには、@ConfigProperty を使用します。@ConfigProperty アノテーションが付けられたメンバーの @Inject アノテーションを含める必要はありません。

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

   ./mvnw quarkus:dev

   Copy to Clipboard Toggle word wrap

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

   curl http://localhost:8080/greeting

   Copy to Clipboard Toggle word wrap

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

   hello quarkus!

   Copy to Clipboard Toggle word wrap
7. アプリケーションを停止するには、CTRL+C を押します。

手順

1. GreetingResourceTest.java ファイルを開きます。

2. testHelloEndpoint メソッドの内容を更新します。

   package org.acme.config;
   
   import io.quarkus.test.junit.QuarkusTest;
   import org.junit.jupiter.api.Test;
   
   import static io.restassured.RestAssured.given;
   import static org.hamcrest.CoreMatchers.is;
   
   @QuarkusTest
   public class GreetingResourceTest {
   
       @Test
       public void testHelloEndpoint() {
           given()
             .when().get("/greeting")
             .then()
                .statusCode(200)
                .body(is("hello quarkus!")); // Modified line
       }
   
   }

   Copy to Clipboard Toggle word wrap

手順

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

   ./mvnw clean package

   Copy to Clipboard Toggle word wrap

2. 以下のメソッドのいずれかを使用して、設定プロパティーを設定します。

   • システムプロパティーの設定

     以下のコマンドを、<property_name> は追加する設定プロパティーの名前に、<value> はプロパティーの値に置き換えて入力します。

     java -D<property_name>=<value> -jar target/quarkus-app/quarkus-run.jar

     Copy to Clipboard Toggle word wrap

     たとえば、quarkus.datasource.password プロパティーの値を設定するには、以下のコマンドを入力します。

     java -Dgreeting.suffix=? -jar target/quarkus-app/quarkus-run.jar

     Copy to Clipboard Toggle word wrap

   • 環境変数の設定

     以下のコマンドを、<property_name> は設定する設定プロパティーの名前に、<value> はプロパティーの値に置き換えて入力します。

     export <property_name>=<value> ; java -jar target/quarkus-app/quarkus-run.jar

     Copy to Clipboard Toggle word wrap
     注記

     環境変数名は、Eclipse MicroProfile の変換ルールに従います。名前を大文字に変換し、英数字以外の文字をすべてアンダースコア (_) に置き換えます。

   • 環境ファイルの使用

     現在の作業ディレクトリーに .env ファイルを作成し、<PROPERTY_NAME> はプロパティー名に、<value> はプロパティーの値に置き換えて設定プロパティーを追加します。

     <PROPERTY_NAME>=<value>

     Copy to Clipboard Toggle word wrap
     注記

     開発モードでは、このファイルはプロジェクトのルートディレクトリーにあります。バージョン管理でファイルは追跡しないでください。プロジェクトのルートディレクトリーに .env ファイルを作成する場合は、プログラムがプロパティーとして読み取るキーおよび値を定義できます。

   • application.properties ファイルを使用します。

     アプリケーションが実行される $PWD/config/application.properties ディレクトリーに設定ファイルを配置し、そのファイルで定義されているランタイムプロパティーがデフォルトの設定をオーバーライドできるようにします。

     注記

     開発モードで config/application.properties 機能を使用することもできます。config/application.properties ファイルを target ディレクトリーに配置します。ビルドツールからのクリーニング操作 (mvn clean など) では、config ディレクトリーも削除されます。

手順

1. Java リソースファイルを開き、以下のインポートステートメントを追加します。

   import io.quarkus.runtime.configuration.ConfigUtils;

   Copy to Clipboard Toggle word wrap

2. 現在のプロファイルのリストを取得するには、ConfigUtils.getProfiles() メソッドを呼び出してログを追加します。

   LOGGER.infof("The application is starting with profiles `%s`", ConfigUtils.getProfiles());

   Copy to Clipboard Toggle word wrap

手順

1. org.eclipse.microprofile.config.spi.ConfigSourceProvider インターフェイスを実装するプロジェクトでクラスファイルを作成します。ConfigSource オブジェクトのリストを返すには、getConfigSources() メソッドをオーバーライドする必要があります。

   org.acme.config.InMemoryConfigSourceProvider の例

   package org.acme.config;
   
   import org.eclipse.microprofile.config.spi.ConfigSource;
   import org.eclipse.microprofile.config.spi.ConfigSourceProvider;
   
   import java.util.List;
   
   public class InMemoryConfigSourceProvider implements ConfigSourceProvider {
   
       @Override
       public Iterable<ConfigSource> getConfigSources(ClassLoader classLoader) {
       return List.of(new InMemoryConfigSource());
       }
   }

   Copy to Clipboard Toggle word wrap

2. org.eclipse.microprofile.config.spi.ConfigSource インターフェイスを実装する InMemoryConfigSource クラスを作成します。

   org.acme.config.InMemoryConfigSource の例

   package org.acme.config;
   
   import org.eclipse.microprofile.config.spi.ConfigSource;
   
   import java.util.HashMap;
   import java.util.Map;
   import java.util.Set;
   
   public class InMemoryConfigSource implements ConfigSource {
   private static final Map<String, String> configuration = new HashMap<>();
   
   
     static {
         configuration.put("my.prop", "1234");
     }
   
       @Override
       public int getOrdinal() { 

   1

   
         return 275;
       }
   
       @Override
       public Set<String> getPropertyNames() {
         return configuration.keySet();
       }
   
       @Override
       public String getValue(final String propertyName) {
         return configuration.get(propertyName);
       }
   
       @Override
       public String getName() {
         return InMemoryConfigSource.class.getSimpleName();
       }
   }

   Copy to Clipboard Toggle word wrap

   1

   getOrdinal() メソッドは、ConfigSource クラスの優先度を返します。そのため、複数の設定ソースが同じプロパティーを定義している場合でも、Quarkus は最も優先度の高いConfigSource クラスで定義されている適切な値を選択できます。

3. プロジェクトの src/main/resources/META-INF/services/ サブディレクトリーに org.eclipse.microprofile.config.spi.ConfigSourceProvider という名前のファイルを作成し、作成したファイルに ConfigSourceProvider を実装するクラスの完全修飾名を入力します。

   org.eclipse.microprofile.config.spi.ConfigSourceProvider ファイルの例:

   org.acme.config.InMemoryConfigSourceProvider

   Copy to Clipboard Toggle word wrap

   アプリケーションをコンパイルして開始する際に、作成した ConfigSourceProvider が確実に登録およびインストールされているようにするには、前の手順を完了する必要があります。

4. プロジェクト内の GreetingResource.java ファイルを編集して、次の更新を追加します。

   @ConfigProperty(name="my.prop") int value;

   Copy to Clipboard Toggle word wrap

5. GreetingResource.java ファイルで、hello メソッドを展開して新しいプロパティーを使用します。

   @GET
   @Produces(MediaType.TEXT_PLAIN)
   public String hello() {
     return message + " " + name.orElse("world") + " " + value;
   }

   Copy to Clipboard Toggle word wrap

6. 以下のコマンドを入力して、開発モードでアプリケーションをコンパイルし、起動します。

   ./mvnw quarkus:dev

   Copy to Clipboard Toggle word wrap

7. ターミナルウィンドウを開いて次のコマンドを入力し、/greeting エンドポイントが予期したメッセージを返すことを確認します。

   要求の例

   curl http://localhost:8080/greeting

   Copy to Clipboard Toggle word wrap

8. アプリケーションがカスタム設定を正常に読み取ると、コマンドは次のレスポンスを返します。

   hello world 1234

   Copy to Clipboard Toggle word wrap

手順

1. org.acme.config パッケージで、次の内容を含む org.acme.config.MyCustomValue クラスを作成します。

   カスタム設定値の例

   package org.acme.config;
   
   public class MyCustomValue {
   
       private final int value;
   
       public MyCustomValue(Integer value) {
           this.value = value;
       }
   
       public int value() {
           return value;
       }
   }

   Copy to Clipboard Toggle word wrap

2. コンバータークラスを実装し、convert メソッドをオーバーライドして MyCustomValue インスタンスを生成します。

   コンバータークラスの実装例

   package org.acme.config;
   
   import org.eclipse.microprofile.config.spi.Converter;
   
   public class MyCustomValueConverter implements Converter<MyCustomValue> {
   
       @Override
       public MyCustomValue convert(String value) {
           return new MyCustomValue(Integer.valueOf(value));
       }
   }

   Copy to Clipboard Toggle word wrap

3. コンバーターの完全修飾クラス名 org.acme.config.MyCustomValueConverter を META-INF/services/org.eclipse.microprofile.config.spi.Converter サービスファイルに追加します。

4. GreetingResource.java ファイルに、MyCustomValue プロパティーを注入します。

   @ConfigProperty(name="custom")
   MyCustomValue value;

   Copy to Clipboard Toggle word wrap

5. この値を使用するように hello メソッドを編集します。

   @GET
   @Produces(MediaType.TEXT_PLAIN)
   public String hello() {
       return message + " " + name.orElse("world") + " - " + value.value();
   }

   Copy to Clipboard Toggle word wrap

6. application.properties ファイルに、変換する文字列表現を追加します。

   custom=1234

   Copy to Clipboard Toggle word wrap

7. 以下のコマンドを入力して、開発モードでアプリケーションをコンパイルし、起動します。

   ./mvnw quarkus:dev

   Copy to Clipboard Toggle word wrap

8. ターミナルウィンドウを開いて次のコマンドを入力し、/greeting エンドポイントが予期したメッセージを返すことを確認します。

   要求の例

   curl http://localhost:8080/greeting

   Copy to Clipboard Toggle word wrap

9. アプリケーションがカスタム設定を正常に読み取ると、コマンドは次のレスポンスを返します。

   hello world - 1234

   Copy to Clipboard Toggle word wrap
   注記

   カスタムコンバータークラスは public で、引数なしのコンストラクター public がなければなりません。カスタムコンバータークラスは abstract であってはなりません。