Module io.helidon.config

Package io.helidon.config

Provides interfaces and classes for loading and working with immutable, tree-structured configuration data.

Loading a Configuration

The program loads a configuration from either the default sources (using Config.create()) or from specified ConfigSources (using Config.Builder).

The default sources include all of the following, in order:

  1. environment variables
  2. Java system properties
  3. the first of the following (if any) on the classpath:
    1. application.yaml
    2. application.conf (HOCON format)
    3. application.json
    4. application.properties
The config implementation supports sources in the above formats. The program can add support for other formats by implementing ConfigParser.

See Config for further information.

Using a Configuration Tree

This overview summarizes how a program can use loaded configuration. For full details see the Config class.

Once loaded, configuration information is available to the program as Config nodes in a tree. Each node has:

  • a name,
  • a Config.Key representing the full path from the root to the node, and
  • some content.
The Config.type() method returns an enum value Config.Type that tells how the program should interpret the content of the node.
Config Node Types
Type Meaning Useful Config Methods
VALUE value node with an optional direct String value
LIST list of indexed nodes with an optional "direct" value Config.asList(java.lang.Class), Config.asNodeList()
OBJECT object node with, possibly, child nodes and an optional "direct" value Config.asNodeList()

Configuration Values and Types

While each node's direct value is accessible as an Optional<String>, the program can also have the node convert its String value to a typed ConfigValue using methods such as Config.asString(), Config.asLong() etc.

The program can provide its own ConfigMapperProvider implementations to deal with more complicated value mapping needs. See also Config.Builder.addStringMapper(java.lang.Class<T>, java.util.function.Function<java.lang.String, T>) and Config.Builder.addMapper(java.lang.Class, java.util.function.Function).

Navigation

The program can retrieve a node's child nodes as a List.

The program can navigate directly to a given subnode using the Config.get(java.lang.String) method and passing the dotted path to the subnode.

The Config.traverse() methods return a stream of nodes in depth-first order.

Bulk Retrieval of Values

The program can retrieve a Map of dotted names to String values for a node's entire subtree using Config.asMap().

Monitoring Changes

The program can react to configuration changes by passing a listener to Config.onChange(java.util.function.Consumer).

Converting Configuration to Java Types

The Config class provides many methods for converting config String values to Java primitives and simple Java types, as well as mapping parts of the config tree to Lists and Maps.

The application can convert config data to arbitrary types using the Config.as(java.lang.Class) and Config.as(java.util.function.Function) methods, and can provide its own conversions to handle custom types by implementing a mapping function and registering it with a Config.Builder using the Config.Builder.addMapper(java.lang.Class<T>, java.util.function.Function<io.helidon.config.Config, T>) method.

If the Config.as method finds no matching registered mapper it will throw a ConfigMappingException. Support for automated mapping to types is available in module config-beans.

See Also:
Configuration SPI