The API for a {@code Config} is in terms of path expressions, while the APIfor a {@code ConfigObject} is in terms of keys. Conceptually, {@code Config}is a one-level map from paths to values, while a {@code ConfigObject} is a tree of nested maps from keys to values.
Use {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath} to convertbetween path expressions and individual path elements (keys).
Another difference between {@code Config} and {@code ConfigObject} is thatconceptually, {@code ConfigValue}s with a {@link ConfigValue#valueType() valueType()} of {@link ConfigValueType#NULL NULL} exist in a{@code ConfigObject}, while a {@code Config} treats null values as if theywere missing.
{@code Config} is an immutable object and thus safe to use from multiplethreads. There's never a need for "defensive copies."
The "getters" on a {@code Config} all work in the same way. They never returnnull, nor do they return a {@code ConfigValue} with{@link ConfigValue#valueType() valueType()} of {@link ConfigValueType#NULL NULL}. Instead, they throw {@link ConfigException.Missing} if the value iscompletely absent or set to null. If the value is set to null, a subtype of {@code ConfigException.Missing} called {@link ConfigException.Null} will bethrown. {@link ConfigException.WrongType} will be thrown anytime you ask fora type and the value has an incompatible type. Reasonable type conversions are performed for you though.
If you want to iterate over the contents of a {@code Config}, you can get its {@code ConfigObject} with {@link #root()}, and then iterate over the {@code ConfigObject} (which implements java.util.Map). Or, youcan use {@link #entrySet()} which recurses the object tree for you and buildsup a Set of all path-value pairs where the value is not null.
Do not implement {@code 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.
| |