Chapter 4. Injecting configuration values into your Quarkus application

Red Hat build of Quarkus uses the MicroProfile Config feature to inject configuration data into the application. You can access the configuration through context and dependency injection (CDI) or by using a method defined in your code.

You can use the @ConfigProperty annotation to map an object property to a key in the MicroProfile ConfigSources file of your application. This procedure shows you how to inject an individual property configuration into a Quarkus config-quickstart project.

Prerequisites

  • You have created the Quarkus config-quickstart project.

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

4.1. Annotating a class with @ConfigProperties

As an alternative to injecting multiple related configuration values individually, you can use the @io.quarkus.arc.config.ConfigProperties annotation to group configuration properties. The following procedure demonstrates the use of @ConfigProperties annotation on the Quarkus config-quickstart project.

Prerequisites

  • You have created the Quarkus config-quickstart project.

Procedure

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

    package org.acme.config;

import java.util.Optional;
import javax.inject.Inject;
  2. Create a file GreetingConfiguration.java in the src/main/java/org/acme/config directory.

  3. Add the @ConfigProperties and @Optional imports to the GreetingConfiguration.java file: 

    package org.acme.config;

import io.quarkus.arc.config.ConfigProperties;
import java.util.Optional;

  4. Create a GreetingConfiguration class for the greeting properties in your GreetingConfiguration.java file: 

    @ConfigProperties(prefix = "greeting") 1
public class GreetingConfiguration {

    private String message;
    private String suffix = "!"; 2
    private Optional<String> name;

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public String getSuffix() {
        return suffix;
    }

    public void setSuffix(String suffix) {
        this.suffix = suffix;
    }

    public Optional<String> getName() {
        return name;
    }

    public void setName(Optional<String> name) {
        this.name = name;
    }
}
    1
    prefix is optional. If you do not set the prefix, it will be determined by the class name. In this example, it will be greeting.
    2
    If greeting.suffix is not set, ! will be the default value.

  5. Inject the attribute into the GreetingResource class using the context and dependency injection (CDI) @Inject annotation: 

    @Inject
GreetingConfiguration greetingConfiguration;

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

    ./mvnw quarkus:dev
    Important

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

4.2. Using nested object configuration

You can define a nested class inside an existing class. This procedure demonstrates how to create a nested class configuration in the Quarkus config-quickstart project.

Prerequisites

  • You have created the Quarkus config-quickstart project.

Procedure

  1. Review the GreetingConfiguration.java file and make sure it includes the following import statements: 

    import io.quarkus.arc.config.ConfigProperties;
import java.util.Optional;
import java.util.List;

  2. Add the configuration in your GreetingConfiguration.java file using the @ConfigProperties annotation.

    The following example shows the configuration of the GreetingConfiguration class and its properties: 

    @ConfigProperties(prefix = "greeting")
public class GreetingConfiguration {

    public String message;
    public String suffix = "!";
    public Optional<String> name;
}

  3. Add a nested class configuration similar to the following example: 

    @ConfigProperties(prefix = "greeting")
public class GreetingConfiguration {

    public String message;
    public String suffix = "!";
    public Optional<String> name;
    public HiddenConfig hidden;

    public static class HiddenConfig {
        public Integer prizeAmount;
        public List<String> recipients;
    }
}

    This example shows a nested class HiddenConfig. The name of the field, in this case hidden, determines the name of the properties bound to the object.

  4. Add the equivalent configuration properties to your application.properties file.

    The following example shows the value of properties for the GreetingConfiguration and HiddenConfig classes: 

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

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

    ./mvnw quarkus:dev
Note

Classes annotated with @ConfigProperties can be annotated with Bean Validation annotations similar to the following example: 

@ConfigProperties(prefix = "greeting")
public class GreetingConfiguration {

    @Size(min = 20)
    public String message;
    public String suffix = "!";
}

Your project must include the quarkus-hibernate-validator dependency.

4.3. Annotating an interface with @ConfigProperties

An alternative method for managing properties is to define them as an interface. If you annotate an interface with @ConfigProperties, the interface can extend other interfaces, and you can use methods from the entire interface hierarchy to bind properties.

This procedure shows an implementation of the GreetingConfiguration class as an interface in the Quarkus config-quickstart project.

Prerequisites

  • You have created the Quarkus config-quickstart project.

Procedure

  1. Review the GreetingConfiguration.java file and make sure it includes the following import statements: 

    package org.acme.config;

import io.quarkus.arc.config.ConfigProperties;
import org.eclipse.microprofile.config.inject.ConfigProperty;
import java.util.Optional;

  2. Add a GreetingConfiguration class as an interface to your GreetingConfiguration.java file: 

    @ConfigProperties(prefix = "greeting")
public interface GreetingConfiguration {

    @ConfigProperty(name = "message") 1
    String message();

    @ConfigProperty(defaultValue = "!")
    String getSuffix(); 2

    Optional<String> getName(); 3
}
    1
    You must set the @ConfigProperty annotation because the name of the configuration property does not follow the getter method naming conventions.
    2
    In this example, name was not set so the corresponding property will be greeting.suffix.
    3
    You do not need to specify the @ConfigProperty annotation because the method name follows the getter method naming conventions (greeting.name being the corresponding property) and no default value is needed.

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

    ./mvnw quarkus:dev
    Important

    If you do not provide a value for an interface field, the application fails and an javax.enterprise.inject.spi.DeploymentException is thrown indicating a missing value. This does not apply to Optional fields and fields with a default value.