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

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

cd helidon-quickstart-mp

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 META-INF/microprofile-config.properties. For example, if you specify a custom server port in META-INF/microprofile-config.properties then your server will listen on that port.

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

    static Server startServer() {
        return Server.create().start(); 
    }

• There is no Config object being used during server creation, so the default configuration is used.

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. Properties specified in META-INF/microprofile-config.properties

Each of these sources specify configuration properties in Java Property format (key/value), like color=red. 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=HelloFromMPConfig

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

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

export APP_GREETING=HelloFromEnvironment
java -jar target/helidon-quickstart-mp.jar

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

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

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

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

1. Java system properties - the property is a name/value pair.
2. Environment variables - 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 is 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 io.helidon.config.Config; 
import static io.helidon.config.ConfigSources.classpath;
...

  static Server startServer() {
        return Server.builder()
            .config(buildConfig()) 
            .build()
            .start();
    }

  private static Config buildConfig() {
    return Config.builder()
        .disableEnvironmentVariablesSource() 
        .sources(
            classpath("config.properties"), 
            classpath("META-INF/microprofile-config.properties")) 
        .build();
  }

• Import config classes.
• Pass the custom Config object to the Server.Builder.
• Disable the environment variables as a source.
• Specify the new config.properties resource that is in the classpath.
• You must specify the existing META-INF/microprofile-config.properties 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 META-INF/microprofile-config.properties.

Swap the source order and run the test again.

  private static Config buildConfig() {
      return Config.builder()
          .disableEnvironmentVariablesSource()
          .sources(
              classpath("META-INF/microprofile-config.properties"), 
              classpath("config.properties"))
          .build();
  }

• Swap the source order, putting META-INF/microprofile-config.properties first.

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

• The file META-INF/microprofile-config.properties 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=HelloFromConfigFile

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

  private static Config buildConfig() {
      return Config.builder()
          .sources(
              file("config-file.properties"), 
              classpath("META-INF/microprofile-config.properties"))
          .build();
  }

• Add a mandatory configuration file.

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

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

  private static Config buildConfig() {
      return Config.builder()
          .sources(
              file("missing-file"), 
              classpath("META-INF/microprofile-config.properties"))
          .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("META-INF/microprofile-config.properties"))
          .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

import io.helidon.config.ConfigSources;
...

  private static Config buildConfig() {
      return Config.builder()
          .sources(ConfigSources.create(   
              directory("conf"),
              file("config-file.properties"),
              classpath("config.properties").optional(),
              classpath("META-INF/microprofile-config.properties")))
          .build();
  }

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

{
  "message": "HelloFromFileInDirectoryConf World!"
}

Instead of directly specifying the configuration sources in your code, you can use meta-configuration in a file that declares the configuration sources and their attributes. This requires using the Config.loadSourcesFrom method rather than a Config.Buider object. The contents of the meta-configuration file needs to be in JSON, YAML, or HOCON format. YAML is used in the following example.

sources:
  - type: "classpath" 
    properties:
      resource: "META-INF/microprofile-config.properties" 

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

  private static Config buildConfig() {
      return Config.loadSourcesFrom( file("meta-config.yaml")); 
  }

• Specify the meta-configuration file, which contains a single configuration source.

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

• The META-INF/microprofile-config.properties resource file was used to get the greeting.

The source precedence order in a meta-configuration 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: "META-INF/microprofile-config.properties"
  - 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": "HelloFromConfigFile World!" 
}

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

When using a meta-config 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: "META-INF/microprofile-config.properties"
  - 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.

You can inject configuration at the field level as shown below. Use the volatile keyword since you cannot use AtomicReference with field level injection.

sources:
  - type: "classpath"
    properties:
      resource: "META-INF/microprofile-config.properties"  

• This example only uses the default classpath source.

@ApplicationScoped
public class GreetingProvider {

    @Inject
    @ConfigProperty(name = "app.greeting") 
    private volatile String message; 

    String getMessage() {
        return message;
    }

    void setMessage(String message) {
        this.message = message;
    }
}

• Inject the value of app.greeting into the GreetingProvider object.
• Define a class member variable to hold the greeting.

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

You can inject the Config object into the class and access it directly as shown below. This object is not initialized when the GreetingProvider constructor is called, so you need to provide a method (onStartup) that observes @Initialized. This method will be called when GreetingProvider is ready for use.

import io.helidon.config.Config;
import javax.enterprise.context.Initialized;
import javax.enterprise.event.Observes;
...

@ApplicationScoped
public class GreetingProvider {
    private final AtomicReference<String> message = new AtomicReference<>();

    @Inject
    Config config;  

    public void onStartUp(@Observes @Initialized(ApplicationScoped.class) Object init) {
        message.set(config.get("app.greeting").asString().get()); 
    }

    String getMessage() {
        return message.get();
    }

    void setMessage(String message) {
        this.message.set(message);
    }
}

• Add three new imports.
• Inject the Config object into the GreetingProvider object.
• Get the app.greeting value from the Config object and set the member variable.

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

Helidon offers a variety of methods to access in-memory configuration. These can be categorized as key access or tree navigation. You have been using key access for all of the examples to this point. For example app.greeting is accessing the greeting child node of the app parent node. There are many options for access this data using navigation methods as described in Hierarchical Config and Advanced Config. This simple example below demonstrates how to access a child node as a detached configuration sub-tree.

app:
  greeting:
    sender: Joe
    message: Hello-from-config-file.yaml

sources:
  - type: "classpath"
    properties:
      resource: "META-INF/microprofile-config.properties"
  - type: "file"
    properties:
      path: "./config-file.yaml"

@ApplicationScoped
public class GreetingProvider {
    private final AtomicReference<String> message = new AtomicReference<>();
    private final AtomicReference<String> sender = new AtomicReference<>();

    @Inject
    Config config;

    public void onStartUp(@Observes @Initialized(ApplicationScoped.class) Object init) {
        Config appNode = config.get("app.greeting"); 
        message.set(appNode.get("message").asString().get());  
        sender.set(appNode.get("sender").asString().get());   
    }

    String getMessage() {
        return sender.get() + " says " + message.get();
    }

    void setMessage(String message) {
        this.message.set(message);
    }
}

• Get the configuration subtree where the app.greeting node is the root.
• Get the value from the message Config node.
• Get the value from the sender Config node.

curl http://localhost:8080/greet
...
{
  "message": "Joe says Hello-from-config-file.yaml World!"
}