Module io.helidon.config

Package 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

Related Packages

Module	Package	Description
io.helidon.config.encryption	io.helidon.config.encryption	Support for encrypted properties.
io.helidon.config.etcd	io.helidon.config.etcd	Etcd configuration source.
io.helidon.config.git	io.helidon.config.git	Git configuration source.
io.helidon.config.hocon	io.helidon.config.hocon	HOCON format ConfigParser implementation using Typesafe (Lightbend) Config library.
io.helidon.config.metadata	io.helidon.config.metadata	Configuration metadata to support IDE auto completion and generation of documentation.
io.helidon.config.mp	io.helidon.config.mp	Helidon implementation of microprofile config.
io.helidon.config.objectmapping	io.helidon.config.objectmapping	Mappers that can map Config to classes with factory methods, classes with Builders and general "bean" classes with constructor and setters.
io.helidon.config	io.helidon.config.spi	Configuration SPI that defines the behavior developers can implement to extend the config system.
io.helidon.config.testing	io.helidon.config.testing	Configuration Testing Support.
io.helidon.config.yaml	io.helidon.config.yaml	YAML format ConfigParser implementation.

Class	Description
AbstractConfigSource	A base implementation for config sources, that combines configuration from any type of a config source.
AbstractConfigSourceBuilder<B extends AbstractConfigSourceBuilder<B,U>,U>	Common ancestor for config source builders, taking care of configurable options understood by the config module.
AbstractNodeBuilderImpl<ID,B>	Common implementation of ConfigNode.ListNode.Builder and ConfigNode.ObjectNode.Builder.
AbstractNodeBuilderImpl.MergingKey	Internal config node key useful during internal structure building.
AbstractSource	Source options as a super set of all possible combinations of source implementation.
AbstractSourceBuilder<B extends AbstractSourceBuilder<B,U>,U>	Base class for common builder methods of a Source implementation.
ClasspathConfigSource	ConfigSource implementation that loads configuration content from a resource on a classpath.
ClasspathConfigSource.Builder	Classpath ConfigSource Builder.
ClasspathOverrideSource	OverrideSource implementation that loads override definitions from a resource on a classpath.
ClasspathOverrideSource.Builder	Classpath OverrideSource Builder.
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.
Config.Type	Configuration node types.
ConfigException	Exception is thrown by Config implementations.
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.
ConfigMappingException	Configuration value mapping exception.
ConfigParsers	Provides access to built-in ConfigParser implementations.
ConfigSourceRuntime	The runtime of a config source.
ConfigSources	Provides access to built-in ConfigSource implementations.
ConfigSources.SystemPropertiesConfigSource	System properties config source.
ConfigSources.SystemPropertiesConfigSource.Builder	A fluent API builder for ConfigSources.SystemPropertiesConfigSource.
ConfigValue<T>	A typed value of a Config node.
ConfigValues	Factory for config values.
DeprecatedConfig	A utility class to handle configuration properties that should no longer be used.
DirectoryConfigSource	ConfigSource implementation that loads configuration content from a directory on a filesystem.
DirectoryConfigSource.Builder	Common ancestor for config source builders, taking care of configurable options understood by the config module.
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.
FileConfigSource	ConfigSource implementation that loads configuration content from a file on a filesystem.
FileConfigSource.Builder	File ConfigSource Builder.
FileOverrideSource	OverrideSource implementation that loads override definitions from a file on a filesystem.
FileOverrideSource.Builder	File OverrideSource Builder.
FileSourceHelper	Utilities for file-related source classes.
FileSourceHelper.DataAndDigest	Data and digest of a file.
FileSystemWatcher	This change watcher is backed by WatchService to fire a polling event with every change on monitored Path.
FileSystemWatcher.Builder	Fluent API builder for FileSystemWatcher.
InMemoryOverrideSource	In-memory implementation of override source.
InMemoryOverrideSource.Builder	Fluent API builder for InMemoryOverrideSource.
ListNodeBuilderImpl	Implementation of ConfigNode.ListNode.Builder.
MapConfigSource	ConfigSource implementation based on Map<String, String>.
MapConfigSource.Builder	Fluent API builder for MapConfigSource.
MapConfigSource.MapBuilder<T extends MapConfigSource.MapBuilder<T>>	An abstract fluent API builder for MapConfigSource.
MergeableNode	Extension of ConfigNode that supports merging with other nodes.
MetaConfig	Meta configuration.
MissingValueException	Exception representing a specific failures related to a missing configuration value.
MutabilitySupport	Mutability support for file based sources.
ObjectNodeBuilderImpl	Implementation of ConfigNode.ObjectNode.Builder.
ObjectNodeImpl	Implements ConfigNode.ObjectNode.
OverrideConfigFilter	A config filter that replaces values with a new ones of keys that matching with Pattern.
OverrideSources	Class provides access to built-in OverrideSource implementations.
PollingStrategies	Built-in PollingStrategy implementations.
PollingStrategies.ScheduledBuilder	A builder for a scheduled polling strategy.
PrefixedConfigSource	ConfigSource implementation wraps another config source and add key prefix to original one.
PropertiesConfigParser	ConfigParser implementation that parses Java Properties content.
PropertiesFilter	Filter properties with provided and default filter pattern.
RetryPolicies	Class provides access to built-in RetryPolicy implementations.
ScheduledPollingStrategy	A strategy which allows the user to schedule periodically fired polling event.
ScheduledPollingStrategy.Builder	A fluent API builder for ScheduledPollingStrategy.
ScheduledPollingStrategy.RecurringPolicy	An SPI that allows users to define their own policy how to change the interval between scheduled ticking.
ScheduledPollingStrategy.RecurringPolicy.AdaptiveBuilder	Creates a builder of ScheduledPollingStrategy.RecurringPolicy with an ability to change the behaviour, with a boundaries and the possibility to react to feedback given by ScheduledPollingStrategy.RecurringPolicy.shorten() or ScheduledPollingStrategy.RecurringPolicy.lengthen().
ScheduledPollingStrategy.RegularRecurringPolicy	Regular polling strategy implementation.
SimpleRetryPolicy	A default retry policy implementation with ScheduledExecutorService.
SimpleRetryPolicy.Builder	Fluent API builder for SimpleRetryPolicy.
UrlConfigSource	ConfigSource implementation that loads configuration content from specified endpoint URL.
UrlConfigSource.Builder	Url ConfigSource Builder.
UrlOverrideSource	OverrideSource implementation that loads configuration override content from specified endpoint URL.
UrlOverrideSource.Builder	Url Override Source Builder.
ValueNodeImpl	Implements ConfigNode.ValueNode.
ValueResolvingFilter	A config filter that replaces all placeholders in a config value String with their corresponding values looked up from the config.