HelidonHelidon4.5.0

Supported Formats

Additional Supported Formats and Sources

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 Formats

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:

pom.xml
<dependency>
  <groupId>io.helidon.config</groupId>
  <artifactId>helidon-config-yaml</artifactId>
</dependency>

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"));1
  1. The config system automatically maps the file type .yaml to the media type application/x-yaml which the Helidon YAML parser matches.
Config config = Config.create(classpath("my-config")1
    .parser(YamlConfigParser.create()));2
  1. The media type of the source my-config is unknown, so the config system cannot choose a parser automatically.
  2. The config system will parse the resource my-config on the runtime classpath using the YAML parser instance created by the YamlConfigParser. The create() method creates a config parser with default behavior.
Config config = Config.create(classpath("my-config")1
    .mediaType(MediaTypes.APPLICATION_X_YAML));2
  1. The media type of the source my-config is unknown, so the config system cannot choose a parser automatically.
  2. 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.
Config config = Config.builder(classpath("application.yaml"))
    .disableParserServices()1
    .addParser(YamlConfigParser.create())2
    .build();
  1. Disables automatic parser lookup and registration.
  2. 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:

pom.xml
<dependency>
  <groupId>io.helidon.config</groupId>
  <artifactId>helidon-config-hocon</artifactId>
</dependency>

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"));1
  1. 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")1
    .parser(HoconConfigParser.create()));2
  1. the media type of the source my-config is unknown, so the config system cannot choose a parser automatically.
  2. 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")1
    .mediaType(MediaTypes.APPLICATION_HOCON));2
  1. The media type of the source my-config is unknown, so the config system cannot choose a parser automatically.
  2. 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()1
    .addParser(HoconConfigParser.create())2
    .build();
  1. Disables automatic parser lookup and registration.
  2. Explicit registration of the HOCON parser is therefore required.

Customized HOCON parser:

Config config = Config.builder(classpath("application.conf"))
    .disableParserServices()
    .addParser(HoconConfigParser.builder()1
        .resolvingEnabled(false)2
        .build())3
    .build();
  1. Creates new instance of the parser builder.
  2. Disables resolution of substitutions. (See the HOCON documentation.)
  3. Builds a new instance of the HOCON config parser.

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

Additional Sources

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:

pom.xml
<dependency>
  <groupId>io.helidon.config</groupId>
  <artifactId>helidon-config-etcd</artifactId>
</dependency>

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(
        EtcdConfigSource1
                .create(URI.create("http://my-etcd:2379"),2
                        "/config.yaml",3
                        EtcdConfigSourceBuilder.EtcdApi.v3));4
  1. Use the factory method EtcdConfigSource.create to create the EtcdConfigSource.
  2. Specify the Etcd endpoint address.
  3. Specify the Etcd key of the configuration document.
  4. Version of the Etcd API to use; v3 is supported. v2 is deprecated.

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 AbstractConfigSourceBuilder and so supports the usual settings on config sources.

Monitoring for Source Changes

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

Use Etcd config source:

Config config = Config.create(
        EtcdConfigSource
                .builder()
                .uri(URI.create("http://my-etcd:2379"))
                .key("/config.yaml")
                .api(EtcdConfigSourceBuilder.EtcdApi.v3)
                .changeWatcher(EtcdWatcher.create()));1
  1. Use the etcd-specific change watcher strategy.

Loading Meta-configuration via Etcd

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. v2 is deprecated.

Other optional properties are inherited from AbstractConfigSourceBuilder. (see javadoc)

Load Config from meta-configuration:

Config config = Config.create(classpath("config-meta-etcd.yaml"));

Meta-config config-meta-etcd.yaml for the etcd source:

config-meta-etcd.yaml
sources:
    - type: "etcd"1
      properties:
          uri: "http://my-etcd:2379"2
          key: "/config.yaml"2
          api: "v3"2
          change-watcher:
              type: "etcd"3
  1. etcd config source type
  2. Etcd source-specific (mandatory) properties: uri, key and api.
  3. Watcher strategy EtcdWatcher 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:

pom.xml
<dependency>
  <groupId>io.helidon.config</groupId>
  <artifactId>helidon-config-git</artifactId>
</dependency>

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(
    GitConfigSource
        .builder()1
        .uri(URI.create("https://github.com/okosatka/test-config.git"))2
        .directory(Paths.get("/config"))3
        .branch("dev"));4
  1. Use the factory method GitConfigSource.builder to initialize the builder.
  2. Specify the git repository URI.
  3. Specify a directory where the git repository is already cloned, or it will be cloned.
  4. 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 AbstractConfigSourceBuilder.

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(
    GitConfigSource.builder()
        .uri(URI.create("https://github.com/okosatka/test-config.git"))
        .pollingStrategy(PollingStrategies.regular(Duration.ofMinutes(
            5))));1
  1. 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 AbstractConfigSourceBuilder (see javadoc)

Load Config from meta-configuration:

Config config = Config.create(classpath("config-meta-git.yaml"));

Meta-config config-meta-git.yaml for the git source:

config-meta-git.yaml
sources:
    - type: "git"1
      properties:
          path: "application.conf"2
          uri: "https://github.com/okosatka/test-config.git"2
          directory: "/config"2
          branch: "dev"2
          polling-strategy:
              type: "regular"3
              properties:
                  interval: "PT5M"3
  1. git config source type
  2. git source-specific properties: path, uri, directory and branch.
  3. Polling strategy regular with an interval, in Duration format, of 5 minutes in this example.

Property Mapping

Helidon Config property mapping

Configuration Profiles

Helidon Config profiles

Copyright © 2018, 2026 Oracle and/or its affiliates.