    001/**
    002 *   Copyright (C) 2011-2012 Typesafe Inc. <http://typesafe.com>
    003 */
    004package com.typesafe.config;
    005
    006/**
    007 * A set of options related to resolving substitutions. Substitutions use the
    008 * <code>${foo.bar}</code> syntax and are documented in the <a
    009 * href="https://github.com/typesafehub/config/blob/master/HOCON.md">HOCON</a>
    010 * spec.
    011 * <p>
    012 * Typically this class would be used with the method
    013 * {@link Config#resolve(ConfigResolveOptions)}.
    014 * <p>
    015 * This object is immutable, so the "setters" return a new object.
    016 * <p>
    017 * Here is an example of creating a custom {@code ConfigResolveOptions}:
    018 *
    019 * <pre>
    020 *     ConfigResolveOptions options = ConfigResolveOptions.defaults()
    021 *         .setUseSystemEnvironment(false)
    022 * </pre>
    023 * <p>
    024 * In addition to {@link ConfigResolveOptions#defaults}, there's a prebuilt
    025 * {@link ConfigResolveOptions#noSystem} which avoids looking at any system
    026 * environment variables or other external system information. (Right now,
    027 * environment variables are the only example.)
    028 */
    029public final class ConfigResolveOptions {
    030    private final boolean useSystemEnvironment;
    031    private final boolean allowUnresolved;
    032
    033    private ConfigResolveOptions(boolean useSystemEnvironment, boolean allowUnresolved) {
    034        this.useSystemEnvironment = useSystemEnvironment;
    035        this.allowUnresolved = allowUnresolved;
    036    }
    037
    038    /**
    039     * Returns the default resolve options. By default the system environment
    040     * will be used and unresolved substitutions are not allowed.
    041     *
    042     * @return the default resolve options
    043     */
    044    public static ConfigResolveOptions defaults() {
    045        return new ConfigResolveOptions(true, false);
    046    }
    047
    048    /**
    049     * Returns resolve options that disable any reference to "system" data
    050     * (currently, this means environment variables).
    051     *
    052     * @return the resolve options with env variables disabled
    053     */
    054    public static ConfigResolveOptions noSystem() {
    055        return defaults().setUseSystemEnvironment(false);
    056    }
    057
    058    /**
    059     * Returns options with use of environment variables set to the given value.
    060     *
    061     * @param value
    062     *            true to resolve substitutions falling back to environment
    063     *            variables.
    064     * @return options with requested setting for use of environment variables
    065     */
    066    public ConfigResolveOptions setUseSystemEnvironment(boolean value) {
    067        return new ConfigResolveOptions(value, allowUnresolved);
    068    }
    069
    070    /**
    071     * Returns whether the options enable use of system environment variables.
    072     * This method is mostly used by the config lib internally, not by
    073     * applications.
    074     *
    075     * @return true if environment variables should be used
    076     */
    077    public boolean getUseSystemEnvironment() {
    078        return useSystemEnvironment;
    079    }
    080
    081    /**
    082     * Returns options with "allow unresolved" set to the given value. By
    083     * default, unresolved substitutions are an error. If unresolved
    084     * substitutions are allowed, then a future attempt to use the unresolved
    085     * value may fail, but {@link Config#resolve(ConfigResolveOptions)} itself
    086     * will not throw.
    087     *
    088     * @param value
    089     *            true to silently ignore unresolved substitutions.
    090     * @return options with requested setting for whether to allow substitutions
    091     * @since 1.2.0
    092     */
    093    public ConfigResolveOptions setAllowUnresolved(boolean value) {
    094        return new ConfigResolveOptions(useSystemEnvironment, value);
    095    }
    096
    097    /**
    098     * Returns whether the options allow unresolved substitutions. This method
    099     * is mostly used by the config lib internally, not by applications.
    100     *
    101     * @return true if unresolved substitutions are allowed
    102     * @since 1.2.0
    103     */
    104    public boolean getAllowUnresolved() {
    105        return allowUnresolved;
    106    }
    107}