Helidon SE Helpings: Default Configuration Sources
When we use Helidon SE we can use the Config
class to pass configuration properties to our application. The static method create()
creates a default configuration. The Config
class is then configured to support different input sources. This configuration reads configuration properties from the following sources in order:
-
Java system properties,
-
system environment variables,
-
a file on the classpath that has the name
application.properties
(based on default config parser that is part of the artifacthelidon-config
).
The last input source behaves differently based on which classes that can parse a configuration file are on the classpath of our application. If we use the helidon-config
artifact on the classpath then the configuration file read is application.properties
. To read a JSON formatted configuration file we must add the helidon-config-hocon
artifact to the classpath. The file that is read is application.json
. With the same artifact we can read a HOCON formatted configuration file that is named application.conf
. Finally if we add the helidon-config-yaml
artifact to the classpath we can read a YAML formatted configuration file that is named application.yaml
or application.yml
. Helidon SE will only read one configuration file from the classpath with the following order of preference:
-
application.yaml
orapplication.yml
, -
application.conf
, -
application.json
, -
application.properties
.
In the following example class we create a default configuration using Config.create()
and we show the contents of the configuration property app.message
:
// File: src/main/java/mrhaki/helidon/Application.java
package mrhaki.helidon;
import io.helidon.config.Config;
public class Application {
public static void main(String[] args) {
// Create the default configuration.
// Configuration properties are read from in order:
// - from Java system properties
// - from system environment variables
// - from a file on the classpath that has the name
// 'application.properties' (based on default config
// parser that is part of the artifact helidon-config).
Config config = Config.create();
// Get the configuration property app.message.
// If the property is not set, the fallback value
// is defined as "Hello from application code".
String message = config.get("app.message")
.asString()
.orElse("Hello from application code");
// Print the value of the configuration property to System.out.
System.out.printf("app.message = %s%n", message);
}
}
In our pom.xml
we first only have the dependency for the artifact helidon-config
:
...
<dependencies>
<dependency>
<groupId>io.helidon.config</groupId>
<artifactId>helidon-config</artifactId>
</dependency>
</dependencies>
...
Let’s build our application and run it without any configuration properties and rely on the default value that we defined in our code:
$ helidon build
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Detecting the operating system and CPU architecture
[INFO] ------------------------------------------------------------------------
[INFO] os.detected.name: osx
[INFO] os.detected.arch: x86_64
[INFO] os.detected.version: 15.0
[INFO] os.detected.version.major: 15
[INFO] os.detected.version.minor: 0
[INFO] os.detected.classifier: osx-x86_64
[INFO]
[INFO] -----------------------< mrhaki.helidon:config >------------------------
[INFO] Building config 0.0.0-SNAPSHOT
[INFO] from pom.xml
...
$ java -jar target/config.jar
app.message = Hello from application code
Next we add the file application.properties
to the directory src/main/resources
. This will put the file in the JAR file we build and make it available on the classpath:
# File: src/main/resources/application.properties
app.message=Hello from 'application.properties'
When we build and run our application again we see that the value of the configuration property app.message
is read from the file application.properties
on the classpath:
$ helidon build
...
$ java -jar target/config.jar
app.message = Hello from 'application.properties'
Our code also support setting the configuration property using environment variables. The value set by the environment variable APP_MESSAGE
will overrule the value found in application.properties
:
$ APP_MESSAGE="Hello from environment variable" java -jar target/config.jar
app.message = Hello from environment variable
We can overrule the value of the environment variable by setting the configuration property using the Java system properties:
$ APP_MESSAGE="Hello from environment variable" java -Dapp.message="Hello from Java system property" -jar target/config.jar
app.message = Hello from Java system property
If we replace the artifact helidon-config
with helidon-config-hocon
we can read a file named application.json
from the classpath. First we change our dependency in the pom.xml
:
...
<dependencies>
<dependency>
<groupId>io.helidon.config</groupId>
<artifactId>helidon-config-hocon</artifactId>
</dependency>
</dependencies>
...
Next we add the file application.json
in src/main/resources
:
{
"app": {
"message": "Hello from 'aplication.json'"
}
}
We can rebuild our application and run it to see the following output:
$ helidon build
...
$ java -jar target/config.jar
app.message = Hello from 'aplication.json'
Instead of a JSON file we can also use file with the extension .conf
written in HOCON format. The following example file application.conf
in src/main/resources
sets the configuration property app.message
:
// File: src/main/resources/application.conf
app {
message = Hello from 'application.conf'
}
When we build and run our application we see the following output:
$ helidon build
...
$ java -jar target/config.jar
app.message = Hello from 'application.conf'
To support a configuration file with the name application.yaml
or application.yml
in YAML format we must add the artifact helidon-config-yaml
as dependency:
...
<dependencies>
<dependency>
<groupId>io.helidon.config</groupId>
<artifactId>helidon-config-yaml</artifactId>
</dependency>
</dependencies>
...
Our example application.yaml
will look like this:
# File: src/amin/resources/application.yaml
app:
message: Hello from 'application.yaml'
For the final time we build and run the application to show the output:
$ helidon build
...
$ java -jar target/config.jar
app.message = Hello from 'application.yaml'
Written with Helidon SE 4.1.2.