Skip to content
Branch: master
Find file Copy path
Find file Copy path
6 contributors

Users who have contributed to this file

@struberg @Emily-Jiang @johnament @OndroMih @jmesnil @doychin
159 lines (116 sloc) 6.36 KB


A ConfigSource is exactly what its name says: a source for configured values. The Config uses all configured implementations of ConfigSource to look up the property in question.

ConfigSource Ordering

Each ConfigSource has a specified ordinal, which is used to determine the importance of the values taken from the associated ConfigSource. A higher ordinal means that the values taken from this ConfigSource will override values from lower-priority ConfigSources. This allows a configuration to be customized from outside a binary, assuming that external ConfigSource s have higher ordinal values than the ones whose values originate within the release binaries.

It can also be used to implement a drop-in configuration approach. Simply create a jar containing a ConfigSource with a higher ordinal and override configuration values in it. If the jar is present on the classpath then it will override configuration values from ConfigSources with lower ordinal values.

Manually defining the Ordinal of a built-in ConfigSource

Note that a special property config_ordinal can be set within any built-in ConfigSource implementation. The default implementation of getOrdinal() will attempt to read this value. If found and a valid integer, the value will be used. Otherwise the respective default value will be used.

config_ordinal = 120
com.acme.myproject.someserver.url = http://more_important.server/some/endpoint

Default ConfigSources

A Microprofile-Config implementation must provide ConfigSources for the following data out of the box:

  • System properties (default ordinal=400).

  • Environment variables (default ordinal=300).

    Some operating systems allow only alphabetic characters or an underscore, _, in environment variables. Other characters such as ., /, etc may be disallowed. In order to set a value for a config property that has a name containing such disallowed characters from an environment variable, the following rules are used.

This ConfigSource searches 3 environment variables for a given property name (e.g. com.ACME.size):

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

  2. Replace the character that is neither alphanumeric nor _ with _ (i.e. com_ACME_size)

  3. Replace the character that is neither alphanumeric nor _ with _ and convert to upper case (i.e. COM_ACME_SIZE)

    The first environment variable that is found is returned by this ConfigSource.

    • A ConfigSource for each property file META-INF/ found on the classpath. (default ordinal = 100).

Custom ConfigSources

ConfigSources are discovered using the java.util.ServiceLoader mechanism.

To add a custom ConfigSource, implement the interface org.eclipse.microprofile.config.spi.ConfigSource.

public class CustomDbConfigSource implements ConfigSource {

    public int getOrdinal() {
        return 112;

    public Set<String> getPropertyNames() {
        return readPropertyNames();

    public Map<String, String> getProperties() {
        return readPropertiesFromDb();

    public String getValue(String key) {
        return readPropertyFromDb(key);

    public String getName() {
        return "customDbConfig";


Then register your implementation in a resource file /META-INF/services/org.eclipse.microprofile.config.spi.ConfigSource by including the fully-qualified class name of the custom implementation in the file.

Custom ConfigSources via ConfigSourceProvider

If you need dynamic ConfigSources you can also register a ConfigSourceProvider in a similar manner. This is useful if you need to dynamically pick up multiple ConfigSources of the same kind; for example, to pick up all resources from all the JARs in your classpath.

A custom ConfigSourceProvider must implement the interface org.eclipse.microprofile.config.spi.ConfigSourceProvider. Register your implementation in a resource file /META-INF/services/org.eclipse.microprofile.config.spi.ConfigSourceProvider by including the fully-qualified class name of the custom implementation/s in the file.

An example which registers all YAML files with the name exampleconfig.yaml:

public class ExampleYamlConfigSourceProvider
        implements org.eclipse.microprofile.config.spi.ConfigSourceProvider {
    public List<ConfigSource> getConfigSources(ClassLoader forClassLoader) {
        List<ConfigSource> configSources = new ArrayList<>();

        Enumeration<URL> yamlFiles
            = forClassLoader.getResources("sampleconfig.yaml");
        while (yamlFiles.hasMoreElements()) {
            configSources.add(new SampleYamlConfigSource(yamlFiles.nextElement()));
        return configSources;

Please note that a single ConfigSource should be either registered directly or via a ConfigSourceProvider, but never both ways.

Cleaning up a ConfigSource

If a ConfigSource implements the java.lang.AutoCloseable interface then the close() method will be called when the underlying Config is being released.

ConfigSource and Mutable Data

A Config instance provides no caching but iterates over all ConfigSources for each getValue(String) operation. A ConfigSource is allowed to cache the underlying values itself.

You can’t perform that action at this time.