001/**
002 *   Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com>
003 */
004package com.typesafe.config;
005
006import com.typesafe.config.impl.ConfigImpl;
007import com.typesafe.config.impl.Parseable;
008
009import java.io.File;
010import java.io.Reader;
011import java.net.URL;
012import java.util.Map;
013import java.util.Properties;
014import java.util.concurrent.Callable;
015
016/**
017 * Contains static methods for creating {@link Config} instances.
018 *
019 * <p>
020 * See also {@link ConfigValueFactory} which contains static methods for
021 * converting Java values into a {@link ConfigObject}. You can then convert a
022 * {@code ConfigObject} into a {@code Config} with {@link ConfigObject#toConfig}.
023 *
024 * <p>
025 * The static methods with "load" in the name do some sort of higher-level
026 * operation potentially parsing multiple resources and resolving substitutions,
027 * while the ones with "parse" in the name just create a {@link ConfigValue}
028 * from a resource and nothing else.
029 *
030 * <p> You can find an example app and library <a
031 * href="https://github.com/lightbend/config/tree/master/examples">on
032 * GitHub</a>.  Also be sure to read the <a
033 * href="package-summary.html#package_description">package
034 * overview</a> which describes the big picture as shown in those
035 * examples.
036 */
037public final class ConfigFactory {
038    private static final String STRATEGY_PROPERTY_NAME = "config.strategy";
039
040    private ConfigFactory() {
041    }
042
043    /**
044     * Loads an application's configuration from the given classpath resource or
045     * classpath resource basename, sandwiches it between default reference
046     * config and default overrides, and then resolves it. The classpath
047     * resource is "raw" (it should have no "/" prefix, and is not made relative
048     * to any package, so it's like {@link ClassLoader#getResource} not
049     * {@link Class#getResource}).
050     *
051     * <p>
052     * Resources are loaded from the current thread's
053     * {@link Thread#getContextClassLoader()}. In general, a library needs its
054     * configuration to come from the class loader used to load that library, so
055     * the proper "reference.conf" are present.
056     *
057     * <p>
058     * The loaded object will already be resolved (substitutions have already
059     * been processed). As a result, if you add more fallbacks then they won't
060     * be seen by substitutions. Substitutions are the "${foo.bar}" syntax. If
061     * you want to parse additional files or something then you need to use
062     * {@link #load(Config)}.
063     *
064     * <p>
065     * To load a standalone resource (without the default reference and default
066     * overrides), use {@link #parseResourcesAnySyntax(String)} rather than this
067     * method. To load only the reference config use {@link #defaultReference()}
068     * and to load only the overrides use {@link #defaultOverrides()}.
069     *
070     * @param resourceBasename
071     *            name (optionally without extension) of a resource on classpath
072     * @return configuration for an application relative to context class loader
073     */
074    public static Config load(String resourceBasename) {
075        return load(resourceBasename, ConfigParseOptions.defaults(),
076                ConfigResolveOptions.defaults());
077    }
078
079    /**
080     * Like {@link #load(String)} but uses the supplied class loader instead of
081     * the current thread's context class loader.
082     * 
083     * <p>
084     * To load a standalone resource (without the default reference and default
085     * overrides), use {@link #parseResourcesAnySyntax(ClassLoader, String)}
086     * rather than this method. To load only the reference config use
087     * {@link #defaultReference(ClassLoader)} and to load only the overrides use
088     * {@link #defaultOverrides(ClassLoader)}.
089     * 
090     * @param loader class loader to look for resources in
091     * @param resourceBasename basename (no .conf/.json/.properties suffix)
092     * @return configuration for an application relative to given class loader
093     */
094    public static Config load(ClassLoader loader, String resourceBasename) {
095        return load(resourceBasename, ConfigParseOptions.defaults().setClassLoader(loader),
096                ConfigResolveOptions.defaults());
097    }
098
099    /**
100     * Like {@link #load(String)} but allows you to specify parse and resolve
101     * options.
102     *
103     * @param resourceBasename
104     *            the classpath resource name with optional extension
105     * @param parseOptions
106     *            options to use when parsing the resource
107     * @param resolveOptions
108     *            options to use when resolving the stack
109     * @return configuration for an application
110     */
111    public static Config load(String resourceBasename, ConfigParseOptions parseOptions,
112            ConfigResolveOptions resolveOptions) {
113        ConfigParseOptions withLoader = ensureClassLoader(parseOptions, "load");
114        Config appConfig = ConfigFactory.parseResourcesAnySyntax(resourceBasename, withLoader);
115        return load(withLoader.getClassLoader(), appConfig, resolveOptions);
116    }
117
118    /**
119     * Like {@link #load(String,ConfigParseOptions,ConfigResolveOptions)} but
120     * has a class loader parameter that overrides any from the
121     * {@code ConfigParseOptions}.
122     *
123     * @param loader
124     *            class loader in which to find resources (overrides loader in
125     *            parse options)
126     * @param resourceBasename
127     *            the classpath resource name with optional extension
128     * @param parseOptions
129     *            options to use when parsing the resource (class loader
130     *            overridden)
131     * @param resolveOptions
132     *            options to use when resolving the stack
133     * @return configuration for an application
134     */
135    public static Config load(ClassLoader loader, String resourceBasename,
136            ConfigParseOptions parseOptions, ConfigResolveOptions resolveOptions) {
137        return load(resourceBasename, parseOptions.setClassLoader(loader), resolveOptions);
138    }
139
140    private static ClassLoader checkedContextClassLoader(String methodName) {
141        ClassLoader loader = Thread.currentThread().getContextClassLoader();
142        if (loader == null)
143            throw new ConfigException.BugOrBroken("Context class loader is not set for the current thread; "
144                    + "if Thread.currentThread().getContextClassLoader() returns null, you must pass a ClassLoader "
145                    + "explicitly to ConfigFactory." + methodName);
146        else
147            return loader;
148    }
149
150    private static ConfigParseOptions ensureClassLoader(ConfigParseOptions options, String methodName) {
151        if (options.getClassLoader() == null)
152            return options.setClassLoader(checkedContextClassLoader(methodName));
153        else
154            return options;
155    }
156
157    /**
158     * Assembles a standard configuration using a custom <code>Config</code>
159     * object rather than loading "application.conf". The <code>Config</code>
160     * object will be sandwiched between the default reference config and
161     * default overrides and then resolved.
162     *
163     * @param config
164     *            the application's portion of the configuration
165     * @return resolved configuration with overrides and fallbacks added
166     */
167    public static Config load(Config config) {
168        return load(checkedContextClassLoader("load"), config);
169    }
170
171    /**
172     * Like {@link #load(Config)} but allows you to specify
173     * the class loader for looking up resources.
174     *
175     * @param loader
176     *            the class loader to use to find resources
177     * @param config
178     *            the application's portion of the configuration
179     * @return resolved configuration with overrides and fallbacks added
180     */
181    public static Config load(ClassLoader loader, Config config) {
182        return load(loader, config, ConfigResolveOptions.defaults());
183    }
184
185    /**
186     * Like {@link #load(Config)} but allows you to specify
187     * {@link ConfigResolveOptions}.
188     *
189     * @param config
190     *            the application's portion of the configuration
191     * @param resolveOptions
192     *            options for resolving the assembled config stack
193     * @return resolved configuration with overrides and fallbacks added
194     */
195    public static Config load(Config config, ConfigResolveOptions resolveOptions) {
196        return load(checkedContextClassLoader("load"), config, resolveOptions);
197    }
198
199    /**
200     * Like {@link #load(Config,ConfigResolveOptions)} but allows you to specify
201     * a class loader other than the context class loader.
202     *
203     * @param loader
204     *            class loader to use when looking up override and reference
205     *            configs
206     * @param config
207     *            the application's portion of the configuration
208     * @param resolveOptions
209     *            options for resolving the assembled config stack
210     * @return resolved configuration with overrides and fallbacks added
211     */
212    public static Config load(ClassLoader loader, Config config, ConfigResolveOptions resolveOptions) {
213        return defaultOverrides(loader).withFallback(config).withFallback(defaultReference(loader))
214                .resolve(resolveOptions);
215    }
216
217
218
219    /**
220     * Loads a default configuration, equivalent to {@link #load(Config)
221     * load(defaultApplication())} in most cases. This configuration should be used by
222     * libraries and frameworks unless an application provides a different one.
223     * <p>
224     * This method may return a cached singleton so will not see changes to
225     * system properties or config files. (Use {@link #invalidateCaches()} to
226     * force it to reload.)
227     *
228     * @return configuration for an application
229     */
230    public static Config load() {
231        ClassLoader loader = checkedContextClassLoader("load");
232        return load(loader);
233    }
234
235    /**
236     * Like {@link #load()} but allows specifying parse options.
237     *
238     * @param parseOptions
239     *            Options for parsing resources
240     * @return configuration for an application
241     */
242    public static Config load(ConfigParseOptions parseOptions) {
243        return load(parseOptions, ConfigResolveOptions.defaults());
244    }
245
246    /**
247     * Like {@link #load()} but allows specifying a class loader other than the
248     * thread's current context class loader.
249     *
250     * @param loader
251     *            class loader for finding resources
252     * @return configuration for an application
253     */
254    public static Config load(final ClassLoader loader) {
255        final ConfigParseOptions withLoader = ConfigParseOptions.defaults().setClassLoader(loader);
256        return ConfigImpl.computeCachedConfig(loader, "load", new Callable<Config>() {
257            @Override
258            public Config call() {
259                return load(loader, defaultApplication(withLoader));
260            }
261        });
262    }
263
264    /**
265     * Like {@link #load()} but allows specifying a class loader other than the
266     * thread's current context class loader and also specify parse options.
267     *
268     * @param loader
269     *            class loader for finding resources (overrides any loader in parseOptions)
270     * @param parseOptions
271     *            Options for parsing resources
272     * @return configuration for an application
273     */
274    public static Config load(ClassLoader loader, ConfigParseOptions parseOptions) {
275        return load(parseOptions.setClassLoader(loader));
276    }
277
278    /**
279     * Like {@link #load()} but allows specifying a class loader other than the
280     * thread's current context class loader and also specify resolve options.
281     *
282     * @param loader
283     *            class loader for finding resources
284     * @param resolveOptions
285     *            options for resolving the assembled config stack
286     * @return configuration for an application
287     */
288    public static Config load(ClassLoader loader, ConfigResolveOptions resolveOptions) {
289        return load(loader, ConfigParseOptions.defaults(), resolveOptions);
290    }
291
292
293    /**
294     * Like {@link #load()} but allows specifying a class loader other than the
295     * thread's current context class loader, parse options, and resolve options.
296     *
297     * @param loader
298     *            class loader for finding resources (overrides any loader in parseOptions)
299     * @param parseOptions
300     *            Options for parsing resources
301     * @param resolveOptions
302     *            options for resolving the assembled config stack
303     * @return configuration for an application
304     */
305    public static Config load(ClassLoader loader, ConfigParseOptions parseOptions, ConfigResolveOptions resolveOptions) {
306        final ConfigParseOptions withLoader = ensureClassLoader(parseOptions, "load");
307        return load(loader, defaultApplication(withLoader), resolveOptions);
308    }
309
310    /**
311     * Like {@link #load()} but allows specifying parse options and resolve
312     * options.
313     *
314     * @param parseOptions
315     *            Options for parsing resources
316     * @param resolveOptions
317     *            options for resolving the assembled config stack
318     * @return configuration for an application
319     *
320     * @since 1.3.0
321     */
322    public static Config load(ConfigParseOptions parseOptions, final ConfigResolveOptions resolveOptions) {
323        final ConfigParseOptions withLoader = ensureClassLoader(parseOptions, "load");
324        return load(defaultApplication(withLoader), resolveOptions);
325    }
326
327    /**
328     * Obtains the default reference configuration, which is currently created
329     * by merging all resources "reference.conf" found on the classpath and
330     * overriding the result with system properties. The returned reference
331     * configuration will already have substitutions resolved.
332     * 
333     * <p>
334     * Libraries and frameworks should ship with a "reference.conf" in their
335     * jar.
336     * 
337     * <p>
338     * The reference config must be looked up in the class loader that contains
339     * the libraries that you want to use with this config, so the
340     * "reference.conf" for each library can be found. Use
341     * {@link #defaultReference(ClassLoader)} if the context class loader is not
342     * suitable.
343     * 
344     * <p>
345     * The {@link #load()} methods merge this configuration for you
346     * automatically.
347     * 
348     * <p>
349     * Future versions may look for reference configuration in more places. It
350     * is not guaranteed that this method <em>only</em> looks at
351     * "reference.conf".
352     * 
353     * @return the default reference config for context class loader
354     */
355    public static Config defaultReference() {
356        return defaultReference(checkedContextClassLoader("defaultReference"));
357    }
358
359    /**
360     * Like {@link #defaultReference()} but allows you to specify a class loader
361     * to use rather than the current context class loader.
362     *
363     * @param loader class loader to look for resources in
364     * @return the default reference config for this class loader
365     */
366    public static Config defaultReference(ClassLoader loader) {
367        return ConfigImpl.defaultReference(loader);
368    }
369
370    /**
371     * Obtains the default override configuration, which currently consists of
372     * system properties. The returned override configuration will already have
373     * substitutions resolved.
374     *
375     * <p>
376     * The {@link #load()} methods merge this configuration for you
377     * automatically.
378     *
379     * <p>
380     * Future versions may get overrides in more places. It is not guaranteed
381     * that this method <em>only</em> uses system properties.
382     *
383     * @return the default override configuration
384     */
385    public static Config defaultOverrides() {
386        return systemProperties();
387    }
388
389    /**
390     * Like {@link #defaultOverrides()} but allows you to specify a class loader
391     * to use rather than the current context class loader.
392     *
393     * @param loader class loader to look for resources in
394     * @return the default override configuration
395     */
396    public static Config defaultOverrides(ClassLoader loader) {
397        return systemProperties();
398    }
399
400    /**
401     * Obtains the default application-specific configuration,
402     * which defaults to parsing <code>application.conf</code>,
403     * <code>application.json</code>, and
404     * <code>application.properties</code> on the classpath, but
405     * can also be rerouted using the <code>config.file</code>,
406     * <code>config.resource</code>, and <code>config.url</code>
407     * system properties.
408     *
409     * <p> The no-arguments {@link #load()} method automatically
410     * stacks the {@link #defaultReference()}, {@link
411     * #defaultApplication()}, and {@link #defaultOverrides()}
412     * configs. You would use <code>defaultApplication()</code>
413     * directly only if you're somehow customizing behavior by
414     * reimplementing <code>load()</code>.
415     *
416     * <p>The configuration returned by
417     * <code>defaultApplication()</code> will not be resolved
418     * already, in contrast to <code>defaultReference()</code> and
419     * <code>defaultOverrides()</code>. This is because
420     * application.conf would normally be resolved <em>after</em>
421     * merging with the reference and override configs.
422     *
423     * <p>
424     * If the system properties <code>config.resource</code>,
425     * <code>config.file</code>, or <code>config.url</code> are set, then the
426     * classpath resource, file, or URL specified in those properties will be
427     * used rather than the default
428     * <code>application.{conf,json,properties}</code> classpath resources.
429     * These system properties should not be set in code (after all, you can
430     * just parse whatever you want manually and then use {@link #load(Config)}
431     * if you don't want to use <code>application.conf</code>). The properties
432     * are intended for use by the person or script launching the application.
433     * For example someone might have a <code>production.conf</code> that
434     * include <code>application.conf</code> but then change a couple of values.
435     * When launching the app they could specify
436     * <code>-Dconfig.resource=production.conf</code> to get production mode.
437     *
438     * <p>
439     * If no system properties are set to change the location of the default
440     * configuration, <code>defaultApplication()</code> is equivalent to
441     * <code>ConfigFactory.parseResources("application")</code>.
442     *
443     * @since 1.3.0
444     *
445     * @return the default application.conf or system-property-configured configuration
446     */
447    public static Config defaultApplication() {
448        return defaultApplication(ConfigParseOptions.defaults());
449    }
450
451    /**
452     * Like {@link #defaultApplication()} but allows you to specify a class loader
453     * to use rather than the current context class loader.
454     *
455     * @since 1.3.0
456     *
457     * @param loader class loader to look for resources in
458     * @return the default application configuration
459     */
460    public static Config defaultApplication(ClassLoader loader) {
461        return defaultApplication(ConfigParseOptions.defaults().setClassLoader(loader));
462    }
463
464    /**
465     * Like {@link #defaultApplication()} but allows you to specify parse options.
466     *
467     * @since 1.3.0
468     *
469     * @param options the options
470     * @return the default application configuration
471     */
472    public static Config defaultApplication(ConfigParseOptions options) {
473        return getConfigLoadingStrategy().parseApplicationConfig(ensureClassLoader(options, "defaultApplication"));
474    }
475
476    /**
477     * Reloads any cached configs, picking up changes to system properties for
478     * example. Because a {@link Config} is immutable, anyone with a reference
479     * to the old configs will still have the same outdated objects. However,
480     * new calls to {@link #load()} or {@link #defaultOverrides()} or
481     * {@link #defaultReference} may return a new object.
482     * <p>
483     * This method is primarily intended for use in unit tests, for example,
484     * that may want to update a system property then confirm that it's used
485     * correctly. In many cases, use of this method may indicate there's a
486     * better way to set up your code.
487     * <p>
488     * Caches may be reloaded immediately or lazily; once you call this method,
489     * the reload can occur at any time, even during the invalidation process.
490     * So FIRST make the changes you'd like the caches to notice, then SECOND
491     * call this method to invalidate caches. Don't expect that invalidating,
492     * making changes, then calling {@link #load()}, will work. Make changes
493     * before you invalidate.
494     */
495    public static void invalidateCaches() {
496        // We rely on this having the side effect that it drops
497        // all caches
498        ConfigImpl.reloadSystemPropertiesConfig();
499        ConfigImpl.reloadEnvVariablesConfig();
500    }
501
502    /**
503     * Gets an empty configuration. See also {@link #empty(String)} to create an
504     * empty configuration with a description, which may improve user-visible
505     * error messages.
506     *
507     * @return an empty configuration
508     */
509    public static Config empty() {
510        return empty(null);
511    }
512
513    /**
514     * Gets an empty configuration with a description to be used to create a
515     * {@link ConfigOrigin} for this <code>Config</code>. The description should
516     * be very short and say what the configuration is, like "default settings"
517     * or "foo settings" or something. (Presumably you will merge some actual
518     * settings into this empty config using {@link Config#withFallback}, making
519     * the description more useful.)
520     *
521     * @param originDescription
522     *            description of the config
523     * @return an empty configuration
524     */
525    public static Config empty(String originDescription) {
526        return ConfigImpl.emptyConfig(originDescription);
527    }
528
529    /**
530     * Gets a <code>Config</code> containing the system properties from
531     * {@link java.lang.System#getProperties()}, parsed and converted as with
532     * {@link #parseProperties}.
533     * <p>
534     * This method can return a global immutable singleton, so it's preferred
535     * over parsing system properties yourself.
536     * <p>
537     * {@link #load} will include the system properties as overrides already, as
538     * will {@link #defaultReference} and {@link #defaultOverrides}.
539     *
540     * <p>
541     * Because this returns a singleton, it will not notice changes to system
542     * properties made after the first time this method is called. Use
543     * {@link #invalidateCaches()} to force the singleton to reload if you
544     * modify system properties.
545     *
546     * @return system properties parsed into a <code>Config</code>
547     */
548    public static Config systemProperties() {
549        return ConfigImpl.systemPropertiesAsConfig();
550    }
551
552    /**
553     * Gets a <code>Config</code> containing the system's environment variables.
554     * This method can return a global immutable singleton.
555     *
556     * <p>
557     * Environment variables are used as fallbacks when resolving substitutions
558     * whether or not this object is included in the config being resolved, so
559     * you probably don't need to use this method for most purposes. It can be a
560     * nicer API for accessing environment variables than raw
561     * {@link java.lang.System#getenv(String)} though, since you can use methods
562     * such as {@link Config#getInt}.
563     *
564     * @return system environment variables parsed into a <code>Config</code>
565     */
566    public static Config systemEnvironment() {
567        return ConfigImpl.envVariablesAsConfig();
568    }
569
570    /**
571     * Converts a Java {@link java.util.Properties} object to a
572     * {@link ConfigObject} using the rules documented in the <a
573     * href="https://github.com/lightbend/config/blob/master/HOCON.md">HOCON
574     * spec</a>. The keys in the <code>Properties</code> object are split on the
575     * period character '.' and treated as paths. The values will all end up as
576     * string values. If you have both "a=foo" and "a.b=bar" in your properties
577     * file, so "a" is both the object containing "b" and the string "foo", then
578     * the string value is dropped.
579     *
580     * <p>
581     * If you want to have <code>System.getProperties()</code> as a
582     * ConfigObject, it's better to use the {@link #systemProperties()} method
583     * which returns a cached global singleton.
584     *
585     * @param properties
586     *            a Java Properties object
587     * @param options
588     *            the parse options
589     * @return the parsed configuration
590     */
591    public static Config parseProperties(Properties properties,
592            ConfigParseOptions options) {
593        return Parseable.newProperties(properties, options).parse().toConfig();
594    }
595
596    /**
597     * Like {@link #parseProperties(Properties, ConfigParseOptions)} but uses default
598     * parse options.
599     * @param properties
600     *            a Java Properties object
601     * @return the parsed configuration
602     */
603    public static Config parseProperties(Properties properties) {
604        return parseProperties(properties, ConfigParseOptions.defaults());
605    }
606
607    /**
608     * Parses a Reader into a Config instance. Does not call
609     * {@link Config#resolve} or merge the parsed stream with any
610     * other configuration; this method parses a single stream and
611     * does nothing else. It does process "include" statements in
612     * the parsed stream, and may end up doing other IO due to those
613     * statements.
614     *
615     * @param reader
616     *       the reader to parse
617     * @param options
618     *       parse options to control how the reader is interpreted
619     * @return the parsed configuration
620     * @throws ConfigException on IO or parse errors
621     */
622    public static Config parseReader(Reader reader, ConfigParseOptions options) {
623        return Parseable.newReader(reader, options).parse().toConfig();
624    }
625
626    /**
627     * Parses a reader into a Config instance as with
628     * {@link #parseReader(Reader,ConfigParseOptions)} but always uses the
629     * default parse options.
630     *
631     * @param reader
632     *       the reader to parse
633     * @return the parsed configuration
634     * @throws ConfigException on IO or parse errors
635     */
636    public static Config parseReader(Reader reader) {
637        return parseReader(reader, ConfigParseOptions.defaults());
638    }
639
640    /**
641     * Parses a URL into a Config instance. Does not call
642     * {@link Config#resolve} or merge the parsed stream with any
643     * other configuration; this method parses a single stream and
644     * does nothing else. It does process "include" statements in
645     * the parsed stream, and may end up doing other IO due to those
646     * statements.
647     *
648     * @param url
649     *       the url to parse
650     * @param options
651     *       parse options to control how the url is interpreted
652     * @return the parsed configuration
653     * @throws ConfigException on IO or parse errors
654     */
655    public static Config parseURL(URL url, ConfigParseOptions options) {
656        return Parseable.newURL(url, options).parse().toConfig();
657    }
658
659    /**
660     * Parses a url into a Config instance as with
661     * {@link #parseURL(URL,ConfigParseOptions)} but always uses the
662     * default parse options.
663     *
664     * @param url
665     *       the url to parse
666     * @return the parsed configuration
667     * @throws ConfigException on IO or parse errors
668     */
669    public static Config parseURL(URL url) {
670        return parseURL(url, ConfigParseOptions.defaults());
671    }
672
673    /**
674     * Parses a file into a Config instance. Does not call
675     * {@link Config#resolve} or merge the file with any other
676     * configuration; this method parses a single file and does
677     * nothing else. It does process "include" statements in the
678     * parsed file, and may end up doing other IO due to those
679     * statements.
680     *
681     * @param file
682     *       the file to parse
683     * @param options
684     *       parse options to control how the file is interpreted
685     * @return the parsed configuration
686     * @throws ConfigException on IO or parse errors
687     */
688    public static Config parseFile(File file, ConfigParseOptions options) {
689        return Parseable.newFile(file, options).parse().toConfig();
690    }
691
692    /**
693     * Parses a file into a Config instance as with
694     * {@link #parseFile(File,ConfigParseOptions)} but always uses the
695     * default parse options.
696     *
697     * @param file
698     *       the file to parse
699     * @return the parsed configuration
700     * @throws ConfigException on IO or parse errors
701     */
702    public static Config parseFile(File file) {
703        return parseFile(file, ConfigParseOptions.defaults());
704    }
705
706    /**
707     * Parses a file with a flexible extension. If the <code>fileBasename</code>
708     * already ends in a known extension, this method parses it according to
709     * that extension (the file's syntax must match its extension). If the
710     * <code>fileBasename</code> does not end in an extension, it parses files
711     * with all known extensions and merges whatever is found.
712     *
713     * <p>
714     * In the current implementation, the extension ".conf" forces
715     * {@link ConfigSyntax#CONF}, ".json" forces {@link ConfigSyntax#JSON}, and
716     * ".properties" forces {@link ConfigSyntax#PROPERTIES}. When merging files,
717     * ".conf" falls back to ".json" falls back to ".properties".
718     *
719     * <p>
720     * Future versions of the implementation may add additional syntaxes or
721     * additional extensions. However, the ordering (fallback priority) of the
722     * three current extensions will remain the same.
723     *
724     * <p>
725     * If <code>options</code> forces a specific syntax, this method only parses
726     * files with an extension matching that syntax.
727     *
728     * <p>
729     * If {@link ConfigParseOptions#getAllowMissing options.getAllowMissing()}
730     * is true, then no files have to exist; if false, then at least one file
731     * has to exist.
732     *
733     * @param fileBasename
734     *            a filename with or without extension
735     * @param options
736     *            parse options
737     * @return the parsed configuration
738     */
739    public static Config parseFileAnySyntax(File fileBasename,
740            ConfigParseOptions options) {
741        return ConfigImpl.parseFileAnySyntax(fileBasename, options).toConfig();
742    }
743
744    /**
745     * Like {@link #parseFileAnySyntax(File,ConfigParseOptions)} but always uses
746     * default parse options.
747     *
748     * @param fileBasename
749     *            a filename with or without extension
750     * @return the parsed configuration
751     */
752    public static Config parseFileAnySyntax(File fileBasename) {
753        return parseFileAnySyntax(fileBasename, ConfigParseOptions.defaults());
754    }
755
756    /**
757     * Parses all resources on the classpath with the given name and merges them
758     * into a single <code>Config</code>.
759     *
760     * <p>
761     * If the resource name does not begin with a "/", it will have the supplied
762     * class's package added to it, in the same way as
763     * {@link java.lang.Class#getResource}.
764     *
765     * <p>
766     * Duplicate resources with the same name are merged such that ones returned
767     * earlier from {@link ClassLoader#getResources} fall back to (have higher
768     * priority than) the ones returned later. This implies that resources
769     * earlier in the classpath override those later in the classpath when they
770     * configure the same setting. However, in practice real applications may
771     * not be consistent about classpath ordering, so be careful. It may be best
772     * to avoid assuming too much.
773     *
774     * @param klass
775     *            <code>klass.getClassLoader()</code> will be used to load
776     *            resources, and non-absolute resource names will have this
777     *            class's package added
778     * @param resource
779     *            resource to look up, relative to <code>klass</code>'s package
780     *            or absolute starting with a "/"
781     * @param options
782     *            parse options
783     * @return the parsed configuration
784     */
785    public static Config parseResources(Class<?> klass, String resource,
786            ConfigParseOptions options) {
787        return Parseable.newResources(klass, resource, options).parse()
788                .toConfig();
789    }
790
791    /**
792     * Like {@link #parseResources(Class,String,ConfigParseOptions)} but always uses
793     * default parse options.
794     *
795     * @param klass
796     *            <code>klass.getClassLoader()</code> will be used to load
797     *            resources, and non-absolute resource names will have this
798     *            class's package added
799     * @param resource
800     *            resource to look up, relative to <code>klass</code>'s package
801     *            or absolute starting with a "/"
802     * @return the parsed configuration
803     */
804    public static Config parseResources(Class<?> klass, String resource) {
805        return parseResources(klass, resource, ConfigParseOptions.defaults());
806    }
807
808    /**
809     * Parses classpath resources with a flexible extension. In general, this
810     * method has the same behavior as
811     * {@link #parseFileAnySyntax(File,ConfigParseOptions)} but for classpath
812     * resources instead, as in {@link #parseResources}.
813     *
814     * <p>
815     * There is a thorny problem with this method, which is that
816     * {@link java.lang.ClassLoader#getResources} must be called separately for
817     * each possible extension. The implementation ends up with separate lists
818     * of resources called "basename.conf" and "basename.json" for example. As a
819     * result, the ideal ordering between two files with different extensions is
820     * unknown; there is no way to figure out how to merge the two lists in
821     * classpath order. To keep it simple, the lists are simply concatenated,
822     * with the same syntax priorities as
823     * {@link #parseFileAnySyntax(File,ConfigParseOptions) parseFileAnySyntax()}
824     * - all ".conf" resources are ahead of all ".json" resources which are
825     * ahead of all ".properties" resources.
826     *
827     * @param klass
828     *            class which determines the <code>ClassLoader</code> and the
829     *            package for relative resource names
830     * @param resourceBasename
831     *            a resource name as in {@link java.lang.Class#getResource},
832     *            with or without extension
833     * @param options
834     *            parse options (class loader is ignored in favor of the one
835     *            from klass)
836     * @return the parsed configuration
837     */
838    public static Config parseResourcesAnySyntax(Class<?> klass, String resourceBasename,
839            ConfigParseOptions options) {
840        return ConfigImpl.parseResourcesAnySyntax(klass, resourceBasename,
841                options).toConfig();
842    }
843
844    /**
845     * Like {@link #parseResourcesAnySyntax(Class,String,ConfigParseOptions)}
846     * but always uses default parse options.
847     *
848     * @param klass
849     *            <code>klass.getClassLoader()</code> will be used to load
850     *            resources, and non-absolute resource names will have this
851     *            class's package added
852     * @param resourceBasename
853     *            a resource name as in {@link java.lang.Class#getResource},
854     *            with or without extension
855     * @return the parsed configuration
856     */
857    public static Config parseResourcesAnySyntax(Class<?> klass, String resourceBasename) {
858        return parseResourcesAnySyntax(klass, resourceBasename, ConfigParseOptions.defaults());
859    }
860
861    /**
862     * Parses all resources on the classpath with the given name and merges them
863     * into a single <code>Config</code>.
864     *
865     * <p>
866     * This works like {@link java.lang.ClassLoader#getResource}, not like
867     * {@link java.lang.Class#getResource}, so the name never begins with a
868     * slash.
869     *
870     * <p>
871     * See {@link #parseResources(Class,String,ConfigParseOptions)} for full
872     * details.
873     *
874     * @param loader
875     *            will be used to load resources by setting this loader on the
876     *            provided options
877     * @param resource
878     *            resource to look up
879     * @param options
880     *            parse options (class loader is ignored)
881     * @return the parsed configuration
882     */
883    public static Config parseResources(ClassLoader loader, String resource,
884            ConfigParseOptions options) {
885        return parseResources(resource, options.setClassLoader(loader));
886    }
887
888    /**
889     * Like {@link #parseResources(ClassLoader,String,ConfigParseOptions)} but always uses
890     * default parse options.
891     *
892     * @param loader
893     *            will be used to load resources
894     * @param resource
895     *            resource to look up in the loader
896     * @return the parsed configuration
897     */
898    public static Config parseResources(ClassLoader loader, String resource) {
899        return parseResources(loader, resource, ConfigParseOptions.defaults());
900    }
901
902    /**
903     * Parses classpath resources with a flexible extension. In general, this
904     * method has the same behavior as
905     * {@link #parseFileAnySyntax(File,ConfigParseOptions)} but for classpath
906     * resources instead, as in
907     * {@link #parseResources(ClassLoader,String,ConfigParseOptions)}.
908     *
909     * <p>
910     * {@link #parseResourcesAnySyntax(Class,String,ConfigParseOptions)} differs
911     * in the syntax for the resource name, but otherwise see
912     * {@link #parseResourcesAnySyntax(Class,String,ConfigParseOptions)} for
913     * some details and caveats on this method.
914     *
915     * @param loader
916     *            class loader to look up resources in, will be set on options
917     * @param resourceBasename
918     *            a resource name as in
919     *            {@link java.lang.ClassLoader#getResource}, with or without
920     *            extension
921     * @param options
922     *            parse options (class loader ignored)
923     * @return the parsed configuration
924     */
925    public static Config parseResourcesAnySyntax(ClassLoader loader, String resourceBasename,
926            ConfigParseOptions options) {
927        return ConfigImpl.parseResourcesAnySyntax(resourceBasename, options.setClassLoader(loader))
928                .toConfig();
929    }
930
931    /**
932     * Like {@link #parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions)} but always uses
933     * default parse options.
934     *
935     * @param loader
936     *            will be used to load resources
937     * @param resourceBasename
938     *            a resource name as in
939     *            {@link java.lang.ClassLoader#getResource}, with or without
940     *            extension
941     * @return the parsed configuration
942     */
943    public static Config parseResourcesAnySyntax(ClassLoader loader, String resourceBasename) {
944        return parseResourcesAnySyntax(loader, resourceBasename, ConfigParseOptions.defaults());
945    }
946
947    /**
948     * Like {@link #parseResources(ClassLoader,String,ConfigParseOptions)} but
949     * uses thread's current context class loader if none is set in the
950     * ConfigParseOptions.
951     * @param resource the resource name
952     * @param options parse options
953     * @return the parsed configuration
954     */
955    public static Config parseResources(String resource, ConfigParseOptions options) {
956        ConfigParseOptions withLoader = ensureClassLoader(options, "parseResources");
957        return Parseable.newResources(resource, withLoader).parse().toConfig();
958    }
959
960    /**
961     * Like {@link #parseResources(ClassLoader,String)} but uses thread's
962     * current context class loader.
963     * @param resource the resource name
964     * @return the parsed configuration
965     */
966    public static Config parseResources(String resource) {
967        return parseResources(resource, ConfigParseOptions.defaults());
968    }
969
970    /**
971     * Like
972     * {@link #parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions)}
973     * but uses thread's current context class loader.
974     * @param resourceBasename the resource basename (no file type suffix)
975     * @param options parse options
976     * @return the parsed configuration
977     */
978    public static Config parseResourcesAnySyntax(String resourceBasename, ConfigParseOptions options) {
979        return ConfigImpl.parseResourcesAnySyntax(resourceBasename, options).toConfig();
980    }
981
982    /**
983     * Like {@link #parseResourcesAnySyntax(ClassLoader,String)} but uses
984     * thread's current context class loader.
985     * @param resourceBasename the resource basename (no file type suffix)
986     * @return the parsed configuration
987     */
988    public static Config parseResourcesAnySyntax(String resourceBasename) {
989        return parseResourcesAnySyntax(resourceBasename, ConfigParseOptions.defaults());
990    }
991
992    /**
993     * Parses a string (which should be valid HOCON or JSON by default, or
994     * the syntax specified in the options otherwise).
995     *
996     * @param s string to parse
997     * @param options parse options
998     * @return the parsed configuration
999     */
1000    public static Config parseString(String s, ConfigParseOptions options) {
1001        return Parseable.newString(s, options).parse().toConfig();
1002    }
1003
1004    /**
1005     * Parses a string (which should be valid HOCON or JSON).
1006     *
1007     * @param s string to parse
1008     * @return the parsed configuration
1009     */
1010    public static Config parseString(String s) {
1011        return parseString(s, ConfigParseOptions.defaults());
1012    }
1013
1014    /**
1015     * Creates a {@code Config} based on a {@link java.util.Map} from paths to
1016     * plain Java values. Similar to
1017     * {@link ConfigValueFactory#fromMap(Map,String)}, except the keys in the
1018     * map are path expressions, rather than keys; and correspondingly it
1019     * returns a {@code Config} instead of a {@code ConfigObject}. This is more
1020     * convenient if you are writing literal maps in code, and less convenient
1021     * if you are getting your maps from some data source such as a parser.
1022     *
1023     * <p>
1024     * An exception will be thrown (and it is a bug in the caller of the method)
1025     * if a path is both an object and a value, for example if you had both
1026     * "a=foo" and "a.b=bar", then "a" is both the string "foo" and the parent
1027     * object of "b". The caller of this method should ensure that doesn't
1028     * happen.
1029     *
1030     * @param values map from paths to plain Java objects
1031     * @param originDescription
1032     *            description of what this map represents, like a filename, or
1033     *            "default settings" (origin description is used in error
1034     *            messages)
1035     * @return the map converted to a {@code Config}
1036     */
1037    public static Config parseMap(Map<String, ? extends Object> values,
1038            String originDescription) {
1039        return ConfigImpl.fromPathMap(values, originDescription).toConfig();
1040    }
1041
1042    /**
1043     * See the other overload of {@link #parseMap(Map, String)} for details,
1044     * this one just uses a default origin description.
1045     *
1046     * @param values map from paths to plain Java values
1047     * @return the map converted to a {@code Config}
1048     */
1049    public static Config parseMap(Map<String, ? extends Object> values) {
1050        return parseMap(values, null);
1051    }
1052
1053    private static ConfigLoadingStrategy getConfigLoadingStrategy() {
1054        String className = System.getProperties().getProperty(STRATEGY_PROPERTY_NAME);
1055
1056        if (className != null) {
1057            try {
1058                return ConfigLoadingStrategy.class.cast(Class.forName(className).newInstance());
1059            } catch (Throwable e) {
1060                throw new ConfigException.BugOrBroken("Failed to load strategy: " + className, e);
1061            }
1062        } else {
1063            return new DefaultConfigLoadingStrategy();
1064        }
1065    }
1066}