Use the Helidon SE Maven archetype to create a simple project that can be used for the examples in this guide.

mvn -U archetype:generate -DinteractiveMode=false \
    -DarchetypeGroupId=io.helidon.archetypes \
    -DarchetypeArtifactId=helidon-quickstart-se \
    -DarchetypeVersion=3.2.16 \
    -DgroupId=io.helidon.examples \
    -DartifactId=helidon-quickstart-se \
    -Dpackage=io.helidon.examples.quickstart.se

cd helidon-quickstart-se

Helidon configuration sources can use different formats for the configuration data. You can specify the format on a per-source bases, mixing and matching formats as required. Here are the supported formats, each with the extension name you should use. By default, Helidon will determine the media type based on the extension name.

• Java Property (.properties)

• JSON (.json)

• YAML (.yaml)

• HOCON (.conf)

The remainder of this document will use these formats in examples and show you how to configure Helidon to parse them.

Helidon has an internal configuration, so you are not required to provide any configuration data for your application, though in practice you most likely would. By default, that configuration can be overridden from three sources: system properties, environment variables, and the contents of application.yaml in the classpath. For example, if you specify a custom server port in application.yaml then your server will listen on that port.

In your application code, Helidon uses the default configuration when you create a default Config object. See the following code from the project you created.

Config config = Config.create(); 

• The Config object is created with default settings.

In order to properly configure your application using configuration sources, you need to understand the precedence rules that Helidon uses to merge your configuration data. By default, Helidon will use the following sources in precedence order:

1. Java system properties
2. Environment variables
3. Configuration specified in application.yaml

If any of the Helidon required properties are not specified in one of these source, like server.port, then Helidon will use a default value.

The following examples will demonstrate the default precedence order.

Default Configuration Resource

app:
  greeting: HelloFrom-application.yaml

mvn package -DskipTests=true
java -jar target/helidon-quickstart-se.jar

curl http://localhost:8080/greet

{
  "message": "HelloFrom-application.yaml World!" 
}

java -Dapp.greeting="HelloFromSystemProperty"  -jar target/helidon-quickstart-se.jar

curl http://localhost:8080/greet

{
  "message": "HelloFromSystemProperty World!" 
}

export APP_GREETING=HelloFromEnvironment
java -Dapp.greeting="HelloFromSystemProperty"  -jar target/helidon-quickstart-se.jar

curl http://localhost:8080/greet

{
  "message": "HelloFromEnvironment World!" 
}

Here is the full list of external config sources that you can use programmatically.

1. Environment variables - the property is a name/value pair.
2. Java system properties - the property is a name/value pair.
3. Resources in the classpath - the contents of the resource is parsed according to its inferred format.
4. File - the contents of the file is parsed according to its inferred format.
5. Directory - each non-directory file in the directory becomes a config entry: the file name is the key. and the contents of that file are used as the corresponding config String value.
6. A URL resource - contents is parsed according to its inferred format.

You can also define custom sources, such as Git, and use them in your Helidon application. See Advanced Config for more information.

The first custom resource example demonstrates how to add a second internal configuration resource that is discovered in the classpath. The code needs to build a Config object, which in turn is used to build the Server object. The Config object can be built using a Config.Builder, which lets you inject any number of sources into the builder. Furthermore, you can set precedence for the sources. The first source has highest precedence, then the next has second highest, and so forth.

app.greeting=HelloFrom-config.properties

