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.Function<io.helidon.config.Config, java.lang.Boolean>).

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

Interface Summary

Interface	Description
Config	Configuration
Config.Builder	Config Builder.
Config.Context	Context associated with specific Config node that allows to access the last loaded instance of the node or to request reloading of whole configuration.
Config.Key	Object represents fully-qualified key of config node.
ConfigSources.MergingStrategy	An algorithm for combining multiple ConfigNode.ObjectNode root nodes into a single ConfigNode.ObjectNode root node.
ConfigValue<T>	A typed value of a Config node.

Class Summary

Class	Description
ConfigFilters	Class provides access to built-in ConfigFilter implementations.
ConfigFilters.ValueResolvingBuilder	A builder for value reference resolving filter.
ConfigHelper	Common Configuration utilities.
ConfigMappers	Utility methods for converting configuration to Java types.
ConfigParsers	Provides access to built-in ConfigParser implementations.
ConfigSources	Provides access to built-in ConfigSource implementations.
ConfigSources.CompositeBuilder	Builder of a ConfigSource that encapsulates multiple separate ConfigSources.
ConfigSources.MapBuilder	Builder of a ConfigSource based on a Map containing config entries.
ConfigValues	Factory for config values.
EnvironmentVariableAliases	Provides configuration key aliases in an attempt to map to legal environment variable names.
EnvironmentVariables	Provides environment variables that include aliases enabling setting or overriding configuration with keys that are unlikely to be legal as environment variables.
OverrideSources	Class provides access to built-in OverrideSource implementations.
PollingStrategies	Built-in PollingStrategy implementations.
PollingStrategies.FilesystemWatchBuilder	A builder for a filesystem watch polling strategy.
PollingStrategies.ScheduledBuilder	A builder for a scheduled polling strategy.
RetryPolicies	Class provides access to built-in RetryPolicy implementations.
RetryPolicies.Builder	A builder of the default RetryPolicy.

Enum Summary

Enum	Description
Config.Type	Configuration node types.

Exception Summary

Exception	Description
ConfigException	Exception is thrown by Config implementations.
ConfigMappingException	Configuration value mapping exception.
MissingValueException	Exception representing a specific failures related to a missing configuration value.