Chapter 1. Configuring your Red Hat build of Quarkus applications by using a properties file

Procedure

1. Verify that Maven uses OpenJDK 17 or 21 and that the Maven version is 3.9.9:

   Copy to Clipboard Toggle word wrap

   mvn --version

2. If the mvn command does not return OpenJDK 17 or 21, ensure that the directory where OpenJDK 17 or 21 is installed on your system is included in the PATH environment variable:

   Copy to Clipboard Toggle word wrap

   export PATH=$PATH:<path_to_JDK>

3. Enter the following command to generate the project:

   Copy to Clipboard Toggle word wrap

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

Procedure

1. Open the src/main/resources/application.properties file.

2. Add configuration properties to your configuration file where <property_name> is the property name and <value> is the value of the property:

   Copy to Clipboard Toggle word wrap

   <property_name>=<value>

   The following example shows how to set the values for the greeting.message and the greeting.name properties in the Quarkus config-quickstart project:

   Example application.properties file

   Copy to Clipboard Toggle word wrap

   greeting.message=hello
   greeting.name=quarkus

   Important

   When you are configuring your applications, do not prefix application-specific properties with the string quarkus. The quarkus prefix is reserved for configuring Quarkus at the framework level. Using quarkus as a prefix for application-specific properties might lead to unexpected results when your application runs.

3. Review the GreetingResource.java Java file in your project. The file contains the GreetingResource class with the hello() method that returns a message when you send an HTTP request on the /greeting endpoint:

   Example GreetingResource.java file

   Copy to Clipboard Toggle word wrap

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

   In the example provided, the values of the message and name strings in the hello() method are not initialized. The application throws a NullPointerException when the endpoint is called and starts successfully in this state.

4. Define the message, name, and suffix fields, and annotate them with @ConfigProperty, matching the values that you defined for the greeting.message and greeting.name properties. Use the @ConfigProperty annotation to inject the configuration value for each string. For example:

   Example GreetingResource.java file

   Copy to Clipboard Toggle word wrap

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

   1

   If you do not configure a value for the greeting.message string, the application fails and throws the following exception: 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

   If you do not configure a value for the greeting.suffix, Quarkus resolves it to the default value.

   3

   If you do not define the greeting.name property, the value of name is not available. Your application still runs even when this value is not available because you set the Optional parameter on name.

   Note

   To inject a configured value, you can use @ConfigProperty. You do not need to include the @Inject annotation for members that you annotate with @ConfigProperty.

5. Compile and start your application in development mode:

   Copy to Clipboard Toggle word wrap

   ./mvnw quarkus:dev

6. Enter the following command in a new terminal window to verify that the endpoint returns the message:

   Copy to Clipboard Toggle word wrap

   curl http://localhost:8080/greeting

   This command returns the following output:

   Copy to Clipboard Toggle word wrap

   hello quarkus!

7. To stop the application, press Ctrl+C.

Procedure

1. Open the GreetingResourceTest.java file.

2. Update the content of the testHelloEndpoint method:

   Copy to Clipboard Toggle word wrap

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

3. Compile and start your application in development mode:

   Copy to Clipboard Toggle word wrap

   ./mvnw quarkus:dev

4. To start running the tests, press r on your keyboard.

Procedure

1. To package your Quarkus project, enter the following command:

   Copy to Clipboard Toggle word wrap

   ./mvnw clean package

2. Use one of the following methods to set the configuration properties:

   • Setting system properties:

     Enter the following command, where <property_name> is the name of the configuration property that you want to add and <value> is the value of the property:

     Copy to Clipboard Toggle word wrap

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

     For example, to set the value of the greeting.suffix property to ?, enter the following command:

     Copy to Clipboard Toggle word wrap

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

   • Setting environment variables:

     Enter the following command, where <property_name> is the name of the configuration property that you want to set and <value> is the value of the property:

     Copy to Clipboard Toggle word wrap

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

     Note

     Environment variable names follow the conversion rules of Eclipse MicroProfile. Convert the name to upper case and replace any character that is not alphanumeric with an underscore (_).

   • Using an environment file:

     Create a .env file in your current working directory and add configuration properties, where <PROPERTY_NAME> is the property name and <value> is the value of the property:

     Copy to Clipboard Toggle word wrap

     <PROPERTY_NAME>=<value>

     Note

     In development mode, this file is in the root directory of your project. Do not track the file in version control. If you create a .env file in the root directory of your project, you can define keys and values that the program reads as properties.

   • Using the application.properties file:

     Place the configuration file in the $PWD/config/application.properties directory where the application runs so that any runtime properties that are defined in that file override the default configuration.

     Note

     You can also use the config/application.properties features in development mode. Place the config/application.properties file inside the target directory. Any cleaning operation from the build tool, for example, mvn clean, also removes the config directory.

