Configuring your Quarkus applications by using a properties file

Procedure

1. Verify that Maven is using OpenJDK 11 or 17 and that the Maven version is 3.8.4 or higher:

   mvn --version

   Copy to Clipboard Toggle word wrap

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

   export PATH=$PATH:/path/to/jdk-11

   Copy to Clipboard Toggle word wrap

2. Enter the following command to generate the project:

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

   Copy to Clipboard Toggle word wrap

   Verification

   This command creates the following items in the config-quickstart directory:

   • The Maven project directory structure
   • An org.acme.config.GreetingResource resource
   • A landing page that you can access at http://localhost:8080 after you start the application
   • Associated unit tests for testing your application in native mode and JVM mode
   • Example Dockerfile.jvm and Dockerfile.native files in the src/main/docker subdirectory
   • The application configuration file
   Note

   Alternatively, you can download a Quarkus Maven project to use in this tutorial from the Quarkus quickstart archive or clone the Quarkus Quickstarts Git repository. The exercise is located in the config-quickstart directory.

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:

   <property_name>=<value>

   Copy to Clipboard Toggle word wrap

   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

   greeting.message = hello
   greeting.name = quarkus

   Copy to Clipboard Toggle word wrap

   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

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

   Copy to Clipboard Toggle word wrap

   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, as shown in the following example:

   Example GreetingResource.java file

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

   Copy to Clipboard Toggle word wrap

   1

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

   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 the name is not available. Your application still runs even when this value is not available because you set the Optional parameter on the 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:

   ./mvnw quarkus:dev

   Copy to Clipboard Toggle word wrap

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

   curl http://localhost:8080/greeting

   Copy to Clipboard Toggle word wrap

   This command returns the following output:

   hello quarkus!

   Copy to Clipboard Toggle word wrap
7. To stop the application, press Ctrl+C.

Procedure

1. Open the GreetingResourceTest.java file.

2. Update the content of the testHelloEndpoint method:

   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

Procedure

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

   ./mvnw clean package

   Copy to Clipboard Toggle word wrap

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:

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

     Copy to Clipboard Toggle word wrap

     For example, to set the value of the quarkus.datasource.password property, enter the following command:

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

     Copy to Clipboard Toggle word wrap

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

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

     Copy to Clipboard Toggle word wrap
     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:

     <PROPERTY_NAME>=<value>

     Copy to Clipboard Toggle word wrap
     Note

     For development mode, this file can be located in the root directory of your project, but it is recommended to 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 will 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 your Java resource file and add the following import statement:

   import io.quarkus.runtime.configuration.ProfileManager;

   Copy to Clipboard Toggle word wrap

2. To display the current configuration profile, add a log invoking the ProfileManager.getActiveProfile() method:

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

   Copy to Clipboard Toggle word wrap
   Note

   You cannot access the current profile by using the @ConfigProperty("quarkus.profile") method.

Procedure

1. Create a class file in your project that implements the org.eclipse.microprofile.config.spi.ConfigSourceProvider interface. To return a list of ConfigSource objects, you must override the getConfigSources() method.

   The following example shows a custom implementation of the ConfigSourceProvider and the ConfigSource interfaces:

   Example ExampleConfigSourceProvider.java file

   package org.acme.config;
   
   import java.util.Collections;
   import java.util.HashMap;
   import java.util.Map;
   import java.util.Set;
   
   import org.eclipse.microprofile.config.spi.ConfigSource;
   import org.eclipse.microprofile.config.spi.ConfigSourceProvider;
   
   public class ExampleConfigSourceProvider implements ConfigSourceProvider {
   
       private final int times = 2;
       private final String name = "example";
       private final String value = "value";
   
       @Override
       public Iterable<ConfigSource> getConfigSources(ClassLoader forClassLoader) {
           InMemoryConfigSource configSource = new InMemoryConfigSource(Integer.MIN_VALUE, "example config source");
           for (int i = 0; i < this.times; i++) {
               configSource.add(this.name + ".key" + (i + 1), this.value + (i + 1));
           }
           return Collections.singletonList(configSource);
       }
   
       private static final class InMemoryConfigSource implements ConfigSource {
   
           private final Map<String, String> values = new HashMap<>();
           private final int ordinal;
           private final String name;
   
           private InMemoryConfigSource(int ordinal, String name) {
               this.ordinal = ordinal;
               this.name = name;
           }
   
           public void add(String key, String value) {
               values.put(key, value);
           }
   
           @Override
           public Map<String, String> getProperties() {
               return values;
           }
   
           @Override
           public Set<String> getPropertyNames() {
               return values.keySet();
           }
   
           @Override
           public int getOrdinal() {
               return ordinal;
           }
   
           @Override
           public String getValue(String propertyName) {
               return values.get(propertyName);
           }
   
           @Override
           public String getName() {
               return name;
           }
       }
   }

   Copy to Clipboard Toggle word wrap

2. Create a file named org.eclipse.microprofile.config.spi.ConfigSourceProvider in the src/main/resources/META-INF/services/ subdirectory of your project, 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

   org.acme.config.ExampleConfigSourceProvider

   Copy to Clipboard Toggle word wrap

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

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

   ./mvnw quarkus:dev

   Copy to Clipboard Toggle word wrap

4. To verify that the /greeting endpoint returns the expected message, in a terminal window enter the following command:

   Example request

   curl http://localhost:8080/greeting

   Copy to Clipboard Toggle word wrap

5. When your application successfully reads the custom configuration, you receive the following response:

   Example response

   hello quarkus!

   Copy to Clipboard Toggle word wrap

Procedure

1. Include the fully qualified class name of the converter in your META-INF/services/org.eclipse.microprofile.config.spi.Converter service file as shown in the following example:

   Example org.eclipse.microprofile.config.spi.Converter file

   org.acme.config.MicroProfileCustomValueConverter
   org.acme.config.SomeOtherConverter
   org.acme.config.YetAnotherConverter

   Copy to Clipboard Toggle word wrap

2. Implement the converter class to override the convert method:

   Example of implementing the converter class

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

   Copy to Clipboard Toggle word wrap

   Note

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

3. Use your custom type as a configuration value:

   @ConfigProperty(name = "configuration.value.name")
   MicroProfileCustomValue value;

   Copy to Clipboard Toggle word wrap