|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.typesafe.config.ConfigFactory
public final class ConfigFactory
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 on GitHub. Also be sure to read the package overview which describes the big picture as shown in those examples.
Method Summary | |
---|---|
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) . |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Method Detail |
---|
public 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 classpath
public 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 stack
public 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 stack
public 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 configuration
public static Config load(java.lang.ClassLoader loader, Config config)
public 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 stack
public 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 stack
public 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 options
parseOptions
- Options for parsing resources
public 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 resources
public 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 options
loader
- class loader for finding resourcesparseOptions
- Options for parsing resources
public 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 options
loader
- class loader for finding resourcesresolveOptions
- options for resolving the assembled config stack
public 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 options
loader
- class loader for finding resourcesparseOptions
- Options for parsing resourcesresolveOptions
- options for resolving the assembled config stack
public 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 config
public 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.
Config
public 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)
.
Config
public 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 options
public 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 options
public 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)
Config
public 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
-
Config
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |