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}