getDoubleList(java.lang.String path)
java.lang.LonglonggetDuration(java.lang.String path,
java.util.concurrent.TimeUnit unit)
java.lang.Long getDuration(java.lang.String path, - java.util.concurrent.TimeUnit unit)+
long getDuration(java.lang.String path, + java.util.concurrent.TimeUnit unit)
TimeUnit. If the value is already a
number, then it's taken as milliseconds and then converted to the
diff --git a/latest/api/com/typesafe/config/ConfigException.BadPath.html b/latest/api/com/typesafe/config/ConfigException.BadPath.html
index 8baec2e8..ab35d31f 100644
--- a/latest/api/com/typesafe/config/ConfigException.BadPath.html
+++ b/latest/api/com/typesafe/config/ConfigException.BadPath.html
@@ -2,9 +2,9 @@
-
+
public interface Config +extends ConfigMergeable+
foo.bar.baz. Values are as in JSON
+ (booleans, strings, numbers, lists, or objects), represented by
+ ConfigValue instances. Values accessed through the
+ Config interface are never null.
+
+
+ Config is an immutable object and thus safe to use from multiple
+ threads. There's never a need for "defensive copies."
+
+
+ Fundamental operations on a Config include getting configuration
+ values, resolving substitutions with resolve(), and
+ merging configs using withFallback(ConfigMergeable).
+
+
+ All operations return a new immutable Config rather than modifying
+ the original instance.
+
+
+ Examples + +
+ You can find an example app and library on + GitHub. Also be sure to read the package overview which + describes the big picture as shown in those examples. + +
+ Paths, keys, and Config vs. ConfigObject + +
+ Config is a view onto a tree of ConfigObject; the
+ corresponding object tree can be found through root().
+ ConfigObject is a map from config keys, rather than
+ paths, to config values. Think of ConfigObject as a JSON object
+ and Config as a configuration API.
+
+
+ The API tries to consistently use the terms "key" and "path." A key is a key + in a JSON object; it's just a string that's the key in a map. A "path" is a + parseable expression with a syntax and it refers to a series of keys. Path + expressions are described in the spec for + Human-Optimized Config Object Notation. In brief, a path is + period-separated so "a.b.c" looks for key c in object b in object a in the + root object. Sometimes double quotes are needed around special characters in + path expressions. + +
+ The API for a Config is in terms of path expressions, while the API
+ for a ConfigObject is in terms of keys. Conceptually, Config
+ is a one-level map from paths to values, while a
+ ConfigObject is a tree of nested maps from keys to values.
+
+
+ Use ConfigUtil.joinPath(java.lang.String...) and ConfigUtil.splitPath(java.lang.String) to convert
+ between path expressions and individual path elements (keys).
+
+
+ Another difference between Config and ConfigObject is that
+ conceptually, ConfigValues with a valueType() of NULL exist in a
+ ConfigObject, while a Config treats null values as if they
+ were missing.
+
+
+ Getting configuration values + +
+ The "getters" on a Config all work in the same way. They never return
+ null, nor do they return a ConfigValue with
+ valueType() of NULL. Instead, they throw ConfigException.Missing if the value is
+ completely absent or set to null. If the value is set to null, a subtype of
+ ConfigException.Missing called ConfigException.Null will be
+ thrown. ConfigException.WrongType will be thrown anytime you ask for
+ a type and the value has an incompatible type. Reasonable type conversions
+ are performed for you though.
+
+
+ Iteration + +
+ If you want to iterate over the contents of a Config, you can get its
+ ConfigObject with root(), and then iterate over the
+ ConfigObject (which implements java.util.Map). Or, you
+ can use entrySet() which recurses the object tree for you and builds
+ up a Set of all path-value pairs where the value is not null.
+
+
+ Resolving substitutions + +
+ Substitutions are the ${foo.bar} syntax in config
+ files, described in the here. Resolving substitutions replaces these references with real
+ values.
+
+
+ Before using a Config it's necessary to call resolve()
+ to handle substitutions (though ConfigFactory.load() and similar
+ methods will do the resolve for you already).
+
+
+ Merging + +
+ The full Config for your application can be constructed using
+ the associative operation withFallback(ConfigMergeable). If
+ you use ConfigFactory.load() (recommended), it merges system
+ properties over the top of application.conf over the top of
+ reference.conf, using withFallback. You can add in
+ additional sources of configuration in the same way (usually, custom layers
+ should go either just above or just below application.conf,
+ keeping reference.conf at the bottom and system properties at
+ the top).
+
+
+ This is an interface but don't implement it yourself + +
+ Do not implement Config; it should only be implemented by
+ the config library. Arbitrary implementations will not work because the
+ library internals assume a specific concrete implementation. Also, this
+ interface is likely to grow new methods over time, so third-party
+ implementations will break.
| Modifier and Type | +Method and Description | +
|---|---|
Config |
+atKey(java.lang.String key)
+Places the config inside a
+Config at the given key. |
+
Config |
+atPath(java.lang.String path)
+Places the config inside another
+Config at the given path. |
+
void |
+checkValid(Config reference,
+ java.lang.String... restrictToPaths)
+Validates this config against a reference config, throwing an exception
+ if it is invalid.
+ |
+
java.util.Set<java.util.Map.Entry<java.lang.String,ConfigValue>> |
+entrySet()
+Returns the set of path-value pairs, excluding any null values, found by
+ recursing
+the root object. |
+
java.lang.Object |
+getAnyRef(java.lang.String path)
+Gets the value at the path as an unwrapped Java boxed value (
+
+Boolean, Integer, and
+ so on - see ConfigValue.unwrapped()). |
+
java.util.List<? extends java.lang.Object> |
+getAnyRefList(java.lang.String path) |
+
boolean |
+getBoolean(java.lang.String path) |
+
java.util.List<java.lang.Boolean> |
+getBooleanList(java.lang.String path) |
+
java.lang.Long |
+getBytes(java.lang.String path)
+Gets a value as a size in bytes (parses special strings like "128M").
+ |
+
java.util.List<java.lang.Long> |
+getBytesList(java.lang.String path) |
+
Config |
+getConfig(java.lang.String path) |
+
java.util.List<? extends Config> |
+getConfigList(java.lang.String path) |
+
double |
+getDouble(java.lang.String path) |
+
java.util.List<java.lang.Double> |
+getDoubleList(java.lang.String path) |
+
long |
+getDuration(java.lang.String path,
+ java.util.concurrent.TimeUnit unit)
+Gets a value as a duration in a specified
+
+TimeUnit. |
+
java.util.List<java.lang.Long> |
+getDurationList(java.lang.String path,
+ java.util.concurrent.TimeUnit unit)
+Gets a list, converting each value in the list to a duration, using the
+ same rules as
+getDuration(String, TimeUnit). |
+
int |
+getInt(java.lang.String path) |
+
java.util.List<java.lang.Integer> |
+getIntList(java.lang.String path) |
+
ConfigList |
+getList(java.lang.String path)
+Gets a list value (with any element type) as a
+ConfigList, which
+ implements java.util.List<ConfigValue>. |
+
long |
+getLong(java.lang.String path) |
+
java.util.List<java.lang.Long> |
+getLongList(java.lang.String path) |
+
java.lang.Long |
+getMilliseconds(java.lang.String path)
+Deprecated.
+
+As of release 1.1, replaced by
+getDuration(String, TimeUnit) |
+
java.util.List<java.lang.Long> |
+getMillisecondsList(java.lang.String path)
+Deprecated.
+
+As of release 1.1, replaced by
+getDurationList(String, TimeUnit) |
+
java.lang.Long |
+getNanoseconds(java.lang.String path)
+Deprecated.
+
+As of release 1.1, replaced by
+getDuration(String, TimeUnit) |
+
java.util.List<java.lang.Long> |
+getNanosecondsList(java.lang.String path)
+Deprecated.
+
+As of release 1.1, replaced by
+getDurationList(String, TimeUnit) |
+
java.lang.Number |
+getNumber(java.lang.String path) |
+
java.util.List<java.lang.Number> |
+getNumberList(java.lang.String path) |
+
ConfigObject |
+getObject(java.lang.String path) |
+
java.util.List<? extends ConfigObject> |
+getObjectList(java.lang.String path) |
+
java.lang.String |
+getString(java.lang.String path) |
+
java.util.List<java.lang.String> |
+getStringList(java.lang.String path) |
+
ConfigValue |
+getValue(java.lang.String path)
+Gets the value at the given path, unless the value is a
+ null value or missing, in which case it throws just like
+ the other getters.
+ |
+
boolean |
+hasPath(java.lang.String path)
+Checks whether a value is present and non-null at the given path.
+ |
+
boolean |
+isEmpty()
+Returns true if the
+Config's root object contains no key-value
+ pairs. |
+
boolean |
+isResolved()
+Checks whether the config is completely resolved.
+ |
+
ConfigOrigin |
+origin()
+Gets the origin of the
+Config, which may be a file, or a file
+ with a line number, or just a descriptive phrase. |
+
Config |
+resolve()
+Returns a replacement config with all substitutions (the
+
+${foo.bar} syntax, see the
+ spec) resolved. |
+
Config |
+resolve(ConfigResolveOptions options)
+Like
+resolve() but allows you to specify non-default
+ options. |
+
Config |
+resolveWith(Config source)
+Like
+resolve() except that substitution values are looked
+ up in the given source, rather than in this instance. |
+
Config |
+resolveWith(Config source,
+ ConfigResolveOptions options)
+Like
+resolveWith(Config) but allows you to specify
+ non-default options. |
+
ConfigObject |
+root()
+Gets the
+Config as a tree of ConfigObject. |
+
Config |
+withFallback(ConfigMergeable other)
+Returns a new value computed by merging this value with another, with
+ keys in this value "winning" over the other one.
+ |
+
Config |
+withOnlyPath(java.lang.String path)
+Clone the config with only the given path (and its children) retained;
+ all sibling paths are removed.
+ |
+
Config |
+withoutPath(java.lang.String path)
+Clone the config with the given path removed.
+ |
+
Config |
+withValue(java.lang.String path,
+ ConfigValue value)
+Returns a
+Config based on this one, but with the given path set
+ to the given value. |
+
ConfigObject root()+
Config as a tree of ConfigObject. This is a
+ constant-time operation (it is not proportional to the number of values
+ in the Config).ConfigOrigin origin()+
Config, which may be a file, or a file
+ with a line number, or just a descriptive phrase.Config for use in error messagesConfig withFallback(ConfigMergeable other)+
ConfigMergeable+ This associative operation may be used to combine configurations from + multiple sources (such as multiple configuration files). + +
+ The semantics of merging are described in the spec + for HOCON. Merging typically occurs when either the same object is + created twice in the same file, or two config files are both loaded. For + example: + +
+ foo = { a: 42 }
+ foo = { b: 43 }
+
+
+ Here, the two objects are merged as if you had written:
+
+
+ foo = { a: 42, b: 43 }
+
+
+
+ Only ConfigObject and Config instances do anything in
+ this method (they need to merge the fallback keys into themselves). All
+ other values just return the original value, since they automatically
+ override any fallback. This means that objects do not merge "across"
+ non-objects; if you write
+ object.withFallback(nonObject).withFallback(otherObject),
+ then otherObject will simply be ignored. This is an
+ intentional part of how merging works, because non-objects such as
+ strings and integers replace (rather than merging with) any prior value:
+
+
+ foo = { a: 42 }
+ foo = 10
+
+
+ Here, the number 10 "wins" and the value of foo would be
+ simply 10. Again, for details see the spec.withFallback in interface ConfigMergeableother - an object whose keys should be used as fallbacks, if the keys
+ are not present in this oneConfig resolve()+
${foo.bar} syntax, see the
+ spec) resolved. Substitutions are looked up using this
+ Config as the root object, that is, a substitution
+ ${foo.bar} will be replaced with the result of
+ getValue("foo.bar").
+
+
+ This method uses ConfigResolveOptions.defaults(), there is
+ another variant resolve(ConfigResolveOptions) which lets
+ you specify non-default options.
+
+
+ A given Config must be resolved before using it to retrieve
+ config values, but ideally should be resolved one time for your entire
+ stack of fallbacks (see withFallback(com.typesafe.config.ConfigMergeable)). Otherwise, some
+ substitutions that could have resolved with all fallbacks available may
+ not resolve, which will be potentially confusing for your application's
+ users.
+
+
+ resolve() should be invoked on root config objects, rather
+ than on a subtree (a subtree is the result of something like
+ config.getConfig("foo")). The problem with
+ resolve() on a subtree is that substitutions are relative to
+ the root of the config and the subtree will have no way to get values
+ from the root. For example, if you did
+ config.getConfig("foo").resolve() on the below config file,
+ it would not work:
+
+
+ common-value = 10
+ foo {
+ whatever = ${common-value}
+ }
+
+
+
+ Many methods on ConfigFactory such as
+ ConfigFactory.load() automatically resolve the loaded
+ Config on the loaded stack of config files.
+
+
+ Resolving an already-resolved config is a harmless no-op, but again, it + is best to resolve an entire stack of fallbacks (such as all your config + files combined) rather than resolving each one individually.
ConfigException.UnresolvedSubstitution - if any substitutions refer to nonexistent pathsConfigException - some other config exception if there are other problemsConfig resolve(ConfigResolveOptions options)+
resolve() but allows you to specify non-default
+ options.options - resolve optionsConfig (may be only partially resolved if options are set to allow unresolved)boolean isResolved()+
resolve() it will be completely resolved, but after
+ calling resolve(ConfigResolveOptions) with
+ allowUnresolved set in the options, it may or may not be
+ completely resolved. A newly-loaded config may or may not be completely
+ resolved depending on whether there were substitutions present in the
+ file.Config resolveWith(Config source)+
resolve() except that substitution values are looked
+ up in the given source, rather than in this instance. This is a
+ special-purpose method which doesn't make sense to use in most cases;
+ it's only needed if you're constructing some sort of app-specific custom
+ approach to configuration. The more usual approach if you have a source
+ of substitution values would be to merge that source into your config
+ stack using withFallback(com.typesafe.config.ConfigMergeable) and then resolve.
+
+ Note that this method does NOT look in this instance for substitution
+ values. If you want to do that, you could either merge this instance into
+ your value source using withFallback(com.typesafe.config.ConfigMergeable), or you could resolve
+ multiple times with multiple sources (using
+ ConfigResolveOptions.setAllowUnresolved(boolean) so the partial
+ resolves don't fail).
source - configuration to pull values fromConfigException.UnresolvedSubstitution - if any substitutions refer to paths which are not in the
+ sourceConfigException - some other config exception if there are other problemsConfig resolveWith(Config source, + ConfigResolveOptions options)+
resolveWith(Config) but allows you to specify
+ non-default options.source - source configuration to pull values fromoptions - resolve optionsConfig (may be only partially resolved
+ if options are set to allow unresolved)void checkValid(Config reference, + java.lang.String... restrictToPaths)+
+ Using this method is always optional, since you can "fail late" instead. + +
+ You must restrict validation to paths you "own" (those whose meaning are + defined by your code module). If you validate globally, you may trigger + errors about paths that happen to be in the config but have nothing to do + with your module. It's best to allow the modules owning those paths to + validate them. Also, if every module validates only its own stuff, there + isn't as much redundant work being done. + +
+ If no paths are specified in checkValid()'s parameter list,
+ validation is for the entire config.
+
+
+ If you specify paths that are not in the reference config, those paths + are ignored. (There's nothing to validate.) + +
+ Here's what validation involves: + +
getMilliseconds(java.lang.String)). Also,
+ it's allowed to set any type to null or override null with any type.
+ + If you want to allow a certain setting to have a flexible type (or + otherwise want validation to be looser for some settings), you could + either remove the problematic setting from the reference config provided + to this method, or you could intercept the validation exception and + screen out certain problems. Of course, this will only work if all other + callers of this method are careful to restrict validation to their own + paths, as they should be. + +
+ If validation fails, the thrown exception contains a list of all problems
+ found. See ConfigException.ValidationFailed.problems. The
+ exception's getMessage() will have all the problems
+ concatenated into one huge string, as well.
+
+
+ Again, checkValid() can't guess every domain-specific way a
+ setting can be invalid, so some problems may arise later when attempting
+ to use the config. checkValid() is limited to reporting
+ generic, but common, problems such as missing settings and blatant type
+ incompatibilities.
reference - a reference configurationrestrictToPaths - only validate values underneath these paths that your code
+ module owns and understandsConfigException.ValidationFailed - if there are any validation issuesConfigException.NotResolved - if this config is not resolvedConfigException.BugOrBroken - if the reference config is unresolved or caller otherwise
+ misuses the APIboolean hasPath(java.lang.String path)+
Map.containsKey() as implemented by
+ ConfigObject: it looks for a path expression, not a key; and it
+ returns false for null values, while containsKey() returns true
+ indicating that the object contains a null value for the key.
+
+
+ If a path exists according to hasPath(String), then
+ getValue(String) will never throw an exception. However, the
+ typed getters, such as getInt(String), will still throw if the
+ value is not convertible to the requested type.
path - the path expressionConfigException.BadPath - if the path expression is invalidboolean isEmpty()+
Config's root object contains no key-value
+ pairs.java.util.Set<java.util.Map.Entry<java.lang.String,ConfigValue>> entrySet()+
the root object. Note that this is very
+ different from root().entrySet() which returns the set of
+ immediate-child keys in the root object and includes null values.ConfigObjectboolean getBoolean(java.lang.String path)+
path - path expressionConfigException.Missing - if value is absent or nullConfigException.WrongType - if value is not convertible to booleanjava.lang.Number getNumber(java.lang.String path)+
path - path expressionConfigException.Missing - if value is absent or nullConfigException.WrongType - if value is not convertible to a numberint getInt(java.lang.String path)+
path - path expressionConfigException.Missing - if value is absent or nullConfigException.WrongType - if value is not convertible to an int (for example it is out
+ of range, or it's a boolean value)long getLong(java.lang.String path)+
path - path expressionConfigException.Missing - if value is absent or nullConfigException.WrongType - if value is not convertible to a longdouble getDouble(java.lang.String path)+
path - path expressionConfigException.Missing - if value is absent or nullConfigException.WrongType - if value is not convertible to a doublejava.lang.String getString(java.lang.String path)+
path - path expressionConfigException.Missing - if value is absent or nullConfigException.WrongType - if value is not convertible to a stringConfigObject getObject(java.lang.String path)+
path - path expressionConfigObject value at the requested pathConfigException.Missing - if value is absent or nullConfigException.WrongType - if value is not convertible to an objectConfig getConfig(java.lang.String path)+
path - path expressionConfig value at the requested pathConfigException.Missing - if value is absent or nullConfigException.WrongType - if value is not convertible to a Configjava.lang.Object getAnyRef(java.lang.String path)+
Boolean, Integer, and
+ so on - see ConfigValue.unwrapped()).path - path expressionConfigException.Missing - if value is absent or nullConfigValue getValue(java.lang.String path)+
get() on the root() object (or other object in the tree) if you
+ want an unprocessed value.path - path expressionConfigException.Missing - if value is absent or nulljava.lang.Long getBytes(java.lang.String path)+
path - path expressionConfigException.Missing - if value is absent or nullConfigException.WrongType - if value is not convertible to Long or StringConfigException.BadValue - if value cannot be parsed as a size in bytes@Deprecated +java.lang.Long getMilliseconds(java.lang.String path)+
getDuration(String, TimeUnit)path - path expressionConfigException.Missing - if value is absent or nullConfigException.WrongType - if value is not convertible to Long or StringConfigException.BadValue - if value cannot be parsed as a number of milliseconds@Deprecated +java.lang.Long getNanoseconds(java.lang.String path)+
getDuration(String, TimeUnit)getDuration(String, TimeUnit).path - path expressionConfigException.Missing - if value is absent or nullConfigException.WrongType - if value is not convertible to Long or StringConfigException.BadValue - if value cannot be parsed as a number of nanosecondslong getDuration(java.lang.String path, + java.util.concurrent.TimeUnit unit)+
TimeUnit. If the value is already a
+ number, then it's taken as milliseconds and then converted to the
+ requested TimeUnit; if it's a string, it's parsed understanding units
+ suffixes like "10m" or "5ns" as documented in the the
+ spec.path - path expressionunit - convert the return value to this time unitConfigException.Missing - if value is absent or nullConfigException.WrongType - if value is not convertible to Long or StringConfigException.BadValue - if value cannot be parsed as a number of the given TimeUnitConfigList getList(java.lang.String path)+
ConfigList, which
+ implements java.util.List<ConfigValue>. Throws if the path is
+ unset or null.path - the path to the list value.ConfigList at the pathConfigException.Missing - if value is absent or nullConfigException.WrongType - if value is not convertible to a ConfigListjava.util.List<java.lang.Boolean> getBooleanList(java.lang.String path)+
java.util.List<java.lang.Number> getNumberList(java.lang.String path)+
java.util.List<java.lang.Integer> getIntList(java.lang.String path)+
java.util.List<java.lang.Long> getLongList(java.lang.String path)+
java.util.List<java.lang.Double> getDoubleList(java.lang.String path)+
java.util.List<java.lang.String> getStringList(java.lang.String path)+
java.util.List<? extends ConfigObject> getObjectList(java.lang.String path)+
java.util.List<? extends Config> getConfigList(java.lang.String path)+
java.util.List<? extends java.lang.Object> getAnyRefList(java.lang.String path)+
java.util.List<java.lang.Long> getBytesList(java.lang.String path)+
@Deprecated +java.util.List<java.lang.Long> getMillisecondsList(java.lang.String path)+
getDurationList(String, TimeUnit)@Deprecated +java.util.List<java.lang.Long> getNanosecondsList(java.lang.String path)+
getDurationList(String, TimeUnit)java.util.List<java.lang.Long> getDurationList(java.lang.String path, + java.util.concurrent.TimeUnit unit)+
getDuration(String, TimeUnit).path - a path expressionunit - time units of the returned valuesConfig withOnlyPath(java.lang.String path)+
path - path to keepConfig withoutPath(java.lang.String path)+
path - path to removeConfig atPath(java.lang.String path)+
Config at the given path.path - path to store this config at.Config instance containing this config at the given
+ path.Config atKey(java.lang.String key)+
Config at the given key. See also
+ atPath().key - key to store this config at.Config instance containing this config at the given
+ key.Config withValue(java.lang.String path, + ConfigValue value)+
Config based on this one, but with the given path set
+ to the given value. Does not modify this instance (since it's immutable).
+ If the path already has a value, that value is replaced. To remove a
+ value, use withoutPath().path - path to addvalue - value at the new pathpublic static class ConfigException.BadPath +extends ConfigException+
ConfigException.BadPath, ConfigException.BadValue, ConfigException.BugOrBroken, ConfigException.Generic, ConfigException.IO, ConfigException.Missing, ConfigException.NotResolved, ConfigException.Null, ConfigException.Parse, ConfigException.UnresolvedSubstitution, ConfigException.ValidationFailed, ConfigException.ValidationProblem, ConfigException.WrongType| Constructor and Description | +
|---|
ConfigException.BadPath(ConfigOrigin origin,
+ java.lang.String message) |
+
ConfigException.BadPath(ConfigOrigin origin,
+ java.lang.String path,
+ java.lang.String message) |
+
ConfigException.BadPath(ConfigOrigin origin,
+ java.lang.String path,
+ java.lang.String message,
+ java.lang.Throwable cause) |
+
ConfigException.BadPath(java.lang.String path,
+ java.lang.String message) |
+
ConfigException.BadPath(java.lang.String path,
+ java.lang.String message,
+ java.lang.Throwable cause) |
+
originaddSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitpublic ConfigException.BadPath(ConfigOrigin origin, + java.lang.String path, + java.lang.String message, + java.lang.Throwable cause)+
public ConfigException.BadPath(ConfigOrigin origin, + java.lang.String path, + java.lang.String message)+
public ConfigException.BadPath(java.lang.String path, + java.lang.String message, + java.lang.Throwable cause)+
public ConfigException.BadPath(java.lang.String path, + java.lang.String message)+
public ConfigException.BadPath(ConfigOrigin origin, + java.lang.String message)+
public static class ConfigException.BadValue +extends ConfigException+
ConfigException.BadPath, ConfigException.BadValue, ConfigException.BugOrBroken, ConfigException.Generic, ConfigException.IO, ConfigException.Missing, ConfigException.NotResolved, ConfigException.Null, ConfigException.Parse, ConfigException.UnresolvedSubstitution, ConfigException.ValidationFailed, ConfigException.ValidationProblem, ConfigException.WrongType| Constructor and Description | +
|---|
ConfigException.BadValue(ConfigOrigin origin,
+ java.lang.String path,
+ java.lang.String message) |
+
ConfigException.BadValue(ConfigOrigin origin,
+ java.lang.String path,
+ java.lang.String message,
+ java.lang.Throwable cause) |
+
ConfigException.BadValue(java.lang.String path,
+ java.lang.String message) |
+
ConfigException.BadValue(java.lang.String path,
+ java.lang.String message,
+ java.lang.Throwable cause) |
+
originaddSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitpublic ConfigException.BadValue(ConfigOrigin origin, + java.lang.String path, + java.lang.String message, + java.lang.Throwable cause)+
public ConfigException.BadValue(ConfigOrigin origin, + java.lang.String path, + java.lang.String message)+
public ConfigException.BadValue(java.lang.String path, + java.lang.String message, + java.lang.Throwable cause)+
public ConfigException.BadValue(java.lang.String path, + java.lang.String message)+
public static class ConfigException.BugOrBroken +extends ConfigException+
ConfigException.BadPath, ConfigException.BadValue, ConfigException.BugOrBroken, ConfigException.Generic, ConfigException.IO, ConfigException.Missing, ConfigException.NotResolved, ConfigException.Null, ConfigException.Parse, ConfigException.UnresolvedSubstitution, ConfigException.ValidationFailed, ConfigException.ValidationProblem, ConfigException.WrongType| Constructor and Description | +
|---|
ConfigException.BugOrBroken(java.lang.String message) |
+
ConfigException.BugOrBroken(java.lang.String message,
+ java.lang.Throwable cause) |
+
originaddSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitpublic static class ConfigException.Generic +extends ConfigException+
ConfigException.BadPath, ConfigException.BadValue, ConfigException.BugOrBroken, ConfigException.Generic, ConfigException.IO, ConfigException.Missing, ConfigException.NotResolved, ConfigException.Null, ConfigException.Parse, ConfigException.UnresolvedSubstitution, ConfigException.ValidationFailed, ConfigException.ValidationProblem, ConfigException.WrongType| Constructor and Description | +
|---|
ConfigException.Generic(java.lang.String message) |
+
ConfigException.Generic(java.lang.String message,
+ java.lang.Throwable cause) |
+
originaddSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitpublic static class ConfigException.IO +extends ConfigException+
ConfigException.BadPath, ConfigException.BadValue, ConfigException.BugOrBroken, ConfigException.Generic, ConfigException.IO, ConfigException.Missing, ConfigException.NotResolved, ConfigException.Null, ConfigException.Parse, ConfigException.UnresolvedSubstitution, ConfigException.ValidationFailed, ConfigException.ValidationProblem, ConfigException.WrongType| Constructor and Description | +
|---|
ConfigException.IO(ConfigOrigin origin,
+ java.lang.String message) |
+
ConfigException.IO(ConfigOrigin origin,
+ java.lang.String message,
+ java.lang.Throwable cause) |
+
originaddSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitpublic ConfigException.IO(ConfigOrigin origin, + java.lang.String message, + java.lang.Throwable cause)+
public ConfigException.IO(ConfigOrigin origin, + java.lang.String message)+
public static class ConfigException.Missing +extends ConfigException+
ConfigException.BadPath, ConfigException.BadValue, ConfigException.BugOrBroken, ConfigException.Generic, ConfigException.IO, ConfigException.Missing, ConfigException.NotResolved, ConfigException.Null, ConfigException.Parse, ConfigException.UnresolvedSubstitution, ConfigException.ValidationFailed, ConfigException.ValidationProblem, ConfigException.WrongType| Modifier | +Constructor and Description | +
|---|---|
protected |
+ConfigException.Missing(ConfigOrigin origin,
+ java.lang.String message) |
+
protected |
+ConfigException.Missing(ConfigOrigin origin,
+ java.lang.String message,
+ java.lang.Throwable cause) |
+
|
+ConfigException.Missing(java.lang.String path) |
+
|
+ConfigException.Missing(java.lang.String path,
+ java.lang.Throwable cause) |
+
originaddSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitpublic ConfigException.Missing(java.lang.String path, + java.lang.Throwable cause)+
public ConfigException.Missing(java.lang.String path)+
protected ConfigException.Missing(ConfigOrigin origin, + java.lang.String message, + java.lang.Throwable cause)+
protected ConfigException.Missing(ConfigOrigin origin, + java.lang.String message)+
public static class ConfigException.NotResolved +extends ConfigException.BugOrBroken+
Config.resolve() was not called). This is always a bug in
+ either application code or the library; it's wrong to write a handler for
+ this exception because you should be able to fix the code to avoid it by
+ adding calls to Config.resolve().ConfigException.BadPath, ConfigException.BadValue, ConfigException.BugOrBroken, ConfigException.Generic, ConfigException.IO, ConfigException.Missing, ConfigException.NotResolved, ConfigException.Null, ConfigException.Parse, ConfigException.UnresolvedSubstitution, ConfigException.ValidationFailed, ConfigException.ValidationProblem, ConfigException.WrongType| Constructor and Description | +
|---|
ConfigException.NotResolved(java.lang.String message) |
+
ConfigException.NotResolved(java.lang.String message,
+ java.lang.Throwable cause) |
+
originaddSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitpublic static class ConfigException.Null +extends ConfigException.Missing+
ConfigException.BadPath, ConfigException.BadValue, ConfigException.BugOrBroken, ConfigException.Generic, ConfigException.IO, ConfigException.Missing, ConfigException.NotResolved, ConfigException.Null, ConfigException.Parse, ConfigException.UnresolvedSubstitution, ConfigException.ValidationFailed, ConfigException.ValidationProblem, ConfigException.WrongType| Constructor and Description | +
|---|
ConfigException.Null(ConfigOrigin origin,
+ java.lang.String path,
+ java.lang.String expected) |
+
ConfigException.Null(ConfigOrigin origin,
+ java.lang.String path,
+ java.lang.String expected,
+ java.lang.Throwable cause) |
+
originaddSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitpublic ConfigException.Null(ConfigOrigin origin, + java.lang.String path, + java.lang.String expected, + java.lang.Throwable cause)+
public ConfigException.Null(ConfigOrigin origin, + java.lang.String path, + java.lang.String expected)+
public static class ConfigException.Parse +extends ConfigException+
ConfigException.BadPath, ConfigException.BadValue, ConfigException.BugOrBroken, ConfigException.Generic, ConfigException.IO, ConfigException.Missing, ConfigException.NotResolved, ConfigException.Null, ConfigException.Parse, ConfigException.UnresolvedSubstitution, ConfigException.ValidationFailed, ConfigException.ValidationProblem, ConfigException.WrongType| Constructor and Description | +
|---|
ConfigException.Parse(ConfigOrigin origin,
+ java.lang.String message) |
+
ConfigException.Parse(ConfigOrigin origin,
+ java.lang.String message,
+ java.lang.Throwable cause) |
+
originaddSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitpublic ConfigException.Parse(ConfigOrigin origin, + java.lang.String message, + java.lang.Throwable cause)+
public ConfigException.Parse(ConfigOrigin origin, + java.lang.String message)+
public static class ConfigException.UnresolvedSubstitution +extends ConfigException.Parse+
Config.resolve().ConfigException.BadPath, ConfigException.BadValue, ConfigException.BugOrBroken, ConfigException.Generic, ConfigException.IO, ConfigException.Missing, ConfigException.NotResolved, ConfigException.Null, ConfigException.Parse, ConfigException.UnresolvedSubstitution, ConfigException.ValidationFailed, ConfigException.ValidationProblem, ConfigException.WrongType| Constructor and Description | +
|---|
ConfigException.UnresolvedSubstitution(ConfigOrigin origin,
+ java.lang.String detail) |
+
ConfigException.UnresolvedSubstitution(ConfigOrigin origin,
+ java.lang.String detail,
+ java.lang.Throwable cause) |
+
originaddSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitpublic ConfigException.UnresolvedSubstitution(ConfigOrigin origin, + java.lang.String detail, + java.lang.Throwable cause)+
public ConfigException.UnresolvedSubstitution(ConfigOrigin origin, + java.lang.String detail)+
public static class ConfigException.ValidationFailed +extends ConfigException+
Config.checkValid(com.typesafe.config.Config, java.lang.String...) found validity
+ problems. The problems are available via the problems() method.
+ The getMessage() of this exception is a potentially very
+ long string listing all the problems found.ConfigException.BadPath, ConfigException.BadValue, ConfigException.BugOrBroken, ConfigException.Generic, ConfigException.IO, ConfigException.Missing, ConfigException.NotResolved, ConfigException.Null, ConfigException.Parse, ConfigException.UnresolvedSubstitution, ConfigException.ValidationFailed, ConfigException.ValidationProblem, ConfigException.WrongType| Constructor and Description | +
|---|
ConfigException.ValidationFailed(java.lang.Iterable<ConfigException.ValidationProblem> problems) |
+
| Modifier and Type | +Method and Description | +
|---|---|
java.lang.Iterable<ConfigException.ValidationProblem> |
+problems() |
+
originaddSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitpublic ConfigException.ValidationFailed(java.lang.Iterable<ConfigException.ValidationProblem> problems)+
public java.lang.Iterable<ConfigException.ValidationProblem> problems()+
public static class ConfigException.ValidationProblem
+extends java.lang.Object
+Config.checkValid(com.typesafe.config.Config, java.lang.String...). A
+ ConfigException.ValidationFailed exception thrown from
+ checkValid() includes a list of problems encountered.| Constructor and Description | +
|---|
ConfigException.ValidationProblem(java.lang.String path,
+ ConfigOrigin origin,
+ java.lang.String problem) |
+
| Modifier and Type | +Method and Description | +
|---|---|
ConfigOrigin |
+origin()
+Returns where the problem occurred (origin may include info on the
+ file, line number, etc.).
+ |
+
java.lang.String |
+path()
+Returns the config setting causing the problem.
+ |
+
java.lang.String |
+problem()
+Returns a description of the problem.
+ |
+
java.lang.String |
+toString() |
+
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitpublic ConfigException.ValidationProblem(java.lang.String path, + ConfigOrigin origin, + java.lang.String problem)+
public java.lang.String path()+
public ConfigOrigin origin()+
public java.lang.String problem()+
public java.lang.String toString()+
toString in class java.lang.Objectpublic static class ConfigException.WrongType +extends ConfigException+
ConfigException.BadPath, ConfigException.BadValue, ConfigException.BugOrBroken, ConfigException.Generic, ConfigException.IO, ConfigException.Missing, ConfigException.NotResolved, ConfigException.Null, ConfigException.Parse, ConfigException.UnresolvedSubstitution, ConfigException.ValidationFailed, ConfigException.ValidationProblem, ConfigException.WrongType| Constructor and Description | +
|---|
ConfigException.WrongType(ConfigOrigin origin,
+ java.lang.String message) |
+
ConfigException.WrongType(ConfigOrigin origin,
+ java.lang.String path,
+ java.lang.String expected,
+ java.lang.String actual) |
+
ConfigException.WrongType(ConfigOrigin origin,
+ java.lang.String path,
+ java.lang.String expected,
+ java.lang.String actual,
+ java.lang.Throwable cause) |
+
ConfigException.WrongType(ConfigOrigin origin,
+ java.lang.String message,
+ java.lang.Throwable cause) |
+
originaddSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitpublic ConfigException.WrongType(ConfigOrigin origin, + java.lang.String path, + java.lang.String expected, + java.lang.String actual, + java.lang.Throwable cause)+
public ConfigException.WrongType(ConfigOrigin origin, + java.lang.String path, + java.lang.String expected, + java.lang.String actual)+
public ConfigException.WrongType(ConfigOrigin origin, + java.lang.String message, + java.lang.Throwable cause)+
public ConfigException.WrongType(ConfigOrigin origin, + java.lang.String message)+
public abstract class ConfigException
+extends java.lang.RuntimeException
+implements java.io.Serializable
+ConfigException.| Modifier and Type | +Class and Description | +
|---|---|
static class |
+ConfigException.BadPath
+Exception indicating that a path expression was invalid.
+ |
+
static class |
+ConfigException.BadValue
+Exception indicating that a value was messed up, for example you may have
+ asked for a duration and the value can't be sensibly parsed as a
+ duration.
+ |
+
static class |
+ConfigException.BugOrBroken
+Exception indicating that there's a bug in something (possibly the
+ library itself) or the runtime environment is broken.
+ |
+
static class |
+ConfigException.Generic
+Exception that doesn't fall into any other category.
+ |
+
static class |
+ConfigException.IO
+Exception indicating that there was an IO error.
+ |
+
static class |
+ConfigException.Missing
+Exception indicates that the setting was never set to anything, not even
+ null.
+ |
+
static class |
+ConfigException.NotResolved
+Exception indicating that you tried to use a function that requires
+ substitutions to be resolved, but substitutions have not been resolved
+ (that is,
+Config.resolve() was not called). |
+
static class |
+ConfigException.Null
+Exception indicates that the setting was treated as missing because it
+ was set to null.
+ |
+
static class |
+ConfigException.Parse
+Exception indicating that there was a parse error.
+ |
+
static class |
+ConfigException.UnresolvedSubstitution
+Exception indicating that a substitution did not resolve to anything.
+ |
+
static class |
+ConfigException.ValidationFailed
+Exception indicating that
+Config.checkValid(com.typesafe.config.Config, java.lang.String...) found validity
+ problems. |
+
static class |
+ConfigException.ValidationProblem
+Information about a problem that occurred in
+Config.checkValid(com.typesafe.config.Config, java.lang.String...). |
+
static class |
+ConfigException.WrongType
+Exception indicating that the type of a value does not match the type you
+ requested.
+ |
+
| Modifier | +Constructor and Description | +
|---|---|
protected |
+ConfigException(ConfigOrigin origin,
+ java.lang.String message) |
+
protected |
+ConfigException(ConfigOrigin origin,
+ java.lang.String message,
+ java.lang.Throwable cause) |
+
protected |
+ConfigException(java.lang.String message) |
+
protected |
+ConfigException(java.lang.String message,
+ java.lang.Throwable cause) |
+
| Modifier and Type | +Method and Description | +
|---|---|
ConfigOrigin |
+origin()
+Returns an "origin" (such as a filename and line number) for the
+ exception, or null if none is available.
+ |
+
addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitprotected ConfigException(ConfigOrigin origin, + java.lang.String message, + java.lang.Throwable cause)+
protected ConfigException(ConfigOrigin origin, + java.lang.String message)+
protected ConfigException(java.lang.String message, + java.lang.Throwable cause)+
protected ConfigException(java.lang.String message)+
public ConfigOrigin origin()+
public final class ConfigFactory
+extends java.lang.Object
+Config instances.
+
+
+ See also ConfigValueFactory which contains static methods for
+ converting Java values into a ConfigObject. You can then convert a
+ ConfigObject into a Config with ConfigObject.toConfig().
+
+
+ The static methods with "load" in the name do some sort of higher-level
+ operation potentially parsing multiple resources and resolving substitutions,
+ while the ones with "parse" in the name just create a ConfigValue
+ from a resource and nothing else.
+
+
You can find an example app and library on + GitHub. Also be sure to read the package + overview which describes the big picture as shown in those + examples.
| Modifier and Type | +Method and Description | +
|---|---|
static Config |
+defaultOverrides()
+Obtains the default override configuration, which currently consists of
+ system properties.
+ |
+
static Config |
+defaultOverrides(java.lang.ClassLoader loader)
+Like
+defaultOverrides() but allows you to specify a class loader
+ to use rather than the current context class loader. |
+
static Config |
+defaultReference()
+Obtains the default reference configuration, which is currently created
+ by merging all resources "reference.conf" found on the classpath and
+ overriding the result with system properties.
+ |
+
static Config |
+defaultReference(java.lang.ClassLoader loader)
+Like
+defaultReference() but allows you to specify a class loader
+ to use rather than the current context class loader. |
+
static Config |
+empty()
+Gets an empty configuration.
+ |
+
static Config |
+empty(java.lang.String originDescription)
+Gets an empty configuration with a description to be used to create a
+
+ConfigOrigin for this Config. |
+
static void |
+invalidateCaches()
+Reloads any cached configs, picking up changes to system properties for
+ example.
+ |
+
static Config |
+load()
+Loads a default configuration, equivalent to
+load("application") in most cases. |
+
static Config |
+load(java.lang.ClassLoader loader)
+Like
+load() but allows specifying a class loader other than the
+ thread's current context class loader. |
+
static Config |
+load(java.lang.ClassLoader loader,
+ Config config) |
+
static Config |
+load(java.lang.ClassLoader loader,
+ Config config,
+ ConfigResolveOptions resolveOptions)
+Like
+load(Config,ConfigResolveOptions) but allows you to specify
+ a class loader other than the context class loader. |
+
static Config |
+load(java.lang.ClassLoader loader,
+ ConfigParseOptions parseOptions)
+Like
+load() but allows specifying a class loader other than the
+ thread's current context class loader, and parse options |
+
static Config |
+load(java.lang.ClassLoader loader,
+ ConfigParseOptions parseOptions,
+ ConfigResolveOptions resolveOptions)
+Like
+load() but allows specifying a class loader other than the
+ thread's current context class loader, parse options, and resolve options |
+
static Config |
+load(java.lang.ClassLoader loader,
+ ConfigResolveOptions resolveOptions)
+Like
+load() but allows specifying a class loader other than the
+ thread's current context class loader, and resolve options |
+
static Config |
+load(java.lang.ClassLoader loader,
+ java.lang.String resourceBasename)
+Like
+load(String) but uses the supplied class loader instead of
+ the current thread's context class loader. |
+
static Config |
+load(java.lang.ClassLoader loader,
+ java.lang.String resourceBasename,
+ ConfigParseOptions parseOptions,
+ ConfigResolveOptions resolveOptions)
+Like
+load(String,ConfigParseOptions,ConfigResolveOptions) but
+ has a class loader parameter that overrides any from the
+ ConfigParseOptions. |
+
static Config |
+load(Config config)
+Assembles a standard configuration using a custom
+Config
+ object rather than loading "application.conf". |
+
static Config |
+load(Config config,
+ ConfigResolveOptions resolveOptions)
+Like
+load(Config) but allows you to specify
+ ConfigResolveOptions. |
+
static Config |
+load(ConfigParseOptions parseOptions)
+Like
+load() but allows specifying parse options |
+
static Config |
+load(java.lang.String resourceBasename)
+Loads an application's configuration from the given classpath resource or
+ classpath resource basename, sandwiches it between default reference
+ config and default overrides, and then resolves it.
+ |
+
static Config |
+load(java.lang.String resourceBasename,
+ ConfigParseOptions parseOptions,
+ ConfigResolveOptions resolveOptions)
+Like
+load(String) but allows you to specify parse and resolve
+ options. |
+
static Config |
+parseFile(java.io.File file) |
+
static Config |
+parseFile(java.io.File file,
+ ConfigParseOptions options) |
+
static Config |
+parseFileAnySyntax(java.io.File fileBasename) |
+
static Config |
+parseFileAnySyntax(java.io.File fileBasename,
+ ConfigParseOptions options)
+Parses a file with a flexible extension.
+ |
+
static Config |
+parseMap(java.util.Map<java.lang.String,? extends java.lang.Object> values)
+See the other overload of
+parseMap(Map, String) for details,
+ this one just uses a default origin description. |
+
static Config |
+parseMap(java.util.Map<java.lang.String,? extends java.lang.Object> values,
+ java.lang.String originDescription)
+Creates a
+Config based on a Map from paths to
+ plain Java values. |
+
static Config |
+parseProperties(java.util.Properties properties) |
+
static Config |
+parseProperties(java.util.Properties properties,
+ ConfigParseOptions options)
+Converts a Java
+Properties object to a
+ ConfigObject using the rules documented in the HOCON
+ spec. |
+
static Config |
+parseReader(java.io.Reader reader) |
+
static Config |
+parseReader(java.io.Reader reader,
+ ConfigParseOptions options) |
+
static Config |
+parseResources(java.lang.Class<?> klass,
+ java.lang.String resource) |
+
static Config |
+parseResources(java.lang.Class<?> klass,
+ java.lang.String resource,
+ ConfigParseOptions options)
+Parses all resources on the classpath with the given name and merges them
+ into a single
+Config. |
+
static Config |
+parseResources(java.lang.ClassLoader loader,
+ java.lang.String resource) |
+
static Config |
+parseResources(java.lang.ClassLoader loader,
+ java.lang.String resource,
+ ConfigParseOptions options)
+Parses all resources on the classpath with the given name and merges them
+ into a single
+Config. |
+
static Config |
+parseResources(java.lang.String resource)
+Like
+parseResources(ClassLoader,String) but uses thread's
+ current context class loader. |
+
static Config |
+parseResources(java.lang.String resource,
+ ConfigParseOptions options)
+Like
+parseResources(ClassLoader,String,ConfigParseOptions) but
+ uses thread's current context class loader. |
+
static Config |
+parseResourcesAnySyntax(java.lang.Class<?> klass,
+ java.lang.String resourceBasename) |
+
static Config |
+parseResourcesAnySyntax(java.lang.Class<?> klass,
+ java.lang.String resourceBasename,
+ ConfigParseOptions options)
+Parses classpath resources with a flexible extension.
+ |
+
static Config |
+parseResourcesAnySyntax(java.lang.ClassLoader loader,
+ java.lang.String resourceBasename) |
+
static Config |
+parseResourcesAnySyntax(java.lang.ClassLoader loader,
+ java.lang.String resourceBasename,
+ ConfigParseOptions options)
+Parses classpath resources with a flexible extension.
+ |
+
static Config |
+parseResourcesAnySyntax(java.lang.String resourceBasename)
+Like
+parseResourcesAnySyntax(ClassLoader,String) but uses
+ thread's current context class loader. |
+
static Config |
+parseResourcesAnySyntax(java.lang.String resourceBasename,
+ ConfigParseOptions options)
+Like
+
+parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions)
+ but uses thread's current context class loader. |
+
static Config |
+parseString(java.lang.String s) |
+
static Config |
+parseString(java.lang.String s,
+ ConfigParseOptions options) |
+
static Config |
+parseURL(java.net.URL url) |
+
static Config |
+parseURL(java.net.URL url,
+ ConfigParseOptions options) |
+
static Config |
+systemEnvironment()
+Gets a
+Config containing the system's environment variables. |
+
static Config |
+systemProperties()
+Gets a
+Config containing the system properties from
+ System.getProperties(), parsed and converted as with
+ parseProperties(java.util.Properties, com.typesafe.config.ConfigParseOptions). |
+
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitpublic static Config load(java.lang.String resourceBasename)+
ClassLoader.getResource(java.lang.String) not
+ Class.getResource(java.lang.String)).
+
+
+ Resources are loaded from the current thread's
+ Thread.getContextClassLoader(). In general, a library needs its
+ configuration to come from the class loader used to load that library, so
+ the proper "reference.conf" are present.
+
+
+ The loaded object will already be resolved (substitutions have already
+ been processed). As a result, if you add more fallbacks then they won't
+ be seen by substitutions. Substitutions are the "${foo.bar}" syntax. If
+ you want to parse additional files or something then you need to use
+ load(Config).
+
+
+ To load a standalone resource (without the default reference and default
+ overrides), use parseResourcesAnySyntax(String) rather than this
+ method. To load only the reference config use defaultReference()
+ and to load only the overrides use defaultOverrides().
resourceBasename - name (optionally without extension) of a resource on classpathpublic static Config load(java.lang.ClassLoader loader, + java.lang.String resourceBasename)+
load(String) but uses the supplied class loader instead of
+ the current thread's context class loader.
+
+
+ To load a standalone resource (without the default reference and default
+ overrides), use parseResourcesAnySyntax(ClassLoader, String)
+ rather than this method. To load only the reference config use
+ defaultReference(ClassLoader) and to load only the overrides use
+ defaultOverrides(ClassLoader).
loader - resourceBasename - public static Config load(java.lang.String resourceBasename, + ConfigParseOptions parseOptions, + ConfigResolveOptions resolveOptions)+
load(String) but allows you to specify parse and resolve
+ options.resourceBasename - the classpath resource name with optional extensionparseOptions - options to use when parsing the resourceresolveOptions - options to use when resolving the stackpublic static Config load(java.lang.ClassLoader loader, + java.lang.String resourceBasename, + ConfigParseOptions parseOptions, + ConfigResolveOptions resolveOptions)+
load(String,ConfigParseOptions,ConfigResolveOptions) but
+ has a class loader parameter that overrides any from the
+ ConfigParseOptions.loader - class loader in which to find resources (overrides loader in
+ parse options)resourceBasename - the classpath resource name with optional extensionparseOptions - options to use when parsing the resource (class loader
+ overridden)resolveOptions - options to use when resolving the stackpublic static Config load(Config config)+
Config
+ object rather than loading "application.conf". The Config
+ object will be sandwiched between the default reference config and
+ default overrides and then resolved.config - the application's portion of the configurationpublic static Config load(Config config, + ConfigResolveOptions resolveOptions)+
load(Config) but allows you to specify
+ ConfigResolveOptions.config - the application's portion of the configurationresolveOptions - options for resolving the assembled config stackpublic static Config load(java.lang.ClassLoader loader, + Config config, + ConfigResolveOptions resolveOptions)+
load(Config,ConfigResolveOptions) but allows you to specify
+ a class loader other than the context class loader.loader - class loader to use when looking up override and reference
+ configsconfig - the application's portion of the configurationresolveOptions - options for resolving the assembled config stackpublic static Config load()+
load("application") in most cases. This configuration should be used by
+ libraries and frameworks unless an application provides a different one.
+
+ This method may return a cached singleton so will not see changes to
+ system properties or config files. (Use invalidateCaches() to
+ force it to reload.)
+
+ If the system properties config.resource,
+ config.file, or config.url are set, then the
+ classpath resource, file, or URL specified in those properties will be
+ used rather than the default
+ application.{conf,json,properties} classpath resources.
+ These system properties should not be set in code (after all, you can
+ just parse whatever you want manually and then use load(Config)
+ if you don't want to use application.conf). The properties
+ are intended for use by the person or script launching the application.
+ For example someone might have a production.conf that
+ include application.conf but then change a couple of values.
+ When launching the app they could specify
+ -Dconfig.resource=production.conf to get production mode.
+
+ If no system properties are set to change the location of the default
+ configuration, ConfigFactory.load() is equivalent to
+ ConfigFactory.load("application").
public static Config load(ConfigParseOptions parseOptions)+
load() but allows specifying parse optionsparseOptions - Options for parsing resourcespublic static Config load(java.lang.ClassLoader loader)+
load() but allows specifying a class loader other than the
+ thread's current context class loader.loader - class loader for finding resourcespublic static Config load(java.lang.ClassLoader loader, + ConfigParseOptions parseOptions)+
load() but allows specifying a class loader other than the
+ thread's current context class loader, and parse optionsloader - class loader for finding resourcesparseOptions - Options for parsing resourcespublic static Config load(java.lang.ClassLoader loader, + ConfigResolveOptions resolveOptions)+
load() but allows specifying a class loader other than the
+ thread's current context class loader, and resolve optionsloader - class loader for finding resourcesresolveOptions - options for resolving the assembled config stackpublic static Config load(java.lang.ClassLoader loader, + ConfigParseOptions parseOptions, + ConfigResolveOptions resolveOptions)+
load() but allows specifying a class loader other than the
+ thread's current context class loader, parse options, and resolve optionsloader - class loader for finding resourcesparseOptions - Options for parsing resourcesresolveOptions - options for resolving the assembled config stackpublic static Config defaultReference()+
+ Libraries and frameworks should ship with a "reference.conf" in their + jar. + +
+ The reference config must be looked up in the class loader that contains
+ the libraries that you want to use with this config, so the
+ "reference.conf" for each library can be found. Use
+ defaultReference(ClassLoader) if the context class loader is not
+ suitable.
+
+
+ The load() methods merge this configuration for you
+ automatically.
+
+
+ Future versions may look for reference configuration in more places. It + is not guaranteed that this method only looks at + "reference.conf".
public static Config defaultReference(java.lang.ClassLoader loader)+
defaultReference() but allows you to specify a class loader
+ to use rather than the current context class loader.loader - public static Config defaultOverrides()+
+ The load() methods merge this configuration for you
+ automatically.
+
+
+ Future versions may get overrides in more places. It is not guaranteed + that this method only uses system properties.
public static Config defaultOverrides(java.lang.ClassLoader loader)+
defaultOverrides() but allows you to specify a class loader
+ to use rather than the current context class loader.loader - public static void invalidateCaches()+
Config is immutable, anyone with a reference
+ to the old configs will still have the same outdated objects. However,
+ new calls to load() or defaultOverrides() or
+ defaultReference() may return a new object.
+ + This method is primarily intended for use in unit tests, for example, + that may want to update a system property then confirm that it's used + correctly. In many cases, use of this method may indicate there's a + better way to set up your code. +
+ Caches may be reloaded immediately or lazily; once you call this method,
+ the reload can occur at any time, even during the invalidation process.
+ So FIRST make the changes you'd like the caches to notice, then SECOND
+ call this method to invalidate caches. Don't expect that invalidating,
+ making changes, then calling load(), will work. Make changes
+ before you invalidate.
public static Config empty()+
empty(String) to create an
+ empty configuration with a description, which may improve user-visible
+ error messages.public static Config empty(java.lang.String originDescription)+
ConfigOrigin for this Config. The description should
+ be very short and say what the configuration is, like "default settings"
+ or "foo settings" or something. (Presumably you will merge some actual
+ settings into this empty config using Config.withFallback(com.typesafe.config.ConfigMergeable), making
+ the description more useful.)originDescription - description of the configpublic static Config systemProperties()+
Config containing the system properties from
+ System.getProperties(), parsed and converted as with
+ parseProperties(java.util.Properties, com.typesafe.config.ConfigParseOptions).
+ + This method can return a global immutable singleton, so it's preferred + over parsing system properties yourself. +
+ load(java.lang.String) will include the system properties as overrides already, as
+ will defaultReference() and defaultOverrides().
+
+
+ Because this returns a singleton, it will not notice changes to system
+ properties made after the first time this method is called. Use
+ invalidateCaches() to force the singleton to reload if you
+ modify system properties.
Configpublic static Config systemEnvironment()+
Config containing the system's environment variables.
+ This method can return a global immutable singleton.
+
+
+ Environment variables are used as fallbacks when resolving substitutions
+ whether or not this object is included in the config being resolved, so
+ you probably don't need to use this method for most purposes. It can be a
+ nicer API for accessing environment variables than raw
+ System.getenv(String) though, since you can use methods
+ such as Config.getInt(java.lang.String).
Configpublic static Config parseProperties(java.util.Properties properties, + ConfigParseOptions options)+
Properties object to a
+ ConfigObject using the rules documented in the HOCON
+ spec. The keys in the Properties object are split on the
+ period character '.' and treated as paths. The values will all end up as
+ string values. If you have both "a=foo" and "a.b=bar" in your properties
+ file, so "a" is both the object containing "b" and the string "foo", then
+ the string value is dropped.
+
+
+ If you want to have System.getProperties() as a
+ ConfigObject, it's better to use the systemProperties() method
+ which returns a cached global singleton.
properties - a Java Properties objectoptions - public static Config parseProperties(java.util.Properties properties)+
public static Config parseReader(java.io.Reader reader, + ConfigParseOptions options)+
public static Config parseReader(java.io.Reader reader)+
public static Config parseURL(java.net.URL url, + ConfigParseOptions options)+
public static Config parseURL(java.net.URL url)+
public static Config parseFile(java.io.File file, + ConfigParseOptions options)+
public static Config parseFile(java.io.File file)+
public static Config parseFileAnySyntax(java.io.File fileBasename, + ConfigParseOptions options)+
fileBasename
+ already ends in a known extension, this method parses it according to
+ that extension (the file's syntax must match its extension). If the
+ fileBasename does not end in an extension, it parses files
+ with all known extensions and merges whatever is found.
+
+
+ In the current implementation, the extension ".conf" forces
+ ConfigSyntax.CONF, ".json" forces ConfigSyntax.JSON, and
+ ".properties" forces ConfigSyntax.PROPERTIES. When merging files,
+ ".conf" falls back to ".json" falls back to ".properties".
+
+
+ Future versions of the implementation may add additional syntaxes or + additional extensions. However, the ordering (fallback priority) of the + three current extensions will remain the same. + +
+ If options forces a specific syntax, this method only parses
+ files with an extension matching that syntax.
+
+
+ If options.getAllowMissing()
+ is true, then no files have to exist; if false, then at least one file
+ has to exist.
fileBasename - a filename with or without extensionoptions - parse optionspublic static Config parseFileAnySyntax(java.io.File fileBasename)+
public static Config parseResources(java.lang.Class<?> klass, + java.lang.String resource, + ConfigParseOptions options)+
Config.
+
+
+ If the resource name does not begin with a "/", it will have the supplied
+ class's package added to it, in the same way as
+ Class.getResource(java.lang.String).
+
+
+ Duplicate resources with the same name are merged such that ones returned
+ earlier from ClassLoader.getResources(java.lang.String) fall back to (have higher
+ priority than) the ones returned later. This implies that resources
+ earlier in the classpath override those later in the classpath when they
+ configure the same setting. However, in practice real applications may
+ not be consistent about classpath ordering, so be careful. It may be best
+ to avoid assuming too much.
klass - klass.getClassLoader() will be used to load
+ resources, and non-absolute resource names will have this
+ class's package addedresource - resource to look up, relative to klass's package
+ or absolute starting with a "/"options - parse optionspublic static Config parseResources(java.lang.Class<?> klass, + java.lang.String resource)+
public static Config parseResourcesAnySyntax(java.lang.Class<?> klass, + java.lang.String resourceBasename, + ConfigParseOptions options)+
parseFileAnySyntax(File,ConfigParseOptions) but for classpath
+ resources instead, as in parseResources(java.lang.Class<?>, java.lang.String, com.typesafe.config.ConfigParseOptions).
+
+
+ There is a thorny problem with this method, which is that
+ ClassLoader.getResources(java.lang.String) must be called separately for
+ each possible extension. The implementation ends up with separate lists
+ of resources called "basename.conf" and "basename.json" for example. As a
+ result, the ideal ordering between two files with different extensions is
+ unknown; there is no way to figure out how to merge the two lists in
+ classpath order. To keep it simple, the lists are simply concatenated,
+ with the same syntax priorities as
+ parseFileAnySyntax()
+ - all ".conf" resources are ahead of all ".json" resources which are
+ ahead of all ".properties" resources.
klass - class which determines the ClassLoader and the
+ package for relative resource namesresourceBasename - a resource name as in Class.getResource(java.lang.String),
+ with or without extensionoptions - parse options (class loader is ignored in favor of the one
+ from klass)public static Config parseResourcesAnySyntax(java.lang.Class<?> klass, + java.lang.String resourceBasename)+
public static Config parseResources(java.lang.ClassLoader loader, + java.lang.String resource, + ConfigParseOptions options)+
Config.
+
+
+ This works like ClassLoader.getResource(java.lang.String), not like
+ Class.getResource(java.lang.String), so the name never begins with a
+ slash.
+
+
+ See parseResources(Class,String,ConfigParseOptions) for full
+ details.
loader - will be used to load resources by setting this loader on the
+ provided optionsresource - resource to look upoptions - parse options (class loader is ignored)public static Config parseResources(java.lang.ClassLoader loader, + java.lang.String resource)+
public static Config parseResourcesAnySyntax(java.lang.ClassLoader loader, + java.lang.String resourceBasename, + ConfigParseOptions options)+
parseFileAnySyntax(File,ConfigParseOptions) but for classpath
+ resources instead, as in
+ parseResources(ClassLoader,String,ConfigParseOptions).
+
+
+ parseResourcesAnySyntax(Class,String,ConfigParseOptions) differs
+ in the syntax for the resource name, but otherwise see
+ parseResourcesAnySyntax(Class,String,ConfigParseOptions) for
+ some details and caveats on this method.
loader - class loader to look up resources in, will be set on optionsresourceBasename - a resource name as in
+ ClassLoader.getResource(java.lang.String), with or without
+ extensionoptions - parse options (class loader ignored)public static Config parseResourcesAnySyntax(java.lang.ClassLoader loader, + java.lang.String resourceBasename)+
public static Config parseResources(java.lang.String resource, + ConfigParseOptions options)+
parseResources(ClassLoader,String,ConfigParseOptions) but
+ uses thread's current context class loader.public static Config parseResources(java.lang.String resource)+
parseResources(ClassLoader,String) but uses thread's
+ current context class loader.public static Config parseResourcesAnySyntax(java.lang.String resourceBasename, + ConfigParseOptions options)+
parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions)
+ but uses thread's current context class loader.public static Config parseResourcesAnySyntax(java.lang.String resourceBasename)+
parseResourcesAnySyntax(ClassLoader,String) but uses
+ thread's current context class loader.public static Config parseString(java.lang.String s, + ConfigParseOptions options)+
public static Config parseString(java.lang.String s)+
public static Config parseMap(java.util.Map<java.lang.String,? extends java.lang.Object> values, + java.lang.String originDescription)+
Config based on a Map from paths to
+ plain Java values. Similar to
+ ConfigValueFactory.fromMap(Map,String), except the keys in the
+ map are path expressions, rather than keys; and correspondingly it
+ returns a Config instead of a ConfigObject. This is more
+ convenient if you are writing literal maps in code, and less convenient
+ if you are getting your maps from some data source such as a parser.
+
+ + An exception will be thrown (and it is a bug in the caller of the method) + if a path is both an object and a value, for example if you had both + "a=foo" and "a.b=bar", then "a" is both the string "foo" and the parent + object of "b". The caller of this method should ensure that doesn't + happen.
values - originDescription - description of what this map represents, like a filename, or
+ "default settings" (origin description is used in error
+ messages)Configpublic static Config parseMap(java.util.Map<java.lang.String,? extends java.lang.Object> values)+
parseMap(Map, String) for details,
+ this one just uses a default origin description.values - Configpublic interface ConfigIncludeContext
+ConfigIncluder; this interface is only useful
+ inside a ConfigIncluder implementation, and is not intended for apps
+ to implement.
+
+ + Do not implement this interface; it should only be implemented by + the config library. Arbitrary implementations will not work because the + library internals assume a specific concrete implementation. Also, this + interface is likely to grow new methods over time, so third-party + implementations will break.
| Modifier and Type | +Method and Description | +
|---|---|
ConfigParseOptions |
+parseOptions()
+Parse options to use (if you use another method to get a
+
+ConfigParseable then use ConfigParseable.options()
+ instead though). |
+
ConfigParseable |
+relativeTo(java.lang.String filename)
+Tries to find a name relative to whatever is doing the including, for
+ example in the same directory as the file doing the including.
+ |
+
ConfigParseable relativeTo(java.lang.String filename)+
filename - the name to make relative to the resource doing the includingConfigParseOptions parseOptions()+
ConfigParseable then use ConfigParseable.options()
+ instead though).public interface ConfigIncluder
+ConfigParseOptions.setIncluder() to
+ customize handling of include statements in config files. You may
+ also want to implement ConfigIncluderClasspath,
+ ConfigIncluderFile, and ConfigIncluderURL, or not.| Modifier and Type | +Method and Description | +
|---|---|
ConfigObject |
+include(ConfigIncludeContext context,
+ java.lang.String what)
+Parses another item to be included.
+ |
+
ConfigIncluder |
+withFallback(ConfigIncluder fallback)
+Returns a new includer that falls back to the given includer.
+ |
+
ConfigIncluder withFallback(ConfigIncluder fallback)+
fallback - ConfigObject include(ConfigIncludeContext context, + java.lang.String what)+
ConfigIncluder must
+ also implement ConfigIncluderClasspath,
+ ConfigIncluderFile, or ConfigIncluderURL as needed, or a
+ default includer will be used.context - some info about the include contextwhat - the include statement's argumentpublic interface ConfigIncluderClasspath
+ConfigIncluder if you want to
+ support inclusion of files with the include classpath("resource")
+ syntax. If you do not implement this but do implement ConfigIncluder,
+ attempts to load classpath resources will use the default includer.| Modifier and Type | +Method and Description | +
|---|---|
ConfigObject |
+includeResources(ConfigIncludeContext context,
+ java.lang.String what)
+Parses another item to be included.
+ |
+
ConfigObject includeResources(ConfigIncludeContext context, + java.lang.String what)+
context - some info about the include contextwhat - the include statement's argumentpublic interface ConfigIncluderFile
+ConfigIncluder if you want to
+ support inclusion of files with the include file("filename") syntax.
+ If you do not implement this but do implement ConfigIncluder,
+ attempts to load files will use the default includer.| Modifier and Type | +Method and Description | +
|---|---|
ConfigObject |
+includeFile(ConfigIncludeContext context,
+ java.io.File what)
+Parses another item to be included.
+ |
+
ConfigObject includeFile(ConfigIncludeContext context, + java.io.File what)+
context - some info about the include contextwhat - the include statement's argumentpublic interface ConfigIncluderURL
+ConfigIncluder if you want to
+ support inclusion of files with the include url("http://example.com")
+ syntax. If you do not implement this but do implement ConfigIncluder,
+ attempts to load URLs will use the default includer.| Modifier and Type | +Method and Description | +
|---|---|
ConfigObject |
+includeURL(ConfigIncludeContext context,
+ java.net.URL what)
+Parses another item to be included.
+ |
+
ConfigObject includeURL(ConfigIncludeContext context, + java.net.URL what)+
context - some info about the include contextwhat - the include statement's argumentpublic interface ConfigList +extends java.util.List<ConfigValue>, ConfigValue+
ConfigValue representing a list value, as in JSON's
+ [1,2,3] syntax.
+
+
+ ConfigList implements java.util.List<ConfigValue> so you can
+ use it like a regular Java list. Or call unwrapped() to unwrap the
+ list elements into plain Java values.
+
+
+ Like all ConfigValue subtypes, ConfigList is immutable. This
+ makes it threadsafe and you never have to create "defensive copies." The
+ mutator methods from List all throw
+ UnsupportedOperationException.
+
+
+ The ConfigValue.valueType() method on a list returns
+ ConfigValueType.LIST.
+
+
+ Do not implement ConfigList; it should only be implemented
+ by the config library. Arbitrary implementations will not work because the
+ library internals assume a specific concrete implementation. Also, this
+ interface is likely to grow new methods over time, so third-party
+ implementations will break.
| Modifier and Type | +Method and Description | +
|---|---|
java.util.List<java.lang.Object> |
+unwrapped()
+Recursively unwraps the list, returning a list of plain Java values such
+ as Integer or String or whatever is in the list.
+ |
+
add, add, addAll, addAll, clear, contains, containsAll, equals, get, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, retainAll, set, size, subList, toArray, toArrayatKey, atPath, origin, render, render, valueType, withFallbackjava.util.List<java.lang.Object> unwrapped()+
unwrapped in interface ConfigValuepublic interface ConfigMergeable
+Config and
+ ConfigValue. Instances of Config and ConfigValue can
+ be combined into a single new instance using the
+ withFallback() method.
+
+ + Do not implement this interface; it should only be implemented by + the config library. Arbitrary implementations will not work because the + library internals assume a specific concrete implementation. Also, this + interface is likely to grow new methods over time, so third-party + implementations will break.
| Modifier and Type | +Method and Description | +
|---|---|
ConfigMergeable |
+withFallback(ConfigMergeable other)
+Returns a new value computed by merging this value with another, with
+ keys in this value "winning" over the other one.
+ |
+
ConfigMergeable withFallback(ConfigMergeable other)+
+ This associative operation may be used to combine configurations from + multiple sources (such as multiple configuration files). + +
+ The semantics of merging are described in the spec + for HOCON. Merging typically occurs when either the same object is + created twice in the same file, or two config files are both loaded. For + example: + +
+ foo = { a: 42 }
+ foo = { b: 43 }
+
+
+ Here, the two objects are merged as if you had written:
+
+
+ foo = { a: 42, b: 43 }
+
+
+
+ Only ConfigObject and Config instances do anything in
+ this method (they need to merge the fallback keys into themselves). All
+ other values just return the original value, since they automatically
+ override any fallback. This means that objects do not merge "across"
+ non-objects; if you write
+ object.withFallback(nonObject).withFallback(otherObject),
+ then otherObject will simply be ignored. This is an
+ intentional part of how merging works, because non-objects such as
+ strings and integers replace (rather than merging with) any prior value:
+
+
+ foo = { a: 42 }
+ foo = 10
+
+
+ Here, the number 10 "wins" and the value of foo would be
+ simply 10. Again, for details see the spec.other - an object whose keys should be used as fallbacks, if the keys
+ are not present in this onepublic interface ConfigObject +extends ConfigValue, java.util.Map<java.lang.String,ConfigValue>+
ConfigValue representing an object (AKA dictionary or map)
+ value, as in JSON's curly brace { "a" : 42 } syntax.
+
+
+ An object may also be viewed as a Config by calling
+ toConfig().
+
+
+ ConfigObject implements java.util.Map<String, ConfigValue> so
+ you can use it like a regular Java map. Or call unwrapped() to
+ unwrap the map to a map with plain Java values rather than
+ ConfigValue.
+
+
+ Like all ConfigValue subtypes, ConfigObject is immutable.
+ This makes it threadsafe and you never have to create "defensive copies." The
+ mutator methods from Map all throw
+ UnsupportedOperationException.
+
+
+ The ConfigValue.valueType() method on an object returns
+ ConfigValueType.OBJECT.
+
+
+ In most cases you want to use the Config interface rather than this
+ one. Call toConfig() to convert a ConfigObject to a
+ Config.
+
+
+ The API for a ConfigObject is in terms of keys, while the API for a
+ Config is in terms of path expressions. Conceptually,
+ ConfigObject is a tree of maps from keys to values, while a
+ Config is a one-level map from paths to values.
+
+
+ Use ConfigUtil.joinPath(java.lang.String...) and ConfigUtil.splitPath(java.lang.String) to convert
+ between path expressions and individual path elements (keys).
+
+
+ A ConfigObject may contain null values, which will have
+ ConfigValue.valueType() equal to ConfigValueType.NULL. If
+ get(Object) returns Java's null then the key was not
+ present in the parsed file (or wherever this value tree came from). If
+ get("key") returns a ConfigValue with type
+ ConfigValueType#NULL then the key was set to null explicitly in the
+ config file.
+
+
+ Do not implement interface ConfigObject; it should only be
+ implemented by the config library. Arbitrary implementations will not work
+ because the library internals assume a specific concrete implementation.
+ Also, this interface is likely to grow new methods over time, so third-party
+ implementations will break.
java.util.Map.Entry<K,V>| Modifier and Type | +Method and Description | +
|---|---|
ConfigValue |
+get(java.lang.Object key)
+Gets a
+ConfigValue at the given key, or returns null if there is
+ no value. |
+
Config |
+toConfig()
+Converts this object to a
+Config instance, enabling you to use
+ path expressions to find values in the object. |
+
java.util.Map<java.lang.String,java.lang.Object> |
+unwrapped()
+Recursively unwraps the object, returning a map from String to whatever
+ plain Java values are unwrapped from the object's values.
+ |
+
ConfigObject |
+withFallback(ConfigMergeable other)
+Returns a new value computed by merging this value with another, with
+ keys in this value "winning" over the other one.
+ |
+
ConfigObject |
+withOnlyKey(java.lang.String key)
+Clone the object with only the given key (and its children) retained; all
+ sibling keys are removed.
+ |
+
ConfigObject |
+withoutKey(java.lang.String key)
+Clone the object with the given key removed.
+ |
+
ConfigObject |
+withValue(java.lang.String key,
+ ConfigValue value)
+Returns a
+ConfigObject based on this one, but with the given key
+ set to the given value. |
+
atKey, atPath, origin, render, render, valueTypeclear, containsKey, containsValue, entrySet, equals, hashCode, isEmpty, keySet, put, putAll, remove, size, valuesConfig toConfig()+
Config instance, enabling you to use
+ path expressions to find values in the object. This is a constant-time
+ operation (it is not proportional to the size of the object).Config with this object as its rootjava.util.Map<java.lang.String,java.lang.Object> unwrapped()+
unwrapped in interface ConfigValueMap containing plain Java objectsConfigObject withFallback(ConfigMergeable other)+
ConfigMergeable+ This associative operation may be used to combine configurations from + multiple sources (such as multiple configuration files). + +
+ The semantics of merging are described in the spec + for HOCON. Merging typically occurs when either the same object is + created twice in the same file, or two config files are both loaded. For + example: + +
+ foo = { a: 42 }
+ foo = { b: 43 }
+
+
+ Here, the two objects are merged as if you had written:
+
+
+ foo = { a: 42, b: 43 }
+
+
+
+ Only ConfigObject and Config instances do anything in
+ this method (they need to merge the fallback keys into themselves). All
+ other values just return the original value, since they automatically
+ override any fallback. This means that objects do not merge "across"
+ non-objects; if you write
+ object.withFallback(nonObject).withFallback(otherObject),
+ then otherObject will simply be ignored. This is an
+ intentional part of how merging works, because non-objects such as
+ strings and integers replace (rather than merging with) any prior value:
+
+
+ foo = { a: 42 }
+ foo = 10
+
+
+ Here, the number 10 "wins" and the value of foo would be
+ simply 10. Again, for details see the spec.withFallback in interface ConfigMergeablewithFallback in interface ConfigValueother - an object whose keys should be used as fallbacks, if the keys
+ are not present in this oneConfigValue get(java.lang.Object key)+
ConfigValue at the given key, or returns null if there is
+ no value. The returned ConfigValue may have
+ ConfigValueType.NULL or any other type, and the passed-in key
+ must be a key in this object (rather than a path expression).get in interface java.util.Map<java.lang.String,ConfigValue>key - key to look upConfigObject withOnlyKey(java.lang.String key)+
key - key to keepConfigObject withoutKey(java.lang.String key)+
key - key to removeConfigObject withValue(java.lang.String key, + ConfigValue value)+
ConfigObject based on this one, but with the given key
+ set to the given value. Does not modify this instance (since it's
+ immutable). If the key already has a value, that value is replaced. To
+ remove a value, use withoutKey(String).key - key to addvalue - value at the new keypublic interface ConfigOrigin
+ConfigValue for use in error messages. Obtain the origin of a value
+ with ConfigValue.origin(). Exceptions may have an origin, see
+ ConfigException.origin, but be careful because
+ ConfigException.origin() may return null.
+
+ + It's best to use this interface only for debugging; its accuracy is + "best effort" rather than guaranteed, and a potentially-noticeable amount of + memory could probably be saved if origins were not kept around, so in the + future there might be some option to discard origins. + +
+ Do not implement this interface; it should only be implemented by + the config library. Arbitrary implementations will not work because the + library internals assume a specific concrete implementation. Also, this + interface is likely to grow new methods over time, so third-party + implementations will break.
| Modifier and Type | +Method and Description | +
|---|---|
java.util.List<java.lang.String> |
+comments()
+Returns any comments that appeared to "go with" this place in the file.
+ |
+
java.lang.String |
+description()
+Returns a string describing the origin of a value or exception.
+ |
+
java.lang.String |
+filename()
+Returns a filename describing the origin.
+ |
+
int |
+lineNumber()
+Returns a line number where the value or exception originated.
+ |
+
java.lang.String |
+resource()
+Returns a classpath resource name describing the origin.
+ |
+
java.net.URL |
+url()
+Returns a URL describing the origin.
+ |
+
java.lang.String description()+
java.lang.String filename()+
java.net.URL url()+
java.lang.String resource()+
int lineNumber()+
java.util.List<java.lang.String> comments()+
public final class ConfigParseOptions
+extends java.lang.Object
++ This object is immutable, so the "setters" return a new object. + +
+ Here is an example of creating a custom ConfigParseOptions:
+
+
+ ConfigParseOptions options = ConfigParseOptions.defaults() + .setSyntax(ConfigSyntax.JSON) + .setAllowMissing(false) +
| Modifier and Type | +Method and Description | +
|---|---|
ConfigParseOptions |
+appendIncluder(ConfigIncluder includer) |
+
static ConfigParseOptions |
+defaults() |
+
boolean |
+getAllowMissing() |
+
java.lang.ClassLoader |
+getClassLoader()
+Get the class loader; never returns
+null, if the class loader was
+ unset, returns
+ Thread.currentThread().getContextClassLoader(). |
+
ConfigIncluder |
+getIncluder() |
+
java.lang.String |
+getOriginDescription() |
+
ConfigSyntax |
+getSyntax() |
+
ConfigParseOptions |
+prependIncluder(ConfigIncluder includer) |
+
ConfigParseOptions |
+setAllowMissing(boolean allowMissing)
+Set to false to throw an exception if the item being parsed (for example
+ a file) is missing.
+ |
+
ConfigParseOptions |
+setClassLoader(java.lang.ClassLoader loader)
+Set the class loader.
+ |
+
ConfigParseOptions |
+setIncluder(ConfigIncluder includer)
+Set a ConfigIncluder which customizes how includes are handled.
+ |
+
ConfigParseOptions |
+setOriginDescription(java.lang.String originDescription)
+Set a description for the thing being parsed.
+ |
+
ConfigParseOptions |
+setSyntax(ConfigSyntax syntax)
+Set the file format.
+ |
+
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitpublic static ConfigParseOptions defaults()+
public ConfigParseOptions setSyntax(ConfigSyntax syntax)+
ConfigSyntax.CONF.syntax - a syntax or null for best guesspublic ConfigSyntax getSyntax()+
public ConfigParseOptions setOriginDescription(java.lang.String originDescription)+
ConfigOrigin of the parsed values.originDescription - public java.lang.String getOriginDescription()+
public ConfigParseOptions setAllowMissing(boolean allowMissing)+
allowMissing - public boolean getAllowMissing()+
public ConfigParseOptions setIncluder(ConfigIncluder includer)+
includer - public ConfigParseOptions prependIncluder(ConfigIncluder includer)+
public ConfigParseOptions appendIncluder(ConfigIncluder includer)+
public ConfigIncluder getIncluder()+
public ConfigParseOptions setClassLoader(java.lang.ClassLoader loader)+
Thread.currentThread().getContextClassLoader() will be used.loader - a class loader or null to use thread context class
+ loaderpublic java.lang.ClassLoader getClassLoader()+
null, if the class loader was
+ unset, returns
+ Thread.currentThread().getContextClassLoader().public interface ConfigParseable
+ConfigIncludeContext.
+
+ + Do not implement this interface; it should only be implemented by + the config library. Arbitrary implementations will not work because the + library internals assume a specific concrete implementation. Also, this + interface is likely to grow new methods over time, so third-party + implementations will break.
| Modifier and Type | +Method and Description | +
|---|---|
ConfigParseOptions |
+options()
+Get the initial options, which can be modified then passed to parse().
+ |
+
ConfigOrigin |
+origin()
+Returns a
+ConfigOrigin describing the origin of the parseable
+ item. |
+
ConfigObject |
+parse(ConfigParseOptions options)
+Parse whatever it is.
+ |
+
ConfigObject parse(ConfigParseOptions options)+
options() but you could tweak them if you
+ like.options - parse options, should be based on the ones from
+ options()ConfigOrigin origin()+
ConfigOrigin describing the origin of the parseable
+ item.ConfigParseOptions options()+
public final class ConfigRenderOptions
+extends java.lang.Object
+
+ A set of options related to rendering a ConfigValue. Passed to
+ ConfigValue.render(ConfigRenderOptions).
+
+
+ Here is an example of creating a ConfigRenderOptions:
+
+
+ ConfigRenderOptions options = + ConfigRenderOptions.defaults().setComments(false) +
| Modifier and Type | +Method and Description | +
|---|---|
static ConfigRenderOptions |
+concise()
+Returns concise render options (no whitespace or comments).
+ |
+
static ConfigRenderOptions |
+defaults()
+Returns the default render options which are verbose (commented and
+ formatted).
+ |
+
boolean |
+getComments()
+Returns whether the options enable comments.
+ |
+
boolean |
+getFormatted()
+Returns whether the options enable formatting.
+ |
+
boolean |
+getJson()
+Returns whether the options enable JSON.
+ |
+
boolean |
+getOriginComments()
+Returns whether the options enable automated origin comments.
+ |
+
ConfigRenderOptions |
+setComments(boolean value)
+Returns options with comments toggled.
+ |
+
ConfigRenderOptions |
+setFormatted(boolean value)
+Returns options with formatting toggled.
+ |
+
ConfigRenderOptions |
+setJson(boolean value)
+Returns options with JSON toggled.
+ |
+
ConfigRenderOptions |
+setOriginComments(boolean value)
+Returns options with origin comments toggled.
+ |
+
java.lang.String |
+toString() |
+
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitpublic static ConfigRenderOptions defaults()+
concise() for stripped-down
+ options. This rendering will not be valid JSON since it has comments.public static ConfigRenderOptions concise()+
Config, the concise rendering will be valid JSON.public ConfigRenderOptions setComments(boolean value)+
setOriginComments(boolean).value - true to include comments in the renderpublic boolean getComments()+
public ConfigRenderOptions setOriginComments(boolean value)+
ConfigValue.origin() of that setting's value. For example these
+ comments might tell you which file a setting comes from.
+
+
+ setOriginComments() controls only these autogenerated
+ "origin of this setting" comments, to toggle regular comments use
+ setComments(boolean).
value - true to include autogenerated setting-origin comments in the
+ renderpublic boolean getOriginComments()+
public ConfigRenderOptions setFormatted(boolean value)+
value - true to include comments in the renderpublic boolean getFormatted()+
public ConfigRenderOptions setJson(boolean value)+
setComments(boolean)
+ and setOriginComments(boolean) options. So if you enable
+ comments you will get invalid JSON despite setting this to true.value - true to include non-JSON extensions in the renderpublic boolean getJson()+
public java.lang.String toString()+
toString in class java.lang.Objectpublic final class ConfigResolveOptions
+extends java.lang.Object
+${foo.bar} syntax and are documented in the HOCON
+ spec.
+
+ Typically this class would be used with the method
+ Config.resolve(ConfigResolveOptions).
+
+ This object is immutable, so the "setters" return a new object. +
+ Here is an example of creating a custom ConfigResolveOptions:
+
+
+ ConfigResolveOptions options = ConfigResolveOptions.defaults() + .setUseSystemEnvironment(false) ++
+ In addition to defaults(), there's a prebuilt
+ noSystem() which avoids looking at any system
+ environment variables or other external system information. (Right now,
+ environment variables are the only example.)
| Modifier and Type | +Method and Description | +
|---|---|
static ConfigResolveOptions |
+defaults()
+Returns the default resolve options.
+ |
+
boolean |
+getAllowUnresolved()
+Returns whether the options allow unresolved substitutions.
+ |
+
boolean |
+getUseSystemEnvironment()
+Returns whether the options enable use of system environment variables.
+ |
+
static ConfigResolveOptions |
+noSystem()
+Returns resolve options that disable any reference to "system" data
+ (currently, this means environment variables).
+ |
+
ConfigResolveOptions |
+setAllowUnresolved(boolean value)
+Returns options with "allow unresolved" set to the given value.
+ |
+
ConfigResolveOptions |
+setUseSystemEnvironment(boolean value)
+Returns options with use of environment variables set to the given value.
+ |
+
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitpublic static ConfigResolveOptions defaults()+
public static ConfigResolveOptions noSystem()+
public ConfigResolveOptions setUseSystemEnvironment(boolean value)+
value - true to resolve substitutions falling back to environment
+ variables.public boolean getUseSystemEnvironment()+
public ConfigResolveOptions setAllowUnresolved(boolean value)+
Config.resolve(ConfigResolveOptions) itself
+ will now throw.value - true to silently ignore unresolved substitutions.public boolean getAllowUnresolved()+
public enum ConfigSyntax +extends java.lang.Enum<ConfigSyntax>+ +
| Enum Constant and Description | +
|---|
CONF
+The JSON-superset HOCON format.
+ |
+
JSON
+Pedantically strict JSON format; no
+ comments, no unexpected commas, no duplicate keys in the same object.
+ |
+
PROPERTIES
+Standard Java properties format.
+ |
+
| Modifier and Type | +Method and Description | +
|---|---|
static ConfigSyntax |
+valueOf(java.lang.String name)
+Returns the enum constant of this type with the specified name.
+ |
+
static ConfigSyntax[] |
+values()
+Returns an array containing the constants of this enum type, in
+the order they are declared.
+ |
+
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOfgetClass, notify, notifyAll, wait, wait, waitpublic static final ConfigSyntax JSON+
.json file extension and
+ application/json Content-Type.public static final ConfigSyntax CONF+
.conf file extension
+ and application/hocon Content-Type.public static final ConfigSyntax PROPERTIES+
.properties
+ file extension and text/x-java-properties Content-Type.public static ConfigSyntax[] values()+
+for (ConfigSyntax c : ConfigSyntax.values()) + System.out.println(c); +
public static ConfigSyntax valueOf(java.lang.String name)+
name - the name of the enum constant to be returned.java.lang.IllegalArgumentException - if this enum type has no constant
+with the specified namejava.lang.NullPointerException - if the argument is nullpublic final class ConfigUtil
+extends java.lang.Object
+| Modifier and Type | +Method and Description | +
|---|---|
static java.lang.String |
+joinPath(java.util.List<java.lang.String> elements)
+Converts a list of strings to a path expression, by quoting the path
+ elements as needed and then joining them separated by a period.
+ |
+
static java.lang.String |
+joinPath(java.lang.String... elements)
+Converts a list of keys to a path expression, by quoting the path
+ elements as needed and then joining them separated by a period.
+ |
+
static java.lang.String |
+quoteString(java.lang.String s)
+Quotes and escapes a string, as in the JSON specification.
+ |
+
static java.util.List<java.lang.String> |
+splitPath(java.lang.String path)
+Converts a path expression into a list of keys, by splitting on period
+ and unquoting the individual path elements.
+ |
+
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitpublic static java.lang.String quoteString(java.lang.String s)+
s - a stringpublic static java.lang.String joinPath(java.lang.String... elements)+
Config, while individual path
+ elements are usable with a ConfigObject.elements - the keys in the pathConfigException - if there are no elementspublic static java.lang.String joinPath(java.util.List<java.lang.String> elements)+
Config, while individual path
+ elements are usable with a ConfigObject.elements - the keys in the pathConfigException - if the list is emptypublic static java.util.List<java.lang.String> splitPath(java.lang.String path)+
Config, while individual path elements are usable with a
+ ConfigObject.path - a path expressionConfigException - if the path expression is invalidpublic interface ConfigValue +extends ConfigMergeable+
+ Because this object is immutable, it is safe to use from multiple threads and + there's no need for "defensive copies." + +
+ Do not implement interface ConfigValue; it should only be
+ implemented by the config library. Arbitrary implementations will not work
+ because the library internals assume a specific concrete implementation.
+ Also, this interface is likely to grow new methods over time, so third-party
+ implementations will break.
| Modifier and Type | +Method and Description | +
|---|---|
Config |
+atKey(java.lang.String key)
+Places the value inside a
+Config at the given key. |
+
Config |
+atPath(java.lang.String path)
+Places the value inside a
+Config at the given path. |
+
ConfigOrigin |
+origin()
+The origin of the value (file, line number, etc.), for debugging and
+ error messages.
+ |
+
java.lang.String |
+render()
+Renders the config value as a HOCON string.
+ |
+
java.lang.String |
+render(ConfigRenderOptions options)
+Renders the config value to a string, using the provided options.
+ |
+
java.lang.Object |
+unwrapped()
+Returns the value as a plain Java boxed value, that is, a
+String,
+ Number, Boolean, Map<String,Object>,
+ List<Object>, or null, matching the valueType()
+ of this ConfigValue. |
+
ConfigValueType |
+valueType()
+The
+ConfigValueType of the value; matches the JSON type schema. |
+
ConfigValue |
+withFallback(ConfigMergeable other)
+Returns a new value computed by merging this value with another, with
+ keys in this value "winning" over the other one.
+ |
+
ConfigOrigin origin()+
ConfigValueType valueType()+
ConfigValueType of the value; matches the JSON type schema.java.lang.Object unwrapped()+
String,
+ Number, Boolean, Map<String,Object>,
+ List<Object>, or null, matching the valueType()
+ of this ConfigValue. If the value is a ConfigObject or
+ ConfigList, it is recursively unwrapped.java.lang.String render()+
+ If the config value has not been resolved (see Config.resolve()),
+ it's possible that it can't be rendered as valid HOCON. In that case the
+ rendering should still be useful for debugging but you might not be able
+ to parse it. If the value has been resolved, it will always be parseable.
+
+
+ This method is equivalent to
+ render(ConfigRenderOptions.defaults()).
java.lang.String render(ConfigRenderOptions options)+
+ If the config value has not been resolved (see Config.resolve()),
+ it's possible that it can't be rendered as valid HOCON. In that case the
+ rendering should still be useful for debugging but you might not be able
+ to parse it. If the value has been resolved, it will always be parseable.
+
+
+ If the config value has been resolved and the options disable all + HOCON-specific features (such as comments), the rendering will be valid + JSON. If you enable HOCON-only features such as comments, the rendering + will not be valid JSON.
options - the rendering optionsConfigValue withFallback(ConfigMergeable other)+
ConfigMergeable+ This associative operation may be used to combine configurations from + multiple sources (such as multiple configuration files). + +
+ The semantics of merging are described in the spec + for HOCON. Merging typically occurs when either the same object is + created twice in the same file, or two config files are both loaded. For + example: + +
+ foo = { a: 42 }
+ foo = { b: 43 }
+
+
+ Here, the two objects are merged as if you had written:
+
+
+ foo = { a: 42, b: 43 }
+
+
+
+ Only ConfigObject and Config instances do anything in
+ this method (they need to merge the fallback keys into themselves). All
+ other values just return the original value, since they automatically
+ override any fallback. This means that objects do not merge "across"
+ non-objects; if you write
+ object.withFallback(nonObject).withFallback(otherObject),
+ then otherObject will simply be ignored. This is an
+ intentional part of how merging works, because non-objects such as
+ strings and integers replace (rather than merging with) any prior value:
+
+
+ foo = { a: 42 }
+ foo = 10
+
+
+ Here, the number 10 "wins" and the value of foo would be
+ simply 10. Again, for details see the spec.withFallback in interface ConfigMergeableother - an object whose keys should be used as fallbacks, if the keys
+ are not present in this oneConfig atPath(java.lang.String path)+
Config at the given path. See also
+ atKey(String).path - path to store this value at.Config instance containing this value at the given
+ path.Config atKey(java.lang.String key)+
Config at the given key. See also
+ atPath(String).key - key to store this value at.Config instance containing this value at the given key.public final class ConfigValueFactory
+extends java.lang.Object
+ConfigValue
+ instances. See also ConfigFactory which has methods for parsing files
+ and certain in-memory data structures.| Modifier and Type | +Method and Description | +
|---|---|
static ConfigValue |
+fromAnyRef(java.lang.Object object)
+See the other overload
+fromAnyRef(Object,String) for details,
+ this one just uses a default origin description. |
+
static ConfigValue |
+fromAnyRef(java.lang.Object object,
+ java.lang.String originDescription)
+Creates a
+ConfigValue from a plain Java boxed value, which may be
+ a Boolean, Number, String,
+ Map, Iterable, or null. |
+
static ConfigList |
+fromIterable(java.lang.Iterable<? extends java.lang.Object> values)
+See the other overload of
+fromIterable(Iterable, String) for
+ details, this one just uses a default origin description. |
+
static ConfigList |
+fromIterable(java.lang.Iterable<? extends java.lang.Object> values,
+ java.lang.String originDescription)
+See the
+fromAnyRef(Object,String) documentation for details. |
+
static ConfigObject |
+fromMap(java.util.Map<java.lang.String,? extends java.lang.Object> values)
+See the other overload
+fromMap(Map,String) for details, this one
+ just uses a default origin description. |
+
static ConfigObject |
+fromMap(java.util.Map<java.lang.String,? extends java.lang.Object> values,
+ java.lang.String originDescription)
+See the
+fromAnyRef(Object,String) documentation for details. |
+
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitpublic static ConfigValue fromAnyRef(java.lang.Object object, + java.lang.String originDescription)+
ConfigValue from a plain Java boxed value, which may be
+ a Boolean, Number, String,
+ Map, Iterable, or null. A
+ Map must be a Map from String to more values
+ that can be supplied to fromAnyRef(). An
+ Iterable must iterate over more values that can be supplied
+ to fromAnyRef(). A Map will become a
+ ConfigObject and an Iterable will become a
+ ConfigList. If the Iterable is not an ordered
+ collection, results could be strange, since ConfigList is
+ ordered.
+
+
+ In a Map passed to fromAnyRef(), the map's keys
+ are plain keys, not path expressions. So if your Map has a
+ key "foo.bar" then you will get one object with a key called "foo.bar",
+ rather than an object with a key "foo" containing another object with a
+ key "bar".
+
+
+ The originDescription will be used to set the origin() field on the + ConfigValue. It should normally be the name of the file the values came + from, or something short describing the value such as "default settings". + The originDescription is prefixed to error messages so users can tell + where problematic values are coming from. + +
+ Supplying the result of ConfigValue.unwrapped() to this function is + guaranteed to work and should give you back a ConfigValue that matches + the one you unwrapped. The re-wrapped ConfigValue will lose some + information that was present in the original such as its origin, but it + will have matching values. + +
+ This function throws if you supply a value that cannot be converted to a + ConfigValue, but supplying such a value is a bug in your program, so you + should never handle the exception. Just fix your program (or report a bug + against this library).
object - object to convert to ConfigValueoriginDescription - name of origin file or brief description of what the value ispublic static ConfigObject fromMap(java.util.Map<java.lang.String,? extends java.lang.Object> values, + java.lang.String originDescription)+
fromAnyRef(Object,String) documentation for details.
+ This is a typesafe wrapper that only works on Map and
+ returns ConfigObject rather than ConfigValue.
+
+
+ If your Map has a key "foo.bar" then you will get one object
+ with a key called "foo.bar", rather than an object with a key "foo"
+ containing another object with a key "bar". The keys in the map are keys;
+ not path expressions. That is, the Map corresponds exactly
+ to a single ConfigObject. The keys will not be parsed or
+ modified, and the values are wrapped in ConfigValue. To get nested
+ ConfigObject, some of the values in the map would have to be more
+ maps.
+
+
+ See also ConfigFactory.parseMap(Map,String) which interprets the
+ keys in the map as path expressions.
values - originDescription - ConfigObject valuepublic static ConfigList fromIterable(java.lang.Iterable<? extends java.lang.Object> values, + java.lang.String originDescription)+
fromAnyRef(Object,String) documentation for details.
+ This is a typesafe wrapper that only works on Iterable
+ and returns ConfigList rather than ConfigValue.values - originDescription - ConfigList valuepublic static ConfigValue fromAnyRef(java.lang.Object object)+
fromAnyRef(Object,String) for details,
+ this one just uses a default origin description.object - ConfigValuepublic static ConfigObject fromMap(java.util.Map<java.lang.String,? extends java.lang.Object> values)+
fromMap(Map,String) for details, this one
+ just uses a default origin description.
+
+
+ See also ConfigFactory.parseMap(Map) which interprets the keys in
+ the map as path expressions.
values - ConfigObjectpublic static ConfigList fromIterable(java.lang.Iterable<? extends java.lang.Object> values)+
fromIterable(Iterable, String) for
+ details, this one just uses a default origin description.values - ConfigListpublic enum ConfigValueType +extends java.lang.Enum<ConfigValueType>+
| Enum Constant and Description | +
|---|
BOOLEAN |
+
LIST |
+
NULL |
+
NUMBER |
+
OBJECT |
+
STRING |
+
| Modifier and Type | +Method and Description | +
|---|---|
static ConfigValueType |
+valueOf(java.lang.String name)
+Returns the enum constant of this type with the specified name.
+ |
+
static ConfigValueType[] |
+values()
+Returns an array containing the constants of this enum type, in
+the order they are declared.
+ |
+
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOfgetClass, notify, notifyAll, wait, wait, waitpublic static final ConfigValueType OBJECT+
public static final ConfigValueType LIST+
public static final ConfigValueType NUMBER+
public static final ConfigValueType BOOLEAN+
public static final ConfigValueType NULL+
public static final ConfigValueType STRING+
public static ConfigValueType[] values()+
+for (ConfigValueType c : ConfigValueType.values()) + System.out.println(c); +
public static ConfigValueType valueOf(java.lang.String name)+
name - the name of the enum constant to be returned.java.lang.IllegalArgumentException - if this enum type has no constant
+with the specified namejava.lang.NullPointerException - if the argument is nullSee: Description
+| Interface | +Description | +
|---|---|
| Config | +
+ An immutable map from config paths to config values.
+ |
+
| ConfigIncludeContext | +
+ Context provided to a
+ConfigIncluder; this interface is only useful
+ inside a ConfigIncluder implementation, and is not intended for apps
+ to implement. |
+
| ConfigIncluder | +
+ Implement this interface and provide an instance to
+
+ConfigParseOptions.setIncluder() to
+ customize handling of include statements in config files. |
+
| ConfigIncluderClasspath | +
+ Implement this in addition to
+ConfigIncluder if you want to
+ support inclusion of files with the include classpath("resource")
+ syntax. |
+
| ConfigIncluderFile | +
+ Implement this in addition to
+ConfigIncluder if you want to
+ support inclusion of files with the include file("filename") syntax. |
+
| ConfigIncluderURL | +
+ Implement this in addition to
+ConfigIncluder if you want to
+ support inclusion of files with the include url("http://example.com")
+ syntax. |
+
| ConfigList | +
+ Subtype of
+ConfigValue representing a list value, as in JSON's
+ [1,2,3] syntax. |
+
| ConfigMergeable | +
+ Marker for types whose instances can be merged, that is
+Config and
+ ConfigValue. |
+
| ConfigObject | +
+ Subtype of
+ConfigValue representing an object (AKA dictionary or map)
+ value, as in JSON's curly brace { "a" : 42 } syntax. |
+
| ConfigOrigin | +
+ Represents the origin (such as filename and line number) of a
+
+ConfigValue for use in error messages. |
+
| ConfigParseable | +
+ An opaque handle to something that can be parsed, obtained from
+
+ConfigIncludeContext. |
+
| ConfigValue | +
+ An immutable value, following the JSON type
+ schema.
+ |
+
| Class | +Description | +
|---|---|
| ConfigException.ValidationProblem | +
+ Information about a problem that occurred in
+Config.checkValid(com.typesafe.config.Config, java.lang.String...). |
+
| ConfigFactory | +
+ Contains static methods for creating
+Config instances. |
+
| ConfigParseOptions | +
+ A set of options related to parsing.
+ |
+
| ConfigRenderOptions | +
+
+ A set of options related to rendering a
+ConfigValue. |
+
| ConfigResolveOptions | +
+ A set of options related to resolving substitutions.
+ |
+
| ConfigUtil | +
+ Contains static utility methods.
+ |
+
| ConfigValueFactory | +
+ This class holds some static factory methods for building
+ConfigValue
+ instances. |
+
| Enum | +Description | +
|---|---|
| ConfigSyntax | ++ + | +
| ConfigValueType | +
+ The type of a configuration value (following the JSON type schema).
+ |
+
| Exception | +Description | +
|---|---|
| ConfigException | +
+ All exceptions thrown by the library are subclasses of
+
+ConfigException. |
+
| ConfigException.BadPath | +
+ Exception indicating that a path expression was invalid.
+ |
+
| ConfigException.BadValue | +
+ Exception indicating that a value was messed up, for example you may have
+ asked for a duration and the value can't be sensibly parsed as a
+ duration.
+ |
+
| ConfigException.BugOrBroken | +
+ Exception indicating that there's a bug in something (possibly the
+ library itself) or the runtime environment is broken.
+ |
+
| ConfigException.Generic | +
+ Exception that doesn't fall into any other category.
+ |
+
| ConfigException.IO | +
+ Exception indicating that there was an IO error.
+ |
+
| ConfigException.Missing | +
+ Exception indicates that the setting was never set to anything, not even
+ null.
+ |
+
| ConfigException.NotResolved | +
+ Exception indicating that you tried to use a function that requires
+ substitutions to be resolved, but substitutions have not been resolved
+ (that is,
+Config.resolve() was not called). |
+
| ConfigException.Null | +
+ Exception indicates that the setting was treated as missing because it
+ was set to null.
+ |
+
| ConfigException.Parse | +
+ Exception indicating that there was a parse error.
+ |
+
| ConfigException.UnresolvedSubstitution | +
+ Exception indicating that a substitution did not resolve to anything.
+ |
+
| ConfigException.ValidationFailed | +
+ Exception indicating that
+Config.checkValid(com.typesafe.config.Config, java.lang.String...) found validity
+ problems. |
+
| ConfigException.WrongType | +
+ Exception indicating that the type of a value does not match the type you
+ requested.
+ |
+
+An API for loading and using configuration files, see the project site +for more information. +
+ +
+Typically you would load configuration with a static method from ConfigFactory and then use
+it with methods in the Config interface. Configuration may be in the form of JSON files,
+Java properties, or HOCON files; you may also
+build your own configuration in code or from your own file formats.
+
+An application can simply call ConfigFactory.load() and place
+its configuration in "application.conf" on the classpath.
+If you use the default configuration from ConfigFactory.load()
+there's no need to pass a configuration to your libraries
+and frameworks, as long as they all default to this same default, which they should.
+
Example application code: Java and Scala.
+
Showing a couple of more special-purpose features, a more complex example: Java and Scala.
+
+A library or framework should ship a file "reference.conf" in its jar, and allow an application to pass in a
+Config to be used for the library. If no Config is provided,
+call ConfigFactory.load()
+to get the default one. Typically a library might offer two constructors, one with a Config parameter
+and one which uses ConfigFactory.load().
+
Example library code: Java and Scala.
+
+Check out the full examples directory on GitHub. +
+ ++What else to read: +
Config..conf files in addition to .json and .properties,
+ see the README for some short examples
+ and the full HOCON spec for the long version.| Method and Description | +
|---|
| com.typesafe.config.Config.getMilliseconds(String)
+ As of release 1.1, replaced by
+Config.getDuration(String, TimeUnit) |
+
| com.typesafe.config.Config.getMillisecondsList(String)
+ As of release 1.1, replaced by
+Config.getDurationList(String, TimeUnit) |
+
| com.typesafe.config.Config.getNanoseconds(String)
+ As of release 1.1, replaced by
+Config.getDuration(String, TimeUnit) |
+
| com.typesafe.config.Config.getNanosecondsList(String)
+ As of release 1.1, replaced by
+Config.getDurationList(String, TimeUnit) |
+
Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain six categories:
+Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:
+Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.
+Each annotation type has its own separate page with the following sections:
+Each enum has its own separate page with the following sections:
+There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object. The interfaces do not inherit from java.lang.Object.
The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.
+The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.
+These links take you to the next or previous class, interface, package, or related page.
+These links show and hide the HTML frames. All pages are available with or without frames.
+The All Classes link shows all classes and interfaces except non-static nested types.
+Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.
+The Constant Field Values page lists the static final fields and their values.
+Config at the given key.Config at the given key.Config at the given path.Config at the given path.ConfigException.Config.resolve() was not called).Config.checkValid(com.typesafe.config.Config, java.lang.String...) found validity
+ problems.Config.checkValid(com.typesafe.config.Config, java.lang.String...).Config instances.ConfigIncluder; this interface is only useful
+ inside a ConfigIncluder implementation, and is not intended for apps
+ to implement.ConfigParseOptions.setIncluder() to
+ customize handling of include statements in config files.ConfigIncluder if you want to
+ support inclusion of files with the include classpath("resource")
+ syntax.ConfigIncluder if you want to
+ support inclusion of files with the include file("filename") syntax.ConfigIncluder if you want to
+ support inclusion of files with the include url("http://example.com")
+ syntax.ConfigValue representing a list value, as in JSON's
+ [1,2,3] syntax.Config and
+ ConfigValue.ConfigValue representing an object (AKA dictionary or map)
+ value, as in JSON's curly brace { "a" : 42 } syntax.ConfigValue for use in error messages.ConfigIncludeContext.ConfigValue.ConfigValue
+ instances.ConfigFactory.defaultOverrides() but allows you to specify a class loader
+ to use rather than the current context class loader.ConfigFactory.defaultReference() but allows you to specify a class loader
+ to use rather than the current context class loader.ConfigOrigin for this Config.the root object.ConfigValue from a plain Java boxed value, which may be
+ a Boolean, Number, String,
+ Map, Iterable, or null.ConfigValueFactory.fromAnyRef(Object,String) for details,
+ this one just uses a default origin description.ConfigValueFactory.fromAnyRef(Object,String) documentation for details.ConfigValueFactory.fromIterable(Iterable, String) for
+ details, this one just uses a default origin description.ConfigValueFactory.fromAnyRef(Object,String) documentation for details.ConfigValueFactory.fromMap(Map,String) for details, this one
+ just uses a default origin description.ConfigValue at the given key, or returns null if there is
+ no value.Boolean, Integer, and
+ so on - see ConfigValue.unwrapped()).null, if the class loader was
+ unset, returns
+ Thread.currentThread().getContextClassLoader().TimeUnit.Config.getDuration(String, TimeUnit).ConfigList, which
+ implements java.util.List<ConfigValue>.Config.getDuration(String, TimeUnit)Config.getDurationList(String, TimeUnit)Config.getDuration(String, TimeUnit)Config.getDurationList(String, TimeUnit)Config's root object contains no key-value
+ pairs.ConfigFactory.load(String) but uses the supplied class loader instead of
+ the current thread's context class loader.ConfigFactory.load(String) but allows you to specify parse and resolve
+ options.ConfigFactory.load(String,ConfigParseOptions,ConfigResolveOptions) but
+ has a class loader parameter that overrides any from the
+ ConfigParseOptions.Config
+ object rather than loading "application.conf".ConfigFactory.load(Config) but allows you to specify
+ ConfigResolveOptions.ConfigFactory.load(Config,ConfigResolveOptions) but allows you to specify
+ a class loader other than the context class loader.load("application") in most cases.ConfigFactory.load() but allows specifying parse optionsConfigFactory.load() but allows specifying a class loader other than the
+ thread's current context class loader.ConfigFactory.load() but allows specifying a class loader other than the
+ thread's current context class loader, and parse optionsConfigFactory.load() but allows specifying a class loader other than the
+ thread's current context class loader, and resolve optionsConfigFactory.load() but allows specifying a class loader other than the
+ thread's current context class loader, parse options, and resolve optionsConfig, which may be a file, or a file
+ with a line number, or just a descriptive phrase.ConfigOrigin describing the origin of the parseable
+ item.Config based on a Map from paths to
+ plain Java values.ConfigFactory.parseMap(Map, String) for details,
+ this one just uses a default origin description.ConfigParseable then use ConfigParseable.options()
+ instead though).Properties object to a
+ ConfigObject using the rules documented in the HOCON
+ spec.Config.Config.ConfigFactory.parseResources(ClassLoader,String,ConfigParseOptions) but
+ uses thread's current context class loader.ConfigFactory.parseResources(ClassLoader,String) but uses thread's
+ current context class loader.ConfigFactory.parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions)
+ but uses thread's current context class loader.ConfigFactory.parseResourcesAnySyntax(ClassLoader,String) but uses
+ thread's current context class loader.${foo.bar} syntax, see the
+ spec) resolved.Config.resolve() but allows you to specify non-default
+ options.Config.resolve() except that substitution values are looked
+ up in the given source, rather than in this instance.Config.resolveWith(Config) but allows you to specify
+ non-default options.Config as a tree of ConfigObject.Config containing the system's environment variables.Config containing the system properties from
+ System.getProperties(), parsed and converted as with
+ ConfigFactory.parseProperties(java.util.Properties, com.typesafe.config.ConfigParseOptions).Config instance, enabling you to use
+ path expressions to find values in the object.String,
+ Number, Boolean, Map<String,Object>,
+ List<Object>, or null, matching the ConfigValue.valueType()
+ of this ConfigValue.ConfigValueType of the value; matches the JSON type schema.Config based on this one, but with the given path set
+ to the given value.ConfigObject based on this one, but with the given key
+ set to the given value.private void readObject(java.io.ObjectInputStream in) + throws java.io.IOException, + java.lang.ClassNotFoundException+
java.io.IOExceptionjava.lang.ClassNotFoundExceptionprivate void writeObject(java.io.ObjectOutputStream out) + throws java.io.IOException+
java.io.IOExceptionjava.lang.Iterable<T> problems+