Module io.helidon.config

Package io.helidon.config

Interface Config.Builder

All Superinterfaces:

Builder<Config.Builder,Config>, Supplier<Config>

Enclosing interface:

Config

public static interface Config.Builder
extends Builder<Config.Builder,Config>

Config Builder.

A factory for a Config object.

The application can set the following characteristics:

• overrides - instance of override source;
• sources - instances of configuration source;
• mappers - ordered list of mapper functions. It is also possible to disable loading of ConfigMapperProviders as a service.
• parsers - ordered list of configuration content parsers. It is also possible to disable loading of ConfigParsers as a service.
• token reference resolving - a resolving of reference tokens in a key can be disabled
• filters - ordered list of configuration value filters. It is also possible to disable loading of ConfigFilters as a service.
• caching - can be elementary configuration value processed by filter cached?

In case of ConfigMapperProviders, if there is no one that could be used to map appropriate type, the mapping attempt throws a ConfigMappingException.

A more sophisticated approach can be achieved using the "config beans" module, that provides reflection access and mapping for static factory methods, constructors, builder patterns and more.

If a ConfigSource is not specified, following default config source is used. Same as Config.create() uses. It builds composite config source from following sources, checked in order:

1. Tries to load configuration from meta one of following meta configuration files on classpath, in order:
   1. meta-config.yaml - meta configuration file in YAML format
   2. meta-config.conf - meta configuration file in HOCON format
   3. meta-config.json - meta configuration file in JSON format
   4. meta-config.properties - meta configuration file in Java Properties format
2. Otherwise, configuration consists of:
   1. Environment variables;
   2. or else System properties
   3. one of following files on classpath, checked in order:
      1. application.yaml - configuration file in YAML format
      2. application.conf - configuration file in HOCON format
      3. application.json - configuration file in JSON format
      4. application.properties - configuration file in Java Properties format

It uses the first and only one file that exists and there is a ConfigParser available that supports appropriate media type. Available parser means that the parser:

1. is loaded as a service using ServiceLoader;
2. or if it does not exist, a config core built-in parser is used, if exists.

See Also:

• Config.create()
• ConfigSource
• ConfigParser
• ConfigFilter

Method Summary

Modifier and Type	Method	Description
Config.Builder	addFilter(ConfigFilter configFilter)	Registers a ConfigFilter instance that will be used by Config to filter elementary value before it is returned to a user.
Config.Builder	addFilter(Function<Config,ConfigFilter> configFilterProvider)	Registers a ConfigFilter provider as a Function<Config, ConfigFilter>.
Config.Builder	addFilter(Supplier<Function<Config,ConfigFilter>> configFilterSupplier)	Registers a ConfigFilter provider as a Supplier<Function<Config, ConfigFilter>>.
<T> Config.Builder	addMapper(GenericType<T> type, Function<Config,T> mapper)	Register a mapping function for specified GenericType.
Config.Builder	addMapper(ConfigMapperProvider configMapperProvider)	Registers a ConfigMapperProvider with a map of String to specified type.
<T> Config.Builder	addMapper(Class<T> type, Function<Config,T> mapper)	Registers mapping function for specified type.
Config.Builder	addParser(ConfigParser configParser)	Registers a ConfigParser instance that can be used by config system to parse ConfigParser.Content of ParsableSource.
Config.Builder	addSource(ConfigSource source)	Add a config source to the list of sources.
default Config.Builder	addSource(Supplier<? extends ConfigSource> source)	Add a single config source to this builder.
<T> Config.Builder	addStringMapper(Class<T> type, Function<String,T> mapper)	Registers simple Function from String for specified type.
Config	build()	Builds new instance of Config.
Config.Builder	changesExecutor(Executor changesExecutor)	Specifies "observe-on" Executor to be used by Config.onChange(java.util.function.Consumer) to deliver new Config instance.
Config.Builder	config(Config metaConfig)	Configure this config builder from meta configuration.
Config.Builder	disableCaching()	Disables caching of elementary configuration values on Config side.
Config.Builder	disableEnvironmentVariablesSource()	Disables use of environment variables config source.
Config.Builder	disableFilterServices()	Disables automatic registration of filters loaded as a service.
Config.Builder	disableKeyResolving()	Disables any usage of resolving key tokens.
Config.Builder	disableMapperServices()	Disables automatic registration of mappers via ConfigMapperProvider SPI loaded as a service.
Config.Builder	disableParserServices()	Disables automatic registration of parsers loaded as a service.
Config.Builder	disableSystemPropertiesSource()	Disables use of system properties config source.
Config.Builder	disableValueResolving()	Disables any usage of resolving value tokens.
Config.Builder	failOnMissingKeyReference(boolean shouldFail)	When key resolving is enabled and a reference cannot be resolved, should we fail, or use the key verbatim.
Config.Builder	failOnMissingValueReference(boolean shouldFail)	When value resolving is enabled and a reference cannot be resolved, should we fail, or use the value verbatim.
Config.Builder	mergingStrategy(MergingStrategy strategy)	Merging Strategy to use when more than one config source is used.
default Config.Builder	metaConfig()	Check if meta configuration is present and if so, update this builder using the meta configuration.
Config.Builder	overrides(Supplier<? extends OverrideSource> overridingSource)	Sets the source of an override source.
default Config.Builder	sources(Supplier<? extends ConfigSource> configSource)	Sets a ConfigSource instance to be used as a source of configuration to be wrapped into Config API.
default Config.Builder	sources(Supplier<? extends ConfigSource> configSource, Supplier<? extends ConfigSource> configSource2)	Sets an ordered pair of ConfigSource instances to be used as single source of configuration to be wrapped into Config API.
default Config.Builder	sources(Supplier<? extends ConfigSource> configSource, Supplier<? extends ConfigSource> configSource2, Supplier<? extends ConfigSource> configSource3)	Sets an ordered trio of ConfigSource instances to be used as single source of configuration to be wrapped into Config API.
Config.Builder	sources(List<Supplier<? extends ConfigSource>> configSources)	Sets ordered list of ConfigSource instance to be used as single source of configuration to be wrapped into Config API.

