Config Sources

SmallRye Config provides a few enhancements and extensions to MicroProfile Config ConfigSource.

Config Source Factory

Another way to create a ConfigSource is via the ConfigSourceFactory. The difference between the SmallRye Factory and the standard way to create a ConfigSource as specified in MicroProfile Config, is the Factory ability to provide a context with access to the available configuration. With the ConfigSourceFactory it is possible to bootstrap a ConfigSource that configures itself with previously initialized ConfigSources.

By implementing ConfigSourceFactory, a list of ConfigSources may be provided via the Iterable<ConfigSource> getConfigSources(ConfigSourceContext context) method. The ConfigSourceFactory may also assign a priority by overriding the default method OptionalInt getPriority(). This is only used to sort multiple factories during initialization. Once all the factories are initialized, the provided ConfigSources will use their own ordinal and be sorted with all ConfigSources available in the Config instance.

When the Factory is initializing, the provided ConfigSourceContext may call the method ConfigValue getValue(String name). This method lookups configuration names in all ConfigSources that were already initialized by the Config instance, including sources with lower ordinals than the ones defined in the ConfigSourceFactory. ConfigSources provided by a ConfigSourceFactory is not taken into account to configure other sources produced by a lower priority ConfigSourceFactory.

Registration of a ConfigSourceFactory is done via the ServiceLoader mechanism by providing the implementation classes in a META-INF/services/io.smallrye.config.ConfigSourceFactory file. Alternatively, factories may be registered via the Programmatic API in SmallRyeConfigBuilder#withSources.

Available Config Sources

In addition to the default Config Sources specified by MicroProfile Config (Environment Variables, System Properties and microprofile-config.properties file), SmallRye Config provides the following additional Sources:

Properties Config Source

Creates a ConfigSource from Java Properties or Map<String, String> objects or a properties file (referenced by its URL). Check PropertiesConfigSource.java.

Config Value Properties Config Source

Creates a Config Source with ConfigValue support from a properties file (referenced by its URL).

The ConfigValue is a metadata object, containing additional information to each configuration. This includes the Config Source origin, ordinal, or the line number from where the Config was loaded. This is useful for debugging information.

Usage

This Config Source is not automatically registered. This means that need to provide your own ConfigSourceProvider implementation and registration via ServiceLoader to use this Config Source like documented in MicroProfile Config ConfigSource specification.

FileSystem Config Source

Creates a ConfigSource that will look into a directory where each file corresponds to a property (the file name is the property key and its textual content is the property value).

For example, if a directory structure looks like:

foo/
|__num.max
|__num.size

A new FileSystemConfigSource("foo") will provide 2 properties:

  • num.max

  • num.size

And their values is the file content.

Nested directories are not supported.

This Config Source can be used to read configuration from Kubernetes ConfigMap. Check the Kubernetes ConfigMap ConfigSource Example.

The same mapping rules as defined for environment variables are applied, so the FileSystemConfigSource will search for a given property name (e.g. com.ACME.size):

  • Exact match (i.e. com.ACME.size)

  • Replace each character that is neither alphanumeric nor _ with _ (i.e. com_ACME_size)

  • Replace each character that is neither alphanumeric nor _ with _; then convert the name to upper case (i.e. COM_ACME_SIZE)

Usage

To use the FileSystem Config Source, add the following to your Maven pom.xml:

<dependency>
    <groupId>io.smallrye.config</groupId>
    <artifactId>smallrye-config-source-file-system</artifactId>
    <version>2.4.0</version>
</dependency>

This Config Source register itself with the application if the dependency is present. Use the configuration property smallrye.config.source.file.locations to set the directory paths to lookup additional configurations. It accepts multiple locations separated by a comma and each must represent a valid URI to a directory.

HOCON Config Source

ConfigSource implementation to support HOCON file format.

This Configuration Source will be looking for the following file META-INF/microprofile-config.conf and will be loaded with a lower ordinal than the default sources. The loading ordinal is 50.

Usage

To use the HOCON Config Source, add the following to your Maven pom.xml:

<dependency>
    <groupId>io.smallrye.config</groupId>
    <artifactId>smallrye-config-source-hocon</artifactId>
    <version>2.4.0</version>
</dependency>

This Config Source will automatically register with your application.

YAML Config Source

This Config Source allows you to use a yaml file to describe your configuration. By default, the YAML Config Source loads the configuration from the file microprofile-config.yaml.

This Config Source has a higher priority than the default microprofile-config.properties.

Usage

To use the YAML Config Source, add the following to your Maven pom.xml:

<dependency>
    <groupId>io.smallrye.config</groupId>
    <artifactId>smallrye-config-source-yaml</artifactId>
    <version>2.4.0</version>
</dependency>

This Config Source will automatically register with your application.

ZooKeeper Config Source

Config Source implementation to support Apache Zookeeper.

The benefits are that configurations can be shared across applications and a future version will allow applications to subscribe to updates to the configuration parameters.

Usage

To use the Zookeeper Config Source, add the following to your Maven pom.xml:

<dependency>
    <groupId>io.smallrye.config</groupId>
    <artifactId>smallrye-config-source-zookeeper</artifactId>
    <version>2.4.0</version>
</dependency>

This Config Source will automatically register with your application.

You also need to bootstrap your application with the location of your Zookeeper server and a unique identifier for your application. Add the following to src/main/resources/META-INF/microprofile-config.properties or create equivalent Environment Variables.

io.smallrye.configsource.zookeeper.url=localhost:2181
io.smallrye.configsource.zookeeper.applicationId=com.example.my-application

Any properties that are looked up via the Config API or Injected will be looked up in Zookeeper in addition to the default MicroProfile Config locations.

The ConfigSource will store the following znodes in the specified Zookeeper server /applicationId/propertyName = value.

This Config Source has a lower priority than the default Sources and thus will not override property files or Environment Variables.