Sources

Sources are the runtime component that populate your configuration objects with runtime values. The most common source is EnvSource, which reads values from environment variables, but there are others that read from files or even hardcoded maps (though that’s largely a toy implementation).

You use sources to construct generated configuration objects; by default, just a single EnvSource is used. You can only construct use a single Source object, but there are Source classes that delegate to multiple sources, e.g. MultiSource.

The Source interface is pretty simple:

interface Source {
    fun getInt(key: String): Int?
    fun getString(key: String): String?
    fun getDouble(key: String): Double?
    fun getBoolean(key: String): Boolean?
    fun getList(key: String): List<String>?
}

EnvSource

EnvSource reads environment variables to populate configuration.

Keys are translated from lower camel case to screaming snake case when checking in the environment. Additionally, periods are also translated into underscores.

Config Key	Environment Variable
port	PORT
applicationPort	APPLICATION_PORT
database.port	DATABASE_PORT
database.userName	DATABASE_USER_NAME

MapSource

MapSource simply takes a Map<String, Any> as a constructor argument that you provide when constructing the source. The map can be hardcoded or built any way you like, though you’re encouraged to just implement Source directly for anything non-trivial.

By default, keys are passed through as is — the key applicationPort is queried directly against the map as applicationPort. No case-translation unless you request it in the constructor.

MultiSource

MultiSource is a higher-order source that takes a list of other sources as an input. When querying the MultiSource, it simply queries each source provided, in order, until one provides a non-null value.

If one constructs a MultiSource like this:

val source = MultiSource(source1, source2)
val config = GeneratedConfig(source)
val port = config.port

Then MultiSource will query source1 for configuration, and if none is found, query source2, and so on.

If this behavior isn’t to your needs, you can also implement your own Source.

CachedSource

CachedSource is another higher-order source that wraps another, presumably slow, source, by calling through to the delegated source and saving its results internally.

It also defines a .cached() extension method on Sources for convenience.

Usage is like this:

val source: Source = MySlowSource().cached()

However, none of the built-in sources are slow enough to benefit from caching, so this is provided mainly for user-provided sources that perhaps pull configuration from the network.