Methods inherited from interface io.helidon.common.Builder

get, identity, update

Method Details

sources

Config.Builder sources(List<Supplier<? extends ConfigSource>> configSources)

Sets ordered list of ConfigSource instance to be used as single source of configuration to be wrapped into Config API.

Configuration sources found earlier in the list are considered to have a higher priority than the latter ones. I.e., when resolving a value of a key, the sources are consulted in the order they have been provided and as soon as the value is found in a configuration source, the value immediately is returned without consulting any of the remaining configuration sources in the prioritized collection.

Target source is composed of following sources, in order:

1. environment variables config source
   Can disabled by disableEnvironmentVariablesSource()
2. system properties config source Can disabled by disableSystemPropertiesSource()
3. Source(s) specified by user in the method.

Parameters:

configSources - ordered list of configuration sources

Returns:

an updated builder instance

See Also:

• disableEnvironmentVariablesSource()
• disableSystemPropertiesSource()

addSource

Config.Builder addSource(ConfigSource source)

Add a config source to the list of sources.

Parameters:

source - to add

Returns:

updated builder instance

mergingStrategy

Config.Builder mergingStrategy(MergingStrategy strategy)

Merging Strategy to use when more than one config source is used.

Parameters:

strategy - strategy to use, defaults to a strategy where a value for first source wins over values from later sources

Returns:

updated builder instance

addSource

default Config.Builder addSource(Supplier<? extends ConfigSource> source)

Add a single config source to this builder.

Parameters:

source - config source to add

Returns:

updated builder instance

sources

default Config.Builder sources(Supplier<? extends ConfigSource> configSource)

Sets a ConfigSource instance to be used as a source of configuration to be wrapped into Config API.

Target source is composed of configSource and following sources (unless they are disabled) in order:

1. environment variables config source
   Can disabled by disableEnvironmentVariablesSource()
2. system properties config source Can disabled by disableSystemPropertiesSource()
3. Source(s) specified by user in the method.

Parameters:

configSource - the only config source

Returns:

an updated builder instance

See Also:

• Config.create(Supplier...)
• sources(List)
• disableEnvironmentVariablesSource()
• disableSystemPropertiesSource()

sources

default Config.Builder sources(Supplier<? extends ConfigSource> configSource,
 Supplier<? extends ConfigSource> configSource2)

Sets an ordered pair of ConfigSource instances to be used as single source of configuration to be wrapped into Config API.

Target source is of from configSource and following sources (unless they are disabled) in order:

1. environment variables config source
   Can disabled by disableEnvironmentVariablesSource()
2. system properties config source Can disabled by disableSystemPropertiesSource()
3. Source(s) specified by user in the method.

Parameters:

configSource - the first config source

configSource2 - the second config source

