Chapter 1. Configuring your Quarkus applications

Procedure

1. Review the GreetingResource.java file in your project and ensure that it contains the contents that are shown in this example. To use the @ConfigPoperties annotation to inject configuration properties from another configuration source into this class, you must import the java.util.Optional and org.eclipse.microprofile.config.inject.ConfigProperty packages.

   src/main/java/org/acme/config/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")
       String message;
   
       @ConfigProperty(name = "greeting.suffix", defaultValue="!")
       String suffix;
   
       @ConfigProperty(name = "greeting.name")
       Optional<String> name;
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return message + " " + name.orElse("world") + suffix;
       }
   }

   Copy to Clipboard Toggle word wrap

2. Create a GreetingConfiguration.java file in the src/main/java/org/acme/config directory. Add the import statements for ConfigMapping and Optional to the file:

   src/main/java/org/acme/config/GreetingConfiguration.java

   import io.smallrye.config.ConfigMapping;
   import io.smallrye.config.WithDefault;
   import java.util.Optional;
   
   @ConfigMapping(prefix = "greeting")
   public interface GreetingConfiguration {
       String message();
   
       @WithDefault("!")
       String suffix();
   
       Optional<String> name();
   }

   Copy to Clipboard Toggle word wrap

   The prefix property is optional. For example, in this scenario, the prefix is greeting.

   If greeting.suffix is not set, ! is used as the default value.

3. Inject the GreetingConfiguration instance into the GreetingResource class by using the @Inject annotation, as follows:

   Note

   This snippet replaces the three fields that are annotated with @ConfigProperty that are in the initial version of the config-quickstart project.

   src/main/java/org/acme/config/GreetingResource.java

   @Path("/greeting")
   public class GreetingResource {
   
       @Inject
       GreetingConfiguration config;
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return config.message() + " " + config.name().orElse("world") + config.suffix();
       }
   }

   Copy to Clipboard Toggle word wrap

4. Compile and start your application in development mode:

   ./mvnw quarkus:dev

   Copy to Clipboard Toggle word wrap
   Important

   If you do not provide values for the class properties, the application fails to compile and a io.smallrye.config.ConfigValidationException error is returned to indicate that a value is missing. This does not apply to fields that are optional or fields with a default value.

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

   curl http://localhost:8080/greeting

   Copy to Clipboard Toggle word wrap

6. You receive the following message:

   hello quarkus!

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

Procedure

1. Review the GreetingResource.java 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:

   src/main/java/org/acme/config/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")
       String message;
   
       @ConfigProperty(name = "greeting.suffix", defaultValue="!")
       String suffix;
   
       @ConfigProperty(name = "greeting.name")
       Optional<String> name;
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return message + " " + name.orElse("world") + suffix;
       }
   }

   Copy to Clipboard Toggle word wrap

2. Create a GreetingConfiguration.java class file with the GreetingConfiguration instance. This class contains the externalized configuration for the hello() method that is defined in the GreetingResource class:

   src/main/java/org/acme/config/GreetingConfiguration.java

   import io.smallrye.config.ConfigMapping;
   import io.smallrye.config.WithDefault;
   import java.util.Optional;
   
   @ConfigMapping(prefix = "greeting")
   public interface GreetingConfiguration {
       String message();
   
       @WithDefault("!")
       String suffix();
   
       Optional<String> name();
   }

   Copy to Clipboard Toggle word wrap

3. Create the ContentConfig class that is nested inside the GreetingConfiguration instance, as shown in the following example:

   src/main/java/org/acme/config/GreetingConfiguration.java

   import io.smallrye.config.ConfigMapping;
   import io.smallrye.config.WithDefault;
   
   import java.util.List;
   import java.util.Optional;
   
   @ConfigMapping(prefix = "greeting")
   public interface GreetingConfiguration {
       String message();
   
       @WithDefault("!")
       String suffix();
   
       Optional<String> name();
   
       ContentConfig content();
   
       interface ContentConfig {
           Integer prizeAmount();
   
           List<String> recipients();
       }
   }

   Copy to Clipboard Toggle word wrap

   Note

   The method name of the ContentConfig class is content. To ensure that you bind the properties to the correct interface, when you define configuration properties for this class, use content in the prefix. Doing this can also prevent property name conflicts and unexpected application behavior.

4. Define the greeting.content.prize-amount and greeting.content.recipients configuration properties in your application.properties file.

   The following example shows the properties defined for the GreetingConfiguration instance and the ContentConfig classes:

   src/main/resources/application.properties

   greeting.message = hello
   greeting.name = quarkus
   greeting.content.prize-amount=10
   greeting.content.recipients=Jane,John

   Copy to Clipboard Toggle word wrap

5. Instead of the three @ConfigProperty field annotation, inject the GreetingConfiguration instance into the GreetingResource class by using the @Inject annotation, as outlined in the following example. You must also update the message string that the /greeting endpoint returns with the values that you set for the new greeting.content.prize-amount and also the greeting.content.recipients properties that you have added.

   src/main/java/org/acme/config/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 javax.inject.Inject;
   
   @Path("/greeting")
   public class GreetingResource {
   
       @Inject
       GreetingConfiguration config;
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return config.message() + " " + config.name().orElse("world") + config.suffix() + "\n" + config.content().recipients() + " receive total of candies: " + config.content().prizeAmount();
       }
   }

   Copy to Clipboard Toggle word wrap