Procedure

1. Open the application.properties file in the src/main/resources directory of your project.

2. Add profile-specific configuration using one of the following approaches:

   • Add a property to your properties file and prefix it with a profile name nested between % and ., such as %dev., %test., or %prod.. For example:

     Copy to Clipboard Toggle word wrap

     %dev.quarkus.datasource.username=devuser
     %prod.quarkus.datasource.username=produser

   • Alternatively, create a profile-specific configuration file such as application-dev.properties, application-test.properties, or application-prod.properties to contain the profile-specific values.

     Example application-dev.properties

     Copy to Clipboard Toggle word wrap

     quarkus.datasource.username=devuser

3. Activate a profile at runtime by setting the quarkus.profile configuration option as a system property or environment variable:

   Copy to Clipboard Toggle word wrap

   $ ./mvnw package -Dquarkus.profile=<profile>

   Replace <profile> with one or more comma-separated profile names, such as dev, test, or prod.

Procedure

1. In your project, create a new class that implements the org.eclipse.microprofile.config.spi.ConfigSourceProvider interface. Override the getConfigSources() method to return a list of your custom ConfigSource objects.

   Example org.acme.config.InMemoryConfigSourceProvider

   Copy to Clipboard Toggle word wrap

   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. To define your custom configuration source, create an InMemoryConfigSource class that implements the org.eclipse.microprofile.config.spi.ConfigSource interface:

   Example org.acme.config.InMemoryConfigSource

   Copy to Clipboard Toggle word wrap

   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

   The getOrdinal() method returns the priority of the ConfigSource class. Therefore, when multiple configuration sources define the same property, Quarkus can select the appropriate value as defined by the ConfigSource class with the highest priority.

3. In the src/main/resources/META-INF/services/ subdirectory of your project, create a file named org.eclipse.microprofile.config.spi.ConfigSourceProvider and enter the fully-qualified name of the class that implements the ConfigSourceProvider in the file that you created:

   Example org.eclipse.microprofile.config.spi.ConfigSourceProvider file:

   Copy to Clipboard Toggle word wrap

   org.acme.config.InMemoryConfigSourceProvider

   To ensure that the ConfigSourceProvider that you created is registered and installed when you compile and start your application, you must complete the previous step.

4. Edit the GreetingResource.java file in your project to add the following update:

   Copy to Clipboard Toggle word wrap

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

5. In the GreetingResource.java file, extend the hello method to use the new property:

   Copy to Clipboard Toggle word wrap

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

6. Compile and start your application in development mode:

   Copy to Clipboard Toggle word wrap

   ./mvnw quarkus:dev

7. Open a terminal window and send a request to the /greeting endpoint:

   Copy to Clipboard Toggle word wrap

   curl http://localhost:8080/greeting

8. Verify that your application has read the custom configuration and returned the expected message:

   Copy to Clipboard Toggle word wrap

   hello world 1234

Procedure

1. In the org.acme.config package, create the org.acme.config.MyCustomValue class with the following content:

   Example of custom configuration value

   Copy to Clipboard Toggle word wrap

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

2. Implement the converter class to override the convert method to produce a MyCustomValue instance.

   Example implementation of converter class

   Copy to Clipboard Toggle word wrap

   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. Add the fully-qualified class name of the converter, org.acme.config.MyCustomValueConverter, to your META-INF/services/org.eclipse.microprofile.config.spi.Converter service file.

4. In the GreetingResource.java file, inject the MyCustomValue property:

   Copy to Clipboard Toggle word wrap

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

5. Edit the hello method to use this value:

   Copy to Clipboard Toggle word wrap

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

6. In the application.properties file, add the string representation to be converted:

   Copy to Clipboard Toggle word wrap

   custom=1234

7. To compile and start your application in development mode, enter the following command:

   Copy to Clipboard Toggle word wrap

   ./mvnw quarkus:dev

8. To verify that the /greeting endpoint returns the expected message, open a terminal window and enter the following command:

   Copy to Clipboard Toggle word wrap

   curl http://localhost:8080/greeting

9. When your application successfully reads the custom configuration, the command returns the following response:

   Copy to Clipboard Toggle word wrap

   hello world - 1234

   Note

   Your custom converter class must be public and must have a public no-argument constructor. Your custom converter class cannot be abstract.