Returns:

an updated builder instance

See Also:

• Config.create(Supplier...)
• sources(List)
• disableEnvironmentVariablesSource()
• disableSystemPropertiesSource()

sources

default Config.Builder sources(Supplier<? extends ConfigSource> configSource,
 Supplier<? extends ConfigSource> configSource2,
 Supplier<? extends ConfigSource> configSource3)

Sets an ordered trio of ConfigSource instances to be used as single source of configuration to be wrapped into Config API.

Target source is composed of config sources parameters and following sources (unless they are disabled) in order:

1. environment variables config source
   Can disabled by disableEnvironmentVariablesSource()
2. system properties config source Can disabled by disableSystemPropertiesSource()
3. Source(s) specified by user in the method.

Parameters:

configSource - the first config source

configSource2 - the second config source

configSource3 - the third config source

Returns:

an updated builder instance

See Also:

• Config.create(Supplier...)
• sources(List)
• disableEnvironmentVariablesSource()
• disableSystemPropertiesSource()

overrides

Config.Builder overrides(Supplier<? extends OverrideSource> overridingSource)

Sets the source of an override source.

The feature allows user to override existing values with other ones, specified by wildcards. Default values might be defined with key token references (i.e. $env.$pod.logging.level: INFO) that might be overridden by a config source with a higher weight to identify the current environment (i.e. env: test and pod: qwerty). The overrides are able to redefine values using wildcards (or without them). For example test.*.logging.level = FINE overrides logging.level for all pods in test environment.

Override definitions are applied before any filter.

Parameters:

overridingSource - a source with overriding key patterns and assigned values

Returns:

an updated builder instance

disableKeyResolving

Config.Builder disableKeyResolving()

Disables any usage of resolving key tokens.

A key can contain tokens starting with $ (i.e. $host.$port), that are resolved by default and tokens are replaced with a value of the key with the token as a key.

Returns:

an updated builder instance

failOnMissingKeyReference

Config.Builder failOnMissingKeyReference(boolean shouldFail)

When key resolving is enabled and a reference cannot be resolved, should we fail, or use the key verbatim. Defaults to false, so key resolving does not fail when a reference is missing.

Parameters:

shouldFail - whether to fail when key reference cannot be resolved

Returns:

updated builder

See Also:

• disableKeyResolving()

disableValueResolving

Config.Builder disableValueResolving()

Disables any usage of resolving value tokens.

A value can contain tokens enclosed in ${} (i.e. ${name}), that are resolved by default and tokens are replaced with a value of the key with the token as a key.

By default, a value resolving filter is added to configuration. When this method is called, the filter will not be added and value resolving will be disabled

Returns:

an updated builder instance

failOnMissingValueReference

Config.Builder failOnMissingValueReference(boolean shouldFail)

When value resolving is enabled and a reference cannot be resolved, should we fail, or use the value verbatim. Defaults to false, so value resolving does not fail when a reference is missing.

Parameters:

shouldFail - whether to fail when value reference cannot be resolved

Returns:

updated builder

See Also:

• disableValueResolving()

disableEnvironmentVariablesSource

Config.Builder disableEnvironmentVariablesSource()

Disables use of environment variables config source.

Returns:

an updated builder instance

See Also:

• ConfigSources.environmentVariables()

disableSystemPropertiesSource

Config.Builder disableSystemPropertiesSource()

Disables use of system properties config source.

Returns:

an updated builder instance

See Also:

• ConfigSources.systemProperties()

addMapper

<T> Config.Builder addMapper(Class<T> type,
 Function<Config,T> mapper)

Registers mapping function for specified type. The last registration of same type overwrites previous one. Programmatically registered mappers have priority over other options.

As another option, mappers are loaded automatically as a service via ConfigMapperProvider SPI unless it is disabled.

And the last option, built-in mappers are registered.

Type Parameters:

T - type the mapper is registered for

Parameters:

type - class of type the mapper is registered for

mapper - mapping function

Returns:

an updated builder instance

See Also:

• addStringMapper(Class, Function)
• addMapper(ConfigMapperProvider)
• disableMapperServices()

addMapper

<T> Config.Builder addMapper(GenericType<T> type,
 Function<Config,T> mapper)

Register a mapping function for specified GenericType. This is useful for mappers that support specifically typed generics, such as Map<String, Integer> or Set<Foo<Bar>>. To support mappers that can map any type (e.g. all cases of Map<String, V>), use addMapper(ConfigMapperProvider) as it gives you full control over which types are supported, through ConfigMapperProvider.mapper(GenericType).

