Package io.helidon.config

Interface Config.Builder

Enclosing interface:

Config

public static interface Config.Builder

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 configuration node mappers. It is also possible to disable loading of ConfigMappers 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 ConfigMappers, if there is no one that could be used to map appropriate type, it uses reflection API to find public constructor or a public static method to construct type instance from config node:

1. a static method named from with a single Config argument that return an instance of the type;
2. a constructor that accepts a single Config argument;
3. a static method named valueOf with a single Config argument that return an instance of the type;
4. a static method named fromConfig with a single Config argument that return an instance of the type;
5. a static method named from with a single String argument that return an instance of the type;
6. a constructor that accepts a single String argument;
7. a static method named valueOf with a single String argument that return an instance of the type;
8. a static method named fromString with a single String argument that return an instance of the type;
9. a static method builder() that creates instance of a builder class. Generic JavaBean deserialization is applied on the builder instance using config sub-nodes. See the last list item for more details about generic deserialization support. Builder has build() method to create new instance of a bean.
10. a factory method from with parameters (loaded from config sub-nodes) creates new instance of a bean; Annotation Config.Value is used on parameters to customize sub-key and/or default value.
11. a "factory" constructor with parameters (loaded from config sub-nodes); Annotation Config.Value is used on parameters to customize sub-key and/or default value.
12. a no-parameter constructor to create new instance of type and apply recursively same mapping behaviour described above on each JavaBean property of such object, a.k.a. JavaBean deserialization. Public property setter is used by default to set a property value loaded from appropriate config sub-node. By default a setter pattern is required - public method named set* with single parameter that returns void. It is possible to suppress returned void and set* name requirements by marking a method by Config.Value annotation. If there is no public setter, a public property field is used to set a property value. Generic mapping behaviour can be customized by Config.Value and Config.Transient annotations.

See Config.Value documentation for more details about generic deserialization feature.

If ConfigSource 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, ConfigMapper

Method Summary

