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