Type Parameters:

T - type of the result

Parameters:

type - generic type to register a mapper for

mapper - mapping function

Returns:

updated builder instance

addStringMapper

<T> Config.Builder addStringMapper(Class<T> type,
 Function<String,T> mapper)

Registers simple Function from String for specified type. The last registration of same type overwrites previous one. Programmatically registered mappers have priority over other options.

As another option, mappers are loaded automatically as a service via ConfigMapperProvider SPI, if not disabled.

And the last option, built-in mappers are registered.

Type Parameters:

T - type the mapper is registered for

Parameters:

type - class of type the mapper is registered for

mapper - mapper instance

Returns:

an updated builder instance

See Also:

• addMapper(ConfigMapperProvider)
• ConfigMappers
• disableMapperServices()

addMapper

Config.Builder addMapper(ConfigMapperProvider configMapperProvider)

Registers a ConfigMapperProvider with a map of String to specified type. The last registration of same type overwrites previous one. Programmatically registered mappers have priority over other options.

As another option, mappers are loaded automatically as a service via ConfigMapperProvider SPI, if not disabled.

And the last option, built-in mappers are registered.

Parameters:

configMapperProvider - mapper provider instance

Returns:

modified builder instance

See Also:

• addStringMapper(Class, Function)
• ConfigMappers
• disableMapperServices()

disableMapperServices

Config.Builder disableMapperServices()

Disables automatic registration of mappers via ConfigMapperProvider SPI loaded as a service.

Order of configuration mapper providers loaded as a service is defined by Weight annotation.

Automatic registration of mappers as a service is enabled by default.

Returns:

an updated builder instance

See Also:

• ConfigMapperProvider

addParser

Config.Builder addParser(ConfigParser configParser)

Registers a ConfigParser instance that can be used by config system to parse ConfigParser.Content of ParsableSource. Parsers ConfigParser.supportedMediaTypes() is queried in same order as was registered by this method. Programmatically registered parsers have priority over other options.

As another option, parsers are loaded automatically as a service, if not disabled.

Parameters:

configParser - parser instance

Returns:

an updated builder instance

See Also:

• disableParserServices()

disableParserServices

Config.Builder disableParserServices()

Disables automatic registration of parsers loaded as a service.

Order of configuration parsers loaded as a service is defined by Weight annotation.

Automatic registration of parsers as a service is enabled by default.

Returns:

an updated builder instance

See Also:

• ConfigParser

addFilter

Config.Builder addFilter(ConfigFilter configFilter)

Registers a ConfigFilter instance that will be used by Config to filter elementary value before it is returned to a user.

Filters are applied in same order as was registered by this method, addFilter(Function) or addFilter(Supplier) method.

ConfigFilter is actually a BiFunction<String,String,String> where the first input parameter is the config key, the second is the original value and the result is the new value. So the filter can be added as simply as:

     Config.builder()
          .addFilter((key, originalValue) -> originalValue.toUpperCase())
          .build();
 

The config system will automatically load filters defined as a service, unless disabled.

Parameters:

configFilter - filter instance

Returns:

an updated builder instance

See Also:

• addFilter(Function)
• addFilter(Supplier)

addFilter

Config.Builder addFilter(Function<Config,ConfigFilter> configFilterProvider)

Registers a ConfigFilter provider as a Function<Config, ConfigFilter>. An obtained filter will be used by Config to filter elementary value before it is returned to a user.

Filters are applied in same order as was registered by the addFilter(ConfigFilter), this method, or addFilter(Supplier) method.

Registered provider's Function.apply(Object) method is called every time the new Config is created. E.g. when this builder's build() method creates the Config or when the new Config.onChange(java.util.function.Consumer) is fired with new Config instance with its own filter instance is created.

Parameters:

configFilterProvider - a config filter provider as a function of Config to ConfigFilter

Returns:

an updated builder instance

See Also:

• addFilter(ConfigFilter)
• addFilter(Supplier)

addFilter

Config.Builder addFilter(Supplier<Function<Config,ConfigFilter>> configFilterSupplier)

Registers a ConfigFilter provider as a Supplier<Function<Config, ConfigFilter>>. An obtained filter will be used by Config to filter elementary value before it is returned to a user.

Filters are applied in same order as was registered by the addFilter(ConfigFilter), addFilter(Function), or this method.

