Class ConfigFactory
- java.lang.Object
-
- com.typesafe.config.ConfigFactory
-
public final class ConfigFactory extends java.lang.Object
Contains static methods for creatingConfig
instances.See also
ConfigValueFactory
which contains static methods for converting Java values into aConfigObject
. You can then convert aConfigObject
into aConfig
withConfigObject.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.
-
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static Config
defaultOverrides()
Obtains the default override configuration, which currently consists of system properties.static Config
defaultOverrides(java.lang.ClassLoader loader)
LikedefaultOverrides()
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)
LikedefaultReference()
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 aConfigOrigin
for thisConfig
.static void
invalidateCaches()
Reloads any cached configs, picking up changes to system properties for example.static Config
load()
Loads a default configuration, equivalent toload("application")
in most cases.static Config
load(Config config)
Assembles a standard configuration using a customConfig
object rather than loading "application.conf".static Config
load(ConfigParseOptions parseOptions)
Likeload()
but allows specifying parse optionsstatic Config
load(Config config, ConfigResolveOptions resolveOptions)
Likeload(Config)
but allows you to specifyConfigResolveOptions
.static Config
load(java.lang.ClassLoader loader)
Likeload()
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, ConfigParseOptions parseOptions)
Likeload()
but allows specifying a class loader other than the thread's current context class loader, and parse optionsstatic Config
load(java.lang.ClassLoader loader, ConfigParseOptions parseOptions, ConfigResolveOptions resolveOptions)
Likeload()
but allows specifying a class loader other than the thread's current context class loader, parse options, and resolve optionsstatic Config
load(java.lang.ClassLoader loader, Config config, ConfigResolveOptions resolveOptions)
Likeload(Config,ConfigResolveOptions)
but allows you to specify a class loader other than the context class loader.static Config
load(java.lang.ClassLoader loader, ConfigResolveOptions resolveOptions)
Likeload()
but allows specifying a class loader other than the thread's current context class loader, and resolve optionsstatic Config
load(java.lang.ClassLoader loader, java.lang.String resourceBasename)
Likeload(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)
Likeload(String,ConfigParseOptions,ConfigResolveOptions)
but has a class loader parameter that overrides any from theConfigParseOptions
.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)
Likeload(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 ofparseMap(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 aConfig
based on aMap
from paths to plain Java values.static Config
parseProperties(java.util.Properties properties)
static Config
parseProperties(java.util.Properties properties, ConfigParseOptions options)
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 singleConfig
.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 singleConfig
.static Config
parseResources(java.lang.String resource)
LikeparseResources(ClassLoader,String)
but uses thread's current context class loader.static Config
parseResources(java.lang.String resource, ConfigParseOptions options)
LikeparseResources(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)
LikeparseResourcesAnySyntax(ClassLoader,String)
but uses thread's current context class loader.static Config
parseResourcesAnySyntax(java.lang.String resourceBasename, ConfigParseOptions options)
LikeparseResourcesAnySyntax(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 aConfig
containing the system's environment variables.static Config
systemProperties()
Gets aConfig
containing the system properties fromSystem.getProperties()
, parsed and converted as withparseProperties(java.util.Properties, com.typesafe.config.ConfigParseOptions)
.
-
-
-
Method Detail
-
load
public 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. The classpath resource is "raw" (it should have no "/" prefix, and is not made relative to any package, so it's likeClassLoader.getResource(java.lang.String)
notClass.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 usedefaultReference()
and to load only the overrides usedefaultOverrides()
.- Parameters:
resourceBasename
- name (optionally without extension) of a resource on classpath- Returns:
- configuration for an application relative to context class loader
-
load
public static Config load(java.lang.ClassLoader loader, java.lang.String resourceBasename)
Likeload(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 usedefaultReference(ClassLoader)
and to load only the overrides usedefaultOverrides(ClassLoader)
.- Parameters:
loader
-resourceBasename
-- Returns:
- configuration for an application relative to given class loader
-
load
public static Config load(java.lang.String resourceBasename, ConfigParseOptions parseOptions, ConfigResolveOptions resolveOptions)
Likeload(String)
but allows you to specify parse and resolve options.- Parameters:
resourceBasename
- the classpath resource name with optional extensionparseOptions
- options to use when parsing the resourceresolveOptions
- options to use when resolving the stack- Returns:
- configuration for an application
-
load
public static Config load(java.lang.ClassLoader loader, java.lang.String resourceBasename, ConfigParseOptions parseOptions, ConfigResolveOptions resolveOptions)
Likeload(String,ConfigParseOptions,ConfigResolveOptions)
but has a class loader parameter that overrides any from theConfigParseOptions
.- Parameters:
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 stack- Returns:
- configuration for an application
-
load
public static Config load(Config config)
Assembles a standard configuration using a customConfig
object rather than loading "application.conf". TheConfig
object will be sandwiched between the default reference config and default overrides and then resolved.- Parameters:
config
- the application's portion of the configuration- Returns:
- resolved configuration with overrides and fallbacks added
-
load
public static Config load(Config config, ConfigResolveOptions resolveOptions)
Likeload(Config)
but allows you to specifyConfigResolveOptions
.- Parameters:
config
- the application's portion of the configurationresolveOptions
- options for resolving the assembled config stack- Returns:
- resolved configuration with overrides and fallbacks added
-
load
public static Config load(java.lang.ClassLoader loader, Config config, ConfigResolveOptions resolveOptions)
Likeload(Config,ConfigResolveOptions)
but allows you to specify a class loader other than the context class loader.- Parameters:
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 stack- Returns:
- resolved configuration with overrides and fallbacks added
-
load
public static Config load()
Loads a default configuration, equivalent toload("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
, orconfig.url
are set, then the classpath resource, file, or URL specified in those properties will be used rather than the defaultapplication.{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 useload(Config)
if you don't want to useapplication.conf
). The properties are intended for use by the person or script launching the application. For example someone might have aproduction.conf
that includeapplication.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 toConfigFactory.load("application")
.- Returns:
- configuration for an application
-
load
public static Config load(ConfigParseOptions parseOptions)
Likeload()
but allows specifying parse options- Parameters:
parseOptions
- Options for parsing resources- Returns:
- configuration for an application
-
load
public static Config load(java.lang.ClassLoader loader)
Likeload()
but allows specifying a class loader other than the thread's current context class loader.- Parameters:
loader
- class loader for finding resources- Returns:
- configuration for an application
-
load
public static Config load(java.lang.ClassLoader loader, ConfigParseOptions parseOptions)
Likeload()
but allows specifying a class loader other than the thread's current context class loader, and parse options- Parameters:
loader
- class loader for finding resourcesparseOptions
- Options for parsing resources- Returns:
- configuration for an application
-
load
public static Config load(java.lang.ClassLoader loader, ConfigResolveOptions resolveOptions)
Likeload()
but allows specifying a class loader other than the thread's current context class loader, and resolve options- Parameters:
loader
- class loader for finding resourcesresolveOptions
- options for resolving the assembled config stack- Returns:
- configuration for an application
-
load
public static Config load(java.lang.ClassLoader loader, ConfigParseOptions parseOptions, ConfigResolveOptions resolveOptions)
Likeload()
but allows specifying a class loader other than the thread's current context class loader, parse options, and resolve options- Parameters:
loader
- class loader for finding resourcesparseOptions
- Options for parsing resourcesresolveOptions
- options for resolving the assembled config stack- Returns:
- configuration for an application
-
defaultReference
public 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. 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".
- Returns:
- the default reference config for context class loader
-
defaultReference
public static Config defaultReference(java.lang.ClassLoader loader)
LikedefaultReference()
but allows you to specify a class loader to use rather than the current context class loader.- Parameters:
loader
-- Returns:
- the default reference config for this class loader
-
defaultOverrides
public static Config defaultOverrides()
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.
- Returns:
- the default override configuration
-
defaultOverrides
public static Config defaultOverrides(java.lang.ClassLoader loader)
LikedefaultOverrides()
but allows you to specify a class loader to use rather than the current context class loader.- Parameters:
loader
-- Returns:
- the default override configuration
-
invalidateCaches
public static void invalidateCaches()
Reloads any cached configs, picking up changes to system properties for example. Because aConfig
is immutable, anyone with a reference to the old configs will still have the same outdated objects. However, new calls toload()
ordefaultOverrides()
ordefaultReference()
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.
-
empty
public static Config empty()
Gets an empty configuration. See alsoempty(String)
to create an empty configuration with a description, which may improve user-visible error messages.- Returns:
- an empty configuration
-
empty
public static Config empty(java.lang.String originDescription)
Gets an empty configuration with a description to be used to create aConfigOrigin
for thisConfig
. 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 usingConfig.withFallback(com.typesafe.config.ConfigMergeable)
, making the description more useful.)- Parameters:
originDescription
- description of the config- Returns:
- an empty configuration
-
systemProperties
public static Config systemProperties()
Gets aConfig
containing the system properties fromSystem.getProperties()
, parsed and converted as withparseProperties(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 willdefaultReference()
anddefaultOverrides()
.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.- Returns:
- system properties parsed into a
Config
-
systemEnvironment
public static Config systemEnvironment()
Gets aConfig
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 asConfig.getInt(java.lang.String)
.- Returns:
- system environment variables parsed into a
Config
-
parseProperties
public static Config parseProperties(java.util.Properties properties, ConfigParseOptions options)
Converts a JavaProperties
object to aConfigObject
using the rules documented in the HOCON spec. The keys in theProperties
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 thesystemProperties()
method which returns a cached global singleton.- Parameters:
properties
- a Java Properties objectoptions
-- Returns:
- the parsed configuration
-
parseProperties
public static Config parseProperties(java.util.Properties properties)
-
parseReader
public static Config parseReader(java.io.Reader reader, ConfigParseOptions options)
-
parseReader
public static Config parseReader(java.io.Reader reader)
-
parseURL
public static Config parseURL(java.net.URL url, ConfigParseOptions options)
-
parseURL
public static Config parseURL(java.net.URL url)
-
parseFile
public static Config parseFile(java.io.File file, ConfigParseOptions options)
-
parseFile
public static Config parseFile(java.io.File file)
-
parseFileAnySyntax
public static Config parseFileAnySyntax(java.io.File fileBasename, ConfigParseOptions options)
Parses a file with a flexible extension. If thefileBasename
already ends in a known extension, this method parses it according to that extension (the file's syntax must match its extension). If thefileBasename
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" forcesConfigSyntax.JSON
, and ".properties" forcesConfigSyntax.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.- Parameters:
fileBasename
- a filename with or without extensionoptions
- parse options- Returns:
- the parsed configuration
-
parseFileAnySyntax
public static Config parseFileAnySyntax(java.io.File fileBasename)
-
parseResources
public 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 singleConfig
.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.- Parameters:
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 toklass
's package or absolute starting with a "/"options
- parse options- Returns:
- the parsed configuration
-
parseResources
public static Config parseResources(java.lang.Class<?> klass, java.lang.String resource)
-
parseResourcesAnySyntax
public static Config parseResourcesAnySyntax(java.lang.Class<?> klass, java.lang.String resourceBasename, ConfigParseOptions options)
Parses classpath resources with a flexible extension. In general, this method has the same behavior asparseFileAnySyntax(File,ConfigParseOptions)
but for classpath resources instead, as inparseResources(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 asparseFileAnySyntax()
- all ".conf" resources are ahead of all ".json" resources which are ahead of all ".properties" resources.- Parameters:
klass
- class which determines theClassLoader
and the package for relative resource namesresourceBasename
- a resource name as inClass.getResource(java.lang.String)
, with or without extensionoptions
- parse options (class loader is ignored in favor of the one from klass)- Returns:
- the parsed configuration
-
parseResourcesAnySyntax
public static Config parseResourcesAnySyntax(java.lang.Class<?> klass, java.lang.String resourceBasename)
-
parseResources
public 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 singleConfig
.This works like
ClassLoader.getResource(java.lang.String)
, not likeClass.getResource(java.lang.String)
, so the name never begins with a slash.See
parseResources(Class,String,ConfigParseOptions)
for full details.- Parameters:
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)- Returns:
- the parsed configuration
-
parseResources
public static Config parseResources(java.lang.ClassLoader loader, java.lang.String resource)
-
parseResourcesAnySyntax
public static Config parseResourcesAnySyntax(java.lang.ClassLoader loader, java.lang.String resourceBasename, ConfigParseOptions options)
Parses classpath resources with a flexible extension. In general, this method has the same behavior asparseFileAnySyntax(File,ConfigParseOptions)
but for classpath resources instead, as inparseResources(ClassLoader,String,ConfigParseOptions)
.parseResourcesAnySyntax(Class,String,ConfigParseOptions)
differs in the syntax for the resource name, but otherwise seeparseResourcesAnySyntax(Class,String,ConfigParseOptions)
for some details and caveats on this method.- Parameters:
loader
- class loader to look up resources in, will be set on optionsresourceBasename
- a resource name as inClassLoader.getResource(java.lang.String)
, with or without extensionoptions
- parse options (class loader ignored)- Returns:
- the parsed configuration
-
parseResourcesAnySyntax
public static Config parseResourcesAnySyntax(java.lang.ClassLoader loader, java.lang.String resourceBasename)
-
parseResources
public static Config parseResources(java.lang.String resource, ConfigParseOptions options)
LikeparseResources(ClassLoader,String,ConfigParseOptions)
but uses thread's current context class loader.
-
parseResources
public static Config parseResources(java.lang.String resource)
LikeparseResources(ClassLoader,String)
but uses thread's current context class loader.
-
parseResourcesAnySyntax
public static Config parseResourcesAnySyntax(java.lang.String resourceBasename, ConfigParseOptions options)
LikeparseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions)
but uses thread's current context class loader.
-
parseResourcesAnySyntax
public static Config parseResourcesAnySyntax(java.lang.String resourceBasename)
LikeparseResourcesAnySyntax(ClassLoader,String)
but uses thread's current context class loader.
-
parseString
public static Config parseString(java.lang.String s, ConfigParseOptions options)
-
parseString
public static Config parseString(java.lang.String s)
-
parseMap
public static Config parseMap(java.util.Map<java.lang.String,? extends java.lang.Object> values, java.lang.String originDescription)
Creates aConfig
based on aMap
from paths to plain Java values. Similar toConfigValueFactory.fromMap(Map,String)
, except the keys in the map are path expressions, rather than keys; and correspondingly it returns aConfig
instead of aConfigObject
. 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.
- Parameters:
values
-originDescription
- description of what this map represents, like a filename, or "default settings" (origin description is used in error messages)- Returns:
- the map converted to a
Config
-
parseMap
public static Config parseMap(java.util.Map<java.lang.String,? extends java.lang.Object> values)
See the other overload ofparseMap(Map, String)
for details, this one just uses a default origin description.- Parameters:
values
-- Returns:
- the map converted to a
Config
-
-