The content of this guide and been revised and split into additional topics. Please check the Additional Information section. |
Hardcoded values in your code are a no go (even if we all did it at some point ;-)). In this guide, we will learn how to configure a Quarkus application.
Prerequisites
To complete this guide, you need:
-
between 5 and 10 minutes
-
an IDE
-
JDK 11+ installed with
JAVA_HOME
configured appropriately -
Apache Maven 3.8.1
Solution
We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.
Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git
, or download an archive.
The solution is located in the config-quickstart
directory.
Create the Maven project
First, we need a new project. Create a new project with the following command:
mvn io.quarkus.platform:quarkus-maven-plugin:2.4.0.CR1:create \
-DprojectGroupId=org.acme \
-DprojectArtifactId=config-quickstart \
-DclassName="org.acme.config.GreetingResource" \
-Dpath="/greeting"
cd config-quickstart
It generates:
-
the Maven structure
-
a landing page accessible on
http://localhost:8080
-
example
Dockerfile
files for bothnative
andjvm
modes -
the application configuration file
-
an
org.acme.config.GreetingResource
resource -
an associated test
Create the configuration
A Quarkus application uses the SmallRye Config API to provide all mechanisms related with configuration.
By default, Quarkus reads configuration properties from several sources.
For the purpose of this guide, we will use an application configuration file located in src/main/resources/application.properties
.
Edit the file with the following content:
# Your configuration properties
greeting.message = hello
greeting.name = quarkus
Inject the configuration
Quarkus uses MicroProfile Config annotations to inject the configuration properties in the application.
@ConfigProperty(name = "greeting.message") (1)
String message;
1 | You can use @Inject @ConfigProperty or just @ConfigProperty . The @Inject annotation is not necessary for
members annotated with @ConfigProperty . |
If the application attempts to inject a configuration property that is not set, an error is thrown. |
Edit the org.acme.config.GreetingResource
, and introduce the following configuration properties:
@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 startup fails with javax.enterprise.inject.spi.DeploymentException: No config value of type [class java.lang.String] exists for: greeting.message . |
2 | The default value is injected if the configuration does not provide a value for greeting.suffix . |
3 | This property is optional - an empty Optional is injected if the configuration does not provide a value for greeting.name . |
Now, modify the hello
method to use the injected properties:
@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
return message + " " + name.orElse("world") + suffix;
}
Once set, check the application with:
$ curl http://localhost:8080/greeting
hello quarkus!
Use @io.smallrye.config.ConfigMapping annotation to group multiple configurations in a single interface. Please,
check the Config Mappings documentation.
|
Update the test
We also need to update the functional test to reflect the changes made to the endpoint.
Edit the src/test/java/org/acme/config/GreetingResourceTest.java
file and change the content of the testHelloEndpoint
method to:
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
}
}
Package and run the application
Run the application with: ./mvnw compile quarkus:dev
.
Open your browser to http://localhost:8080/greeting.
Changing the configuration file is immediately reflected.
You can add the greeting.suffix
, remove the other properties, change the values, etc.
As usual, the application can be packaged using ./mvnw clean package
and executed using the target/quarkus-app/quarkus-run.jar
file.
You can also generate the native executable with ./mvnw clean package -Pnative
.
Programmatically access the configuration
The org.eclipse.microprofile.config.ConfigProvider.getConfig()
API allows to access the Config API programmatically.
This API is mostly useful in situations where CDI injection is not available.
String databaseName = ConfigProvider.getConfig().getValue("database.name", String.class);
Optional<String> maybeDatabaseName = ConfigProvider.getConfig().getOptionalValue("database.name", String.class);
Configuring Quarkus
Quarkus itself is configured via the same mechanism as your application. Quarkus reserves the quarkus.
namespace
for its own configuration. For example to configure the HTTP server port you can set quarkus.http.port
in
application.properties
. All the Quarkus configuration properties are documented and searchable.
As mentioned above, properties prefixed with |
Build Time configuration
Some Quarkus configurations only take effect during build time, meaning is not possible to change them at runtime. These configurations are still available at runtime but as read-only and have no effect in Quarkus behaviour. A change to any of these configurations requires a rebuild of the application itself to reflect changes of such properties.
The properties fixed at build time are marked with a lock icon () in the list of all configuration options. |
However, some extensions do define properties overridable at runtime. A simple example is the database URL, username and password which is only known specifically in your target environment, so they can be set and influence the application behaviour at runtime.
Additional Information
Quarkus relies on SmallRye Config and inherits its features:
-
Additional
ConfigSource
s -
Additional
Converter
s -
Indexed properties
-
Parent profile
-
Interceptors for configuration value resolution
-
Relocate configuration properties
-
Fallback configuration properties
-
Logging
-
Hide secrets
For more information, please check the SmallRye Config documentation.