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
-
Open the
src/main/resources/application.properties
file. 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 thegreeting.name
properties in the Quarkusconfig-quickstart
project:greeting.message = hello greeting.name = quarkus
ImportantUse
quarkus
as a prefix to Quarkus properties.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;
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 forgreeting.name
.
NoteTo inject a configured value, you can use
@ConfigProperty
. The@Inject
annotation is not necessary for members annotated with@ConfigProperty
.Edit your
hello
method to return the following message:@GET @Produces(MediaType.TEXT_PLAIN) public String hello() { return message + " " + name.orElse("world") + suffix; }
To compile your Quarkus application in development mode, enter the following command from the project directory:
./mvnw quarkus:dev
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!
- 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
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;
-
Create a file
GreetingConfiguration.java
in thesrc/main/java/org/acme/config
directory. Add the
@ConfigProperties
and@Optional
imports to theGreetingConfiguration.java
file:package org.acme.config; import io.quarkus.arc.config.ConfigProperties; import java.util.Optional;
Create a
GreetingConfiguration
class for thegreeting
properties in yourGreetingConfiguration.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; } }
Inject the attribute into the
GreetingResource
class using the context and dependency injection (CDI)@Inject
annotation:@Inject GreetingConfiguration greetingConfiguration;
To compile your application in development mode, enter the following command from the project directory:
./mvnw quarkus:dev
ImportantIf 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 toOptional
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
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;
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; }
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 casehidden
, determines the name of the properties bound to the object.Add the equivalent configuration properties to your
application.properties
file.The following example shows the value of properties for the
GreetingConfiguration
andHiddenConfig
classes:greeting.message = hello greeting.name = quarkus greeting.hidden.prize-amount=10 greeting.hidden.recipients=Jane,John
To compile your application in development mode, enter the following command from the project directory:
./mvnw quarkus:dev
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
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;
Add a
GreetingConfiguration
class as an interface to yourGreetingConfiguration.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 begreeting.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.
To compile your application in development mode, enter the following command from the project directory:
./mvnw quarkus:dev
ImportantIf 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 toOptional
fields and fields with a default value.