trait 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-summary.html#package_description 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(String*) and ConfigUtil.splitPath(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. (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 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).
Serialization
Convert a Config to a JSON or HOCON string by calling root to
get the ConfigObject and then call
render on the root object,
myConfig.root.render. There's also a variant
render(ConfigRenderOptions)
inherited from ConfigValue 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 render, the toString
method produces a debug-output-oriented representation (which is not valid
JSON).
Note: no arg render links do not link correctly. See https://github.com/lampepfl/dotty/issues/14212
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.
- Alphabetic
- By Inheritance
- Config
- ConfigMergeable
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
Abstract Value Members
- abstract def atKey(key: String): Config
Places the config inside a
Configat the given key.Places the config inside a
Configat the given key. See also atPath. Note that a key is NOT a path expression (see ConfigUtil$.joinPath(elements:String*)* and ConfigUtil#splitPath).- key
key to store this config at.
- returns
a
Configinstance containing this config at the given key.
- abstract def atPath(path: String): Config
Places the config inside another
Configat the given path.Places the config inside another
Configat the given path.Note that path expressions have a syntax and sometimes require quoting (see ConfigUtil$.joinPath(elements:String*)* and ConfigUtil#splitPath).
- path
path expression to store this config at.
- returns
a
Configinstance containing this config at the given path.
- abstract def checkValid(reference: Config, restrictToPaths: String*): Unit
Validates this config against a reference config, throwing an exception if it is invalid.
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 getDuration(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
getMessagewill have all the problems concatenated into one huge string, as well.Again,
checkValidcan't guess every domain-specific way a setting can be invalid, so some problems may arise later when attempting to use the config.checkValidis limited to reporting generic, but common, problems such as missing settings and blatant type incompatibilities.- reference
a reference configuration
- restrictToPaths
only validate values underneath these paths that your code module owns and understands
- Annotations
- @varargs()
- Exceptions thrown
ConfigException.BugOrBrokenif the reference config is unresolved or caller otherwise misuses the APIConfigException.NotResolvedif this config is not resolvedConfigException.ValidationFailedif there are any validation issues
- abstract def entrySet: Set[Entry[String, ConfigValue]]
Returns the set of path-value pairs, excluding any null values, found by recursing the root object.
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.entrySetwhich returns the set of immediate-child keys in the root object and includes null values.Entries contain path expressions meaning there may be quoting and escaping involved. Parse path expressions with ConfigUtil#splitPath.
Because a
Configis conceptually a single-level map from paths to values, there will not be any ConfigObject values in the entries (that is, all entries represent leaf nodes). Use ConfigObject rather thanConfigif you want a tree. (OK, this is a slight lie:Configentries may contain ConfigList and the lists may contain objects. But no objects are directly included as entry values.)- returns
set of paths with non-null values, built up by recursing the entire tree of ConfigObject and creating an entry for each leaf value.
- abstract def getAnyRef(path: String): AnyRef
Gets the value at the path as an unwrapped Java boxed value (
java.lang.Booleanjava.lang.Integer, and so on - see ConfigValue#unwrapped).Gets the value at the path as an unwrapped Java boxed value (
java.lang.Booleanjava.lang.Integer, and so on - see ConfigValue#unwrapped).- path
path expression
- returns
the unwrapped value at the requested path
- Exceptions thrown
ConfigException.Missingif value is absent or null
- abstract def getAnyRefList(path: String): List[_ <: AnyRef]
Gets a list value with any kind of elements.
Gets a list value with any kind of elements. Throws if the path is unset or null or not a list. Each element is "unwrapped" (see ConfigValue#unwrapped).
- path
the path to the list value.
- returns
the list at the path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a list
- abstract def getBoolean(path: String): Boolean
- path
path expression
- returns
the boolean value at the requested path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to boolean
- abstract def getBooleanList(path: String): List[Boolean]
Gets a list value with boolean elements.
Gets a list value with boolean elements. Throws if the path is unset or null or not a list or contains values not convertible to boolean.
- path
the path to the list value.
- returns
the list at the path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a list of booleans
- abstract def getBytes(path: String): Long
Gets a value as a size in bytes (parses special strings like "128M").
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.
- path
path expression
- returns
the value at the requested path, in bytes
- Exceptions thrown
ConfigException.BadValueif value cannot be parsed as a size in bytesConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to Long or String
- abstract def getBytesList(path: String): List[Long]
Gets a list value with elements representing a size in bytes.
Gets a list value with elements representing a size in bytes. Throws if the path is unset or null or not a list or contains values not convertible to memory sizes.
- path
the path to the list value.
- returns
the list at the path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a list of memory sizes
- abstract def getConfig(path: String): Config
- path
path expression
- returns
the nested
Configvalue at the requested path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a Config
- abstract def getConfigList(path: String): List[_ <: Config]
Gets a list value with
Configelements.Gets a list value with
Configelements. Throws if the path is unset or null or not a list or contains values not convertible toConfig.- path
the path to the list value.
- returns
the list at the path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a list of configs
- abstract def getDouble(path: String): Double
- path
path expression
- returns
the floating-point value at the requested path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a double
- abstract def getDoubleList(path: String): List[Double]
Gets a list value with double elements.
Gets a list value with double elements. Throws if the path is unset or null or not a list or contains values not convertible to double.
- path
the path to the list value.
- returns
the list at the path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a list of doubles
- abstract def getDuration(path: String): Duration
Gets a value as a java.time.Duration.
Gets a value as a java.time.Duration. If the value is already a number, then it's taken as milliseconds; if it's a string, it's parsed understanding units suffixes like "10m" or "5ns" as documented in the <a href="https://github.com/lightbend/config/blob/master/HOCON.md">the spec. This method never returns null.
- path
path expression
- returns
the duration value at the requested path
- Since
1.3.0
- Exceptions thrown
ConfigException.BadValueif value cannot be parsed as a number of the given TimeUnitConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to Long or String
- abstract def getDuration(path: String, unit: TimeUnit): Long
Gets a value as a duration in a specified
java.util.concurrent.TimeUnit.Gets a value as a duration in a specified
java.util.concurrent.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 <a the HOCON spec.- path
path expression
- unit
convert the return value to this time unit
- returns
the duration value at the requested path, in the given TimeUnit
- Since
1.2.0
- Exceptions thrown
ConfigException.BadValueif value cannot be parsed as a number of the given TimeUnitConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to Long or String
- abstract def getDurationList(path: String): List[Duration]
Gets a list, converting each value in the list to a duration, using the same rules as getDuration(String).
Gets a list, converting each value in the list to a duration, using the same rules as getDuration(String).
- path
a path expression
- returns
list of durations
- Since
1.3.0
- abstract def getDurationList(path: String, unit: TimeUnit): List[Long]
Gets a list, converting each value in the list to a duration, using the same rules as getDuration(String, TimeUnit).
Gets a list, converting each value in the list to a duration, using the same rules as getDuration(String, TimeUnit).
- path
a path expression
- unit
time units of the returned values
- returns
list of durations, in the requested units
- Since
1.2.0
- abstract def getEnum[T <: Enum[T]](enumClass: Class[T], path: String): T
- enumClass
an enum class
- path
path expression
- returns
the
Enumvalue at the requested path of the requested enum class
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to an Enum
- abstract def getEnumList[T <: Enum[T]](enumClass: Class[T], path: String): List[T]
Gets a list value with
Enumelements.Gets a list value with
Enumelements. Throws if the path is unset or null or not a list or contains values not convertible toEnum.- enumClass
the enum class
- path
the path to the list value.
- returns
the list at the path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a list ofEnum
- abstract def getInt(path: String): Int
Gets the integer at the given path.
Gets the integer at the given path. If the value at the path has a fractional (floating point) component, it will be discarded and only the integer part will be returned (it works like a "narrowing primitive conversion" in the Java language specification).
- path
path expression
- returns
the 32-bit integer value at the requested path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to an int (for example it is out of range, or it's a boolean value)
- abstract def getIntList(path: String): List[Integer]
Gets a list value with int elements.
Gets a list value with int elements. Throws if the path is unset or null or not a list or contains values not convertible to int.
- path
the path to the list value.
- returns
the list at the path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a list of ints
- abstract def getIsNull(path: String): Boolean
Checks whether a value is set to null at the given path, but throws an exception if the value is entirely unset.
Checks whether a value is set to null at the given path, but throws an exception if the value is entirely unset. This method will not throw if #hasPathOrNull returned true for the same path, so to avoid any possible exception check
hasPathOrNullfirst. However, an exception for unset paths will usually be the right thing (because areference.confshould exist that has the path set, the path should never be unset unless something is broken).Note that path expressions have a syntax and sometimes require quoting (see ConfigUtil$.joinPath(elements:String*)* and ConfigUtil#splitPath).
- path
the path expression
- returns
true if the value exists and is null, false if it exists and is not null
- Exceptions thrown
ConfigException.BadPathif the path expression is invalidConfigException.Missingif value is not set at all
- abstract def getList(path: String): ConfigList
Gets a list value (with any element type) as a ConfigList, which implements
java.util.List<ConfigValue>.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.- path
the path to the list value.
- returns
the ConfigList at the path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a ConfigList
- abstract def getLong(path: String): Long
Gets the long integer at the given path.
Gets the long integer at the given path. If the value at the path has a fractional (floating point) component, it will be discarded and only the integer part will be returned (it works like a "narrowing primitive conversion" in the Java language specification).
- path
path expression
- returns
the 64-bit long value at the requested path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a long
- abstract def getLongList(path: String): List[Long]
Gets a list value with long elements.
Gets a list value with long elements. Throws if the path is unset or null or not a list or contains values not convertible to long.
- path
the path to the list value.
- returns
the list at the path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a list of longs
- abstract def getMemorySize(path: String): ConfigMemorySize
Gets a value as an amount of memory (parses special strings like "128M").
Gets a value as an amount of memory (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.
- path
path expression
- returns
the value at the requested path, in bytes
- Since
1.3.0
- Exceptions thrown
ConfigException.BadValueif value cannot be parsed as a size in bytesConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to Long or String
- abstract def getMemorySizeList(path: String): List[ConfigMemorySize]
Gets a list, converting each value in the list to a memory size, using the same rules as #getMemorySize.
Gets a list, converting each value in the list to a memory size, using the same rules as #getMemorySize.
- path
a path expression
- returns
list of memory sizes
- Since
1.3.0
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a list of memory sizes
- abstract def getNumber(path: String): Number
- path
path expression
- returns
the numeric value at the requested path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a number
- abstract def getNumberList(path: String): List[Number]
Gets a list value with number elements.
Gets a list value with number elements. Throws if the path is unset or null or not a list or contains values not convertible to number.
- path
the path to the list value.
- returns
the list at the path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a list of numbers
- abstract def getObject(path: String): ConfigObject
- path
path expression
- returns
the ConfigObject value at the requested path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to an object
- abstract def getObjectList(path: String): List[_ <: ConfigObject]
Gets a list value with object elements.
Gets a list value with object elements. Throws if the path is unset or null or not a list or contains values not convertible to
ConfigObject.- path
the path to the list value.
- returns
the list at the path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a list of objects
- abstract def getPeriod(path: String): Period
Gets a value as a java.time.Period.
Gets a value as a java.time.Period. If the value is already a number, then it's taken as days; if it's a string, it's parsed understanding units suffixes like "10d" or "5w" as documented in the <a href="https://github.com/lightbend/config/blob/master/HOCON.md">the spec. This method never returns null.
- path
path expression
- returns
the period value at the requested path
- Since
1.3.0
- Exceptions thrown
ConfigException.BadValueif value cannot be parsed as a number of the given TimeUnitConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to Long or String
- abstract def getString(path: String): String
- path
path expression
- returns
the string value at the requested path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a string
- abstract def getStringList(path: String): List[String]
Gets a list value with string elements.
Gets a list value with string elements. Throws if the path is unset or null or not a list or contains values not convertible to string.
- path
the path to the list value.
- returns
the list at the path
- Exceptions thrown
ConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to a list of strings
- abstract def getTemporal(path: String): TemporalAmount
Gets a value as a java.time.temporal.TemporalAmount.
Gets a value as a java.time.temporal.TemporalAmount. This method will first try get get the value as a java.time.Duration, and if unsuccessful, then as a java.time.Period. This means that values like "5m" will be parsed as 5 minutes rather than 5 months
- path
path expression
- returns
the temporal value at the requested path
- Exceptions thrown
ConfigException.BadValueif value cannot be parsed as a TemporalAmountConfigException.Missingif value is absent or nullConfigException.WrongTypeif value is not convertible to Long or String
- abstract def getValue(path: String): ConfigValue
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.
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
geton the Config#root object (or other object in the tree) if you want an unprocessed value.- path
path expression
- returns
the value at the requested path
- Exceptions thrown
ConfigException.Missingif value is absent or null
- abstract def hasPath(path: String): Boolean
Checks whether a value is present and non-null at the given path.
Checks whether a value is present and non-null at the given path. This differs in two ways from
Map.containsKeyas implemented by ConfigObject: it looks for a path expression, not a key; and it returns false for null values, whilecontainsKeyreturns true indicating that the object contains a null value for the key.If a path exists according to #hasPath, then #getValue will never throw an exception. However, the typed getters, such as #getInt, will still throw if the value is not convertible to the requested type.
Note that path expressions have a syntax and sometimes require quoting (see ConfigUtil$.joinPath(elements:String*)* and ConfigUtil#splitPath).
- path
the path expression
- returns
true if a non-null value is present at the path
- Exceptions thrown
ConfigException.BadPathif the path expression is invalid
- abstract def hasPathOrNull(path: String): Boolean
Checks whether a value is present at the given path, even if the value is null.
Checks whether a value is present at the given path, even if the value is null. Most of the getters on
Configwill throw if you try to get a null value, so if you plan to call #getValue, #getInt, or another getter you may want to use plain #hasPath rather than this method.To handle all three cases (unset, null, and a non-null value) the code might look like:
if (config.hasPathOrNull(path)) { if (config.getIsNull(path)) { // handle null setting } else { // get and use non-null setting } } else { // handle entirely unset path }
However, the usual thing is to allow entirely unset paths to be a bug that throws an exception (because you set a default in your
reference.conf), so in that case it's OK to call #getIsNull without checkinghasPathOrNullfirst.Note that path expressions have a syntax and sometimes require quoting (see ConfigUtil$.joinPath(elements:String*)* and ConfigUtil#splitPath).
- path
the path expression
- returns
true if a value is present at the path, even if the value is null
- Exceptions thrown
ConfigException.BadPathif the path expression is invalid
- abstract def isEmpty: Boolean
Returns true if the
Config's root object contains no key-value pairs.Returns true if the
Config's root object contains no key-value pairs.- returns
true if the configuration is empty
- abstract def isResolved: Boolean
Checks whether the config is completely resolved.
Checks whether the config is completely resolved. After a successful call to resolve() it will be completely resolved, but after calling resolve(ConfigResolveOptions) with
allowUnresolvedset 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
- abstract def origin: ConfigOrigin
Gets the origin of the
Config, which may be a file, or a file with a line number, or just a descriptive phrase.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
Configfor use in error messages
- abstract def resolve(options: ConfigResolveOptions): Config
Like resolve() but allows you to specify non-default options.
Like resolve() but allows you to specify non-default options.
- options
resolve options
- returns
the resolved
Config(may be only partially resolved if options are set to allow unresolved)
- abstract def resolve(): Config
Returns a replacement config with all substitutions (the
${foo.bar}syntax, see HOCON spec for resolved.Returns a replacement config with all substitutions (the
${foo.bar}syntax, see HOCON spec for resolved. Substitutions are looked up using thisConfigas the root object, that is, a substitution${foo.bar}will be replaced with the result ofgetValue("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 Config#withFallback). Otherwise, some substitutions that could have resolved with all fallbacks available may not resolve, which will be potentially confusing for your application's users.
resolveshould be invoked on root config objects, rather than on a subtree (a subtree is the result of something likeconfig.getConfig("foo")). The problem withresolveon 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 didconfig.getConfig("foo").resolveon 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
Configon 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
- Exceptions thrown
ConfigExceptionsome other config exception if there are other problemsConfigException.UnresolvedSubstitutionif any substitutions refer to nonexistent paths
- abstract def resolveWith(source: Config, options: ConfigResolveOptions): Config
Like resolveWith(Config) but allows you to specify non-default options.
Like resolveWith(Config) but allows you to specify non-default options.
- 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
- abstract def resolveWith(source: Config): Config
Like resolve() except that substitution values are looked up in the given source, rather than in this instance.
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 Config#withFallback 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 Config#withFallback, or you could resolve multiple times with multiple sources (using ConfigResolveOptions#setAllowUnresolved so the partial resolves don't fail).
- source
configuration to pull values from
- returns
an immutable object with substitutions resolved
- Since
1.2.0
- Exceptions thrown
ConfigExceptionsome other config exception if there are other problemsConfigException.UnresolvedSubstitutionif any substitutions refer to paths which are not in the source
- abstract def root: ConfigObject
Gets the
Configas a tree of ConfigObject.Gets the
Configas a tree of ConfigObject. This is a constant-time operation (it is not proportional to the number of values in theConfig).- returns
the root object in the configuration
- abstract def withFallback(other: ConfigMergeable): Config
Returns a new value computed by merging this value with another, with keys in this value "winning" over the other one.
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), thenotherObjectwill 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 = 10Here, the number 10 "wins" and the value of
foowould be simply 10. Again, for details see the spec.- 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)
- Definition Classes
- Config → ConfigMergeable
- abstract def withOnlyPath(path: String): Config
Clone the config with only the given path (and its children) retained; all sibling paths are removed.
Clone the config with only the given path (and its children) retained; all sibling paths are removed.
Note that path expressions have a syntax and sometimes require quoting (see ConfigUtil$.joinPath(elements:String*)* and ConfigUtil#splitPath).
- path
path to keep
- returns
a copy of the config minus all paths except the one specified
- abstract def withValue(path: String, value: ConfigValue): Config
Returns a
Configbased on this one, but with the given path set to the given value.Returns a
Configbased 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.Note that path expressions have a syntax and sometimes require quoting (see ConfigUtil$.joinPath(elements:String*)* and ConfigUtil#splitPath).
- path
path expression for the value's new location
- value
value at the new path
- returns
the new instance with the new map entry
- abstract def withoutPath(path: String): Config
Clone the config with the given path removed.
Clone the config with the given path removed.
Note that path expressions have a syntax and sometimes require quoting (see ConfigUtil$.joinPath(elements:String*)* and ConfigUtil#splitPath).
- path
path expression to remove
- returns
a copy of the config minus the specified path
Concrete Value Members
- final def !=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def ##: Int
- Definition Classes
- AnyRef → Any
- final def ==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def asInstanceOf[T0]: T0
- Definition Classes
- Any
- def clone(): AnyRef
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.CloneNotSupportedException]) @IntrinsicCandidate() @native()
- final def eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def equals(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef → Any
- final def getClass(): Class[_ <: AnyRef]
- Definition Classes
- AnyRef → Any
- Annotations
- @IntrinsicCandidate() @native()
- def hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @IntrinsicCandidate() @native()
- final def isInstanceOf[T0]: Boolean
- Definition Classes
- Any
- final def ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- final def notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @IntrinsicCandidate() @native()
- final def notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @IntrinsicCandidate() @native()
- final def synchronized[T0](arg0: => T0): T0
- Definition Classes
- AnyRef
- def toString(): String
- Definition Classes
- AnyRef → Any
- final def wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException]) @native()
- final def wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
Deprecated Value Members
- def finalize(): Unit
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.Throwable]) @Deprecated
- Deprecated
(Since version 9)