com.typesafe.config

## Interface Config

All Superinterfaces:
  ConfigMergeable

    public interface Config
    extends ConfigMergeable

An immutable map from config paths to config values.

Contrast with `ConfigObject` which is a map from config keys, rather than paths, to config values. A `Config` contains a tree of `ConfigObject`, and `root()` returns the tree's root object.

Throughout the API, there is a distinction between "keys" and "paths". 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 a `ConfigObject` is in terms of keys. Conceptually, `Config` is a one-level map from paths to values, while a `ConfigObject` is a tree of nested maps from keys to values.

Another difference between `Config` and `ConfigObject` is that conceptually, `ConfigValue`s with a `valueType()` of `NULL` exist in a `ConfigObject`, while a `Config` treats null values as if they were missing.

`Config` is an immutable object and thus safe to use from multiple threads. There's never a need for "defensive copies."

The "getters" on a `Config` all work in the same way. They never return null, nor do they return a `ConfigValue` with `valueType()` of `NULL`. Instead, they throw `ConfigException.Missing` if the value is completely absent or set to null. If the value is set to null, a subtype of `ConfigException.Missing` called `ConfigException.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.

If you want to iterate over the contents of a `Config`, you can get its `ConfigObject` with `root()`, and then iterate over the `ConfigObject` (which implements `java.util.Map`). Or, you can use `entrySet()` which recurses the object tree for you and builds up a `Set` of all path-value pairs where the value is not null.

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

Methods
`void` `checkValid(Config reference, String... restrictToPaths)` Validates this config against a reference config, throwing an exception if it is invalid.
`Set<Map.Entry<String,ConfigValue>>` `entrySet()` Returns the set of path-value pairs, excluding any null values, found by recursing `the root object`.
`Object` `getAnyRef(String path)` Gets the value at the path as an unwrapped Java boxed value ( `Boolean`, `Integer`, and so on - see `ConfigValue.unwrapped()`).
`List<? extends Object>` `getAnyRefList(String path)`
`boolean` `getBoolean(String path)`
`List<Boolean>` `getBooleanList(String path)`
`Long` `getBytes(String path)` Gets a value as a size in bytes (parses special strings like "128M").
`List<Long>` `getBytesList(String path)`
`Config` `getConfig(String path)`
`List<? extends Config>` `getConfigList(String path)`
`double` `getDouble(String path)`
`List<Double>` `getDoubleList(String path)`
`int` `getInt(String path)`
`List<Integer>` `getIntList(String path)`
`ConfigList` `getList(String path)` Gets a list value (with any element type) as a `ConfigList`, which implements `java.util.List<ConfigValue>`.
`long` `getLong(String path)`
`List<Long>` `getLongList(String path)`
`Long` `getMilliseconds(String path)` Get value as a duration in milliseconds.
`List<Long>` `getMillisecondsList(String path)`
`Long` `getNanoseconds(String path)` Get value as a duration in nanoseconds.
`List<Long>` `getNanosecondsList(String path)`
`Number` `getNumber(String path)`
`List<Number>` `getNumberList(String path)`
`ConfigObject` `getObject(String path)`
`List<? extends ConfigObject>` `getObjectList(String path)`
`String` `getString(String path)`
`List<String>` `getStringList(String path)`
`ConfigValue` `getValue(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(String path)` Checks whether a value is present and non-null at the given path.
`boolean` `isEmpty()` Returns true if the `Config`'s root object contains no key-value pairs.
`ConfigOrigin` `origin()` Gets the origin of the `Config`, 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)` Like `resolve()` but allows you to specify non-default options.
`ConfigObject` `root()` Gets the `Config` as a tree of `ConfigObject`.
`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.

### Method Detail

#### root

    ConfigObject root()

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`).

Returns:
  the root object in the configuration

#### origin

    ConfigOrigin origin()

Gets the origin of the `Config`, 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. 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.

The semantics of merging are described in the spec for HOCON.

Note 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. Both non-objects, and any object which has fallen back to a non-object, block subsequent fallbacks.

Specified by:
  `withFallback` in interface `ConfigMergeable`
Parameters:
  `other` - an object whose keys should be used 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 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 `withFallback(com.typesafe.config.ConfigMergeable)`). Otherwise, some substitutions that could have resolved with all fallbacks available may not resolve, which will be a user-visible oddity.

