ConfigFactory
Related Docs:
class ConfigFactory
| package config
Like ConfigFactory.defaultApplication() but allows you to specify parse options.
Like ConfigFactory.defaultApplication() but allows you to specify parse options.
the options
the default application configuration
1.3.0
Like ConfigFactory.defaultApplication() but allows you to specify a class loader to use rather than the current context class loader.
Like ConfigFactory.defaultApplication() but allows you to specify a class loader to use rather than the current context class loader.
class loader to look for resources in
the default application configuration
1.3.0
Obtains the default application-specific configuration,
which defaults to parsing application.conf,
application.json, and
application.properties on the classpath, but
can also be rerouted using the config.file,
config.resource, and config.url
system properties.
Obtains the default application-specific configuration,
which defaults to parsing application.conf,
application.json, and
application.properties on the classpath, but
can also be rerouted using the config.file,
config.resource, and config.url
system properties.
The no-arguments ConfigFactory.load() method automatically
stacks the ConfigFactory.defaultReference(), ConfigFactory.defaultApplication(), and ConfigFactory.defaultOverrides()
configs. You would use defaultApplication()
directly only if you're somehow customizing behavior by
reimplementing load().
The configuration returned by
defaultApplication() will not be resolved
already, in contrast to defaultReference() and
defaultOverrides(). This is because
application.conf would normally be resolved after
merging with the reference and override configs.
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 ConfigFactory.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, defaultApplication() is equivalent to
ConfigFactory.parseResources("application").
the default application.conf or system-property-configured configuration
1.3.0
Like ConfigFactory.defaultOverrides() but allows you to specify a class loader to use rather than the current context class loader.
Like ConfigFactory.defaultOverrides() but allows you to specify a class loader to use rather than the current context class loader.
class loader to look for resources in
the default override configuration
Obtains the default override configuration, which currently consists of system properties.
Obtains the default override configuration, which currently consists of system properties. The returned override configuration will already have substitutions resolved.
The ConfigFactory.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.
the default override configuration
Like ConfigFactory.defaultReference() but allows you to specify a class loader to use rather than the current context class loader.
Like ConfigFactory.defaultReference() but allows you to specify a class loader to use rather than the current context class loader.
class loader to look for resources in
the default reference config for this class loader
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.
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. The returned reference configuration will already have substitutions resolved.
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 ConfigFactory.defaultReference(ClassLoader) if the context class loader is not suitable.
The ConfigFactory.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".
the default reference config for context class loader
Gets an empty configuration with a description to be used to create a
ConfigOrigin for this Config.
Gets an empty configuration with a description to be used to create a
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, making
the description more useful.)
description of the config
an empty configuration
Gets an empty configuration.
Gets an empty configuration. See also ConfigFactory.empty(String) to create an empty configuration with a description, which may improve user-visible error messages.
an empty configuration
Reloads any cached configs, picking up changes to system properties for example.
Reloads any cached configs, picking up changes to system properties for example. Because a Config is immutable, anyone with a reference to the old configs will still have the same outdated objects. However, new calls to ConfigFactory.load() or ConfigFactory.defaultOverrides() or ConfigFactory.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 ConfigFactory.load(), will work. Make changes before you invalidate.
Like ConfigFactory.load() but allows specifying parse options and resolve options.
Like ConfigFactory.load() but allows specifying parse options and resolve options.
Options for parsing resources
options for resolving the assembled config stack
configuration for an application
1.3.0
Like ConfigFactory.load() but allows specifying a class loader other than the thread's current context class loader, parse options, and resolve options.
Like ConfigFactory.load() but allows specifying a class loader other than the thread's current context class loader, parse options, and resolve options.
class loader for finding resources (overrides any loader in parseOptions)
Options for parsing resources
options for resolving the assembled config stack
configuration for an application
Like ConfigFactory.load() but allows specifying a class loader other than the thread's current context class loader and also specify resolve options.
Like ConfigFactory.load() but allows specifying a class loader other than the thread's current context class loader and also specify resolve options.
class loader for finding resources
options for resolving the assembled config stack
configuration for an application
Like ConfigFactory.load() but allows specifying a class loader other than the thread's current context class loader and also specify parse options.
Like ConfigFactory.load() but allows specifying a class loader other than the thread's current context class loader and also specify parse options.
class loader for finding resources (overrides any loader in parseOptions)
Options for parsing resources
configuration for an application
Like ConfigFactory.load() but allows specifying a class loader other than the thread's current context class loader.
Like ConfigFactory.load() but allows specifying a class loader other than the thread's current context class loader.
class loader for finding resources
configuration for an application
Like ConfigFactory.load() but allows specifying parse options.
Like ConfigFactory.load() but allows specifying parse options.
Options for parsing resources
configuration for an application
Loads a default configuration, equivalent to ConfigFactory.load(Config) .load(defaultApplication()) in most cases.
Loads a default configuration, equivalent to ConfigFactory.load(Config) .load(defaultApplication()) 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 ConfigFactory.invalidateCaches() to force it to reload.)
configuration for an application
Like ConfigFactory.load(Config,ConfigResolveOptions) but allows you to specify a class loader other than the context class loader.
Like ConfigFactory.load(Config,ConfigResolveOptions) but allows you to specify a class loader other than the context class loader.
class loader to use when looking up override and reference configs
the application's portion of the configuration
options for resolving the assembled config stack
resolved configuration with overrides and fallbacks added
Like ConfigFactory.load(Config) but allows you to specify ConfigResolveOptions.
Like ConfigFactory.load(Config) but allows you to specify ConfigResolveOptions.
the application's portion of the configuration
options for resolving the assembled config stack
resolved configuration with overrides and fallbacks added
Like ConfigFactory.load(Config) but allows you to specify the class loader for looking up resources.
Like ConfigFactory.load(Config) but allows you to specify the class loader for looking up resources.
the class loader to use to find resources
the application's portion of the configuration
resolved configuration with overrides and fallbacks added
Assembles a standard configuration using a custom Config
object rather than loading "application.conf".
Assembles a standard configuration using a custom Config
object rather than loading "application.conf". The Config
object will be sandwiched between the default reference config and
default overrides and then resolved.
the application's portion of the configuration
resolved configuration with overrides and fallbacks added
Like ConfigFactory.load(String,ConfigParseOptions,ConfigResolveOptions) but has a class loader parameter that overrides any from the ConfigParseOptions.
Like ConfigFactory.load(String,ConfigParseOptions,ConfigResolveOptions) but has a class loader parameter that overrides any from the ConfigParseOptions.
class loader in which to find resources (overrides loader in parse options)
the classpath resource name with optional extension
options to use when parsing the resource (class loader overridden)
options to use when resolving the stack
configuration for an application
Like ConfigFactory.load(String) but allows you to specify parse and resolve options.
Like ConfigFactory.load(String) but allows you to specify parse and resolve options.
the classpath resource name with optional extension
options to use when parsing the resource
options to use when resolving the stack
configuration for an application
Like ConfigFactory.load(String) but uses the supplied class loader instead of the current thread's context class loader.
Like ConfigFactory.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 String) rather than this method. To load only the reference config use ConfigFactory.defaultReference(ClassLoader) and to load only the overrides use ConfigFactory.defaultOverrides(ClassLoader).
class loader to look for resources in
basename (no .conf/.json/.properties suffix)
configuration for an application relative to given class loader
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.
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. The classpath resource is "raw" (it should have no "/" prefix, and is not made relative to any package, so it's like ClassLoader#getResource not Class#getResource).
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
ConfigFactory.load(Config).
To load a standalone resource (without the default reference and default overrides), use ConfigFactory.parseResourcesAnySyntax(String) rather than this method. To load only the reference config use ConfigFactory.defaultReference() and to load only the overrides use ConfigFactory.defaultOverrides().
name (optionally without extension) of a resource on classpath
configuration for an application relative to context class loader
Parses a file into a Config instance as with ConfigFactory#parseFile(File,ConfigParseOptions) but always uses the default parse options.
Parses a file into a Config instance as with ConfigFactory#parseFile(File,ConfigParseOptions) but always uses the default parse options.
the file to parse
the parsed configuration
ConfigException on IO or parse errors
Parses a file into a Config instance.
Parses a file into a Config instance. Does not call Config.resolve or merge the file with any other configuration; this method parses a single file and does nothing else. It does process "include" statements in the parsed file, and may end up doing other IO due to those statements.
the file to parse
parse options to control how the file is interpreted
the parsed configuration
ConfigException on IO or parse errors
Like ConfigFactory#parseFileAnySyntax(File,ConfigParseOptions) but always uses default parse options.
Like ConfigFactory#parseFileAnySyntax(File,ConfigParseOptions) but always uses default parse options.
a filename with or without extension
the parsed configuration
Parses a file with a flexible extension.
Parses a file with a flexible extension. If the 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 ConfigParseOptions#getAllowMissing is true, then no files have to exist; if false, then at least one file has to exist.
a filename with or without extension
parse options
the parsed configuration
See the other overload of String) for details, this one just uses a default origin description.
See the other overload of String) for details, this one just uses a default origin description.
map from paths to plain Java values
the map converted to a Config
Creates a Config based on a java.util.Map from paths to plain Java values.
Creates a Config based on a java.util.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.
map from paths to plain Java objects
description of what this map represents, like a filename, or "default settings" (origin description is used in error messages)
the map converted to a Config
Like ConfigParseOptions) but uses default parse options.
Like ConfigParseOptions) but uses default parse options.
a Java Properties object
the parsed configuration
Converts a Java java.util.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.
Converts a Java java.util.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 ConfigFactory.systemProperties() method
which returns a cached global singleton.
a Java Properties object
the parse options
the parsed configuration
Parses a reader into a Config instance as with ConfigFactory.parseReader(Reader,ConfigParseOptions) but always uses the default parse options.
Parses a reader into a Config instance as with ConfigFactory.parseReader(Reader,ConfigParseOptions) but always uses the default parse options.
the reader to parse
the parsed configuration
ConfigException on IO or parse errors
Parses a Reader into a Config instance.
Parses a Reader into a Config instance. Does not call Config.resolve* or merge the parsed stream with any other configuration; this method parses a single stream and does nothing else. It does process "include" statements in the parsed stream, and may end up doing other IO due to those statements.
the reader to parse
parse options to control how the reader is interpreted
the parsed configuration
ConfigException on IO or parse errors
Like ConfigFactory#parseResources(ClassLoader,String) but uses thread's current context class loader.
Like ConfigFactory#parseResources(ClassLoader,String) but uses thread's current context class loader.
the resource name
the parsed configuration
Like ConfigFactory#parseResources(ClassLoader,String,ConfigParseOptions) but uses thread's current context class loader if none is set in the ConfigParseOptions.
Like ConfigFactory#parseResources(ClassLoader,String,ConfigParseOptions) but uses thread's current context class loader if none is set in the ConfigParseOptions.
the resource name
parse options
the parsed configuration
Like ConfigFactory#parseResources(ClassLoader,String,ConfigParseOptions) but always uses default parse options.
Like ConfigFactory#parseResources(ClassLoader,String,ConfigParseOptions) but always uses default parse options.
will be used to load resources
resource to look up in the loader
the parsed configuration
Parses all resources on the classpath with the given name and merges them
into a single Config.
Parses all resources on the classpath with the given name and merges them
into a single Config.
This works like java.lang.ClassLoader#getResource, not like java.lang.Class#getResource, so the name never begins with a slash.
See ConfigFactory#parseResources(Class,String,ConfigParseOptions) for full details.
will be used to load resources by setting this loader on the provided options
resource to look up
parse options (class loader is ignored)
the parsed configuration
Like ConfigFactory#parseResources(Class,String,ConfigParseOptions) but always uses default parse options.
Like ConfigFactory#parseResources(Class,String,ConfigParseOptions) but always uses default parse options.
klass.getClassLoader() will be used to load
resources, and non-absolute resource names will have this
class's package added
resource to look up, relative to klass's package
or absolute starting with a "/"
the parsed configuration
Parses all resources on the classpath with the given name and merges them into a single Config.
Parses all resources on the classpath with the given name and merges them into a single 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 java.lang.Class#getResource.
Duplicate resources with the same name are merged such that ones returned earlier from ClassLoader#getResources 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.getClassLoader() will be used to load
resources, and non-absolute resource names will have this
class's package added
resource to look up, relative to klass's package
or absolute starting with a "/"
parse options
the parsed configuration
Like ConfigFactory#parseResourcesAnySyntax(ClassLoader,String) but uses thread's current context class loader.
Like ConfigFactory#parseResourcesAnySyntax(ClassLoader,String) but uses thread's current context class loader.
the resource basename (no file type suffix)
the parsed configuration
Like ConfigFactory#parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions) but uses thread's current context class loader.
Like ConfigFactory#parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions) but uses thread's current context class loader.
the resource basename (no file type suffix)
parse options
the parsed configuration
Like ConfigFactory#parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions) but always uses default parse options.
Like ConfigFactory#parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions) but always uses default parse options.
will be used to load resources
a resource name as in java.lang.ClassLoader#getResource, with or without extension
the parsed configuration
Parses classpath resources with a flexible extension.
Parses classpath resources with a flexible extension. In general, this method has the same behavior as ConfigFactory#parseFileAnySyntax(File,ConfigParseOptions) but for classpath resources instead, as in ConfigFactory#parseResources(ClassLoader,String,ConfigParseOptions).
ConfigFactory#parseResourcesAnySyntax(Class,String,ConfigParseOptions) differs in the syntax for the resource name, but otherwise see ConfigFactory#parseResourcesAnySyntax(Class,String,ConfigParseOptions) for some details and caveats on this method.
class loader to look up resources in, will be set on options
a resource name as in java.lang.ClassLoader#getResource, with or without extension
parse options (class loader ignored)
the parsed configuration
Like ConfigFactory#parseResourcesAnySyntax(Class,String,ConfigParseOptions) but always uses default parse options.
Like ConfigFactory#parseResourcesAnySyntax(Class,String,ConfigParseOptions) but always uses default parse options.
klass.getClassLoader() will be used to load
resources, and non-absolute resource names will have this
class's package added
a resource name as in java.lang.Class#getResource, with or without extension
the parsed configuration
Parses classpath resources with a flexible extension.
Parses classpath resources with a flexible extension. In general, this method has the same behavior as ConfigFactory#parseFileAnySyntax(File,ConfigParseOptions) but for classpath resources instead, as in ConfigFactory#parseResources.
There is a thorny problem with this method, which is that java.lang.ClassLoader#getResources 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 ConfigFactory#parseFileAnySyntax(File,ConfigParseOptions) - all ".conf" resources are ahead of all ".json" resources which are ahead of all ".properties" resources.
class which determines the ClassLoader and the
package for relative resource names
a resource name as in java.lang.Class#getResource, with or without extension
parse options (class loader is ignored in favor of the one from klass)
the parsed configuration
Parses a string (which should be valid HOCON or JSON).
Parses a string (which should be valid HOCON or JSON).
string to parse
the parsed configuration
Parses a string (which should be valid HOCON or JSON by default, or the syntax specified in the options otherwise).
Parses a string (which should be valid HOCON or JSON by default, or the syntax specified in the options otherwise).
string to parse
parse options
the parsed configuration
Parses a url into a Config instance as with ConfigFactory.parseURL(URL,ConfigParseOptions) but always uses the default parse options.
Parses a url into a Config instance as with ConfigFactory.parseURL(URL,ConfigParseOptions) but always uses the default parse options.
the url to parse
the parsed configuration
ConfigException on IO or parse errors
Parses a URL into a Config instance.
Parses a URL into a Config instance. Does not call Config.resolve* or merge the parsed stream with any other configuration; this method parses a single stream and does nothing else. It does process "include" statements in the parsed stream, and may end up doing other IO due to those statements.
the url to parse
parse options to control how the url is interpreted
the parsed configuration
ConfigException on IO or parse errors
Gets a Config containing the system's environment variables.
Gets a 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 java.lang.System.getenv(String) though, since you can use methods such as Config.getInt.
system environment variables parsed into a Config
Gets a Config containing the system properties from
java.lang.System#getProperties(), parsed and converted as with
ConfigFactory#parseProperties.
Gets a Config containing the system properties from
java.lang.System#getProperties(), parsed and converted as with
ConfigFactory#parseProperties.
This method can return a global immutable singleton, so it's preferred over parsing system properties yourself.
ConfigFactory#load will include the system properties as overrides already, as will ConfigFactory#defaultReference and ConfigFactory#defaultOverrides.
Because this returns a singleton, it will not notice changes to system properties made after the first time this method is called. Use ConfigFactory#invalidateCaches() to force the singleton to reload if you modify system properties.
system properties parsed into a Config
Contains static methods for creating 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 <a on GitHub. Also be sure to read the <a href="package-summary.html#package_description">package overview which describes the big picture as shown in those examples.