import static io.helidon.config.ConfigSources.classpath; 
//...

    static WebServer startServer() throws IOException {
//...
        Config config =  buildConfig(); 


  private static Config buildConfig() {
    return Config.builder()
        .disableEnvironmentVariablesSource() 
        .sources(
            classpath("config.properties"), 
            classpath("application.yaml")) 
        .build();
  }

• Add new import statement.
• Call the new buildConfig method to build a Config object.
• Disable the environment variables as a source.
• Specify the new config.properties resource that is in the classpath.
• You must specify the existing application.yaml or Helidon will not use it as a configuration source even though it is considered a default source.

curl http://localhost:8080/greet
...
{
  "message": "HelloFrom-config.properties World!" 
}

• The greeting was picked up from config.properties, overriding the value in application.yaml.

Swap the source order and run the test again.

  private static Config buildConfig() {
      return Config.builder()
          .disableEnvironmentVariablesSource()
          .sources(
              classpath("application.yaml"), 
              classpath("config.properties"))
          .build();
  }

• Swap the source order, putting application.yaml first.

curl http://localhost:8080/greet
...
{
  "message": "HelloFrom-application.yaml World!" 
}

• The file application.yaml was used to get the greeting since it now has precedence over config.properties.

You can move all or part of your configuration to external files, making them optional or mandatory. The obvious advantage to this approach is that you do not need to rebuild your application to change configuration. In the following example, the app.greeting configuration property will be added to config-file.properties.

unset APP_GREETING

app.greeting=HelloFrom-config-file.properties

import static io.helidon.config.ConfigSources.file;
...

  private static Config buildConfig() {
      return Config.builder()
          .sources(
              file("config-file.properties"), 
              classpath("application.yaml"))
          .build();
  }

• Add a mandatory configuration file.

curl http://localhost:8080/greet
...
{
  "message": "HelloFrom-config-file.properties World!" 
}

• The configuration property from the file config-file.properties takes precedence.

  private static Config buildConfig() {
      return Config.builder()
          .sources(
              file("missing-file"), 
              classpath("application.yaml"))
          .build();
  }

• Specify a file that doesn’t exist.

Exception in thread "main" io.helidon.config.ConfigException: Cannot load data from mandatory source FileConfig[missing-file]. File `missing-file` not found.

To fix this, use the optional method as shown below, then rerun the test.

...
    file("missing-file").optional(), 

• The missing-file configuration file is now optional.

A directory source treats every file in the directory as a key, and the file contents as the value. The following example includes a directory source as highest precedence.

HelloFromFileInDirectoryConf

import static io.helidon.config.ConfigSources.directory;
...

  private static Config buildConfig() {
      return Config.builder()
          .sources(
              directory("conf"), 
              classpath("config.properties").optional(),
              classpath("application.yaml"))
          .build();
  }

• Add a mandatory configuration directory.

curl http://localhost:8080/greet
...
{
  "message": "HelloFromFileInDirectoryConf World!" 
}

• The greeting was fetched from the file named app.greeting.

Exceeding Three Sources

  private static Config buildConfig() {

    return Config.builder()
                .addSource(directory("conf"))  
                .addSource(file("config-file.properties"))
                .addSource(classpath("config.properties").optional())
                .addSource(classpath("application.yaml"))
                .build();
  }

curl http://localhost:8080/greet
...

{
  "message": "HelloFromFileInDirectoryConf World!"
}

Instead of directly specifying the configuration sources in your code, you can use a profile file that declares the configuration sources and their attributes.

Simplest way to use a profile is to define a config-profile.yaml (and possible other files, such as config-profile-dev.yaml for dev profile) on classpath or on file system, and create config using Config.create(). The profile can be changed by a system property config.profile, or using an environment variable HELIDON_CONFIG_PROFILE.

Profile file can use any supported format, following example is using YAML.

sources:
  - type: "classpath" 
    properties:
      resource: "application.yaml" 

• The source type.
• The name of the mandatory configuration resource.

  private static Config buildConfig() {
      return Config.create(); 
  }

• Will use config-profile.yaml by default

curl http://localhost:8080/greet
...
{
  "message": "HelloFrom-application.yaml World!" 
}

• The application.yaml resource file was used to get the greeting.

The source precedence order in a profile file is the order of appearance in the file. This is demonstrated below where the config-file.properties has highest precedence.

sources:
  - type: "file" 
    properties:
      path: "./config-file.properties" 
  - type: "classpath"
    properties:
      resource: "application.yaml"
  - type: "file"
    properties:
      path: "optional-config-file"
      optional: true  

• The source type specifies a file.
• The name of the mandatory configuration file.
• Specify that the optional-config-file file is optional.

curl http://localhost:8080/greet
...
{
  "message": "HelloFrom-config-file.properties World!" 
}

• The config-file.properties source now takes precedence.

When using a profile file, you need to explicitly include both environment variables and system properties as a source if you want to use them.

sources:
  - type: "environment-variables" 
  - type: "system-properties" 
  - type: "classpath"
    properties:
      resource: "application.yaml"
  - type: "file"
    properties:
      path: "./config-file.properties"

• Environment variables are now used as a source.
• System properties are now used as a source.

You can re-run the previous tests that exercised environment variables and system properties. Swap the two types to see the precedence change. Be sure to unset APP_GREETING after you finish testing.

The simplest way to access configuration data is using a key, as shown below in the GreetService class. The key can be composite as shown below:

    GreetService(Config config) {
        greeting.set(config.get("app.greeting").asString().orElse("Ciao")); 
    }

• Get the app.greeting node using a composite key.

You can also access the same greeting by navigating the nodes.

    GreetService(Config config) {
        greeting.set(config.get("app").get("greeting").asString().orElse("Ciao")); 
    }

• Get the app node, then get the child node, greeting.

curl http://localhost:8080/greet
...
{
  "message": "HelloFrom-application.yaml World!"
}

The Helidon Config class provides several methods that allow you to filter and customize the traversal of the configuration tree. The example below shows how to get the greeting node when you only know it is somewhere in the app subtree.

sources:
  - type: "classpath"
    properties:
      resource: "application.yaml"

app:
  child1: child1-node
  child2:
     child2a:
        greeting: HelloFrom-application.yaml under child2a
  child3: child3-node

import java.util.List;
import java.util.stream.Collectors;

    GreetService(Config config) {
        List<Config> appGreetings =  config.get("app")
            .traverse()  
            .filter(node -> node.name().equals("greeting")) 
            .collect(Collectors.toList()); 

        greeting.set(appGreetings.get(0).asString().get());
    }

• Add new imports.
• Traverse the entire subtree of the app node.
• Include only nodes that have the name greeting.
• Add the greeting node to the collection.

curl http://localhost:8080/greet
...
{
  "message": "HelloFrom-application.yaml under child2a World!"
}

Even though in-memory config trees are immutable, the config system internally records configuration source metadata that allows it to watch sources for changes. Your application listens for updates to the underlying config sources and reacts to the changes. See Config Mutability Support for a full discussion on this topic. The following example demonstrates how to listen and react to configuration changes.

sources:
  - type: "file"
    properties:
      path: "./config-file.properties"
      change-watcher:
        type: "file"
  - type: "classpath"
    properties:
      resource: "application.yaml"

import java.util.function.Consumer;
...

    GreetService(Config config) {
        Config greetingConfig = config.get("app.greeting"); 
        greeting.set(greetingConfig.asString().orElse("Ciao"));
        greetingConfig.onChange((Consumer<Config>) cfg -> greeting.set(cfg.asString().orElse("Ciao"))); 
    }

• Get the greeting Config node.
• Register a listener that will get called by Helidon when the configuration changes. The listener will update the greeting with the new value.

curl http://localhost:8080/greet
...

{
  "message": "HelloFrom-config-file.properties World!"
}

app.greeting=Updated HelloFrom-config-file.properties

curl http://localhost:8080/greet
...

{
  "message": "Updated HelloFrom-config-file.properties World!" 
}

• The application reacted to the change and updated the greeting.