6. Compile and start your application in development mode:

   ./mvnw quarkus:dev

   Copy to Clipboard Toggle word wrap
   Important

   If you do not provide values for the class properties, the application fails to compile and you receive a javax.enterprise.inject.spi.DeploymentException that indicates a missing value. This does not apply to Optional fields and fields with a default value.

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

   curl http://localhost:8080/greeting

   Copy to Clipboard Toggle word wrap

8. A message displays containing two lines of output. The first line displays the greeting, and the second line reports the recipients of the prize together with the prize amount, as follows:

   hello quarkus!
   Jane,John receive total of candies: 10

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

Procedure

1. Open the src/main/resources/application.yaml configuration file.

2. Add the nested class configuration properties to your application.yaml file as shown in the following example:

   src/main/resources/application.yaml

   # Properties that configure the JDBC data source driver of your PostgreSQL data source
   quarkus:
     datasource:
       url: jdbc:postgresql://localhost:5432/some-database
       driver: org.postgresql.Driver
       username: quarkus
       password: quarkus
   
   # Property that configures the URL of the endpoint to which the rest client sends requests
   org:
     acme:
       restclient:
         CountriesService/mp-rest/url: https://restcountries.eu/rest
   
   # Property that configures the log message level for your application
   quarkus:
     log:
       category:
   
   # Do not use spaces in names of configuration properties that you place inside quotation marks
         "io.quarkus.category":
           level: INFO

   Copy to Clipboard Toggle word wrap

   In a similar way to how you use comments in the application.properties file, you can use comments to describe your configuration properties in YAML format.

   Note

   Always use spaces to indent the properties in your YAML configuration file. YAML does not allow you to use tabs for indentation.

Procedure

1. Open the src/main/resources/application.yaml configuration file.

2. To set a profile dependent configuration, add the profile name before defining the key-value pairs by using the "%<profile_name>" syntax. Ensure that you place the profile name inside quotation marks.

   Tip

   In YAML, all strings that begin with a special character must be placed inside quotation marks.

   In the following example, the PostgreSQL database is configured to be available at the jdbc:postgresql://localhost:5432/some-database URL when you start your Quarkus application in development mode:

   src/main/resources/application.yaml

   "%dev":
     # Properties that configure the JDBC data source driver of your PostgreSQL data source
     quarkus:
       datasource:
         url: jdbc:postgresql://localhost:5432/some-database
         driver: org.postgresql.Driver
         username: quarkus
         password: quarkus

   Copy to Clipboard Toggle word wrap

Procedure

1. Open your YAML configuration file.

2. To define a YAML property as a prefix of another property, add a tilde (~) in the scope of the property as shown in the following example:

   quarkus:
     http:
       cors:
         ~: true
         methods: GET,PUT,POST

   Copy to Clipboard Toggle word wrap

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

   ./mvnw quarkus:dev

   Copy to Clipboard Toggle word wrap
   Note

   You can use YAML keys for conflicting configuration keys at any level because they are not included in the assembly of configuration property name.

Procedure

1. To set a custom profile, create a configuration property with the profile name in the application.properties file, where <property_name> is the name of the property, <value> is the property value, and <profile> is the name of a profile:

    %<profile>.<property_name>=<value>

   Copy to Clipboard Toggle word wrap

   In the following example configuration, the value of quarkus.http.port is 9090 by default, and becomes 8181 when the dev profile is activated:

   quarkus.http.port=9090
   %dev.quarkus.http.port=8181

   Copy to Clipboard Toggle word wrap

2. Use one of the following methods to enable a profile:

   • Set the quarkus.profile system property.

     • To enable a profile using the quarkus.profile system property, enter the following command:

       mvn -Dquarkus.profile=<value> quarkus:dev

       Copy to Clipboard Toggle word wrap

   • Set the QUARKUS_PROFILE environment variable.

     • To enable profile using an environment variable, enter the following command:

       export QUARKUS_PROFILE=<profile>

       Copy to Clipboard Toggle word wrap
       Note

       The system property value takes precedence over the environment variable value.

3. To repackage the application and change the profile, enter the following command:

   ./mvnw package -Dquarkus.profile=<profile>
    java -jar target/myapp-runner.jar

   Copy to Clipboard Toggle word wrap

   The following example shows a command that activates the prod-aws profile:

   ./mvnw package -Dquarkus.profile=prod-aws
    java -jar target/myapp-runner.jar

   Copy to Clipboard Toggle word wrap

Procedure

1. Set a priority for your custom converter by annotating the class with the @Priority annotation and passing it a priority value. In the following example, the priority value is set to 150.

   ExampleCustomConverter.java

   package org.acme.config;
   
   import javax.annotation.Priority;
   import org.eclipse.microprofile.config.spi.Converter;
   
   @Priority(150)
   public class ExampleCustomConverter implements Converter<MicroProfileCustomValue> {
   
       @Override
       public MicroProfileCustomValue convert(String value) {
   
           final int secretNumber;
           if (value.startsFrom("OBF:")) {
               secretNumber = Integer.valueOf(SecretDecoder.decode(value));
           } else {
               secretNumber = Integer.valueOf(value);
           }
   
           return new MicroProfileCustomValue(secretNumber);
       }
   }

   Copy to Clipboard Toggle word wrap

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

   src/main/resources/META-INF/services/org.eclipse.microprofile.config.spi.Converter

   org.acme.config.ExampleCustomConverter

   Copy to Clipboard Toggle word wrap

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