Registered provider's Function.apply(Object) method is called every time the new Config is created. E.g. when this builder's build() method creates the Config or when the new Config.onChange(java.util.function.Consumer) change event is fired with new Config instance with its own filter instance is created.

Parameters:

configFilterSupplier - a config filter provider as a supplier of a function of Config to ConfigFilter

Returns:

an updated builder instance

See Also:

• addFilter(ConfigFilter)
• addFilter(Function)

disableFilterServices

Config.Builder disableFilterServices()

Disables automatic registration of filters loaded as a service.

Order of configuration filters loaded as a service is defined by Weight annotation.

Automatic registration of filters as a service is enabled by default.

Returns:

an updated builder instance

See Also:

• ConfigFilter

disableCaching

Config.Builder disableCaching()

Disables caching of elementary configuration values on Config side.

Caching is about ConfigFilters. With disabled caching, registered filters are applied always you access elementary configuration value. With enabled caching, registered filters are applied just once per unique config node (key). Repeated access of already filtered key directly returns already cached value.

Caching is enabled by default.

Returns:

an updated builder instance

See Also:

• addFilter(ConfigFilter)

changesExecutor

Config.Builder changesExecutor(Executor changesExecutor)

Specifies "observe-on" Executor to be used by Config.onChange(java.util.function.Consumer) to deliver new Config instance. Executor is also used to process reloading of config from appropriate source.

By default, dedicated thread pool that creates new threads as needed, but will reuse previously constructed threads when they are available is used.

Parameters:

changesExecutor - the executor to use for async delivery of Config.onChange(java.util.function.Consumer)

Returns:

an updated builder instance

See Also:

• Config.onChange(java.util.function.Consumer)

build

Config build()

Builds new instance of Config.

Specified by:

build in interface Builder<Config.Builder,Config>

Returns:

new instance of Config.

metaConfig

default Config.Builder metaConfig()

Check if meta configuration is present and if so, update this builder using the meta configuration.

Returns:

updated builder instance

See Also:

• config(Config)

config

Config.Builder config(Config metaConfig)

Configure this config builder from meta configuration.

The following configuration options are supported in a meta configuration file:

Meta configuration

key	default value	description	reference
caching.enabled	true	Enable or disable caching of results of filters.	disableCaching()
key-resolving.enabled	true	Enable or disable resolving of placeholders in keys.	disableKeyResolving()
value-resolving.enabled	true	Enable or disable resolving of placeholders in values.	disableValueResolving()
parsers.enabled	true	Enable or disable parser services.	disableParserServices()
mappers.enabled	true	Enable or disable mapper services.	disableMapperServices()
override-source	none	Configure an override source. Same as config source configuration (see below)	overrides(java.util.function.Supplier)
sources	Default config sources are prefixed application, and suffix is the first available of yaml, conf, json, properties	Configure config sources to be used by the application. This node contains the array of objects defining config sources	addSource(io.helidon.config.spi.ConfigSource)

Config source configuration options:

Config source

key	default value	description	reference
type		Type of a config source - a string supported by a provider.	MetaConfigurableProvider.create(String, Config)
multi-source	false	If set to true, the provider creates more than one config source to be added	ConfigSourceProvider.createMulti(String, Config)
properties		Configuration options to configure the config source (meta configuration of a source)	MetaConfigurableProvider.create(String, Config), MetaConfig.configSource(Config)
properties.optional	false	Config sources can be configured to be optional	Source.optional()
properties.polling-strategy		Some config sources can have a polling strategy defined	PollableSource.Builder.pollingStrategy(io.helidon.config.spi.PollingStrategy), MetaConfig.pollingStrategy(Config)
properties.change-watcher		Some config sources can have a change watcher defined	WatchableSource.Builder.changeWatcher(io.helidon.config.spi.ChangeWatcher), MetaConfig.changeWatcher(Config)
properties.retry-policy		Config sources can have a retry policy defined	Source.retryPolicy(), MetaConfig.retryPolicy(Config)

Full meta configuration example:

 sources:
   - type: "system-properties"
   - type: "environment-variables"
   - type: "file"
     properties:
       optional: true
       path: "conf/dev-application.yaml"
       polling-strategy:
         type: "regular"
       retry-policy:
         type: "repeat"
         properties:
           retries: 5
    - type: "classpath"
      properties:
        optional: true
        resource: "application.yaml"
 

Parameters:

metaConfig - meta configuration to set this builder up

Returns:

updated builder from meta configuration