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 other ConfigSources

By implementing ConfigSourceFactory, the ConfigSource is made available via the ConfigSource getConfigSource(ConfigSourceContext context) method. The ConfigSourceFactory can be also assigned a priority, like any other ConfigSource by overriding the method OptionalInt getPriority().

When the Factory is initializing, the provided ConfigSourceContext may call a single method ConfigValue getValue(String name). This method lookups configuration names in all ConfigSources that are already initialized by the Config even if they have a lower priority than the one defined in the ConfigSourceFactory. A ConfigSource produced by a ConfigSourceFactory is not taken into account to configure other sources produced by 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.

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>1.9.3-SNAPSHOT</version>
</dependency>

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

HOCON Config Source

ConfigSource implementation to support HOCON file format.

This Configuration Source will be looking for the following files in this order of priority:

  1. META-INF/microprofile-config.conf

  2. WEB-INF/classes/META-INF/microprofile-config.conf

These configuration files have a lower priority than the default sources.

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>1.9.3-SNAPSHOT</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>1.9.3-SNAPSHOT</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 HOCON Config Source, add the following to your Maven pom.xml:

<dependency>
    <groupId>io.smallrye.config</groupId>
    <artifactId>smallrye-config-source-zookeeper</artifactId>
    <version>1.9.3-SNAPSHOT</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.