ConfigObject
Subtype of [[ConfigValue]]
representing an object (AKA dictionary or map)
value, as in JSON's curly brace { "a" : 42 }
syntax.
Subtype of [[ConfigValue]]
representing an object (AKA dictionary or map)
value, as in JSON's curly brace { "a" : 42 }
syntax.
An object may also be viewed as a [[Config]]
by calling
[[ConfigObject#toConfig]]
.
ConfigObject
implements java.util.Map<String, ConfigValue>
so
you can use it like a regular Java map. Or call [[#unwrapped]]
to
unwrap the map to a map with plain Java values rather than
ConfigValue
.
Like all [[ConfigValue]]
subtypes, ConfigObject
is immutable.
This makes it threadsafe and you never have to create "defensive copies." The
mutator methods from java.util.Map
all throw
java.lang.UnsupportedOperationException
.
The [[ConfigValue#valueType]]
method on an object returns
[[ConfigValueType#OBJECT]]
.
In most cases you want to use the [[Config]]
interface rather than this
one. Call [[#toConfig]]
to convert a ConfigObject
to a
Config
.
The API for a ConfigObject
is in terms of keys, while the API for a
[[Config]]
is in terms of path expressions. Conceptually,
ConfigObject
is a tree of maps from keys to values, while a
Config
is a one-level map from paths to values.
Use ConfigUtil.joinPath(String*) and ConfigUtil.splitPath(String) to convert between path expressions and individual path elements (keys).
A ConfigObject
may contain null values, which will have
[[ConfigValue#valueType]]
equal to [[ConfigValueType#NULL]]
. If
[[ConfigObject#get]]
returns Java's null then the key was not
present in the parsed file (or wherever this value tree came from). If
get("key")
returns a [[ConfigValue]]
with type
ConfigValueType#NULL
then the key was set to null explicitly in the
config file.
Do not implement interface ConfigObject
; 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.
Value members
Abstract methods
Gets a [[ConfigValue]]
at the given key, or returns null if there is
no value. The returned [[ConfigValue]]
may have
[[ConfigValueType#NULL]]
or any other type, and the passed-in key
must be a key in this object (rather than a path expression).
Gets a [[ConfigValue]]
at the given key, or returns null if there is
no value. The returned [[ConfigValue]]
may have
[[ConfigValueType#NULL]]
or any other type, and the passed-in key
must be a key in this object (rather than a path expression).
- Value Params
- key
key to look up
- Returns
the value at the key or null if none
- Definition Classes
- Map
Converts this object to a [[Config]]
instance, enabling you to use
path expressions to find values in the object. This is a constant-time
operation (it is not proportional to the size of the object).
Converts this object to a [[Config]]
instance, enabling you to use
path expressions to find values in the object. This is a constant-time
operation (it is not proportional to the size of the object).
- Returns
a
[[Config]]
with this object as its root
Recursively unwraps the object, returning a map from String to whatever plain Java values are unwrapped from the object's values.
Recursively unwraps the object, returning a map from String to whatever plain Java values are unwrapped from the object's values.
- Returns
a
java.util.Map
containing plain Java objects- Definition Classes
Clone the object with only the given key (and its children) retained; all sibling keys are removed.
Clone the object with only the given key (and its children) retained; all sibling keys are removed.
- Value Params
- key
key to keep
- Returns
a copy of the object minus all keys except the one specified
Returns a ConfigObject
based on this one, but with the given key
set to the given value. Does not modify this instance (since it's
immutable). If the key already has a value, that value is replaced. To
remove a value, use [[ConfigObject#withoutKey]]
.
Returns a ConfigObject
based on this one, but with the given key
set to the given value. Does not modify this instance (since it's
immutable). If the key already has a value, that value is replaced. To
remove a value, use [[ConfigObject#withoutKey]]
.
- Value Params
- key
key to add
- value
value at the new key
- Returns
the new instance with the new map entry
Inherited methods
Places the value inside a [[Config]]
at the given key. See also
[[ConfigValue#atPath]]
.
Places the value inside a [[Config]]
at the given key. See also
[[ConfigValue#atPath]]
.
- Value Params
- key
key to store this value at.
- Returns
a
Config
instance containing this value at the given key.- Inherited from
- ConfigValue
Places the value inside a [[Config]]
at the given path. See also
[[ConfigValue#atKey]]
.
Places the value inside a [[Config]]
at the given path. See also
[[ConfigValue#atKey]]
.
- Value Params
- path
path to store this value at.
- Returns
a
Config
instance containing this value at the given path.- Inherited from
- ConfigValue
- Inherited from
- Map
- Inherited from
- Map
- Inherited from
- Map
The origin of the value (file, line number, etc.), for debugging and error messages.
The origin of the value (file, line number, etc.), for debugging and error messages.
- Returns
where the value came from
- Inherited from
- ConfigValue
Renders the config value to a string, using the provided options.
Renders the config value to a string, using the provided options.
If the config value has not been resolved (see [Config.resolve()), it's possible that it can't be rendered as valid HOCON. In that case the rendering should still be useful for debugging but you might not be able to parse it. If the value has been resolved, it will always be parseable.
If the config value has been resolved and the options disable all HOCON-specific features (such as comments), the rendering will be valid JSON. If you enable HOCON-only features such as comments, the rendering will not be valid JSON.
- Value Params
- options
the rendering options
- Returns
the rendered value
- Inherited from
- ConfigValue
Renders the config value as a HOCON string. This method is primarily intended for debugging, so it tries to add helpful comments and whitespace.
Renders the config value as a HOCON string. This method is primarily intended for debugging, so it tries to add helpful comments and whitespace.
If the config value has not been resolved (see Config.resolve()), it's possible that it can't be rendered as valid HOCON. In that case the rendering should still be useful for debugging but you might not be able to parse it. If the value has been resolved, it will always be parseable.
This method is equivalent to
render(ConfigRenderOptions.defaults())
.
- Returns
the rendered value
- Inherited from
- ConfigValue
- Inherited from
- Map
The [[ConfigValueType]]
of the value; matches the JSON type schema.
The [[ConfigValueType]]
of the value; matches the JSON type schema.
- Returns
value's type
- Inherited from
- ConfigValue