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/typesafehub/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/typesafehub/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/typesafehub/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/typesafehub/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/typesafehub/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/typesafehub/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/typesafehub/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/typesafehub/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/typesafehub/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/typesafehub/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}