An immutable map from config paths to config values. Paths are dot-separated expressions such as foo.bar.baz. Values are as in JSON (booleans, strings, numbers, lists, or objects), represented by ConfigValue instances. Values accessed through the Config interface are never null.

Config is an immutable object and thus safe to use from multiple threads. There's never a need for "defensive copies."

Fundamental operations on a Config include getting configuration values, resolving substitutions with Config#resolve(), and merging configs using Config#withFallback(ConfigMergeable).

All operations return a new immutable Config rather than modifying the original instance.

Examples

You can find an example app and library on GitHub. Also be sure to read the package overview which describes the big picture as shown in those examples.

Paths, keys, and Config vs. ConfigObject

Config is a view onto a tree of ConfigObject; the corresponding object tree can be found through Config#root(). ConfigObject is a map from config keys, rather than paths, to config values. Think of ConfigObject as a JSON object and Config as a configuration API.

The API tries to consistently use the terms "key" and "path." A key is a key in a JSON object; it's just a string that's the key in a map. A "path" is a parseable expression with a syntax and it refers to a series of keys. Path expressions are described in the spec for Human-Optimized Config Object Notation. In brief, a path is period-separated so "a.b.c" looks for key c in object b in object a in the root object. Sometimes double quotes are needed around special characters in path expressions.

The API for a Config is in terms of path expressions, while the API for a ConfigObject is in terms of keys. Conceptually, Config is a one-level map from paths to values, while a ConfigObject is a tree of nested maps from keys to values.

Use ConfigUtil#joinPath and ConfigUtil#splitPath to convert between path expressions and individual path elements (keys).

Another difference between Config and ConfigObject is that conceptually, ConfigValues with a valueType() of NULL exist in a ConfigObject, while a Config treats null values as if they were missing. (With the exception of two methods: Config#hasPathOrNull and Config#getIsNull let you detect null values.)

Getting configuration values

The "getters" on a Config all work in the same way. They never return null, nor do they return a ConfigValue with valueType() of NULL. Instead, they throw ConfigException.Missing if the value is completely absent or set to null. If the value is set to null, a subtype of ConfigException.Missing called ConfigException.Null will be thrown. ConfigException.WrongType will be thrown anytime you ask for a type and the value has an incompatible type. Reasonable type conversions are performed for you though.

Iteration

If you want to iterate over the contents of a Config, you can get its ConfigObject with root(), and then iterate over the ConfigObject (which implements java.util.Map). Or, you can use entrySet() which recurses the object tree for you and builds up a Set of all path-value pairs where the value is not null.

Resolving substitutions

Substitutions are the ${foo.bar} syntax in config files, described in the specification. Resolving substitutions replaces these references with real values.

Before using a Config it's necessary to call Config#resolve() to handle substitutions (though ConfigFactory#load() and similar methods will do the resolve for you already).

Merging

The full Config for your application can be constructed using the associative operation Config#withFallback(ConfigMergeable). If you use ConfigFactory#load() (recommended), it merges system properties over the top of application.conf over the top of reference.conf, using withFallback. You can add in additional sources of configuration in the same way (usually, custom layers should go either just above or just below application.conf, keeping reference.conf at the bottom and system properties at the top).

Serialization

Convert a Config to a JSON or HOCON string by calling ConfigObject#render() on the root object, myConfig.root().render(). There's also a variant ConfigObject#render(ConfigRenderOptions) which allows you to control the format of the rendered string. (See ConfigRenderOptions.) Note that Config does not remember the formatting of the original file, so if you load, modify, and re-save a config file, it will be substantially reformatted.

As an alternative to ConfigObject#render(), the toString() method produces a debug-output-oriented representation (which is not valid JSON).

Java serialization is supported as well for Config and all subtypes of ConfigValue.

This is an interface but don't implement it yourself

Do not implement Config; it should only be implemented by the config library. Arbitrary implementations will not work because the library internals assume a specific concrete implementation. Also, this interface is likely to grow new methods over time, so third-party implementations will break.