com.typesafe.config
Interface Config

All Superinterfaces:

ConfigMergeable

public interface Config
extends ConfigMergeable

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 resolve(), and merging configs using 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 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(java.lang.String...) and ConfigUtil.splitPath(java.lang.String) 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.

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 here. Resolving substitutions replaces these references with real values.

Before using a Config it's necessary to call 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 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).

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.

Method Summary

Config	atKey(java.lang.String key) Places the config inside a Config at the given key.
Config	atPath(java.lang.String path) Places the config inside another Config at the given path.
void	checkValid(Config reference, java.lang.String... restrictToPaths) Validates this config against a reference config, throwing an exception if it is invalid.
java.util.Set<java.util.Map.Entry<java.lang.String,ConfigValue>>	entrySet() Returns the set of path-value pairs, excluding any null values, found by recursing the root object.
java.lang.Object	getAnyRef(java.lang.String path) Gets the value at the path as an unwrapped Java boxed value ( Boolean, Integer, and so on - see ConfigValue.unwrapped()).
java.util.List<? extends java.lang.Object>	getAnyRefList(java.lang.String path)
boolean	getBoolean(java.lang.String path)
java.util.List<java.lang.Boolean>	getBooleanList(java.lang.String path)
java.lang.Long	getBytes(java.lang.String path) Gets a value as a size in bytes (parses special strings like "128M").
java.util.List<java.lang.Long>	getBytesList(java.lang.String path)
Config	getConfig(java.lang.String path)
java.util.List<? extends Config>	getConfigList(java.lang.String path)
double	getDouble(java.lang.String path)
java.util.List<java.lang.Double>	getDoubleList(java.lang.String path)
long	getDuration(java.lang.String path, java.util.concurrent.TimeUnit unit) Gets a value as a duration in a specified TimeUnit.
java.util.List<java.lang.Long>	getDurationList(java.lang.String path, java.util.concurrent.TimeUnit unit) Gets a list, converting each value in the list to a duration, using the same rules as getDuration(String, TimeUnit).
int	getInt(java.lang.String path)
java.util.List<java.lang.Integer>	getIntList(java.lang.String path)
ConfigList	getList(java.lang.String path) Gets a list value (with any element type) as a ConfigList, which implements java.util.List<ConfigValue>.
long	getLong(java.lang.String path)
java.util.List<java.lang.Long>	getLongList(java.lang.String path)
java.lang.Long	getMilliseconds(java.lang.String path) Deprecated. As of release 1.1, replaced by getDuration(String, TimeUnit)
java.util.List<java.lang.Long>	getMillisecondsList(java.lang.String path) Deprecated. As of release 1.1, replaced by getDurationList(String, TimeUnit)
java.lang.Long	getNanoseconds(java.lang.String path) Deprecated. As of release 1.1, replaced by getDuration(String, TimeUnit)
java.util.List<java.lang.Long>	getNanosecondsList(java.lang.String path) Deprecated. As of release 1.1, replaced by getDurationList(String, TimeUnit)
java.lang.Number	getNumber(java.lang.String path)
java.util.List<java.lang.Number>	getNumberList(java.lang.String path)
ConfigObject	getObject(java.lang.String path)
java.util.List<? extends ConfigObject>	getObjectList(java.lang.String path)
java.lang.String	getString(java.lang.String path)
java.util.List<java.lang.String>	getStringList(java.lang.String path)
ConfigValue	getValue(java.lang.String path) Gets the value at the given path, unless the value is a null value or missing, in which case it throws just like the other getters.
boolean	hasPath(java.lang.String path) Checks whether a value is present and non-null at the given path.
boolean	isEmpty() Returns true if the Config's root object contains no key-value pairs.
boolean	isResolved() Checks whether the config is completely resolved.
ConfigOrigin	origin() Gets the origin of the Config, which may be a file, or a file with a line number, or just a descriptive phrase.
Config	resolve() Returns a replacement config with all substitutions (the ${foo.bar} syntax, see the spec) resolved.
Config	resolve(ConfigResolveOptions options) Like resolve() but allows you to specify non-default options.
Config	resolveWith(Config source) Like resolve() except that substitution values are looked up in the given source, rather than in this instance.
Config	resolveWith(Config source, ConfigResolveOptions options) Like resolveWith(Config) but allows you to specify non-default options.
ConfigObject	root() Gets the Config as a tree of ConfigObject.
Config	withFallback(ConfigMergeable other) Returns a new value computed by merging this value with another, with keys in this value "winning" over the other one.
Config	withOnlyPath(java.lang.String path) Clone the config with only the given path (and its children) retained; all sibling paths are removed.
Config	withoutPath(java.lang.String path) Clone the config with the given path removed.
Config	withValue(java.lang.String path, ConfigValue value) Returns a Config based on this one, but with the given path set to the given value.

