Places the config inside a Config
at the given key.
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
).
key to store this config at.
a { @code Config} instance containing this config at the given key.
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
).
path expression to store this config at.
a { @code Config} instance containing this config at the given path.
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:
-
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
). 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.
a reference configuration
only validate values underneath these paths that your code module owns and understands
ConfigException.BugOrBroken
if the reference config is unresolved or caller otherwise
misuses the API
ConfigException.NotResolved
if this config is not resolved
ConfigException.ValidationFailed
if there are any validation issues
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.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.)
set of paths with non-null values, built up by recursing the entire tree of { @link ConfigObject} and creating an entry for each leaf value.
Gets the value at the path as an unwrapped Java boxed value (
Boolean
, Integer
, and
so on - see ConfigValue#unwrapped
).
Gets the value at the path as an unwrapped Java boxed value (
Boolean
, Integer
, and
so on - see ConfigValue#unwrapped
).
path expression
the unwrapped value at the requested path
ConfigException.Missing
if value is absent or null
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
).
the path to the list value.
the list at the path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a list
path expression
the boolean value at the requested path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to 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.
the path to the list value.
the list at the path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a list of booleans
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 <a href="https://github.com/lightbend/config/blob/master/HOCON.md">the spec.
path expression
the value at the requested path, in bytes
ConfigException.BadValue
if value cannot be parsed as a size in bytes
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to Long or String
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.
the path to the list value.
the list at the path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a list of memory sizes
path expression
the nested { @code Config} value at the requested path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a Config
Gets a list value with Config
elements.
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
.
the path to the list value.
the list at the path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a list of configs
path expression
the floating-point value at the requested path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a 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.
the path to the list value.
the list at the path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a list of doubles
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 expression
the duration value at the requested path
1.3.0
ConfigException.BadValue
if value cannot be parsed as a number of the given TimeUnit
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to Long or String
Gets a value as a duration in a specified
TimeUnit
.
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 <a
the HOCON spec.
path expression
convert the return value to this time unit
the duration value at the requested path, in the given TimeUnit
1.2.0
ConfigException.BadValue
if value cannot be parsed as a number of the given TimeUnit
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to Long or String
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)
.
a path expression
list of durations
1.3.0
Gets a list, converting each value in the list to a duration, using the
same rules as TimeUnit)
.
Gets a list, converting each value in the list to a duration, using the
same rules as TimeUnit)
.
a path expression
time units of the returned values
list of durations, in the requested units
1.2.0
an enum class
path expression
the { @code Enum} value at the requested path of the requested enum class
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to an Enum
Gets a list value with Enum
elements.
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
.
the enum class
the path to the list value.
the list at the path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a list of { @code Enum}
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 expression
the 32-bit integer value at the requested path
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)
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.
the path to the list value.
the list at the path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a list of ints
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(String)
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
).
the path expression
true if the value exists and is null, false if it exists and is not null
ConfigException.BadPath
if the path expression is invalid
ConfigException.Missing
if value is not set at all
Gets a list value (with any element type) as a ConfigList
, which
implements java.util.List
.
Gets a list value (with any element type) as a ConfigList
, which
implements java.util.List
. Throws if the path is
unset or null.
the path to the list value.
the { @link ConfigList} at the path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a ConfigList
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 expression
the 64-bit long value at the requested path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a 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.
the path to the list value.
the list at the path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a list of longs
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 <a href="https://github.com/lightbend/config/blob/master/HOCON.md">the spec.
path expression
the value at the requested path, in bytes
1.3.0
ConfigException.BadValue
if value cannot be parsed as a size in bytes
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to Long or String
Gets a list, converting each value in the list to a memory size, using the
same rules as #getMemorySize(String)
.
Gets a list, converting each value in the list to a memory size, using the
same rules as #getMemorySize(String)
.
a path expression
list of memory sizes
1.3.0
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a list of memory sizes
path expression
the numeric value at the requested path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a 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.
the path to the list value.
the list at the path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a list of numbers
path expression
the { @link ConfigObject} value at the requested path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to an object
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
.
the path to the list value.
the list at the path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a list of objects
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 expression
the period value at the requested path
1.3.0
ConfigException.BadValue
if value cannot be parsed as a number of the given TimeUnit
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to Long or String
path expression
the string value at the requested path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a 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.
the path to the list value.
the list at the path
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to a list of strings
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 expression
the temporal value at the requested path
ConfigException.BadValue
if value cannot be parsed as a TemporalAmount
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to Long or String
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 get
on the Config#root
object (or other object in the tree) if you
want an unprocessed value.
path expression
the value at the requested path
ConfigException.Missing
if value is absent or null
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.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.
Note that path expressions have a syntax and sometimes require quoting
(see ConfigUtil#joinPath
and ConfigUtil#splitPath
).
true if a non-null value is present at the path
ConfigException.BadPath
if the path expression is invalid
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
Config
will throw if you try to get a null
value, so if you plan to call #getValue(String)
,
#getInt(String)
, or another getter you may want to
use plain #hasPath(String)
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(String)
without
checking hasPathOrNull
first.
Note that path expressions have a syntax and sometimes require quoting
(see ConfigUtil#joinPath
and ConfigUtil#splitPath
).
the path expression
true if a value is present at the path, even if the value is null
ConfigException.BadPath
if the path expression is invalid
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.
true if the configuration is empty
Checks whether the config is completely resolved.
Checks whether the config is completely resolved. After a successful call
to Config#resolve
it will be completely resolved, but after
calling Config#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.
true if there are no unresolved substitutions remaining in this configuration.
1.2.0
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.
the origin of the { @code Config} for use in error messages
Like Config#resolve
but allows you to specify non-default
options.
Like Config#resolve
but allows you to specify non-default
options.
resolve options
the resolved Config
(may be only partially resolved if options are set to allow unresolved)
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 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 Config#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.
an immutable object with substitutions resolved
ConfigException
some other config exception if there are other problems
[[ConfigException.UnresolvedSubstitution]]
if any substitutions refer to nonexistent paths
Like Config#resolveWith(Config)
but allows you to specify
non-default options.
Like Config#resolveWith(Config)
but allows you to specify
non-default options.
source configuration to pull values from
resolve options
the resolved Config
(may be only partially resolved
if options are set to allow unresolved)
1.2.0
Like Config#resolve
except that substitution values are looked
up in the given source, rather than in this instance.
Like Config#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(boolean)
so the partial
resolves don't fail).
configuration to pull values from
an immutable object with substitutions resolved
1.2.0
ConfigException
some other config exception if there are other problems
ConfigException.UnresolvedSubstitution
if any substitutions refer to paths which are not in the
source
Gets the Config
as a tree of ConfigObject
.
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
).
the root object in the configuration
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 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.
an object whose keys should be used as fallbacks, if the keys are not present in this one
a new object (or the original one, if the fallback doesn't get used)
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
).
a copy of the config minus all paths except the one specified
Returns a Config
based on this one, but with the given path set
to the given 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.
Note that path expressions have a syntax and sometimes require quoting
(see ConfigUtil#joinPath
and ConfigUtil#splitPath
).
the new instance with the new map entry
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
).
a copy of the config minus the specified path
Get value as a duration in milliseconds.
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 <a href="https://github.com/lightbend/config/blob/master/HOCON.md">the spec.
path expression
the duration value at the requested path, in milliseconds
(Since version )
ConfigException.BadValue
if value cannot be parsed as a number of milliseconds
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to Long or String
the path
list of millisecond values
(Since version )
Get value as a duration in nanoseconds.
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
TimeUnit)
.
path expression
the duration value at the requested path, in nanoseconds
(Since version )
ConfigException.BadValue
if value cannot be parsed as a number of nanoseconds
ConfigException.Missing
if value is absent or null
ConfigException.WrongType
if value is not convertible to Long or String
the path
list of nanosecond values
(Since version )