Attributes
- Companion
- object
- Graph
-
- Supertypes
-
trait Serializabletrait MergeableValuetrait Configtrait ConfigMergeableclass Objecttrait Matchableclass AnyShow all
Members list
Value members
Concrete methods
Places the config inside a Config at the given key. See also atPath. Note that a key is NOT a path expression (see ConfigUtil$.joinPath and ConfigUtil#splitPath).
Places the config inside a Config at the given key. See also atPath. Note that a key is NOT a path expression (see ConfigUtil$.joinPath and ConfigUtil#splitPath).
Value parameters
- key
-
key to store this config at.
Attributes
- Returns
-
a
Configinstance containing this config at the given key. - Definition Classes
Places the config inside another Config at the given path.
Places the config inside another Config at the given path.
Note that path expressions have a syntax and sometimes require quoting (see ConfigUtil$.joinPath and ConfigUtil#splitPath).
Value parameters
- path
-
path expression to store this config at.
Attributes
- Returns
-
a
Configinstance containing this config at the given path. - Definition Classes
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.
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 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.
Value parameters
- reference
-
a reference configuration
- restrictToPaths
-
only validate values underneath these paths that your code module owns and understands
Attributes
- Throws
-
ConfigException.BugOrBroken
if the reference config is unresolved or caller otherwise misuses the API
ConfigException.NotResolvedif this config is not resolved
ConfigException.ValidationFailedif there are any validation issues
- Definition Classes
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 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.
Entries contain path expressions meaning there may be quoting and escaping involved. Parse path expressions with ConfigUtil#splitPath.
Because a Config is 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 than Config if you want a tree. (OK, this is a slight lie: Config entries may contain ConfigList and the lists may contain objects. But no objects are directly included as entry values.)
Attributes
- 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.
- Definition Classes
Compares the receiver object (this) with the argument object (that) for equivalence.
Compares the receiver object (this) with the argument object (that) for equivalence.
Any implementation of this method should be an equivalence relation:
- It is reflexive: for any instance
xof typeAny,x.equals(x)should returntrue. - It is symmetric: for any instances
xandyof typeAny,x.equals(y)should returntrueif and only ify.equals(x)returnstrue. - It is transitive: for any instances
x,y, andzof typeAnyifx.equals(y)returnstrueandy.equals(z)returnstrue, thenx.equals(z)should returntrue.
If you override this method, you should verify that your implementation remains an equivalence relation. Additionally, when overriding this method it is usually necessary to override hashCode to ensure that objects which are "equal" (o1.equals(o2) returns true) hash to the same scala.Int. (o1.hashCode.equals(o2.hashCode)).
Value parameters
- that
-
the object to compare against this object for equality.
Attributes
- Returns
-
trueif the receiver object is equivalent to the argument;falseotherwise. - Definition Classes
-
Any
Gets the value at the path as an unwrapped Java boxed value ( java.lang.Boolean java.lang.Integer, and so on - see ConfigValue#unwrapped).
Gets the value at the path as an unwrapped Java boxed value ( java.lang.Boolean java.lang.Integer, and so on - see ConfigValue#unwrapped).
Value parameters
- path
-
path expression
Attributes
- Returns
-
the unwrapped value at the requested path
- Throws
-
ConfigException.Missing
if value is absent or null
- Definition Classes
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).
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).
Value parameters
- path
-
the path to the list value.
Attributes
- Returns
-
the list at the path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a list
- Definition Classes
Value parameters
- path
-
path expression
Attributes
- Returns
-
the boolean value at the requested path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to boolean
- Definition Classes
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.
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.
Value parameters
- path
-
the path to the list value.
Attributes
- Returns
-
the list at the path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a list of booleans
- Definition Classes
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.
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.
Value parameters
- path
-
path expression
Attributes
- Returns
-
the value at the requested path, in bytes
- Throws
-
ConfigException.BadValue
if value cannot be parsed as a size in bytes
ConfigException.Missingif value is absent or null
ConfigException.WrongTypeif value is not convertible to Long or String
- Definition Classes
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.
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.
Value parameters
- path
-
the path to the list value.
Attributes
- Returns
-
the list at the path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a list of memory sizes
- Definition Classes
Value parameters
- path
-
path expression
Attributes
- Returns
-
the nested
Configvalue at the requested path - Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a Config
- Definition Classes
Gets a list value with Config elements. Throws if the path is unset or null or not a list or contains values not convertible to Config.
Gets a list value with Config elements. Throws if the path is unset or null or not a list or contains values not convertible to Config.
Value parameters
- path
-
the path to the list value.
Attributes
- Returns
-
the list at the path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a list of configs
- Definition Classes
Value parameters
- path
-
path expression
Attributes
- Returns
-
the floating-point value at the requested path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a double
- Definition Classes
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.
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.
Value parameters
- path
-
the path to the list value.
Attributes
- Returns
-
the list at the path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a list of doubles
- Definition Classes
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.
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.
Value parameters
- path
-
path expression
- unit
-
convert the return value to this time unit
Attributes
- Returns
-
the duration value at the requested path, in the given TimeUnit
- Throws
-
ConfigException.BadValue
if value cannot be parsed as a number of the given TimeUnit
ConfigException.Missingif value is absent or null
ConfigException.WrongTypeif value is not convertible to Long or String
- Since
-
1.2.0
- Definition Classes
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 the spec. This method never returns null.
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 the spec. This method never returns null.
Value parameters
- path
-
path expression
Attributes
- Returns
-
the duration value at the requested path
- Throws
-
ConfigException.BadValue
if value cannot be parsed as a number of the given TimeUnit
ConfigException.Missingif value is absent or null
ConfigException.WrongTypeif value is not convertible to Long or String
- Since
-
1.3.0
- Definition Classes
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).
Value parameters
- path
-
a path expression
- unit
-
time units of the returned values
Attributes
- Returns
-
list of durations, in the requested units
- Since
-
1.2.0
- Definition Classes
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).
Value parameters
- path
-
a path expression
Attributes
- Returns
-
list of durations
- Since
-
1.3.0
- Definition Classes
Value parameters
- [T]
-
a generic denoting a specific type of enum
- enumClass
-
an enum class
- path
-
path expression
Attributes
- Returns
-
the
Enumvalue at the requested path of the requested enum class - Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to an Enum
Gets a list value with Enum elements. Throws if the path is unset or null or not a list or contains values not convertible to Enum.
Gets a list value with Enum elements. Throws if the path is unset or null or not a list or contains values not convertible to Enum.
Value parameters
- [T]
-
a generic denoting a specific type of enum
- enumClass
-
the enum class
- path
-
the path to the list value.
Attributes
- Returns
-
the list at the path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a list of
Enum
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).
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).
Value parameters
- path
-
path expression
Attributes
- Returns
-
the 32-bit integer value at the requested path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to an int (for example it is out of range, or it's a boolean value)
- Definition Classes
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.
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.
Value parameters
- path
-
the path to the list value.
Attributes
- Returns
-
the list at the path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a list of ints
- Definition Classes
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 hasPathOrNull first. However, an exception for unset paths will usually be the right thing (because a reference.conf should exist that has the path set, the path should never be unset unless something is broken).
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 hasPathOrNull first. However, an exception for unset paths will usually be the right thing (because a reference.conf should 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 and ConfigUtil#splitPath).
Value parameters
- path
-
the path expression
Attributes
- Returns
-
true if the value exists and is null, false if it exists and is not null
- Throws
-
ConfigException.BadPath
if the path expression is invalid
ConfigException.Missingif value is not set at all
- Definition Classes
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.
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.
Value parameters
- path
-
the path to the list value.
Attributes
- Returns
-
the ConfigList at the path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a ConfigList
- Definition Classes
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).
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).
Value parameters
- path
-
path expression
Attributes
- Returns
-
the 64-bit long value at the requested path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a long
- Definition Classes
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.
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.
Value parameters
- path
-
the path to the list value.
Attributes
- Returns
-
the list at the path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a list of longs
- Definition Classes
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.
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.
Value parameters
- path
-
path expression
Attributes
- Returns
-
the value at the requested path, in bytes
- Throws
-
ConfigException.BadValue
if value cannot be parsed as a size in bytes
ConfigException.Missingif value is absent or null
ConfigException.WrongTypeif value is not convertible to Long or String
- Since
-
1.3.0
- Definition Classes
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.
Value parameters
- path
-
a path expression
Attributes
- Returns
-
list of memory sizes
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a list of memory sizes
- Since
-
1.3.0
- Definition Classes
Value parameters
- path
-
path expression
Attributes
- Returns
-
the numeric value at the requested path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a number
- Definition Classes
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.
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.
Value parameters
- path
-
the path to the list value.
Attributes
- Returns
-
the list at the path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a list of numbers
- Definition Classes
Value parameters
- path
-
path expression
Attributes
- Returns
-
the ConfigObject value at the requested path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to an object
- Definition Classes
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.
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.
Value parameters
- path
-
the path to the list value.
Attributes
- Returns
-
the list at the path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a list of objects
- Definition Classes
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 the spec. This method never returns null.
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 the spec. This method never returns null.
Value parameters
- path
-
path expression
Attributes
- Returns
-
the period value at the requested path
- Throws
-
ConfigException.BadValue
if value cannot be parsed as a number of the given TimeUnit
ConfigException.Missingif value is absent or null
ConfigException.WrongTypeif value is not convertible to Long or String
- Since
-
1.3.0
- Definition Classes
Value parameters
- path
-
path expression
Attributes
- Returns
-
the string value at the requested path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a string
- Definition Classes
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.
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.
Value parameters
- path
-
the path to the list value.
Attributes
- Returns
-
the list at the path
- Throws
-
ConfigException.Missing
if value is absent or null
ConfigException.WrongTypeif value is not convertible to a list of strings
- Definition Classes
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
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
Value parameters
- path
-
path expression
Attributes
- Returns
-
the temporal value at the requested path
- Throws
-
ConfigException.BadValue
if value cannot be parsed as a TemporalAmount
ConfigException.Missingif value is absent or null
ConfigException.WrongTypeif value is not convertible to Long or String
- Definition Classes
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 Config#root object (or other object in the tree) if you want an unprocessed value.
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 Config#root object (or other object in the tree) if you want an unprocessed value.
Value parameters
- path
-
path expression
Attributes
- Returns
-
the value at the requested path
- Throws
-
ConfigException.Missing
if value is absent or null
- Definition Classes
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.
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, 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 and ConfigUtil#splitPath).
Value parameters
- path
-
the path expression
Attributes
- Returns
-
true if a non-null value is present at the path
- Throws
-
ConfigException.BadPath
if the path expression is invalid
- Definition Classes
Checks whether a value is present at the given path, even if the value is null. Most of the getters on Config will 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.
Checks whether a value is present at the given path, even if the value is null. Most of the getters on Config will 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 checking hasPathOrNull first.
Note that path expressions have a syntax and sometimes require quoting (see ConfigUtil$.joinPath and ConfigUtil#splitPath).
Value parameters
- path
-
the path expression
Attributes
- Returns
-
true if a value is present at the path, even if the value is null
- Throws
-
ConfigException.BadPath
if the path expression is invalid
- Definition Classes
Calculate a hash code value for the object.
Calculate a hash code value for the object.
The default hashing algorithm is platform dependent.
Note that it is allowed for two objects to have identical hash codes (o1.hashCode.equals(o2.hashCode)) yet not be equal (o1.equals(o2) returns false). A degenerate implementation could always return 0. However, it is required that if two objects are equal (o1.equals(o2) returns true) that they have identical hash codes (o1.hashCode.equals(o2.hashCode)). Therefore, when overriding this method, be sure to verify that the behavior is consistent with the equals method.
Attributes
- Returns
-
the hash code value for this object.
- Definition Classes
-
Any
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.
Attributes
- Returns
-
true if the configuration is empty
- Definition Classes
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.
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.
Attributes
- Returns
-
true if there are no unresolved substitutions remaining in this configuration.
- Since
-
1.2.0
- Definition Classes
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.
Attributes
- Returns
-
the origin of the
Configfor use in error messages - Definition Classes
Returns a replacement config with all substitutions (the ${foo.bar} syntax, see HOCON spec for 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").
Returns a replacement config with all substitutions (the ${foo.bar} syntax, see HOCON spec for 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 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.
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.
Attributes
- Returns
-
an immutable object with substitutions resolved
- Throws
-
ConfigException
some other config exception if there are other problems
ConfigException.UnresolvedSubstitutionif any substitutions refer to nonexistent paths
- Definition Classes
Like resolve() but allows you to specify non-default options.
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.
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).
Value parameters
- source
-
configuration to pull values from
Attributes
- Returns
-
an immutable object with substitutions resolved
- Throws
-
ConfigException
some other config exception if there are other problems
ConfigException.UnresolvedSubstitutionif any substitutions refer to paths which are not in the source
- Since
-
1.2.0
- Definition Classes
Like resolveWith(Config) but allows you to specify non-default options.
Like resolveWith(Config) but allows you to specify non-default options.
Value parameters
- options
-
resolve options
- source
-
source configuration to pull values from
Attributes
- Returns
-
the resolved
Config(may be only partially resolved if options are set to allow unresolved) - Since
-
1.2.0
- Definition Classes
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).
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).
Attributes
- Returns
-
the root object in the configuration
- Definition Classes
Attributes
- Definition Classes
Returns a string representation of the object.
Returns a string representation of the object.
The default representation is platform dependent.
Attributes
- Returns
-
a string representation of the object.
- Definition Classes
-
Any
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), then otherObjectwill 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.
Value parameters
- other
-
an object whose keys should be used as fallbacks, if the keys are not present in this one
Attributes
- Returns
-
a new object (or the original one, if the fallback doesn't get used)
- Definition Classes
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 and ConfigUtil#splitPath).
Value parameters
- path
-
path to keep
Attributes
- Returns
-
a copy of the config minus all paths except the one specified
- Definition Classes
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.
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.
Note that path expressions have a syntax and sometimes require quoting (see ConfigUtil$.joinPath and ConfigUtil#splitPath).
Value parameters
- path
-
path expression for the value's new location
- value
-
value at the new path
Attributes
- Returns
-
the new instance with the new map entry
- Definition Classes
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 and ConfigUtil#splitPath).
Value parameters
- path
-
path expression to remove
Attributes
- Returns
-
a copy of the config minus the specified path
- Definition Classes