Method Detail

root

ConfigObject root()

Gets the Config as a tree of ConfigObject. This is a constant-time operation (it is not proportional to the number of values in the Config).

Returns:

the root object in the configuration

origin

ConfigOrigin origin()

Gets the origin of the Config, which may be a file, or a file with a line number, or just a descriptive phrase.

Returns:

the origin of the Config for use in error messages

withFallback

Config withFallback(ConfigMergeable other)

Description copied from interface: ConfigMergeable

Returns a new value computed by merging this value with another, with keys in this value "winning" over the other one.

This associative operation may be used to combine configurations from multiple sources (such as multiple configuration files).

The semantics of merging are described in the spec for HOCON. Merging typically occurs when either the same object is created twice in the same file, or two config files are both loaded. For example:

  foo = { a: 42 }
  foo = { b: 43 }
 

Here, the two objects are merged as if you had written:

  foo = { a: 42, b: 43 }
 

Only ConfigObject and Config instances do anything in this method (they need to merge the fallback keys into themselves). All other values just return the original value, since they automatically override any fallback. This means that objects do not merge "across" non-objects; if you write object.withFallback(nonObject).withFallback(otherObject), then otherObject will simply be ignored. This is an intentional part of how merging works, because non-objects such as strings and integers replace (rather than merging with) any prior value:

 foo = { a: 42 }
 foo = 10
 

Here, the number 10 "wins" and the value of foo would be simply 10. Again, for details see the spec.

Specified by:

withFallback in interface ConfigMergeable

Parameters:

other - an object whose keys should be used as fallbacks, if the keys are not present in this one

Returns:

