Interface Config
-
- All Superinterfaces:
ConfigMergeable
public interface Config extends ConfigMergeable
An immutable map from config paths to config values. Paths are dot-separated expressions such asfoo.bar.baz
. Values are as in JSON (booleans, strings, numbers, lists, or objects), represented byConfigValue
instances. Values accessed through theConfig
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 withresolve()
, and merging configs usingwithFallback(ConfigMergeable)
.All operations return a new immutable
Config
rather than modifying the original instance.Examples
You can find an example app and library on GitHub. Also be sure to read the package overview which describes the big picture as shown in those examples.
Paths, keys, and Config vs. ConfigObject
Config
is a view onto a tree ofConfigObject
; the corresponding object tree can be found throughroot()
.ConfigObject
is a map from config keys, rather than paths, to config values. Think ofConfigObject
as a JSON object andConfig
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 aConfigObject
is in terms of keys. Conceptually,Config
is a one-level map from paths to values, while aConfigObject
is a tree of nested maps from keys to values.Use
ConfigUtil.joinPath(java.lang.String...)
andConfigUtil.splitPath(java.lang.String)
to convert between path expressions and individual path elements (keys).Another difference between
Config
andConfigObject
is that conceptually,ConfigValue
s with avalueType()
ofNULL
exist in aConfigObject
, while aConfig
treats null values as if they were missing. (With the exception of two methods:hasPathOrNull(java.lang.String)
andgetIsNull(java.lang.String)
let you detectnull
values.)Getting configuration values
The "getters" on a
Config
all work in the same way. They never return null, nor do they return aConfigValue
withvalueType()
ofNULL
. Instead, they throwConfigException.Missing
if the value is completely absent or set to null. If the value is set to null, a subtype ofConfigException.Missing
calledConfigException.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 itsConfigObject
withroot()
, and then iterate over theConfigObject
(which implementsjava.util.Map
). Or, you can useentrySet()
which recurses the object tree for you and builds up aSet
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 callresolve()
to handle substitutions (thoughConfigFactory.load()
and similar methods will do the resolve for you already).Merging
The full
Config
for your application can be constructed using the associative operationwithFallback(ConfigMergeable)
. If you useConfigFactory.load()
(recommended), it merges system properties over the top ofapplication.conf
over the top ofreference.conf
, usingwithFallback
. You can add in additional sources of configuration in the same way (usually, custom layers should go either just above or just belowapplication.conf
, keepingreference.conf
at the bottom and system properties at the top).Serialization
Convert a
Config
to a JSON or HOCON string by callingConfigValue.render()
on the root object,myConfig.root().render()
. There's also a variantConfigValue.render(ConfigRenderOptions)
which allows you to control the format of the rendered string. (SeeConfigRenderOptions
.) Note thatConfig
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
ConfigValue.render()
, thetoString()
method produces a debug-output-oriented representation (which is not valid JSON).Java serialization is supported as well for
Config
and all subtypes ofConfigValue
.This is an interface but don't implement it yourself
Do not implement
Config
; it should only be implemented by the config library. Arbitrary implementations will not work because the library internals assume a specific concrete implementation. Also, this interface is likely to grow new methods over time, so third-party implementations will break.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description Config
atKey(java.lang.String key)
Places the config inside aConfig
at the given key.Config
atPath(java.lang.String path)
Places the config inside anotherConfig
at the given path.void
checkValid(Config reference, java.lang.String... restrictToPaths)
Validates this config against a reference config, throwing an exception if it is invalid.java.util.Set<java.util.Map.Entry<java.lang.String,ConfigValue>>
entrySet()
Returns the set of path-value pairs, excluding any null values, found by recursingthe root object
.java.lang.Object
getAnyRef(java.lang.String path)
Gets the value at the path as an unwrapped Java boxed value (Boolean
,Integer
, and so on - seeConfigValue.unwrapped()
).java.util.List<? extends java.lang.Object>
getAnyRefList(java.lang.String path)
Gets a list value with any kind of elements.boolean
getBoolean(java.lang.String path)
java.util.List<java.lang.Boolean>
getBooleanList(java.lang.String path)
Gets a list value with boolean elements.java.lang.Long
getBytes(java.lang.String path)
Gets a value as a size in bytes (parses special strings like "128M").java.util.List<java.lang.Long>
getBytesList(java.lang.String path)
Gets a list value with elements representing a size in bytes.Config
getConfig(java.lang.String path)
java.util.List<? extends Config>
getConfigList(java.lang.String path)
Gets a list value withConfig
elements.double
getDouble(java.lang.String path)
java.util.List<java.lang.Double>
getDoubleList(java.lang.String path)
Gets a list value with double elements.java.time.Duration
getDuration(java.lang.String path)
Gets a value as a java.time.Duration.long
getDuration(java.lang.String path, java.util.concurrent.TimeUnit unit)
Gets a value as a duration in a specifiedTimeUnit
.java.util.List<java.time.Duration>
getDurationList(java.lang.String path)
Gets a list, converting each value in the list to a duration, using the same rules asgetDuration(String)
.java.util.List<java.lang.Long>
getDurationList(java.lang.String path, java.util.concurrent.TimeUnit unit)
Gets a list, converting each value in the list to a duration, using the same rules asgetDuration(String, TimeUnit)
.<T extends java.lang.Enum<T>>
TgetEnum(java.lang.Class<T> enumClass, java.lang.String path)
<T extends java.lang.Enum<T>>
java.util.List<T>getEnumList(java.lang.Class<T> enumClass, java.lang.String path)
Gets a list value withEnum
elements.int
getInt(java.lang.String path)
Gets the integer at the given path.java.util.List<java.lang.Integer>
getIntList(java.lang.String path)
Gets a list value with int elements.boolean
getIsNull(java.lang.String path)
Checks whether a value is set to null at the given path, but throws an exception if the value is entirely unset.ConfigList
getList(java.lang.String path)
Gets a list value (with any element type) as aConfigList
, which implementsjava.util.List<ConfigValue>
.long
getLong(java.lang.String path)
Gets the long integer at the given path.java.util.List<java.lang.Long>
getLongList(java.lang.String path)
Gets a list value with long elements.ConfigMemorySize
getMemorySize(java.lang.String path)
Gets a value as an amount of memory (parses special strings like "128M").java.util.List<ConfigMemorySize>
getMemorySizeList(java.lang.String path)
Gets a list, converting each value in the list to a memory size, using the same rules asgetMemorySize(String)
.java.lang.Long
getMilliseconds(java.lang.String path)
Deprecated.As of release 1.1, replaced bygetDuration(String, TimeUnit)
java.util.List<java.lang.Long>
getMillisecondsList(java.lang.String path)
Deprecated.As of release 1.1, replaced bygetDurationList(String, TimeUnit)
java.lang.Long
getNanoseconds(java.lang.String path)
Deprecated.As of release 1.1, replaced bygetDuration(String, TimeUnit)
java.util.List<java.lang.Long>
getNanosecondsList(java.lang.String path)
Deprecated.As of release 1.1, replaced bygetDurationList(String, TimeUnit)
java.lang.Number
getNumber(java.lang.String path)
java.util.List<java.lang.Number>
getNumberList(java.lang.String path)
Gets a list value with number elements.ConfigObject
getObject(java.lang.String path)
java.util.List<? extends ConfigObject>
getObjectList(java.lang.String path)
Gets a list value with object elements.java.lang.String
getString(java.lang.String path)
java.util.List<java.lang.String>
getStringList(java.lang.String path)
Gets a list value with string elements.ConfigValue
getValue(java.lang.String path)
Gets the value at the given path, unless the value is a null value or missing, in which case it throws just like the other getters.boolean
hasPath(java.lang.String path)
Checks whether a value is present and non-null at the given path.boolean
hasPathOrNull(java.lang.String path)
Checks whether a value is present at the given path, even if the value is null.boolean
isEmpty()
Returns true if theConfig
's root object contains no key-value pairs.boolean
isResolved()
Checks whether the config is completely resolved.ConfigOrigin
origin()
Gets the origin of theConfig
, which may be a file, or a file with a line number, or just a descriptive phrase.Config
resolve()
Returns a replacement config with all substitutions (the${foo.bar}
syntax, see the spec) resolved.Config
resolve(ConfigResolveOptions options)
Likeresolve()
but allows you to specify non-default options.Config
resolveWith(Config source)
Likeresolve()
except that substitution values are looked up in the given source, rather than in this instance.Config
resolveWith(Config source, ConfigResolveOptions options)
LikeresolveWith(Config)
but allows you to specify non-default options.ConfigObject
root()
Gets theConfig
as a tree ofConfigObject
.Config
withFallback(ConfigMergeable other)
Returns a new value computed by merging this value with another, with keys in this value "winning" over the other one.Config
withOnlyPath(java.lang.String path)
Clone the config with only the given path (and its children) retained; all sibling paths are removed.Config
withoutPath(java.lang.String path)
Clone the config with the given path removed.Config
withValue(java.lang.String path, ConfigValue value)
Returns aConfig
based on this one, but with the given path set to the given value.
-
-
-
Method Detail
-
root
ConfigObject root()
Gets theConfig
as a tree ofConfigObject
. This is a constant-time operation (it is not proportional to the number of values in theConfig
).- Returns:
- the root object in the configuration
-
origin
ConfigOrigin origin()
Gets the origin of theConfig
, which may be a file, or a file with a line number, or just a descriptive phrase.- Returns:
- the origin of the
Config
for use in error messages
-
withFallback
Config withFallback(ConfigMergeable other)
Description copied from interface:ConfigMergeable
Returns a new value computed by merging this value with another, with keys in this value "winning" over the other one.This associative operation may be used to combine configurations from multiple sources (such as multiple configuration files).
The semantics of merging are described in the spec for HOCON. Merging typically occurs when either the same object is created twice in the same file, or two config files are both loaded. For example:
foo = { a: 42 } foo = { b: 43 }
Here, the two objects are merged as if you had written:foo = { a: 42, b: 43 }
Only
ConfigObject
andConfig
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 writeobject.withFallback(nonObject).withFallback(otherObject)
, thenotherObject
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 offoo
would be simply 10. Again, for details see the spec.- Specified by:
withFallback
in interfaceConfigMergeable
- Parameters:
other
- an object whose keys should be used as fallbacks, if the keys are not present in this one- Returns:
- a new object (or the original one, if the fallback doesn't get used)
-
resolve
Config resolve()
Returns a replacement config with all substitutions (the${foo.bar}
syntax, see the spec) resolved. Substitutions are looked up using thisConfig
as 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 variantresolve(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 (seewithFallback(com.typesafe.config.ConfigMergeable)
). Otherwise, some substitutions that could have resolved with all fallbacks available may not resolve, which will be potentially confusing for your application's users.resolve()
should be invoked on root config objects, rather than on a subtree (a subtree is the result of something likeconfig.getConfig("foo")
). The problem withresolve()
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 didconfig.getConfig("foo").resolve()
on the below config file, it would not work:common-value = 10 foo { whatever = ${common-value} }
Many methods on
ConfigFactory
such asConfigFactory.load()
automatically resolve the loadedConfig
on the loaded stack of config files.Resolving an already-resolved config is a harmless no-op, but again, it is best to resolve an entire stack of fallbacks (such as all your config files combined) rather than resolving each one individually.
- Returns:
- an immutable object with substitutions resolved
- Throws:
ConfigException.UnresolvedSubstitution
- if any substitutions refer to nonexistent pathsConfigException
- some other config exception if there are other problems
-
resolve
Config resolve(ConfigResolveOptions options)
Likeresolve()
but allows you to specify non-default options.- Parameters:
options
- resolve options- Returns:
- the resolved
Config
(may be only partially resolved if options are set to allow unresolved)
-
isResolved
boolean isResolved()
Checks whether the config is completely resolved. After a successful call toresolve()
it will be completely resolved, but after callingresolve(ConfigResolveOptions)
withallowUnresolved
set in the options, it may or may not be completely resolved. A newly-loaded config may or may not be completely resolved depending on whether there were substitutions present in the file.- Returns:
- true if there are no unresolved substitutions remaining in this configuration.
- Since:
- 1.2.0
-
resolveWith
Config resolveWith(Config source)
Likeresolve()
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 usingwithFallback(com.typesafe.config.ConfigMergeable)
and then resolve.Note that this method does NOT look in this instance for substitution values. If you want to do that, you could either merge this instance into your value source using
withFallback(com.typesafe.config.ConfigMergeable)
, or you could resolve multiple times with multiple sources (usingConfigResolveOptions.setAllowUnresolved(boolean)
so the partial resolves don't fail).- Parameters:
source
- configuration to pull values from- Returns:
- an immutable object with substitutions resolved
- Throws:
ConfigException.UnresolvedSubstitution
- if any substitutions refer to paths which are not in the sourceConfigException
- some other config exception if there are other problems- Since:
- 1.2.0
-
resolveWith
Config resolveWith(Config source, ConfigResolveOptions options)
LikeresolveWith(Config)
but allows you to specify non-default options.- Parameters:
source
- source configuration to pull values fromoptions
- resolve options- Returns:
- the resolved
Config
(may be only partially resolved if options are set to allow unresolved) - Since:
- 1.2.0
-
checkValid
void checkValid(Config reference, java.lang.String... restrictToPaths)
Validates this config against a reference config, throwing an exception if it is invalid. The purpose of this method is to "fail early" with a comprehensive list of problems; in general, anything this method can find would be detected later when trying to use the config, but it's often more user-friendly to fail right away when loading the config.Using this method is always optional, since you can "fail late" instead.
You must restrict validation to paths you "own" (those whose meaning are defined by your code module). If you validate globally, you may trigger errors about paths that happen to be in the config but have nothing to do with your module. It's best to allow the modules owning those paths to validate them. Also, if every module validates only its own stuff, there isn't as much redundant work being done.
If no paths are specified in
checkValid()
's parameter list, validation is for the entire config.If you specify paths that are not in the reference config, those paths are ignored. (There's nothing to validate.)
Here's what validation involves:
- All paths found in the reference config must be present in this config or an exception will be thrown.
-
Some changes in type from the reference config to this config will cause
an exception to be thrown. Not all potential type problems are detected,
in particular it's assumed that strings are compatible with everything
except objects and lists. This is because string types are often "really"
some other type (system properties always start out as strings, or a
string like "5ms" could be used with
getMilliseconds(java.lang.String)
). Also, it's allowed to set any type to null or override null with any type. - Any unresolved substitutions in this config will cause a validation failure; both the reference config and this config should be resolved before validation. If the reference config is unresolved, it's a bug in the caller of this method.
If you want to allow a certain setting to have a flexible type (or otherwise want validation to be looser for some settings), you could either remove the problematic setting from the reference config provided to this method, or you could intercept the validation exception and screen out certain problems. Of course, this will only work if all other callers of this method are careful to restrict validation to their own paths, as they should be.
If validation fails, the thrown exception contains a list of all problems found. See
ConfigException.ValidationFailed.problems
. The exception'sgetMessage()
will have all the problems concatenated into one huge string, as well.Again,
checkValid()
can't guess every domain-specific way a setting can be invalid, so some problems may arise later when attempting to use the config.checkValid()
is limited to reporting generic, but common, problems such as missing settings and blatant type incompatibilities.- Parameters:
reference
- a reference configurationrestrictToPaths
- only validate values underneath these paths that your code module owns and understands- Throws:
ConfigException.ValidationFailed
- if there are any validation issuesConfigException.NotResolved
- if this config is not resolvedConfigException.BugOrBroken
- if the reference config is unresolved or caller otherwise misuses the API
-
hasPath
boolean hasPath(java.lang.String path)
Checks whether a value is present and non-null at the given path. This differs in two ways fromMap.containsKey()
as implemented byConfigObject
: it looks for a path expression, not a key; and it returns false for null values, whilecontainsKey()
returns true indicating that the object contains a null value for the key.If a path exists according to
hasPath(String)
, thengetValue(String)
will never throw an exception. However, the typed getters, such asgetInt(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(java.lang.String...)
andConfigUtil.splitPath(java.lang.String)
).- Parameters:
path
- the path expression- Returns:
- true if a non-null value is present at the path
- Throws:
ConfigException.BadPath
- if the path expression is invalid
-
hasPathOrNull
boolean hasPathOrNull(java.lang.String path)
Checks whether a value is present at the given path, even if the value is null. Most of the getters onConfig
will throw if you try to get a null value, so if you plan to callgetValue(String)
,getInt(String)
, or another getter you may want to use plainhasPath(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 callgetIsNull(String)
without checkinghasPathOrNull
first.Note that path expressions have a syntax and sometimes require quoting (see
ConfigUtil.joinPath(java.lang.String...)
andConfigUtil.splitPath(java.lang.String)
).- Parameters:
path
- the path expression- 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
-
isEmpty
boolean isEmpty()
Returns true if theConfig
's root object contains no key-value pairs.- Returns:
- true if the configuration is empty
-
entrySet
java.util.Set<java.util.Map.Entry<java.lang.String,ConfigValue>> entrySet()
Returns the set of path-value pairs, excluding any null values, found by recursingthe root object
. Note that this is very different fromroot().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(java.lang.String)
.Because a
Config
is conceptually a single-level map from paths to values, there will not be anyConfigObject
values in the entries (that is, all entries represent leaf nodes). UseConfigObject
rather thanConfig
if you want a tree. (OK, this is a slight lie:Config
entries may containConfigList
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.
-
getIsNull
boolean getIsNull(java.lang.String path)
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 ifhasPathOrNull(String)
returned true for the same path, so to avoid any possible exception checkhasPathOrNull()
first. However, an exception for unset paths will usually be the right thing (because areference.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(java.lang.String...)
andConfigUtil.splitPath(java.lang.String)
).- Parameters:
path
- the path expression- 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 invalidConfigException.Missing
- if value is not set at all
-
getBoolean
boolean getBoolean(java.lang.String path)
- Parameters:
path
- path expression- Returns:
- the boolean value at the requested path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to boolean
-
getNumber
java.lang.Number getNumber(java.lang.String path)
- Parameters:
path
- path expression- Returns:
- the numeric value at the requested path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a number
-
getInt
int getInt(java.lang.String 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).- Parameters:
path
- path expression- Returns:
- the 32-bit integer value at the requested path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to an int (for example it is out of range, or it's a boolean value)
-
getLong
long getLong(java.lang.String path)
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).- Parameters:
path
- path expression- Returns:
- the 64-bit long value at the requested path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a long
-
getDouble
double getDouble(java.lang.String path)
- Parameters:
path
- path expression- Returns:
- the floating-point value at the requested path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a double
-
getString
java.lang.String getString(java.lang.String path)
- Parameters:
path
- path expression- Returns:
- the string value at the requested path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a string
-
getEnum
<T extends java.lang.Enum<T>> T getEnum(java.lang.Class<T> enumClass, java.lang.String path)
- Type Parameters:
T
- a generic denoting a specific type of enum- Parameters:
enumClass
- an enum classpath
- path expression- Returns:
- the
Enum
value at the requested path of the requested enum class - Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to an Enum
-
getObject
ConfigObject getObject(java.lang.String path)
- Parameters:
path
- path expression- Returns:
- the
ConfigObject
value at the requested path - Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to an object
-
getConfig
Config getConfig(java.lang.String path)
- Parameters:
path
- path expression- Returns:
- the nested
Config
value at the requested path - Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a Config
-
getAnyRef
java.lang.Object getAnyRef(java.lang.String path)
Gets the value at the path as an unwrapped Java boxed value (Boolean
,Integer
, and so on - seeConfigValue.unwrapped()
).- Parameters:
path
- path expression- Returns:
- the unwrapped value at the requested path
- Throws:
ConfigException.Missing
- if value is absent or null
-
getValue
ConfigValue getValue(java.lang.String path)
Gets the value at the given path, unless the value is a null value or missing, in which case it throws just like the other getters. Useget()
on theroot()
object (or other object in the tree) if you want an unprocessed value.- Parameters:
path
- path expression- Returns:
- the value at the requested path
- Throws:
ConfigException.Missing
- if value is absent or null
-
getBytes
java.lang.Long getBytes(java.lang.String path)
Gets a value as a size in bytes (parses special strings like "128M"). If the value is already a number, then it's left alone; if it's a string, it's parsed understanding unit suffixes such as "128K", as documented in the the spec.- Parameters:
path
- path expression- Returns:
- the value at the requested path, in bytes
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to Long or StringConfigException.BadValue
- if value cannot be parsed as a size in bytes
-
getMemorySize
ConfigMemorySize getMemorySize(java.lang.String path)
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.- Parameters:
path
- path expression- Returns:
- the value at the requested path, in bytes
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to Long or StringConfigException.BadValue
- if value cannot be parsed as a size in bytes- Since:
- 1.3.0
-
getMilliseconds
@Deprecated java.lang.Long getMilliseconds(java.lang.String path)
Deprecated.As of release 1.1, replaced bygetDuration(String, TimeUnit)
Get value as a duration in milliseconds. If the value is already a number, then it's left alone; if it's a string, it's parsed understanding units suffixes like "10m" or "5ns" as documented in the the spec.- Parameters:
path
- path expression- Returns:
- the duration value at the requested path, in milliseconds
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to Long or StringConfigException.BadValue
- if value cannot be parsed as a number of milliseconds
-
getNanoseconds
@Deprecated java.lang.Long getNanoseconds(java.lang.String path)
Deprecated.As of release 1.1, replaced bygetDuration(String, TimeUnit)
Get value as a duration in nanoseconds. If the value is already a number it's taken as milliseconds and converted to nanoseconds. If it's a string, it's parsed understanding unit suffixes, as forgetDuration(String, TimeUnit)
.- Parameters:
path
- path expression- Returns:
- the duration value at the requested path, in nanoseconds
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to Long or StringConfigException.BadValue
- if value cannot be parsed as a number of nanoseconds
-
getDuration
long getDuration(java.lang.String path, java.util.concurrent.TimeUnit unit)
Gets a value as a duration in a specifiedTimeUnit
. If the value is already a number, then it's taken as milliseconds and then converted to the requested TimeUnit; if it's a string, it's parsed understanding units suffixes like "10m" or "5ns" as documented in the the spec.- Parameters:
path
- path expressionunit
- convert the return value to this time unit- Returns:
- the duration value at the requested path, in the given TimeUnit
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to Long or StringConfigException.BadValue
- if value cannot be parsed as a number of the given TimeUnit- Since:
- 1.2.0
-
getDuration
java.time.Duration getDuration(java.lang.String path)
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.- Parameters:
path
- path expression- Returns:
- the duration value at the requested path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to Long or StringConfigException.BadValue
- if value cannot be parsed as a number of the given TimeUnit- Since:
- 1.3.0
-
getList
ConfigList getList(java.lang.String path)
Gets a list value (with any element type) as aConfigList
, which implementsjava.util.List<ConfigValue>
. Throws if the path is unset or null.- Parameters:
path
- the path to the list value.- Returns:
- the
ConfigList
at the path - Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a ConfigList
-
getBooleanList
java.util.List<java.lang.Boolean> getBooleanList(java.lang.String path)
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.- Parameters:
path
- the path to the list value.- Returns:
- the list at the path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a list of booleans
-
getNumberList
java.util.List<java.lang.Number> getNumberList(java.lang.String path)
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.- Parameters:
path
- the path to the list value.- Returns:
- the list at the path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a list of numbers
-
getIntList
java.util.List<java.lang.Integer> getIntList(java.lang.String path)
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.- Parameters:
path
- the path to the list value.- Returns:
- the list at the path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a list of ints
-
getLongList
java.util.List<java.lang.Long> getLongList(java.lang.String path)
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.- Parameters:
path
- the path to the list value.- Returns:
- the list at the path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a list of longs
-
getDoubleList
java.util.List<java.lang.Double> getDoubleList(java.lang.String path)
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.- Parameters:
path
- the path to the list value.- Returns:
- the list at the path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a list of doubles
-
getStringList
java.util.List<java.lang.String> getStringList(java.lang.String path)
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.- Parameters:
path
- the path to the list value.- Returns:
- the list at the path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a list of strings
-
getEnumList
<T extends java.lang.Enum<T>> java.util.List<T> getEnumList(java.lang.Class<T> enumClass, java.lang.String path)
Gets a list value withEnum
elements. Throws if the path is unset or null or not a list or contains values not convertible toEnum
.- Type Parameters:
T
- a generic denoting a specific type of enum- Parameters:
enumClass
- the enum classpath
- the path to the list value.- Returns:
- the list at the path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a list ofEnum
-
getObjectList
java.util.List<? extends ConfigObject> getObjectList(java.lang.String path)
Gets a list value with object elements. Throws if the path is unset or null or not a list or contains values not convertible toConfigObject
.- Parameters:
path
- the path to the list value.- Returns:
- the list at the path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a list of objects
-
getConfigList
java.util.List<? extends Config> getConfigList(java.lang.String path)
Gets a list value withConfig
elements. Throws if the path is unset or null or not a list or contains values not convertible toConfig
.- Parameters:
path
- the path to the list value.- Returns:
- the list at the path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a list of configs
-
getAnyRefList
java.util.List<? extends java.lang.Object> getAnyRefList(java.lang.String path)
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" (seeConfigValue.unwrapped()
).- Parameters:
path
- the path to the list value.- Returns:
- the list at the path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a list
-
getBytesList
java.util.List<java.lang.Long> getBytesList(java.lang.String path)
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.- Parameters:
path
- the path to the list value.- Returns:
- the list at the path
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a list of memory sizes
-
getMemorySizeList
java.util.List<ConfigMemorySize> getMemorySizeList(java.lang.String path)
Gets a list, converting each value in the list to a memory size, using the same rules asgetMemorySize(String)
.- Parameters:
path
- a path expression- Returns:
- list of memory sizes
- Throws:
ConfigException.Missing
- if value is absent or nullConfigException.WrongType
- if value is not convertible to a list of memory sizes- Since:
- 1.3.0
-
getMillisecondsList
@Deprecated java.util.List<java.lang.Long> getMillisecondsList(java.lang.String path)
Deprecated.As of release 1.1, replaced bygetDurationList(String, TimeUnit)
- Parameters:
path
- the path- Returns:
- list of millisecond values
-
getNanosecondsList
@Deprecated java.util.List<java.lang.Long> getNanosecondsList(java.lang.String path)
Deprecated.As of release 1.1, replaced bygetDurationList(String, TimeUnit)
- Parameters:
path
- the path- Returns:
- list of nanosecond values
-
getDurationList
java.util.List<java.lang.Long> getDurationList(java.lang.String path, java.util.concurrent.TimeUnit unit)
Gets a list, converting each value in the list to a duration, using the same rules asgetDuration(String, TimeUnit)
.- Parameters:
path
- a path expressionunit
- time units of the returned values- Returns:
- list of durations, in the requested units
- Since:
- 1.2.0
-
getDurationList
java.util.List<java.time.Duration> getDurationList(java.lang.String path)
Gets a list, converting each value in the list to a duration, using the same rules asgetDuration(String)
.- Parameters:
path
- a path expression- Returns:
- list of durations
- Since:
- 1.3.0
-
withOnlyPath
Config withOnlyPath(java.lang.String path)
Clone the config with only the given path (and its children) retained; all sibling paths are removed.Note that path expressions have a syntax and sometimes require quoting (see
ConfigUtil.joinPath(java.lang.String...)
andConfigUtil.splitPath(java.lang.String)
).- Parameters:
path
- path to keep- Returns:
- a copy of the config minus all paths except the one specified
-
withoutPath
Config withoutPath(java.lang.String path)
Clone the config with the given path removed.Note that path expressions have a syntax and sometimes require quoting (see
ConfigUtil.joinPath(java.lang.String...)
andConfigUtil.splitPath(java.lang.String)
).- Parameters:
path
- path expression to remove- Returns:
- a copy of the config minus the specified path
-
atPath
Config atPath(java.lang.String path)
Places the config inside anotherConfig
at the given path.Note that path expressions have a syntax and sometimes require quoting (see
ConfigUtil.joinPath(java.lang.String...)
andConfigUtil.splitPath(java.lang.String)
).- Parameters:
path
- path expression to store this config at.- Returns:
- a
Config
instance containing this config at the given path.
-
atKey
Config atKey(java.lang.String key)
Places the config inside aConfig
at the given key. See also atPath(). Note that a key is NOT a path expression (seeConfigUtil.joinPath(java.lang.String...)
andConfigUtil.splitPath(java.lang.String)
).- Parameters:
key
- key to store this config at.- Returns:
- a
Config
instance containing this config at the given key.
-
withValue
Config withValue(java.lang.String path, ConfigValue value)
Returns aConfig
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(java.lang.String...)
andConfigUtil.splitPath(java.lang.String)
).- Parameters:
path
- path expression for the value's new locationvalue
- value at the new path- Returns:
- the new instance with the new map entry
-
-