Contents

Overview

Helidon Config provides several extension modules that support other configuration formats (parsers) and sources. This document describes how to include them and use them in your project. In each case you need to add module dependencies to your project and, in some cases, write your application accordingly.

Additional Config Formats and Parsers

Automatic Media Type and File Type Handling

With each of the parsers described here, your application can either

  1. explicitly add a parser of the correct implementation to the Config.Builder, or
  2. rely on Java service loading and the config system’s matching of file types and media types to parsers.

If your application creates a Config.Builder with parser services disabled (see disableParserServices then that builder will not find the Java services for the various parsers and so will be unable to match the file type or media type of sources with the corresponding parser automatically. So if you want to use automatic type matching with a given builder, do not invoke Config.Builder.disableParserServices().

YAML

Maven Coordinates

Add the following dependency in your project:

Config YAML Dependency in pom.xml
    <dependency>
        <groupId>io.helidon.config</groupId>
        <artifactId>helidon-config-yaml</artifactId>
    </dependency>
Copied
Config YAML Dependency in module-info.java
module myModule {
    requires io.helidon.config.yaml;
}
Copied

Using the YAML Parser

The YAML parser handles the following media type:

  • application/x-yaml - YAML format (file type .yaml)

Automatic selection
Config config = Config.create(classpath("application.yaml"));
Copied
  • The config system automatically maps the file type .yaml to the media type application/x-yaml which the Helidon YAML parser matches.
YAML parser specified - no file type on source
Config config = Config.create(classpath("my-config")                                    
                                    .parser(YamlConfigParserBuilder.buildDefault()));
Copied
  • The media type of the source my-config is unknown, so the config system cannot choose a parser automatically.
  • The config system will parse the resource my-config on the runtime classpath using the YAML parser instance created by the YamlConfigParserBuilder. The buildDefault() method creates a config parser with default behavior.
Media type specified
Config config = Config.create(classpath("my-config")                     
                                    .mediaType("application/x-yaml"));
Copied
  • The media type of the source my-config is unknown, so the config system cannot choose a parser automatically.
  • Specifying the media type for the config source allows the config system to use its matching algorithm with the available parsers to choose a parser for that type.
YAML parser specified because parser services disabled
Config config = Config.builder(classpath("application.yaml"))
        .disableParserServices()                                  
        .addParser(YamlConfigParserBuilder.buildDefault())        
        .build();
Copied
  • Disables automatic parser lookup and registration.
  • Explicit registration of the YAML parser is therefore required.

HOCON/JSON

The Helidon HOCON config module handles sources in the HOCON and JSON formats.

Maven Coordinates

Add the following dependency in your project:

Config HOCON Dependency in pom.xml
    <dependency>
        <groupId>io.helidon.config</groupId>
        <artifactId>helidon-config-hocon</artifactId>
    </dependency>
Copied
Config HOCON Dependency in module-info.java
module myModule {
    requires io.helidon.config.hocon;
}
Copied

Using the HOCON/JSON Parser

The parser handles the following media types:

  • application/hocon - HOCON format (file type .conf)

  • application/json - JSON format (file type .json)

Automatic selection
Config config = Config.create(classpath("application.conf"));
Copied
  • The config system automatically maps the file type .conf to the media type `application/hocon which the Helidon HOCON parser matches.

The same module and parser supports file type .json and the media type application/json.

HOCON parser specified - no file type on source
Config config = Config.create(classpath("my-config")                                     
                                    .parser(HoconConfigParser.create()));
Copied
  • the media type of the source my-config is unknown, so the config system cannot choose a parser automatically.
  • The config system will parse the resource my-config using the HOCON parser created by the HoconConfigParser. The create() method creates a config parser with default behavior.
Media type specified
Config config = Config.create(classpath("my-config")                    
                                    .mediaType("application/hocon"));
Copied
  • The media type of the source my-config is unknown, so the config system cannot choose a parser automatically.
  • Specifying the media type for the config source allows the config system to use its matching algorithm with the available parsers to choose a parser for that type.
HOCON parser specified because parser services disabled
Config config = Config.builder(classpath("application.conf"))
        .disableParserServices()                                  
        .addParser(HoconConfigParser.create())                    
        .build();
Copied
  • Disables automatic parser lookup and registration.
  • Explicit registration of the HOCON parser is therefore required.
Customized HOCON parser
Config config = Config.builder(classpath("application.conf"))
        .disableParserServices()
        .addParser(HoconConfigParser.builder()                    
                           .resolvingEnabled(false)               
                           .build())                              
        .build();
Copied
  • Creates new instance of the parser builder.
  • Disables resolution of substitutions. (See the HOCON documentation.)
  • Builds a new instance of the HOCON config parser.

You can also specify ConfigResolveOptions using the HoconConfigParser.builder().resolveOptions method.

Additional Config Source Types

Etcd

The Helidon Etcd config module supports reading configuration from a specified Etcd key.

Maven Coordinates

Add the following dependency to your project:

Config Etcd Dependency in pom.xml
    <dependency>
        <groupId>io.helidon.config</groupId>
        <artifactId>helidon-config-etcd</artifactId>
    </dependency>
Copied
Config Etcd Dependency in module-info.java
module myModule {
    requires io.helidon.config.etcd;
}
Copied

Using the Etcd Config Source

To read configuration from an Etcd source, your application uses the EtcdConfigSourceBuilder.

Use Etcd config source
Config config = Config.create(
        EtcdConfigSourceBuilder                             
                .create(URI.create("http://my-etcd:2379"),  
                      "/config.yaml",                       
                      EtcdConfigSourceBuilder.EtcdApi.v3));
Copied
  • Use the factory method EtcdConfigSourceBuilder.create to initialize the builder.
  • Specify the Etcd endpoint address.
  • Specify the Etcd key of the configuration document.
  • Version of the Etcd API to use; v2 and v3 are supported.

The config system will use the YAML parser automatically in this example because the file type of the key is .yaml.

The EtcdConfigSourceBuilder class extends AbstractParsableConfigSource.Builder and so supports the usual settings on config sources.

Monitoring for Source Changes

The Etcd support includes a polling strategy designed for an etcd config source.

Use Etcd config source
Config config = Config.create(
        EtcdConfigSourceBuilder
                .create(URI.create("http://my-etcd:2379"), "/config.yaml", EtcdApi.v3)
                .pollingStrategy(EtcdWatchPollingStrategy::new));
Copied
  • Use the etcd-specific polling strategy.

Loading Meta-configuration via Etcd

The config system can load information about config sources from meta-configuration rather than requiring your application to construct the builder. To read meta-configuration from an Etcd source set the following required properties for the source:

  • type to etcd, or class to io.helidon.config.etcd.EtcdConfigSourceBuilder

  • uri (type URI) - Etcd endpoint URI.

  • key (type String) - Etcd key that is associated with the configuration.

  • api (type EtcdConfigSourceBuilder.EtcdApi, i.e. v2 or v3) - Etcd API version.

Other optional properties are inherited from AbstractParsableConfigSource.Builder. (see javadoc)

Load Config from meta-configuration
Config config = Config.loadSourcesFrom(classpath("config-meta-etcd.yaml"));
Copied
Meta-config config-meta-etcd.yaml for the etcd source
sources:
    - type: "etcd"                                                 
      properties:
          uri: "http://my-etcd:2379"                               
          key: "/config.yaml"                                      
          api: "v3"                                                
          polling-strategy:
              class: "io.helidon.config.etcd.EtcdWatchPollingStrategy"
Copied
  • etcd config source type
  • Etcd source-specific (mandatory) properties: uri, key and api.
  • Polling strategy EtcdWatchPollingStrategy is automatically initialized by specified mandatory properties.

git

The Helidon git config module supports reading configuration from a git repository.

Maven Coordinates

Add the following dependency to your project:

Config git Dependency in pom.xml
    <dependency>
        <groupId>io.helidon.config</groupId>
        <artifactId>helidon-config-git</artifactId>
    </dependency>
Copied
Config git Dependency in module-info.java
module myModule {
    requires io.helidon.config.git;
}
Copied

Using the git Config Source

To read configuration from a git source, your application uses the GitConfigSourceBuilder.

Use git config source
Config config = Config.create(
        GitConfigSourceBuilder
                .create("application.conf")                                           
                    .uri(URI.create("https://github.com/okosatka/test-config.git")) 
                    .directory(Paths.get("/config"))                                
                    .branch("dev"));
Copied
  • Use the factory method GitConfigSourceBuilder.create to initialize the builder with a mandatory path to the configuration file.
  • Specify the git repository URI.
  • Specify a directory where the git repository is already cloned or it will be cloned.
  • Specify the git branch.

Note that the config system will use the HOCON parser in this example because the file type is .conf. Recall that for this to work the HOCON config module must be on module-path or classpath.

The GitConfigSourceBuilder supports the usual source builder properties because it extends AbstractParsableConfigSource.Builder.

Monitoring for Source Changes

Your application can monitor changes to a configuration loaded from a git source associating the regular built-in polling strategy with the source.

Use of git config source with polling strategy
Config config = Config.create(
        GitConfigSourceBuilder
                .create("application.conf")
                .uri(URI.create("https://github.com/okosatka/test-config.git"))
                .pollingStrategy(PollingStrategies.regular(Duration.ofMinutes(5))));
Copied
  • Use PollingStrategies.regular(Duration duration) to monitor for config changes.

You can also implement your own polling strategy by implementing PollingStrategy. See the mutability support and polling strategy discussions.

Loading Meta-configuration via git

The config system can load information about config sources from meta-configuration rather than requiring your application to construct the builder. To read meta-configuration from a git config source set the following properties for the source:

  • type to git or class to io.helidon.config.git.GitConfigSourceBuilder

  • path (type String) - Relative path to the configuration file in repository.

  • uri (type URI) - URI to the git repository.

  • directory (type Path) - Directory with a cloned repository, by default a temporary directory.

  • branch (type String) - git branch (default is master).

The meta-configuration must set the path and one of uri or directory. Other optional properties are inherited from AbstractParsableConfigSource.Builder (see javadoc)

Load Config from meta-configuration
Config config = Config.loadSourcesFrom(classpath("config-meta-git.yaml"));
Copied
Meta-config config-meta-git.yaml for the git source
sources:
    - type: "git"                                            
      properties:
          path: "application.conf"                           
          uri: "https://github.com/okosatka/test-config.git" 
          directory: "/config"                               
          branch: "dev"                                      
          polling-strategy:
              type: "regular"                                
              properties:
                  interval: "PT5M"
Copied
  • git config source type
  • git source-specific properties: path, uri, directory and branch.
  • Polling strategy regular with an interval, in Duration format, of 5 minutes in this example.