プロパティーファイルを使用した Quarkus アプリケーションの設定

手順

1. Maven が OpenJDK 11 または 17 を使用し、Maven のバージョンが 3.8.x であることを確認します(x は 6 以降)。

   mvn --version

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

   export PATH=$PATH:<path_to_JDK>

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

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

手順

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

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

   <property_name>=<value>

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

   application.properties ファイルの例

   greeting.message = hello
   greeting.name = quarkus

   重要

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

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

   GreetingResource.java ファイルの例

   import java.util.Optional;
   
   import javax.ws.rs.GET;
   import javax.ws.rs.Path;
   import javax.ws.rs.Produces;
   import javax.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;
       }
   }

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

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

   GreetingResource.java ファイルの例

   import java.util.Optional;
   
   import javax.ws.rs.GET;
   import javax.ws.rs.Path;
   import javax.ws.rs.Produces;
   import javax.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;
      }
   }

   1

   greeting.message 文字列の値を設定しない場合、アプリケーションは失敗し、次の例外を出力します： javax.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

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

   curl http://localhost:8080/greeting

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

   hello quarkus!

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

手順

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

   ./mvnw clean package

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

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

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

     java -D<property_name>=<value> -jar target/myapp-runner.jar

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

     java -Dquarkus.datasource.password=youshallnotpass -jar target/myapp-runner.jar

   • 環境変数の設定

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

     export <property_name>=<value> ; java -jar target/myapp-runner.jar

     注記

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

   • 環境ファイルの使用

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

     <PROPERTY_NAME>=<value>

     注記

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

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

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

     注記

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

手順

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

   import io.quarkus.runtime.configuration.ProfileManager;

2. 現在の設定プロファイルを表示するには、ProfileManager.getActiveProfile() メソッドを呼び出してログを追加します。

   LOGGER.infof("The application is starting with profile `%s`", ProfileManager.getActiveProfile());

   注記

   @ConfigProperty("quarkus.profile") メソッドを使用して現在のプロファイルにアクセスすることはできません。

手順

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());
       }
   }

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();
       }
   }

   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

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

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

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

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

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

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

   ./mvnw quarkus:dev

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

   要求の例

   curl http://localhost:8080/greeting

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

   hello world 1234

手順

1. org.acme.config package で、次の内容を含む 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;
      }
   }

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));
       }
   }

3. 次の例に示すように、META-INF/services/org.eclipse.microprofile.config.spi.Converter サービスファイルにコンバーターの完全修飾クラス名を含めます。

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

   org.acme.config.MyCustomValueConverter
   org.acme.config.SomeOtherConverter
   org.acme.config.YetAnotherConverter

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

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

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

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

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

   custom=1234

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

   ./mvnw quarkus:dev

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

   要求の例

   curl http://localhost:8080/greeting

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

   hello world - 1234

   注記

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