Configuring your Quarkus applications

Procedure

1. In a command terminal, enter the following command to verify that Maven is using JDK 11 and that the Maven version is 3.6.3 or higher:

   mvn --version

2. If the preceding command does not return JDK 11, add the path to JDK 11 to the PATH environment variable and enter the preceding command again.

3. To generate the project, enter the following command:

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

   This command creates the following elements in the ./config-quickstart directory:

   • The Maven structure
   • An org.acme.config.GreetingResource resource
   • A landing page that is accessible on http://localhost:8080 after you start the application
   • Example Dockerfile file in src/main/docker
   • The application configuration file

   • An associated test

     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 <key> is the property name and <value> is the value of the property:

   <key>=<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:

   greeting.message = hello
   greeting.name = quarkus

   Important

   Use quarkus as a prefix to Quarkus properties.

3. Review the GreetingResource.java file and make sure it includes the following import statements:

   import org.eclipse.microprofile.config.inject.ConfigProperty;
   import java.util.Optional;

4. Define the equivalent properties by annotating them with the following syntax:

   @ConfigProperty(name = "greeting.message") 1
   String message;
   
   @ConfigProperty(name = "greeting.suffix", defaultValue="!") 2
   String suffix;
   
   @ConfigProperty(name = "greeting.name")
   Optional<String> name; 3

   1

   If you do not provide a value for this property, the application will fail and throw the following exception message:
   javax.enterprise.inject.spi.DeploymentException: No config value of type [class java.lang.String] exists for: greeting.message

   2

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

   3

   If the Optional parameter does not have a value, it returns no value for greeting.name.

   Note

   To inject a configured value, you can use @ConfigProperty. The @Inject annotation is not necessary for members annotated with @ConfigProperty.

5. Edit your hello method to return the following message:

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

6. To compile your Quarkus application in development mode, enter the following command from the project directory:

   ./mvnw quarkus:dev

7. To verify that the endpoint returns the message, enter the following command in a new terminal window:

   curl http://localhost:8080/greeting

   This command returns the following output:

   hello quarkus!

8. To stop the application, press CTRL+C

Procedure

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

   ./mvnw clean package

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

   • Setting system properties:

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

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

     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

   • Setting environment variables:

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

     export <key>=<value> ; java -jar target/myapp-runner.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 an .env file in your current working directory and add configuration properties where <key> is the property name and <value> is the value of the property:

     <key>=<value>

     Note

     For development mode, this file can be located in the root directory of your project, but it is advised to not track the file in version control. If you create an .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 $PWD/config/application.properties directory where the application runs so any runtime properties 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 inside the target directory. Any cleaning operation from the build tool, for example mvn clean, will remove the config directory as well.

Procedure

1. Open your Java resource file and add the following import statement:

   import io.quarkus.runtime.configuration.ProfileManager;

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

   Note

   It is not possible to access the current profile using the @ConfigProperty("quarkus.profile") method.

Procedure

1. Create an ExampleConfigSourceProvider.java file within your project and add the following imports:

   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;

2. Create a class implementing the ConfigSourceProvider interface and make sure to override its getConfigSources method to return a list of ConfigSource objects:

   The following example shows an implementation of a custom ConfigSourceProvider and a ConfigSource classes:

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

3. Create the org.eclipse.microprofile.config.spi.ConfigSourceProvider service file in the META-INF/services/ directory.

4. Open the org.eclipse.microprofile.config.spi.ConfigSourceProvider file and add the fully qualified name of your custom ConfigSourceProvider class:

   org.acme.config.ExampleConfigSourceProvider

5. To compile the application in development mode, enter the following command from the project directory:

   ./mvnw quarkus:dev

   When you restart your application, Quarkus picks up the custom configuration provider.

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:

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

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

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

   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;

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

Procedure

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

   ./mvnw clean package

   This command produces the following JAR files in the /target directory:

   • config-quickstart-1.0-SNAPSHOT.jar: Contains the classes and resources of the projects. This is the regular artifact produced by the Maven build.
   • config-quickstart-1.0-SNAPSHOT-runner.jar: Is an executable JAR file. Be aware that this file is not an uber-JAR file because the dependencies are copied into the target/lib directory.
2. If development mode is running, press CTRL+C to stop development mode. If you do not do this, you will have a port conflict.

3. To run the application, enter the following command:

   java -jar target/config-quickstart-1.0-SNAPSHOT-runner.jar

   Note

   The Class-Path entry of the MANIFEST.MF file from the runner JAR file explicitly lists the JAR files from the lib directory. If you want to deploy your application from another location, you must copy the runner JAR file as well as the lib directory.