`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}
       }

Returns:
  an immutable object with substitutions resolved
Throws:
  `ConfigException.UnresolvedSubstitution` - if any substitutions refer to nonexistent paths
  `ConfigException` - some other config exception if there are other problems

#### resolve

    Config resolve(ConfigResolveOptions options)

Like `resolve()` but allows you to specify non-default options.

Parameters:
  `options` - resolve options
Returns:
  the resolved `Config`

#### checkValid

    void checkValid(Config reference,
                  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'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.

Parameters:
  `reference` - a reference configuration
  `restrictToPaths` - only validate values underneath these paths that your code module owns and understands
Throws:
  `ConfigException.ValidationFailed` - if there are any validation issues
  `ConfigException.NotResolved` - if this config is not resolved
  `ConfigException.BugOrBroken` - if the reference config is unresolved or caller otherwise misuses the API

#### hasPath

    boolean hasPath(String 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.

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

#### isEmpty

    boolean isEmpty()

Returns true if the `Config`'s root object contains no key-value pairs.

Returns:
  true if the configuration is empty

#### entrySet

    Set<Map.Entry<String,ConfigValue>> entrySet()

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:
  set of paths with non-null values, built up by recursing the entire tree of `ConfigObject`

#### getBoolean

    boolean getBoolean(String path)

Parameters:
  `path` - path expression
Returns:
  the boolean value at the requested path
Throws:
  `ConfigException.Missing` - if value is absent or null
  `ConfigException.WrongType` - if value is not convertible to boolean

#### getNumber

    Number getNumber(String path)

Parameters:
  `path` - path expression
Returns:
  the numeric value at the requested path
Throws:
  `ConfigException.Missing` - if value is absent or null
  `ConfigException.WrongType` - if value is not convertible to a number

#### getInt

    int getInt(String path)

Parameters:
  `path` - path expression
Returns:
  the 32-bit integer value at the requested path
Throws:
  `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)

#### getLong

    long getLong(String path)

Parameters:
  `path` - path expression
Returns:
  the 64-bit long value at the requested path
Throws:
  `ConfigException.Missing` - if value is absent or null
  `ConfigException.WrongType` - if value is not convertible to a long

#### getDouble

    double getDouble(String path)

Parameters:
  `path` - path expression
Returns:
  the floating-point value at the requested path
Throws:
  `ConfigException.Missing` - if value is absent or null
  `ConfigException.WrongType` - if value is not convertible to a double

#### getString

    String getString(String path)

Parameters:
  `path` - path expression
Returns:
  the string value at the requested path
Throws:
  `ConfigException.Missing` - if value is absent or null
  `ConfigException.WrongType` - if value is not convertible to a string

#### getObject

    ConfigObject getObject(String path)

Parameters:
  `path` - path expression
Returns:
  the `ConfigObject` value at the requested path
Throws:
  `ConfigException.Missing` - if value is absent or null
  `ConfigException.WrongType` - if value is not convertible to an object

#### getConfig

    Config getConfig(String path)

Parameters:
  `path` - path expression
Returns:
  the nested `Config` value at the requested path
Throws:
  `ConfigException.Missing` - if value is absent or null
  `ConfigException.WrongType` - if value is not convertible to a Config

#### getAnyRef

    Object getAnyRef(String path)

Gets the value at the path as an unwrapped Java boxed value ( `Boolean`, `Integer`, and so on - see `ConfigValue.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(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. Use `get()` from the `Map` interface 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

    Long getBytes(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 null
  `ConfigException.WrongType` - if value is not convertible to Long or String
  `ConfigException.BadValue` - if value cannot be parsed as a size in bytes

#### getMilliseconds

    Long getMilliseconds(String path)

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 null
  `ConfigException.WrongType` - if value is not convertible to Long or String
  `ConfigException.BadValue` - if value cannot be parsed as a number of milliseconds

#### getNanoseconds

    Long getNanoseconds(String path)

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 `getMilliseconds(String)`.

Parameters:
  `path` - path expression
Returns:
  the duration value at the requested path, in nanoseconds
Throws:
  `ConfigException.Missing` - if value is absent or null
  `ConfigException.WrongType` - if value is not convertible to Long or String
  `ConfigException.BadValue` - if value cannot be parsed as a number of nanoseconds

#### getList

    ConfigList getList(String path)

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.

Parameters:
  `path` - the path to the list value.
Returns:
  the `ConfigList` at the path
Throws:
  `ConfigException.Missing` - if value is absent or null
  `ConfigException.WrongType` - if value is not convertible to a ConfigList

#### getBooleanList

    List<Boolean> getBooleanList(String path)

#### getNumberList

    List<Number> getNumberList(String path)

#### getIntList

    List<Integer> getIntList(String path)

#### getLongList

    List<Long> getLongList(String path)

#### getDoubleList

    List<Double> getDoubleList(String path)

#### getStringList

    List<String> getStringList(String path)

#### getObjectList

    List<? extends ConfigObject> getObjectList(String path)

#### getConfigList

    List<? extends Config> getConfigList(String path)

#### getAnyRefList

    List<? extends Object> getAnyRefList(String path)

#### getBytesList

    List<Long> getBytesList(String path)

#### getMillisecondsList

    List<Long> getMillisecondsList(String path)

#### getNanosecondsList

    List<Long> getNanosecondsList(String path)