a new object (or the original one, if the fallback doesn't get used)

resolve

Config resolve()

Returns a replacement config with all substitutions (the ${foo.bar} syntax, see the spec) resolved. Substitutions are looked up using this Config as the root object, that is, a substitution ${foo.bar} will be replaced with the result of getValue("foo.bar").

This method uses ConfigResolveOptions.defaults(), there is another variant resolve(ConfigResolveOptions) which lets you specify non-default options.

A given Config must be resolved before using it to retrieve config values, but ideally should be resolved one time for your entire stack of fallbacks (see withFallback(com.typesafe.config.ConfigMergeable)). Otherwise, some substitutions that could have resolved with all fallbacks available may not resolve, which will be potentially confusing for your application's users.

resolve() should be invoked on root config objects, rather than on a subtree (a subtree is the result of something like config.getConfig("foo")). The problem with resolve() on a subtree is that substitutions are relative to the root of the config and the subtree will have no way to get values from the root. For example, if you did config.getConfig("foo").resolve() on the below config file, it would not work:

   common-value = 10
   foo {
      whatever = ${common-value}
   }
 

Many methods on ConfigFactory such as ConfigFactory.load() automatically resolve the loaded Config on the loaded stack of config files.

Resolving an already-resolved config is a harmless no-op, but again, it is best to resolve an entire stack of fallbacks (such as all your config files combined) rather than resolving each one individually.

Returns:

an immutable object with substitutions resolved

Throws:

ConfigException.UnresolvedSubstitution - if any substitutions refer to nonexistent paths

ConfigException - some other config exception if there are other problems

resolve

Config resolve(ConfigResolveOptions options)

Like resolve() but allows you to specify non-default options.

Parameters:

options - resolve options

Returns:

the resolved Config (may be only partially resolved if options are set to allow unresolved)

isResolved

boolean isResolved()

Checks whether the config is completely resolved. After a successful call to resolve() it will be completely resolved, but after calling resolve(ConfigResolveOptions) with allowUnresolved set in the options, it may or may not be completely resolved. A newly-loaded config may or may not be completely resolved depending on whether there were substitutions present in the file.

Returns:

true if there are no unresolved substitutions remaining in this configuration.

Since:

1.2.0

resolveWith

Config resolveWith(Config source)

Like resolve() except that substitution values are looked up in the given source, rather than in this instance. This is a special-purpose method which doesn't make sense to use in most cases; it's only needed if you're constructing some sort of app-specific custom approach to configuration. The more usual approach if you have a source of substitution values would be to merge that source into your config stack using withFallback(com.typesafe.config.ConfigMergeable) and then resolve.

Note that this method does NOT look in this instance for substitution values. If you want to do that, you could either merge this instance into your value source using withFallback(com.typesafe.config.ConfigMergeable), or you could resolve multiple times with multiple sources (using ConfigResolveOptions.setAllowUnresolved(boolean) so the partial resolves don't fail).

Parameters:

source - configuration to pull values from

Returns:

an immutable object with substitutions resolved

Throws:

ConfigException.UnresolvedSubstitution - if any substitutions refer to paths which are not in the source

ConfigException - some other config exception if there are other problems

Since:

1.2.0

resolveWith

Config resolveWith(Config source,
                   ConfigResolveOptions options)

Like resolveWith(Config) but allows you to specify non-default options.

Parameters:

source - source configuration to pull values from

options - resolve options

Returns:

the resolved Config (may be only partially resolved if options are set to allow unresolved)

Since:

1.2.0

checkValid

void checkValid(Config reference,
                java.lang.String... restrictToPaths)

Validates this config against a reference config, throwing an exception if it is invalid. The purpose of this method is to "fail early" with a comprehensive list of problems; in general, anything this method can find would be detected later when trying to use the config, but it's often more user-friendly to fail right away when loading the config.

Using this method is always optional, since you can "fail late" instead.

You must restrict validation to paths you "own" (those whose meaning are defined by your code module). If you validate globally, you may trigger errors about paths that happen to be in the config but have nothing to do with your module. It's best to allow the modules owning those paths to validate them. Also, if every module validates only its own stuff, there isn't as much redundant work being done.

If no paths are specified in checkValid()'s parameter list, validation is for the entire config.

If you specify paths that are not in the reference config, those paths are ignored. (There's nothing to validate.)

Here's what validation involves:

• All paths found in the reference config must be present in this config or an exception will be thrown.
• Some changes in type from the reference config to this config will cause an exception to be thrown. Not all potential type problems are detected, in particular it's assumed that strings are compatible with everything except objects and lists. This is because string types are often "really" some other type (system properties always start out as strings, or a string like "5ms" could be used with getMilliseconds(java.lang.String)). Also, it's allowed to set any type to null or override null with any type.
• Any unresolved substitutions in this config will cause a validation failure; both the reference config and this config should be resolved before validation. If the reference config is unresolved, it's a bug in the caller of this method.

If you want to allow a certain setting to have a flexible type (or otherwise want validation to be looser for some settings), you could either remove the problematic setting from the reference config provided to this method, or you could intercept the validation exception and screen out certain problems. Of course, this will only work if all other callers of this method are careful to restrict validation to their own paths, as they should be.

If validation fails, the thrown exception contains a list of all problems found. See ConfigException.ValidationFailed.problems. The exception's getMessage() will have all the problems concatenated into one huge string, as well.

Again, checkValid() can't guess every domain-specific way a setting can be invalid, so some problems may arise later when attempting to use the config. checkValid() is limited to reporting generic, but common, problems such as missing settings and blatant type incompatibilities.

Parameters:

reference - a reference configuration

restrictToPaths - only validate values underneath these paths that your code module owns and understands

Throws:

ConfigException.ValidationFailed - if there are any validation issues

ConfigException.NotResolved - if this config is not resolved

ConfigException.BugOrBroken - if the reference config is unresolved or caller otherwise misuses the API

hasPath

boolean hasPath(java.lang.String path)

Checks whether a value is present and non-null at the given path. This differs in two ways from Map.containsKey() as implemented by ConfigObject: it looks for a path expression, not a key; and it returns false for null values, while containsKey() returns true indicating that the object contains a null value for the key.

If a path exists according to hasPath(String), then getValue(String) will never throw an exception. However, the typed getters, such as getInt(String), will still throw if the value is not convertible to the requested type.

Parameters:

path - the path expression

Returns:

true if a non-null value is present at the path

Throws:

ConfigException.BadPath - if the path expression is invalid

isEmpty

boolean isEmpty()

Returns true if the Config's root object contains no key-value pairs.

Returns:

true if the configuration is empty

entrySet

java.util.Set<java.util.Map.Entry<java.lang.String,ConfigValue>> entrySet()

Returns the set of path-value pairs, excluding any null values, found by recursing the root object. Note that this is very different from root().entrySet() which returns the set of immediate-child keys in the root object and includes null values.

Returns:

set of paths with non-null values, built up by recursing the entire tree of ConfigObject

getBoolean

boolean getBoolean(java.lang.String path)

Parameters:

path - path expression

Returns:

the boolean value at the requested path

Throws:

ConfigException.Missing - if value is absent or null

ConfigException.WrongType - if value is not convertible to boolean

getNumber

java.lang.Number getNumber(java.lang.String path)

Parameters:

path - path expression

Returns:

the numeric value at the requested path

Throws:

ConfigException.Missing - if value is absent or null

ConfigException.WrongType - if value is not convertible to a number

getInt

int getInt(java.lang.String path)

Parameters:

path - path expression

Returns:

the 32-bit integer value at the requested path

Throws:

ConfigException.Missing - if value is absent or null

ConfigException.WrongType - if value is not convertible to an int (for example it is out of range, or it's a boolean value)

getLong

long getLong(java.lang.String path)

Parameters:

path - path expression

Returns:

the 64-bit long value at the requested path

Throws:

ConfigException.Missing - if value is absent or null

ConfigException.WrongType - if value is not convertible to a long

getDouble

double getDouble(java.lang.String path)

Parameters:

path - path expression

Returns:

the floating-point value at the requested path

Throws:

ConfigException.Missing - if value is absent or null

ConfigException.WrongType - if value is not convertible to a double

getString

java.lang.String getString(java.lang.String path)

Parameters:

path - path expression

Returns:

the string value at the requested path

Throws:

ConfigException.Missing - if value is absent or null

ConfigException.WrongType - if value is not convertible to a string

getObject

ConfigObject getObject(java.lang.String path)

Parameters:

path - path expression

Returns:

the ConfigObject value at the requested path

Throws:

ConfigException.Missing - if value is absent or null

ConfigException.WrongType - if value is not convertible to an object

getConfig

Config getConfig(java.lang.String path)

Parameters:

path - path expression

Returns:

the nested Config value at the requested path

Throws:

ConfigException.Missing - if value is absent or null

ConfigException.WrongType - if value is not convertible to a Config

getAnyRef

java.lang.Object getAnyRef(java.lang.String path)

Gets the value at the path as an unwrapped Java boxed value ( Boolean, Integer, and so on - see ConfigValue.unwrapped()).

Parameters:

path - path expression

Returns:

the unwrapped value at the requested path

Throws:

ConfigException.Missing - if value is absent or null

getValue

ConfigValue getValue(java.lang.String path)

Gets the value at the given path, unless the value is a null value or missing, in which case it throws just like the other getters. Use get() on the root() object (or other object in the tree) if you want an unprocessed value.

Parameters:

path - path expression

Returns:

the value at the requested path

Throws:

ConfigException.Missing - if value is absent or null

getBytes

java.lang.Long getBytes(java.lang.String path)

Gets a value as a size in bytes (parses special strings like "128M"). If the value is already a number, then it's left alone; if it's a string, it's parsed understanding unit suffixes such as "128K", as documented in the the spec.

Parameters:

path - path expression

Returns:

the value at the requested path, in bytes

Throws:

ConfigException.Missing - if value is absent or null

ConfigException.WrongType - if value is not convertible to Long or String

ConfigException.BadValue - if value cannot be parsed as a size in bytes

getMilliseconds

@Deprecated
java.lang.Long getMilliseconds(java.lang.String path)

Deprecated. As of release 1.1, replaced by getDuration(String, TimeUnit)

Get value as a duration in milliseconds. If the value is already a number, then it's left alone; if it's a string, it's parsed understanding units suffixes like "10m" or "5ns" as documented in the the spec.

Parameters:

path - path expression

Returns:

the duration value at the requested path, in milliseconds

Throws:

ConfigException.Missing - if value is absent or null

ConfigException.WrongType - if value is not convertible to Long or String

ConfigException.BadValue - if value cannot be parsed as a number of milliseconds

getNanoseconds

@Deprecated
java.lang.Long getNanoseconds(java.lang.String path)

Deprecated. As of release 1.1, replaced by getDuration(String, TimeUnit)

Get value as a duration in nanoseconds. If the value is already a number it's taken as milliseconds and converted to nanoseconds. If it's a string, it's parsed understanding unit suffixes, as for getDuration(String, TimeUnit).

Parameters:

path - path expression

Returns:

the duration value at the requested path, in nanoseconds

Throws:

ConfigException.Missing - if value is absent or null

ConfigException.WrongType - if value is not convertible to Long or String

ConfigException.BadValue - if value cannot be parsed as a number of nanoseconds

getDuration

long getDuration(java.lang.String path,
                 java.util.concurrent.TimeUnit unit)

Gets a value as a duration in a specified TimeUnit. If the value is already a number, then it's taken as milliseconds and then converted to the requested TimeUnit; if it's a string, it's parsed understanding units suffixes like "10m" or "5ns" as documented in the the spec.

Parameters:

path - path expression

unit - convert the return value to this time unit

Returns:

the duration value at the requested path, in the given TimeUnit

Throws:

ConfigException.Missing - if value is absent or null

ConfigException.WrongType - if value is not convertible to Long or String

ConfigException.BadValue - if value cannot be parsed as a number of the given TimeUnit

Since:

1.2.0

getList

ConfigList getList(java.lang.String path)

Gets a list value (with any element type) as a ConfigList, which implements java.util.List<ConfigValue>. Throws if the path is unset or null.

Parameters:

path - the path to the list value.

Returns:

the ConfigList at the path

Throws:

ConfigException.Missing - if value is absent or null

ConfigException.WrongType - if value is not convertible to a ConfigList

getBooleanList

java.util.List<java.lang.Boolean> getBooleanList(java.lang.String path)

getNumberList

java.util.List<java.lang.Number> getNumberList(java.lang.String path)

getIntList

java.util.List<java.lang.Integer> getIntList(java.lang.String path)

getLongList

java.util.List<java.lang.Long> getLongList(java.lang.String path)

getDoubleList

java.util.List<java.lang.Double> getDoubleList(java.lang.String path)

getStringList

java.util.List<java.lang.String> getStringList(java.lang.String path)

getObjectList

java.util.List<? extends ConfigObject> getObjectList(java.lang.String path)

getConfigList

java.util.List<? extends Config> getConfigList(java.lang.String path)

getAnyRefList

java.util.List<? extends java.lang.Object> getAnyRefList(java.lang.String path)

getBytesList

java.util.List<java.lang.Long> getBytesList(java.lang.String path)

getMillisecondsList

@Deprecated
java.util.List<java.lang.Long> getMillisecondsList(java.lang.String path)

Deprecated. As of release 1.1, replaced by getDurationList(String, TimeUnit)

getNanosecondsList

@Deprecated
java.util.List<java.lang.Long> getNanosecondsList(java.lang.String path)

Deprecated. As of release 1.1, replaced by getDurationList(String, TimeUnit)

getDurationList

java.util.List<java.lang.Long> getDurationList(java.lang.String path,
                                               java.util.concurrent.TimeUnit unit)

Gets a list, converting each value in the list to a duration, using the same rules as getDuration(String, TimeUnit).

Parameters:

path - a path expression

unit - time units of the returned values

Returns:

list of durations, in the requested units

Since:

1.2.0

withOnlyPath

Config withOnlyPath(java.lang.String path)

Clone the config with only the given path (and its children) retained; all sibling paths are removed.

Parameters:

path - path to keep

Returns:

a copy of the config minus all paths except the one specified

withoutPath

Config withoutPath(java.lang.String path)

Clone the config with the given path removed.

Parameters:

path - path to remove

Returns:

a copy of the config minus the specified path

atPath

Config atPath(java.lang.String path)

Places the config inside another Config at the given path.

Parameters:

path - path to store this config at.

Returns:

a Config instance containing this config at the given path.

atKey

Config atKey(java.lang.String key)

Places the config inside a Config at the given key. See also atPath().

Parameters:

key - key to store this config at.

Returns:

a Config instance containing this config at the given key.

withValue

Config withValue(java.lang.String path,
                 ConfigValue value)

Returns a Config based on this one, but with the given path set to the given value. Does not modify this instance (since it's immutable). If the path already has a value, that value is replaced. To remove a value, use withoutPath().

Parameters:

path - path to add

value - value at the new path

Returns:

the new instance with the new map entry