    001/**
    002 *   Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com>
    003 */
    004package com.typesafe.config;
    005
    006import java.time.Duration;
    007import java.time.Period;
    008import java.time.temporal.TemporalAmount;
    009import java.util.List;
    010import java.util.Map;
    011import java.util.Set;
    012import java.util.concurrent.TimeUnit;
    013
    014/**
    015 * An immutable map from config paths to config values. Paths are dot-separated
    016 * expressions such as <code>foo.bar.baz</code>. Values are as in JSON
    017 * (booleans, strings, numbers, lists, or objects), represented by
    018 * {@link ConfigValue} instances. Values accessed through the
    019 * <code>Config</code> interface are never null.
    020 *
    021 * <p>
    022 * {@code Config} is an immutable object and thus safe to use from multiple
    023 * threads. There's never a need for "defensive copies."
    024 *
    025 * <p>
    026 * Fundamental operations on a {@code Config} include getting configuration
    027 * values, <em>resolving</em> substitutions with {@link Config#resolve()}, and
    028 * merging configs using {@link Config#withFallback(ConfigMergeable)}.
    029 *
    030 * <p>
    031 * All operations return a new immutable {@code Config} rather than modifying
    032 * the original instance.
    033 *
    034 * <p>
    035 * <strong>Examples</strong>
    036 *
    037 * <p>
    038 * You can find an example app and library <a
    039 * href="https://github.com/lightbend/config/tree/master/examples">on
    040 * GitHub</a>. Also be sure to read the <a
    041 * href="package-summary.html#package_description">package overview</a> which
    042 * describes the big picture as shown in those examples.
    043 *
    044 * <p>
    045 * <strong>Paths, keys, and Config vs. ConfigObject</strong>
    046 *
    047 * <p>
    048 * <code>Config</code> is a view onto a tree of {@link ConfigObject}; the
    049 * corresponding object tree can be found through {@link Config#root()}.
    050 * <code>ConfigObject</code> is a map from config <em>keys</em>, rather than
    051 * paths, to config values. Think of <code>ConfigObject</code> as a JSON object
    052 * and <code>Config</code> as a configuration API.
    053 *
    054 * <p>
    055 * The API tries to consistently use the terms "key" and "path." A key is a key
    056 * in a JSON object; it's just a string that's the key in a map. A "path" is a
    057 * parseable expression with a syntax and it refers to a series of keys. Path
    058 * expressions are described in the <a
    059 * href="https://github.com/lightbend/config/blob/master/HOCON.md">spec for
    060 * Human-Optimized Config Object Notation</a>. In brief, a path is
    061 * period-separated so "a.b.c" looks for key c in object b in object a in the
    062 * root object. Sometimes double quotes are needed around special characters in
    063 * path expressions.
    064 *
    065 * <p>
    066 * The API for a {@code Config} is in terms of path expressions, while the API
    067 * for a {@code ConfigObject} is in terms of keys. Conceptually, {@code Config}
    068 * is a one-level map from <em>paths</em> to values, while a
    069 * {@code ConfigObject} is a tree of nested maps from <em>keys</em> to values.
    070 *
    071 * <p>
    072 * Use {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath} to convert
    073 * between path expressions and individual path elements (keys).
    074 *
    075 * <p>
    076 * Another difference between {@code Config} and {@code ConfigObject} is that
    077 * conceptually, {@code ConfigValue}s with a {@link ConfigValue#valueType()
    078 * valueType()} of {@link ConfigValueType#NULL NULL} exist in a
    079 * {@code ConfigObject}, while a {@code Config} treats null values as if they
    080 * were missing. (With the exception of two methods: {@link Config#hasPathOrNull}
    081 * and {@link Config#getIsNull} let you detect <code>null</code> values.)
    082 *
    083 * <p>
    084 * <strong>Getting configuration values</strong>
    085 *
    086 * <p>
    087 * The "getters" on a {@code Config} all work in the same way. They never return
    088 * null, nor do they return a {@code ConfigValue} with
    089 * {@link ConfigValue#valueType() valueType()} of {@link ConfigValueType#NULL
    090 * NULL}. Instead, they throw {@link ConfigException.Missing} if the value is
    091 * completely absent or set to null. If the value is set to null, a subtype of
    092 * {@code ConfigException.Missing} called {@link ConfigException.Null} will be
    093 * thrown. {@link ConfigException.WrongType} will be thrown anytime you ask for
    094 * a type and the value has an incompatible type. Reasonable type conversions
    095 * are performed for you though.
    096 *
    097 * <p>
    098 * <strong>Iteration</strong>
    099 *
    100 * <p>
    101 * If you want to iterate over the contents of a {@code Config}, you can get its
    102 * {@code ConfigObject} with {@link #root()}, and then iterate over the
    103 * {@code ConfigObject} (which implements <code>java.util.Map</code>). Or, you
    104 * can use {@link #entrySet()} which recurses the object tree for you and builds
    105 * up a <code>Set</code> of all path-value pairs where the value is not null.
    106 *
    107 * <p>
    108 * <strong>Resolving substitutions</strong>
    109 *
    110 * <p>
    111 * <em>Substitutions</em> are the <code>${foo.bar}</code> syntax in config
    112 * files, described in the <a href=
    113 * "https://github.com/lightbend/config/blob/master/HOCON.md#substitutions"
    114 * >specification</a>. Resolving substitutions replaces these references with real
    115 * values.
    116 *
    117 * <p>
    118 * Before using a {@code Config} it's necessary to call {@link Config#resolve()}
    119 * to handle substitutions (though {@link ConfigFactory#load()} and similar
    120 * methods will do the resolve for you already).
    121 *
    122 * <p>
    123 * <strong>Merging</strong>
    124 *
    125 * <p>
    126 * The full <code>Config</code> for your application can be constructed using
    127 * the associative operation {@link Config#withFallback(ConfigMergeable)}. If
    128 * you use {@link ConfigFactory#load()} (recommended), it merges system
    129 * properties over the top of <code>application.conf</code> over the top of
    130 * <code>reference.conf</code>, using <code>withFallback</code>. You can add in
    131 * additional sources of configuration in the same way (usually, custom layers
    132 * should go either just above or just below <code>application.conf</code>,
    133 * keeping <code>reference.conf</code> at the bottom and system properties at
    134 * the top).
    135 *
    136 * <p>
    137 * <strong>Serialization</strong>
    138 *
    139 * <p>
    140 * Convert a <code>Config</code> to a JSON or HOCON string by calling
    141 * {@link ConfigObject#render()} on the root object,
    142 * <code>myConfig.root().render()</code>. There's also a variant
    143 * {@link ConfigObject#render(ConfigRenderOptions)} which allows you to control
    144 * the format of the rendered string. (See {@link ConfigRenderOptions}.) Note
    145 * that <code>Config</code> does not remember the formatting of the original
    146 * file, so if you load, modify, and re-save a config file, it will be
    147 * substantially reformatted.
    148 *
    149 * <p>
    150 * As an alternative to {@link ConfigObject#render()}, the
    151 * <code>toString()</code> method produces a debug-output-oriented
    152 * representation (which is not valid JSON).
    153 *
    154 * <p>
    155 * Java serialization is supported as well for <code>Config</code> and all
    156 * subtypes of <code>ConfigValue</code>.
    157 *
    158 * <p>
    159 * <strong>This is an interface but don't implement it yourself</strong>
    160 *
    161 * <p>
    162 * <em>Do not implement {@code Config}</em>; it should only be implemented by
    163 * the config library. Arbitrary implementations will not work because the
    164 * library internals assume a specific concrete implementation. Also, this
    165 * interface is likely to grow new methods over time, so third-party
    166 * implementations will break.
    167 */
    168public interface Config extends ConfigMergeable {
    169    /**
    170     * Gets the {@code Config} as a tree of {@link ConfigObject}. This is a
    171     * constant-time operation (it is not proportional to the number of values
    172     * in the {@code Config}).
    173     *
    174     * @return the root object in the configuration
    175     */
    176    ConfigObject root();
    177
    178    /**
    179     * Gets the origin of the {@code Config}, which may be a file, or a file
    180     * with a line number, or just a descriptive phrase.
    181     *
    182     * @return the origin of the {@code Config} for use in error messages
    183     */
    184    ConfigOrigin origin();
    185
    186    @Override
    187    Config withFallback(ConfigMergeable other);
    188
    189    /**
    190     * Returns a replacement config with all substitutions (the
    191     * <code>${foo.bar}</code> syntax, see <a
    192     * href="https://github.com/lightbend/config/blob/master/HOCON.md">the
    193     * spec</a>) resolved. Substitutions are looked up using this
    194     * <code>Config</code> as the root object, that is, a substitution
    195     * <code>${foo.bar}</code> will be replaced with the result of
    196     * <code>getValue("foo.bar")</code>.
    197     *
    198     * <p>
    199     * This method uses {@link ConfigResolveOptions#defaults()}, there is
    200     * another variant {@link Config#resolve(ConfigResolveOptions)} which lets
    201     * you specify non-default options.
    202     *
    203     * <p>
    204     * A given {@link Config} must be resolved before using it to retrieve
    205     * config values, but ideally should be resolved one time for your entire
    206     * stack of fallbacks (see {@link Config#withFallback}). Otherwise, some
    207     * substitutions that could have resolved with all fallbacks available may
    208     * not resolve, which will be potentially confusing for your application's
    209     * users.
    210     *
    211     * <p>
    212     * <code>resolve()</code> should be invoked on root config objects, rather
    213     * than on a subtree (a subtree is the result of something like
    214     * <code>config.getConfig("foo")</code>). The problem with
    215     * <code>resolve()</code> on a subtree is that substitutions are relative to
    216     * the root of the config and the subtree will have no way to get values
    217     * from the root. For example, if you did
    218     * <code>config.getConfig("foo").resolve()</code> on the below config file,
    219     * it would not work:
    220     *
    221     * <pre>
    222     *   common-value = 10
    223     *   foo {
    224     *      whatever = ${common-value}
    225     *   }
    226     * </pre>
    227     *
    228     * <p>
    229     * Many methods on {@link ConfigFactory} such as
    230     * {@link ConfigFactory#load()} automatically resolve the loaded
    231     * <code>Config</code> on the loaded stack of config files.
    232     *
    233     * <p>
    234     * Resolving an already-resolved config is a harmless no-op, but again, it
    235     * is best to resolve an entire stack of fallbacks (such as all your config
    236     * files combined) rather than resolving each one individually.
    237     *
    238     * @return an immutable object with substitutions resolved
    239     * @throws ConfigException.UnresolvedSubstitution
    240     *             if any substitutions refer to nonexistent paths
    241     * @throws ConfigException
    242     *             some other config exception if there are other problems
    243     */
    244    Config resolve();
    245
    246    /**
    247     * Like {@link Config#resolve()} but allows you to specify non-default
    248     * options.
    249     *
    250     * @param options
    251     *            resolve options
    252     * @return the resolved <code>Config</code> (may be only partially resolved if options are set to allow unresolved)
    253     */
    254    Config resolve(ConfigResolveOptions options);
    255
    256    /**
    257     * Checks whether the config is completely resolved. After a successful call
    258     * to {@link Config#resolve()} it will be completely resolved, but after
    259     * calling {@link Config#resolve(ConfigResolveOptions)} with
    260     * <code>allowUnresolved</code> set in the options, it may or may not be
    261     * completely resolved. A newly-loaded config may or may not be completely
    262     * resolved depending on whether there were substitutions present in the
    263     * file.
    264     *
    265     * @return true if there are no unresolved substitutions remaining in this
    266     *         configuration.
    267     * @since 1.2.0
    268     */
    269    boolean isResolved();
    270
    271    /**
    272     * Like {@link Config#resolve()} except that substitution values are looked
    273     * up in the given source, rather than in this instance. This is a
    274     * special-purpose method which doesn't make sense to use in most cases;
    275     * it's only needed if you're constructing some sort of app-specific custom
    276     * approach to configuration. The more usual approach if you have a source
    277     * of substitution values would be to merge that source into your config
    278     * stack using {@link Config#withFallback} and then resolve.
    279     * <p>
    280     * Note that this method does NOT look in this instance for substitution
    281     * values. If you want to do that, you could either merge this instance into
    282     * your value source using {@link Config#withFallback}, or you could resolve
    283     * multiple times with multiple sources (using
    284     * {@link ConfigResolveOptions#setAllowUnresolved(boolean)} so the partial
    285     * resolves don't fail).
    286     *
    287     * @param source
    288     *            configuration to pull values from
    289     * @return an immutable object with substitutions resolved
    290     * @throws ConfigException.UnresolvedSubstitution
    291     *             if any substitutions refer to paths which are not in the
    292     *             source
    293     * @throws ConfigException
    294     *             some other config exception if there are other problems
    295     * @since 1.2.0
    296     */
    297    Config resolveWith(Config source);
    298
    299    /**
    300     * Like {@link Config#resolveWith(Config)} but allows you to specify
    301     * non-default options.
    302     *
    303     * @param source
    304     *            source configuration to pull values from
    305     * @param options
    306     *            resolve options
    307     * @return the resolved <code>Config</code> (may be only partially resolved
    308     *         if options are set to allow unresolved)
    309     * @since 1.2.0
    310     */
    311    Config resolveWith(Config source, ConfigResolveOptions options);
    312
    313    /**
    314     * Validates this config against a reference config, throwing an exception
    315     * if it is invalid. The purpose of this method is to "fail early" with a
    316     * comprehensive list of problems; in general, anything this method can find
    317     * would be detected later when trying to use the config, but it's often
    318     * more user-friendly to fail right away when loading the config.
    319     *
    320     * <p>
    321     * Using this method is always optional, since you can "fail late" instead.
    322     *
    323     * <p>
    324     * You must restrict validation to paths you "own" (those whose meaning are
    325     * defined by your code module). If you validate globally, you may trigger
    326     * errors about paths that happen to be in the config but have nothing to do
    327     * with your module. It's best to allow the modules owning those paths to
    328     * validate them. Also, if every module validates only its own stuff, there
    329     * isn't as much redundant work being done.
    330     *
    331     * <p>
    332     * If no paths are specified in <code>checkValid()</code>'s parameter list,
    333     * validation is for the entire config.
    334     *
    335     * <p>
    336     * If you specify paths that are not in the reference config, those paths
    337     * are ignored. (There's nothing to validate.)
    338     *
    339     * <p>
    340     * Here's what validation involves:
    341     *
    342     * <ul>
    343     * <li>All paths found in the reference config must be present in this
    344     * config or an exception will be thrown.
    345     * <li>
    346     * Some changes in type from the reference config to this config will cause
    347     * an exception to be thrown. Not all potential type problems are detected,
    348     * in particular it's assumed that strings are compatible with everything
    349     * except objects and lists. This is because string types are often "really"
    350     * some other type (system properties always start out as strings, or a
    351     * string like "5ms" could be used with {@link #getMilliseconds}). Also,
    352     * it's allowed to set any type to null or override null with any type.
    353     * <li>
    354     * Any unresolved substitutions in this config will cause a validation
    355     * failure; both the reference config and this config should be resolved
    356     * before validation. If the reference config is unresolved, it's a bug in
    357     * the caller of this method.
    358     * </ul>
    359     *
    360     * <p>
    361     * If you want to allow a certain setting to have a flexible type (or
    362     * otherwise want validation to be looser for some settings), you could
    363     * either remove the problematic setting from the reference config provided
    364     * to this method, or you could intercept the validation exception and
    365     * screen out certain problems. Of course, this will only work if all other
    366     * callers of this method are careful to restrict validation to their own
    367     * paths, as they should be.
    368     *
    369     * <p>
    370     * If validation fails, the thrown exception contains a list of all problems
    371     * found. See {@link ConfigException.ValidationFailed#problems}. The
    372     * exception's <code>getMessage()</code> will have all the problems
    373     * concatenated into one huge string, as well.
    374     *
    375     * <p>
    376     * Again, <code>checkValid()</code> can't guess every domain-specific way a
    377     * setting can be invalid, so some problems may arise later when attempting
    378     * to use the config. <code>checkValid()</code> is limited to reporting
    379     * generic, but common, problems such as missing settings and blatant type
    380     * incompatibilities.
    381     *
    382     * @param reference
    383     *            a reference configuration
    384     * @param restrictToPaths
    385     *            only validate values underneath these paths that your code
    386     *            module owns and understands
    387     * @throws ConfigException.ValidationFailed
    388     *             if there are any validation issues
    389     * @throws ConfigException.NotResolved
    390     *             if this config is not resolved
    391     * @throws ConfigException.BugOrBroken
    392     *             if the reference config is unresolved or caller otherwise
    393     *             misuses the API
    394     */
    395    void checkValid(Config reference, String... restrictToPaths);
    396
    397    /**
    398     * Checks whether a value is present and non-null at the given path. This
    399     * differs in two ways from {@code Map.containsKey()} as implemented by
    400     * {@link ConfigObject}: it looks for a path expression, not a key; and it
    401     * returns false for null values, while {@code containsKey()} returns true
    402     * indicating that the object contains a null value for the key.
    403     *
    404     * <p>
    405     * If a path exists according to {@link #hasPath(String)}, then
    406     * {@link #getValue(String)} will never throw an exception. However, the
    407     * typed getters, such as {@link #getInt(String)}, will still throw if the
    408     * value is not convertible to the requested type.
    409     *
    410     * <p>
    411     * Note that path expressions have a syntax and sometimes require quoting
    412     * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}).
    413     *
    414     * @param path
    415     *            the path expression
    416     * @return true if a non-null value is present at the path
    417     * @throws ConfigException.BadPath
    418     *             if the path expression is invalid
    419     */
    420    boolean hasPath(String path);
    421
    422    /**
    423     * Checks whether a value is present at the given path, even
    424     * if the value is null. Most of the getters on
    425     * <code>Config</code> will throw if you try to get a null
    426     * value, so if you plan to call {@link #getValue(String)},
    427     * {@link #getInt(String)}, or another getter you may want to
    428     * use plain {@link #hasPath(String)} rather than this method.
    429     *
    430     * <p>
    431     * To handle all three cases (unset, null, and a non-null value)
    432     * the code might look like:
    433     * <pre><code>
    434     * if (config.hasPathOrNull(path)) {
    435     *     if (config.getIsNull(path)) {
    436     *        // handle null setting
    437     *     } else {
    438     *        // get and use non-null setting
    439     *     }
    440     * } else {
    441     *     // handle entirely unset path
    442     * }
    443     * </code></pre>
    444     *
    445     * <p> However, the usual thing is to allow entirely unset
    446     * paths to be a bug that throws an exception (because you set
    447     * a default in your <code>reference.conf</code>), so in that
    448     * case it's OK to call {@link #getIsNull(String)} without
    449     * checking <code>hasPathOrNull</code> first.
    450     *
    451     * <p>
    452     * Note that path expressions have a syntax and sometimes require quoting
    453     * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}).
    454     *
    455     * @param path
    456     *            the path expression
    457     * @return true if a value is present at the path, even if the value is null
    458     * @throws ConfigException.BadPath
    459     *             if the path expression is invalid
    460     */
    461    boolean hasPathOrNull(String path);
    462
    463    /**
    464     * Returns true if the {@code Config}'s root object contains no key-value
    465     * pairs.
    466     *
    467     * @return true if the configuration is empty
    468     */
    469    boolean isEmpty();
    470
    471    /**
    472     * Returns the set of path-value pairs, excluding any null values, found by
    473     * recursing {@link #root() the root object}. Note that this is very
    474     * different from <code>root().entrySet()</code> which returns the set of
    475     * immediate-child keys in the root object and includes null values.
    476     * <p>
    477     * Entries contain <em>path expressions</em> meaning there may be quoting
    478     * and escaping involved. Parse path expressions with
    479     * {@link ConfigUtil#splitPath}.
    480     * <p>
    481     * Because a <code>Config</code> is conceptually a single-level map from
    482     * paths to values, there will not be any {@link ConfigObject} values in the
    483     * entries (that is, all entries represent leaf nodes). Use
    484     * {@link ConfigObject} rather than <code>Config</code> if you want a tree.
    485     * (OK, this is a slight lie: <code>Config</code> entries may contain
    486     * {@link ConfigList} and the lists may contain objects. But no objects are
    487     * directly included as entry values.)
    488     *
    489     * @return set of paths with non-null values, built up by recursing the
    490     *         entire tree of {@link ConfigObject} and creating an entry for
    491     *         each leaf value.
    492     */
    493    Set<Map.Entry<String, ConfigValue>> entrySet();
    494
    495    /**
    496     * Checks whether a value is set to null at the given path,
    497     * but throws an exception if the value is entirely
    498     * unset. This method will not throw if {@link
    499     * #hasPathOrNull(String)} returned true for the same path, so
    500     * to avoid any possible exception check
    501     * <code>hasPathOrNull()</code> first.  However, an exception
    502     * for unset paths will usually be the right thing (because a
    503     * <code>reference.conf</code> should exist that has the path
    504     * set, the path should never be unset unless something is
    505     * broken).
    506     *
    507     * <p>
    508     * Note that path expressions have a syntax and sometimes require quoting
    509     * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}).
    510     *
    511     * @param path
    512     *            the path expression
    513     * @return true if the value exists and is null, false if it
    514     * exists and is not null
    515     * @throws ConfigException.BadPath
    516     *             if the path expression is invalid
    517     * @throws ConfigException.Missing
    518     *             if value is not set at all
    519     */
    520    boolean getIsNull(String path);
    521
    522    /**
    523     *
    524     * @param path
    525     *            path expression
    526     * @return the boolean value at the requested path
    527     * @throws ConfigException.Missing
    528     *             if value is absent or null
    529     * @throws ConfigException.WrongType
    530     *             if value is not convertible to boolean
    531     */
    532    boolean getBoolean(String path);
    533
    534    /**
    535     * @param path
    536     *            path expression
    537     * @return the numeric value at the requested path
    538     * @throws ConfigException.Missing
    539     *             if value is absent or null
    540     * @throws ConfigException.WrongType
    541     *             if value is not convertible to a number
    542     */
    543    Number getNumber(String path);
    544
    545    /**
    546     * Gets the integer at the given path. If the value at the
    547     * path has a fractional (floating point) component, it
    548     * will be discarded and only the integer part will be
    549     * returned (it works like a "narrowing primitive conversion"
    550     * in the Java language specification).
    551     *
    552     * @param path
    553     *            path expression
    554     * @return the 32-bit integer value at the requested path
    555     * @throws ConfigException.Missing
    556     *             if value is absent or null
    557     * @throws ConfigException.WrongType
    558     *             if value is not convertible to an int (for example it is out
    559     *             of range, or it's a boolean value)
    560     */
    561    int getInt(String path);
    562
    563    /**
    564     * Gets the long integer at the given path.  If the value at
    565     * the path has a fractional (floating point) component, it
    566     * will be discarded and only the integer part will be
    567     * returned (it works like a "narrowing primitive conversion"
    568     * in the Java language specification).
    569     *
    570     * @param path
    571     *            path expression
    572     * @return the 64-bit long value at the requested path
    573     * @throws ConfigException.Missing
    574     *             if value is absent or null
    575     * @throws ConfigException.WrongType
    576     *             if value is not convertible to a long
    577     */
    578    long getLong(String path);
    579
    580    /**
    581     * @param path
    582     *            path expression
    583     * @return the floating-point value at the requested path
    584     * @throws ConfigException.Missing
    585     *             if value is absent or null
    586     * @throws ConfigException.WrongType
    587     *             if value is not convertible to a double
    588     */
    589    double getDouble(String path);
    590
    591    /**
    592     * @param path
    593     *            path expression
    594     * @return the string value at the requested path
    595     * @throws ConfigException.Missing
    596     *             if value is absent or null
    597     * @throws ConfigException.WrongType
    598     *             if value is not convertible to a string
    599     */
    600    String getString(String path);
    601
    602    /**
    603     * @param enumClass
    604     *            an enum class
    605     * @param <T>
    606     *            a generic denoting a specific type of enum
    607     * @param path
    608     *            path expression
    609     * @return the {@code Enum} value at the requested path
    610     *              of the requested enum class
    611     * @throws ConfigException.Missing
    612     *             if value is absent or null
    613     * @throws ConfigException.WrongType
    614     *             if value is not convertible to an Enum
    615     */
    616    public <T extends Enum<T>> T getEnum(Class<T> enumClass, String path);
    617
    618    /**
    619     * @param path
    620     *            path expression
    621     * @return the {@link ConfigObject} value at the requested path
    622     * @throws ConfigException.Missing
    623     *             if value is absent or null
    624     * @throws ConfigException.WrongType
    625     *             if value is not convertible to an object
    626     */
    627    ConfigObject getObject(String path);
    628
    629    /**
    630     * @param path
    631     *            path expression
    632     * @return the nested {@code Config} value at the requested path
    633     * @throws ConfigException.Missing
    634     *             if value is absent or null
    635     * @throws ConfigException.WrongType
    636     *             if value is not convertible to a Config
    637     */
    638    Config getConfig(String path);
    639
    640    /**
    641     * Gets the value at the path as an unwrapped Java boxed value (
    642     * {@link java.lang.Boolean Boolean}, {@link java.lang.Integer Integer}, and
    643     * so on - see {@link ConfigValue#unwrapped()}).
    644     *
    645     * @param path
    646     *            path expression
    647     * @return the unwrapped value at the requested path
    648     * @throws ConfigException.Missing
    649     *             if value is absent or null
    650     */
    651    Object getAnyRef(String path);
    652
    653    /**
    654     * Gets the value at the given path, unless the value is a
    655     * null value or missing, in which case it throws just like
    656     * the other getters. Use {@code get()} on the {@link
    657     * Config#root()} object (or other object in the tree) if you
    658     * want an unprocessed value.
    659     *
    660     * @param path
    661     *            path expression
    662     * @return the value at the requested path
    663     * @throws ConfigException.Missing
    664     *             if value is absent or null
    665     */
    666    ConfigValue getValue(String path);
    667
    668    /**
    669     * Gets a value as a size in bytes (parses special strings like "128M"). If
    670     * the value is already a number, then it's left alone; if it's a string,
    671     * it's parsed understanding unit suffixes such as "128K", as documented in
    672     * the <a
    673     * href="https://github.com/lightbend/config/blob/master/HOCON.md">the
    674     * spec</a>.
    675     *
    676     * @param path
    677     *            path expression
    678     * @return the value at the requested path, in bytes
    679     * @throws ConfigException.Missing
    680     *             if value is absent or null
    681     * @throws ConfigException.WrongType
    682     *             if value is not convertible to Long or String
    683     * @throws ConfigException.BadValue
    684     *             if value cannot be parsed as a size in bytes
    685     */
    686    Long getBytes(String path);
    687
    688    /**
    689     * Gets a value as an amount of memory (parses special strings like "128M"). If
    690     * the value is already a number, then it's left alone; if it's a string,
    691     * it's parsed understanding unit suffixes such as "128K", as documented in
    692     * the <a
    693     * href="https://github.com/lightbend/config/blob/master/HOCON.md">the
    694     * spec</a>.
    695     *
    696     * @since 1.3.0
    697     *
    698     * @param path
    699     *            path expression
    700     * @return the value at the requested path, in bytes
    701     * @throws ConfigException.Missing
    702     *             if value is absent or null
    703     * @throws ConfigException.WrongType
    704     *             if value is not convertible to Long or String
    705     * @throws ConfigException.BadValue
    706     *             if value cannot be parsed as a size in bytes
    707     */
    708    ConfigMemorySize getMemorySize(String path);
    709
    710    /**
    711     * Get value as a duration in milliseconds. If the value is already a
    712     * number, then it's left alone; if it's a string, it's parsed understanding
    713     * units suffixes like "10m" or "5ns" as documented in the <a
    714     * href="https://github.com/lightbend/config/blob/master/HOCON.md">the
    715     * spec</a>.
    716     *
    717     * @deprecated  As of release 1.1, replaced by {@link #getDuration(String, TimeUnit)}
    718     *
    719     * @param path
    720     *            path expression
    721     * @return the duration value at the requested path, in milliseconds
    722     * @throws ConfigException.Missing
    723     *             if value is absent or null
    724     * @throws ConfigException.WrongType
    725     *             if value is not convertible to Long or String
    726     * @throws ConfigException.BadValue
    727     *             if value cannot be parsed as a number of milliseconds
    728     */
    729    @Deprecated Long getMilliseconds(String path);
    730
    731    /**
    732     * Get value as a duration in nanoseconds. If the value is already a number
    733     * it's taken as milliseconds and converted to nanoseconds. If it's a
    734     * string, it's parsed understanding unit suffixes, as for
    735     * {@link #getDuration(String, TimeUnit)}.
    736     *
    737     * @deprecated  As of release 1.1, replaced by {@link #getDuration(String, TimeUnit)}
    738     *
    739     * @param path
    740     *            path expression
    741     * @return the duration value at the requested path, in nanoseconds
    742     * @throws ConfigException.Missing
    743     *             if value is absent or null
    744     * @throws ConfigException.WrongType
    745     *             if value is not convertible to Long or String
    746     * @throws ConfigException.BadValue
    747     *             if value cannot be parsed as a number of nanoseconds
    748     */
    749    @Deprecated Long getNanoseconds(String path);
    750
    751    /**
    752     * Gets a value as a duration in a specified
    753     * {@link java.util.concurrent.TimeUnit TimeUnit}. If the value is already a
    754     * number, then it's taken as milliseconds and then converted to the
    755     * requested TimeUnit; if it's a string, it's parsed understanding units
    756     * suffixes like "10m" or "5ns" as documented in the <a
    757     * href="https://github.com/lightbend/config/blob/master/HOCON.md">the
    758     * spec</a>.
    759     *
    760     * @since 1.2.0
    761     *
    762     * @param path
    763     *            path expression
    764     * @param unit
    765     *            convert the return value to this time unit
    766     * @return the duration value at the requested path, in the given TimeUnit
    767     * @throws ConfigException.Missing
    768     *             if value is absent or null
    769     * @throws ConfigException.WrongType
    770     *             if value is not convertible to Long or String
    771     * @throws ConfigException.BadValue
    772     *             if value cannot be parsed as a number of the given TimeUnit
    773     */
    774    long getDuration(String path, TimeUnit unit);
    775
    776    /**
    777     * Gets a value as a java.time.Duration. If the value is
    778     * already a number, then it's taken as milliseconds; if it's
    779     * a string, it's parsed understanding units suffixes like
    780     * "10m" or "5ns" as documented in the <a
    781     * href="https://github.com/lightbend/config/blob/master/HOCON.md">the
    782     * spec</a>. This method never returns null.
    783     *
    784     * @since 1.3.0
    785     *
    786     * @param path
    787     *            path expression
    788     * @return the duration value at the requested path
    789     * @throws ConfigException.Missing
    790     *             if value is absent or null
    791     * @throws ConfigException.WrongType
    792     *             if value is not convertible to Long or String
    793     * @throws ConfigException.BadValue
    794     *             if value cannot be parsed as a number of the given TimeUnit
    795     */
    796    Duration getDuration(String path);
    797
    798    /**
    799     * Gets a value as a java.time.Period. If the value is
    800     * already a number, then it's taken as days; if it's
    801     * a string, it's parsed understanding units suffixes like
    802     * "10d" or "5w" as documented in the <a
    803     * href="https://github.com/lightbend/config/blob/master/HOCON.md">the
    804     * spec</a>. This method never returns null.
    805     *
    806     * @since 1.3.0
    807     *
    808     * @param path
    809     *            path expression
    810     * @return the period value at the requested path
    811     * @throws ConfigException.Missing
    812     *             if value is absent or null
    813     * @throws ConfigException.WrongType
    814     *             if value is not convertible to Long or String
    815     * @throws ConfigException.BadValue
    816     *             if value cannot be parsed as a number of the given TimeUnit
    817     */
    818    Period getPeriod(String path);
    819
    820    /**
    821     * Gets a value as a java.time.temporal.TemporalAmount.
    822     * This method will first try get get the value as a java.time.Duration, and if unsuccessful,
    823     * then as a java.time.Period.
    824     * This means that values like "5m" will be parsed as 5 minutes rather than 5 months
    825     * @param path path expression
    826     * @return the temporal value at the requested path
    827     * @throws ConfigException.Missing
    828     *             if value is absent or null
    829     * @throws ConfigException.WrongType
    830     *             if value is not convertible to Long or String
    831     * @throws ConfigException.BadValue
    832     *             if value cannot be parsed as a TemporalAmount
    833     */
    834    TemporalAmount getTemporal(String path);
    835
    836    /**
    837     * Gets a list value (with any element type) as a {@link ConfigList}, which
    838     * implements {@code java.util.List<ConfigValue>}. Throws if the path is
    839     * unset or null.
    840     *
    841     * @param path
    842     *            the path to the list value.
    843     * @return the {@link ConfigList} at the path
    844     * @throws ConfigException.Missing
    845     *             if value is absent or null
    846     * @throws ConfigException.WrongType
    847     *             if value is not convertible to a ConfigList
    848     */
    849    ConfigList getList(String path);
    850
    851    /**
    852     * Gets a list value with boolean elements.  Throws if the
    853     * path is unset or null or not a list or contains values not
    854     * convertible to boolean.
    855     *
    856     * @param path
    857     *            the path to the list value.
    858     * @return the list at the path
    859     * @throws ConfigException.Missing
    860     *             if value is absent or null
    861     * @throws ConfigException.WrongType
    862     *             if value is not convertible to a list of booleans
    863     */
    864    List<Boolean> getBooleanList(String path);
    865
    866    /**
    867     * Gets a list value with number elements.  Throws if the
    868     * path is unset or null or not a list or contains values not
    869     * convertible to number.
    870     *
    871     * @param path
    872     *            the path to the list value.
    873     * @return the list at the path
    874     * @throws ConfigException.Missing
    875     *             if value is absent or null
    876     * @throws ConfigException.WrongType
    877     *             if value is not convertible to a list of numbers
    878     */
    879    List<Number> getNumberList(String path);
    880
    881    /**
    882     * Gets a list value with int elements.  Throws if the
    883     * path is unset or null or not a list or contains values not
    884     * convertible to int.
    885     *
    886     * @param path
    887     *            the path to the list value.
    888     * @return the list at the path
    889     * @throws ConfigException.Missing
    890     *             if value is absent or null
    891     * @throws ConfigException.WrongType
    892     *             if value is not convertible to a list of ints
    893     */
    894    List<Integer> getIntList(String path);
    895
    896    /**
    897     * Gets a list value with long elements.  Throws if the
    898     * path is unset or null or not a list or contains values not
    899     * convertible to long.
    900     *
    901     * @param path
    902     *            the path to the list value.
    903     * @return the list at the path
    904     * @throws ConfigException.Missing
    905     *             if value is absent or null
    906     * @throws ConfigException.WrongType
    907     *             if value is not convertible to a list of longs
    908     */
    909    List<Long> getLongList(String path);
    910
    911    /**
    912     * Gets a list value with double elements.  Throws if the
    913     * path is unset or null or not a list or contains values not
    914     * convertible to double.
    915     *
    916     * @param path
    917     *            the path to the list value.
    918     * @return the list at the path
    919     * @throws ConfigException.Missing
    920     *             if value is absent or null
    921     * @throws ConfigException.WrongType
    922     *             if value is not convertible to a list of doubles
    923     */
    924    List<Double> getDoubleList(String path);
    925
    926    /**
    927     * Gets a list value with string elements.  Throws if the
    928     * path is unset or null or not a list or contains values not
    929     * convertible to string.
    930     *
    931     * @param path
    932     *            the path to the list value.
    933     * @return the list at the path
    934     * @throws ConfigException.Missing
    935     *             if value is absent or null
    936     * @throws ConfigException.WrongType
    937     *             if value is not convertible to a list of strings
    938     */
    939    List<String> getStringList(String path);
    940
    941    /**
    942     * Gets a list value with {@code Enum} elements.  Throws if the
    943     * path is unset or null or not a list or contains values not
    944     * convertible to {@code Enum}.
    945     *
    946     * @param enumClass
    947     *            the enum class
    948     * @param <T>
    949     *            a generic denoting a specific type of enum
    950     * @param path
    951     *            the path to the list value.
    952     * @return the list at the path
    953     * @throws ConfigException.Missing
    954     *             if value is absent or null
    955     * @throws ConfigException.WrongType
    956     *             if value is not convertible to a list of {@code Enum}
    957     */
    958    <T extends Enum<T>> List<T> getEnumList(Class<T> enumClass, String path);
    959
    960    /**
    961     * Gets a list value with object elements.  Throws if the
    962     * path is unset or null or not a list or contains values not
    963     * convertible to <code>ConfigObject</code>.
    964     *
    965     * @param path
    966     *            the path to the list value.
    967     * @return the list at the path
    968     * @throws ConfigException.Missing
    969     *             if value is absent or null
    970     * @throws ConfigException.WrongType
    971     *             if value is not convertible to a list of objects
    972     */
    973    List<? extends ConfigObject> getObjectList(String path);
    974
    975    /**
    976     * Gets a list value with <code>Config</code> elements.
    977     * Throws if the path is unset or null or not a list or
    978     * contains values not convertible to <code>Config</code>.
    979     *
    980     * @param path
    981     *            the path to the list value.
    982     * @return the list at the path
    983     * @throws ConfigException.Missing
    984     *             if value is absent or null
    985     * @throws ConfigException.WrongType
    986     *             if value is not convertible to a list of configs
    987     */
    988    List<? extends Config> getConfigList(String path);
    989
    990    /**
    991     * Gets a list value with any kind of elements.  Throws if the
    992     * path is unset or null or not a list. Each element is
    993     * "unwrapped" (see {@link ConfigValue#unwrapped()}).
    994     *
    995     * @param path
    996     *            the path to the list value.
    997     * @return the list at the path
    998     * @throws ConfigException.Missing
    999     *             if value is absent or null
    1000     * @throws ConfigException.WrongType
    1001     *             if value is not convertible to a list
    1002     */
    1003    List<? extends Object> getAnyRefList(String path);
    1004
    1005    /**
    1006     * Gets a list value with elements representing a size in
    1007     * bytes.  Throws if the path is unset or null or not a list
    1008     * or contains values not convertible to memory sizes.
    1009     *
    1010     * @param path
    1011     *            the path to the list value.
    1012     * @return the list at the path
    1013     * @throws ConfigException.Missing
    1014     *             if value is absent or null
    1015     * @throws ConfigException.WrongType
    1016     *             if value is not convertible to a list of memory sizes
    1017     */
    1018    List<Long> getBytesList(String path);
    1019
    1020    /**
    1021     * Gets a list, converting each value in the list to a memory size, using the
    1022     * same rules as {@link #getMemorySize(String)}.
    1023     *
    1024     * @since 1.3.0
    1025     * @param path
    1026     *            a path expression
    1027     * @return list of memory sizes
    1028     * @throws ConfigException.Missing
    1029     *             if value is absent or null
    1030     * @throws ConfigException.WrongType
    1031     *             if value is not convertible to a list of memory sizes
    1032     */
    1033    List<ConfigMemorySize> getMemorySizeList(String path);
    1034
    1035    /**
    1036     * @deprecated  As of release 1.1, replaced by {@link #getDurationList(String, TimeUnit)}
    1037     * @param path the path
    1038     * @return list of millisecond values
    1039     */
    1040    @Deprecated List<Long> getMillisecondsList(String path);
    1041
    1042    /**
    1043     * @deprecated  As of release 1.1, replaced by {@link #getDurationList(String, TimeUnit)}
    1044     * @param path the path
    1045     * @return list of nanosecond values
    1046     */
    1047    @Deprecated List<Long> getNanosecondsList(String path);
    1048
    1049    /**
    1050     * Gets a list, converting each value in the list to a duration, using the
    1051     * same rules as {@link #getDuration(String, TimeUnit)}.
    1052     *
    1053     * @since 1.2.0
    1054     * @param path
    1055     *            a path expression
    1056     * @param unit
    1057     *            time units of the returned values
    1058     * @return list of durations, in the requested units
    1059     */
    1060    List<Long> getDurationList(String path, TimeUnit unit);
    1061
    1062    /**
    1063     * Gets a list, converting each value in the list to a duration, using the
    1064     * same rules as {@link #getDuration(String)}.
    1065     *
    1066     * @since 1.3.0
    1067     * @param path
    1068     *            a path expression
    1069     * @return list of durations
    1070     */
    1071    List<Duration> getDurationList(String path);
    1072
    1073    /**
    1074     * Clone the config with only the given path (and its children) retained;
    1075     * all sibling paths are removed.
    1076     * <p>
    1077     * Note that path expressions have a syntax and sometimes require quoting
    1078     * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}).
    1079     *
    1080     * @param path
    1081     *            path to keep
    1082     * @return a copy of the config minus all paths except the one specified
    1083     */
    1084    Config withOnlyPath(String path);
    1085
    1086    /**
    1087     * Clone the config with the given path removed.
    1088     * <p>
    1089     * Note that path expressions have a syntax and sometimes require quoting
    1090     * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}).
    1091     *
    1092     * @param path
    1093     *            path expression to remove
    1094     * @return a copy of the config minus the specified path
    1095     */
    1096    Config withoutPath(String path);
    1097
    1098    /**
    1099     * Places the config inside another {@code Config} at the given path.
    1100     * <p>
    1101     * Note that path expressions have a syntax and sometimes require quoting
    1102     * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}).
    1103     *
    1104     * @param path
    1105     *            path expression to store this config at.
    1106     * @return a {@code Config} instance containing this config at the given
    1107     *         path.
    1108     */
    1109    Config atPath(String path);
    1110
    1111    /**
    1112     * Places the config inside a {@code Config} at the given key. See also
    1113     * atPath(). Note that a key is NOT a path expression (see
    1114     * {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}).
    1115     *
    1116     * @param key
    1117     *            key to store this config at.
    1118     * @return a {@code Config} instance containing this config at the given
    1119     *         key.
    1120     */
    1121    Config atKey(String key);
    1122
    1123    /**
    1124     * Returns a {@code Config} based on this one, but with the given path set
    1125     * to the given value. Does not modify this instance (since it's immutable).
    1126     * If the path already has a value, that value is replaced. To remove a
    1127     * value, use withoutPath().
    1128     * <p>
    1129     * Note that path expressions have a syntax and sometimes require quoting
    1130     * (see {@link ConfigUtil#joinPath} and {@link ConfigUtil#splitPath}).
    1131     *
    1132     * @param path
    1133     *            path expression for the value's new location
    1134     * @param value
    1135     *            value at the new path
    1136     * @return the new instance with the new map entry
    1137     */
    1138    Config withValue(String path, ConfigValue value);
    1139}