ConfigFactory
Related Docs:
class ConfigFactory
| package config
Like defaultApplication() but allows you to specify parse options.
Like defaultApplication() but allows you to specify parse options.
the options
the default application configuration
1.3.0
Like defaultApplication() but allows you to specify a class loader to use rather than the current context class loader.
Like 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 load() method automatically stacks the
defaultReference(),
defaultApplication(), and
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
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 defaultOverrides() but allows you to specify a class loader to use rather than the current context class loader.
Like 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 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 defaultReference() but allows you to specify a class loader to use rather than the current context class loader.
Like 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 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".
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 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 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.
Like load() but allows specifying parse options and resolve options.
Like 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 load() but allows specifying a class loader other than the thread's current context class loader, parse options, and resolve options.
Like 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 load() but allows specifying a class loader other than the thread's current context class loader and also specify resolve options.
Like 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 load() but allows specifying a class loader other than the thread's current context class loader and also specify parse options.
Like 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 load() but allows specifying a class loader other than the thread's current context class loader.
Like 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 load() but allows specifying parse options.
Like load() but allows specifying parse options.
Options for parsing resources
configuration for an application
Loads a default configuration, equivalent to
load(Config)
ConfigFactory.load(defaultApplication()) in most cases. This configuration
should be used by libraries and frameworks unless an application provides a
different one.
Loads a default configuration, equivalent to
load(Config)
ConfigFactory.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 invalidateCaches() to force it to reload.)
configuration for an application
Like load(Config,ConfigResolveOptions) but allows you to specify a class loader other than the context class loader.
Like 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 load(Config) but allows you to specify ConfigResolveOptions.
Like 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 load(Config) but allows you to specify the class loader for looking up resources.
Like 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 load(String,ConfigParseOptions,ConfigResolveOptions) but has a class loader parameter that overrides any from the ConfigParseOptions.
Like 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 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).
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
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().
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 parseFile(File,ConfigParseOptions) but always uses the default parse options.
Parses a file into a Config instance as with 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 parseFileAnySyntax(File,ConfigParseOptions) but always uses default parse options.
Like 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 ConfigFactory.parseMap(Map,String) for details, this one just uses a default origin description.
See the other overload of ConfigFactory.parseMap(Map,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 parseProperties(Properties, ConfigParseOptions) but uses default parse options.
Like parseProperties(Properties, 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 #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 parseReader(Reader, ConfigParseOptions) but always uses the default parse options.
Parses a reader into a Config instance as with 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 parseResources(ClassLoader,String) but uses thread's current context class loader.
Like parseResources(ClassLoader,String) but uses thread's current context class loader.
the resource name
the parsed configuration
Like parseResources(ClassLoader,String,ConfigParseOptions) but uses thread's current context class loader if none is set in the ConfigParseOptions.
Like 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 parseResources(ClassLoader,String,ConfigParseOptions) but always uses default parse options.
Like 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 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 parseResources(Class,String,ConfigParseOptions) but always uses default parse options.
Like 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 parseResourcesAnySyntax(ClassLoader,String) but uses thread's current context class loader.
Like parseResourcesAnySyntax(ClassLoader,String) but uses thread's current context class loader.
the resource basename (no file type suffix)
the parsed configuration
Like parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions) but uses thread's current context class loader.
Like 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 parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions) but always uses default parse options.
Like 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 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 it is useful to review 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 parseResourcesAnySyntax(Class,String,ConfigParseOptions) but always uses default parse options.
Like 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 parseFileAnySyntax(File,ConfigParseOptions) but for classpath resources instead, as in parseResources(String).
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
parseFileAnySyntax(File,ConfigParseOptions)
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
parseProperties(Properties).
Gets a Config containing the system properties from
java.lang.System.getProperties(), parsed and converted as with
parseProperties(Properties).
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 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.
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 package overview which describes the big picture as shown in those examples.