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:

    src/main/resources/application.properties

    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 corresponding properties by annotating them with @ConfigProperty as shown in the following example:

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

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

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

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

  6. Compile and start your application in development mode: 

    ./mvnw quarkus:dev

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

    curl http://localhost:8080/greeting

    This command returns the following output: 

    hello quarkus!
  8. Press CTRL+C to stop the application.

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:

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

    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:

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

    import io.quarkus.arc.config.ConfigProperties;
import java.util.Optional;
import javax.inject.Inject;

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

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

    @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 specify a prefix, it is determined by the name of the class. In this example, the prefix is greeting.
    2
    If greeting.suffix is not set, ! is the default value.

  5. Inject the GreetingConfiguration class into the GreetingResource class using the @Inject annotation:

    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.getMessage() + " " + config.getName().orElse("world") + config.getSuffix();
    }
}

  6. Compile and start your application in development mode: 

    ./mvnw quarkus:dev
    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. Enter the following command in a new terminal window to verify that the endpoint returns the message: 

    curl http://localhost:8080/greeting

  8. You receive the following message: 

    hello quarkus!
  9. Press CTRL+C to stop the application.

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:

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

    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:

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

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

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

  3. Add a nested class inside the GreetingConfiguration class as shown in the following example:

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

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

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

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

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

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

    The following example shows the values of properties for the GreetingConfiguration and ContentConfig classes:

    src/main/resources/application.properties

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

  5. Inject the GreetingConfiguration class into the GreetingResource class using the @Inject annotation, and update the message string that the /greeting endpoint returns to have the message show the values that you set for the new greeting.content.prize-amount and greeting.content.recipients properties that you added:

    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 + "\n" + config.content.recipients + " receive total of candies: " + config.content.prizeAmount;
    }
}

  6. Compile and start your application in development mode: 

    ./mvnw quarkus:dev
    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. Enter the following command in a new terminal window to verify that the endpoint returns the message: 

    curl http://localhost:8080/greeting

  8. You receive the message that contains the greeting on the first line and the recipients of the prize and the prize amount on the second line: 

    hello quarkus!
Jane,John receive total of candies: 10
  9. Press CTRL+C to stop the application.
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:

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

    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:

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

    @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. Inject the GreetingConfiguration class into the GreetingResource class using the @Inject annotation:

    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.getName().orElse("world") + config.getSuffix();
    }
}

  4. Compile and start your application in development mode: 

    ./mvnw quarkus:dev
    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.

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

    curl http://localhost:8080/greeting

  6. You receive the following message: 

    hello quarkus!
  7. Press CTRL+C to stop the application.