Modifier and Type	Method and 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(java.util.function.Function<Config,ConfigFilter> configFilterProvider) Registers a ConfigFilter provider as a Function<Config, ConfigFilter>.
Config.Builder	addFilter(java.util.function.Supplier<java.util.function.Function<Config,ConfigFilter>> configFilterSupplier) Registers a ConfigFilter provider as a Supplier<Function<Config, ConfigFilter>>.
<T> Config.Builder	addMapper(java.lang.Class<T> type, ConfigMapper<T> mapper) Registers contextual ConfigMapper for specified type.
<T> Config.Builder	addMapper(java.lang.Class<T> type, java.util.function.Function<java.lang.String,T> mapper) Registers simple Function from String for specified type.
Config.Builder	addMapper(ConfigMapperProvider configMapperProvider) Registers a ConfigMapper provider with a map of String to specified type.
Config.Builder	addParser(ConfigParser configParser) Registers a ConfigParser instance that can be used by registered ConfigSources to parse configuration content.
Config	build() Builds new instance of Config.
Config.Builder	changesExecutor(java.util.concurrent.Executor changesExecutor) Specifies "observe-on" Executor to be used by Config.changes() to deliver new Config instance.
Config.Builder	changesMaxBuffer(int changesMaxBuffer) Specifies maximum capacity for each subscriber's buffer to be used by by Config.changes() to deliver new Config instance.
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 an 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 an usage of resolving value tokens.
Config.Builder	overrides(java.util.function.Supplier<OverrideSource> overridingSource) Sets source of a override source.
Config.Builder	sources(java.util.List<java.util.function.Supplier<ConfigSource>> configSources) Sets ordered list of ConfigSource instance to be used as single source of configuration to be wrapped into Config API.
default Config.Builder	sources(java.util.function.Supplier<ConfigSource> configSource) Sets a ConfigSource instance to be used as a source of configuration to be wrapped into Config API.
default Config.Builder	sources(java.util.function.Supplier<ConfigSource> configSource, java.util.function.Supplier<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(java.util.function.Supplier<ConfigSource> configSource, java.util.function.Supplier<ConfigSource> configSource2, java.util.function.Supplier<ConfigSource> configSource3) Sets an ordered trio of ConfigSource instances to be used as single source of configuration to be wrapped into Config API.

Method Detail

sources

Config.Builder sources(java.util.List<java.util.function.Supplier<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.

This is default implementation of ConfigSources.from(Supplier...) Composite ConfigSource} provided by Fallback MergingStrategy. It is possible to use custom implementation of merging strategy.

 builder.source(ConfigSources.from(source1, source2, source3)
                      .mergingStrategy(new MyMergingStrategy));
 

Target source is composed from 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(), ConfigSources.from(Supplier...), ConfigSources.CompositeBuilder, ConfigSources.MergingStrategy

sources

default Config.Builder sources(java.util.function.Supplier<ConfigSource> configSource)

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

Target source is composed 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 only config source

Returns:

an updated builder instance

See Also:

Config.from(Supplier...), sources(List), disableEnvironmentVariablesSource(), disableSystemPropertiesSource()

sources

default Config.Builder sources(java.util.function.Supplier<ConfigSource> configSource,
                               java.util.function.Supplier<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 composed 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.from(Supplier...), sources(List), disableEnvironmentVariablesSource(), disableSystemPropertiesSource()

sources

default Config.Builder sources(java.util.function.Supplier<ConfigSource> configSource,
                               java.util.function.Supplier<ConfigSource> configSource2,
                               java.util.function.Supplier<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 from 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.from(Supplier...), sources(List), disableEnvironmentVariablesSource(), disableSystemPropertiesSource()

overrides

Config.Builder overrides(java.util.function.Supplier<OverrideSource> overridingSource)

Sets source of a 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 priority 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 an 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

disableValueResolving

Config.Builder disableValueResolving()

Disables an 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.

Returns:

an updated builder instance

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(java.lang.Class<T> type,
                             ConfigMapper<T> mapper)

Registers contextual ConfigMapper 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(Class, Function), addMapper(ConfigMapperProvider), ConfigMappers, disableMapperServices()

addMapper

<T> Config.Builder addMapper(java.lang.Class<T> type,
                             java.util.function.Function<java.lang.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(Class, ConfigMapper), addMapper(ConfigMapperProvider), ConfigMappers, disableMapperServices()

addMapper

Config.Builder addMapper(ConfigMapperProvider configMapperProvider)

Registers a ConfigMapper provider 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:

addMapper(Class, ConfigMapper), addMapper(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 Priority 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 registered ConfigSources to parse configuration content. Parsers are tried to be used by ConfigContext.findParser(String) in same order as was registered by the addParser(ConfigParser) 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 Priority 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 the addFilter(ConfigFilter), 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(java.util.function.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), addFilter(Function) or addFilter(Supplier) method.

Registered provider's Function.apply(Object) method is called every time the new Config is created. Eg. when this builder's build() method creates the Config or when the new change event 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(java.util.function.Supplier<java.util.function.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 addFilter(Supplier) method.

Registered provider's Function.apply(Object) method is called every time the new Config is created. Eg. when this builder's build() method creates the Config or when the new 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 Priority 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(java.util.concurrent.Executor changesExecutor)

Specifies "observe-on" Executor to be used by Config.changes() 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.changes() events

Returns:

an updated builder instance

See Also:

changesMaxBuffer(int), Config.changes(), Config.onChange(Function), Source.changes()

changesMaxBuffer

Config.Builder changesMaxBuffer(int changesMaxBuffer)

Specifies maximum capacity for each subscriber's buffer to be used by by Config.changes() to deliver new Config instance.

By default Flow.DEFAULT_BUFFER_SIZE is used.

Note: Not consumed events will be dropped off.

Parameters:

changesMaxBuffer - the maximum capacity for each subscriber's buffer of Config.changes() events.

Returns:

an updated builder instance

See Also:

changesExecutor(Executor), Config.changes(), Config.onChange(Function)

build

Config build()

Builds new instance of Config.

Returns:

new instance of Config.