public interface Config
Obtain an instance via one of the following methods:
ConfigImpl.getInstance()
ConfigImpl.getInstanceForDirectory(co.codewizards.cloudstore.core.oio.File)
ConfigImpl.getInstanceForFile(co.codewizards.cloudstore.core.oio.File)
There is one Config
instance available (lazily created, cached temporarily) for every
directory and every file in a repository. Each Config
inherits the settings from the
parent-directory, if not explicitly overwritten.
The configuration is based on Properties
files. Every property file is optional. If it
does not exist, all settings are inherited. If it does exist, only those properties contained in
the file are overriden. All properties not contained in the file are still inherited. Inheritance
is thus applicable on every individual property.
Modifications, deletions, creations of properties files are detected during runtime (pretty immediately). Note, that this detection is based on the files' timestamps. Since most file systems have a granularity of 1 second (some even 2) for the last-modified-timestamp, multiple modifications in the same second might not be detected.
There is a global properties file in the user's home directory (or wherever ConfigDir
points to): ${user.home}/.cloudstore/cloudstore.properties
Additionally, every directory can optionally contain the following files:
.cloudstore.properties
cloudstore.properties
.${anyFileName}.cloudstore.properties
${anyFileName}.cloudstore.properties
The files 1. and 2. are applicable to the entire directory and all sub-directories and files in it. Usually, on GNU/Linux people will prefer 1., but when using Windows, files starting with a "." are sometimes a bit hard to deal with. Therefore, we support both. The file 2. overrides the settings of file 1..
The files 3. and 4. are applicable only to the file ${anyFileName}
. Thus, if you want
to set special behaviour for the file example.db
only, you can create the file
.example.db.cloudstore.properties
in the same directory.
Modifier and Type | Field and Description |
---|---|
static String |
APP_ID_SIMPLE_ID |
static String |
PROPERTIES_FILE_NAME_FOR_DIRECTORY |
static String |
PROPERTIES_FILE_NAME_FOR_DIRECTORY_LOCAL |
static String |
PROPERTIES_FILE_NAME_PARENT |
static String |
PROPERTIES_FILE_NAME_PARENT_PREFIX |
static String |
PROPERTIES_FILE_NAME_SUFFIX |
static String |
SYSTEM_PROPERTY_PREFIX
Prefix used for system properties overriding configuration entries.
|
Modifier and Type | Method and Description |
---|---|
String |
getDirectProperty(String key)
Gets the property identified by the given key; not taking inheritance into account.
|
Map<String,List<String>> |
getKey2GroupsMatching(Pattern regex)
Gets all config-property-keys matching the given regular expression.
|
String |
getProperty(String key,
String defaultValue)
Gets the property identified by the given key.
|
boolean |
getPropertyAsBoolean(String key,
boolean defaultValue) |
Date |
getPropertyAsDate(String key,
Date defaultValue)
Gets the property identified by the given key.
|
<E extends Enum<E>> |
getPropertyAsEnum(String key,
Class<E> enumClass,
E defaultValue)
Gets the property identified by the given key.
|
<E extends Enum<E>> |
getPropertyAsEnum(String key,
E defaultValue)
Gets the property identified by the given key.
|
int |
getPropertyAsInt(String key,
int defaultValue) |
long |
getPropertyAsLong(String key,
long defaultValue) |
String |
getPropertyAsNonEmptyTrimmedString(String key,
String defaultValue)
Gets the property identified by the given key; trimmed.
|
int |
getPropertyAsPositiveOrZeroInt(String key,
int defaultValue) |
long |
getPropertyAsPositiveOrZeroLong(String key,
long defaultValue) |
long |
getVersion()
Gets a version number that is guaranteed to be changed whenever the underlying files change.
|
void |
setDirectProperty(String key,
String value)
Sets the property identified by the given key; not taking inheritance into account.
|
static final String APP_ID_SIMPLE_ID
static final String PROPERTIES_FILE_NAME_SUFFIX
static final String PROPERTIES_FILE_NAME_FOR_DIRECTORY_LOCAL
static final String PROPERTIES_FILE_NAME_FOR_DIRECTORY
static final String PROPERTIES_FILE_NAME_PARENT_PREFIX
static final String PROPERTIES_FILE_NAME_PARENT
static final String SYSTEM_PROPERTY_PREFIX
Every property in the configuration (i.e. in its properties files) can be overridden by a corresponding system property. The system property must be prefixed.
For example, to override the configuration property with the key "deferrableExecutor.timeout", you can pass the system property "cloudstore.deferrableExecutor.timeout" to the JVM. If the system property exists, the configuration is not consulted, but the system property value is used as shortcut.
Additionally, it is possible to override configuration entries via OS environment variables. Since an env var's name must not contain a dot ("."), all dots are replaced by underscores ("_").
String getProperty(String key, String defaultValue)
This method directly delegates to Properties.getProperty(String, String)
.
Thus, an empty String in the internal Properties
is returned instead of the
given defaultValue
. The defaultValue
is only returned, if neither
the internal Properties
of this Config
nor any of its parents contains
the entry.
Important: This is often not the desired behaviour. You might want to use
getPropertyAsNonEmptyTrimmedString(String, String)
instead!
Every property can be overwritten by a system property prefixed with . If - for example - the key "updater.force" is to be read and a system property named "cloudstore.updater.force" is set, this system property is returned instead!
key
- the key identifying the property. Must not be null
.defaultValue
- the default value to fall back to, if neither this Config
's
internal Properties
nor any of its parents contains a matching entry.
May be null
.null
unless defaultValue
is null
.getPropertyAsNonEmptyTrimmedString(String, String)
String getDirectProperty(String key)
This method corresponds to getProperty(String, String)
, but it does not fall back
to any inherited value.
Important: This method should never be used in order to control the behaviour of the application! It is intended for use of administrative tools / UIs which need to read/write directly.
key
- the key identifying the property. Must not be null
.null
, if the property is not set.setDirectProperty(String, String)
void setDirectProperty(String key, String value)
key
- the key identifying the property. Must not be null
.value
- the property's value. null
removes the property from this concrete
configuration instance.getDirectProperty(String)
String getPropertyAsNonEmptyTrimmedString(String key, String defaultValue)
In contrast to getProperty(String, String)
, this method falls back to the given
defaultValue
, if the internal Properties
contains an empty String
(after trimming) as value for the given key
.
It therefore means that a value set to an empty String
in the properties file means
to use the program's default instead. It is therefore consistent with
getPropertyAsLong(String, long)
and all other getPropertyAs...(...)
methods.
The same rules apply to the fall-back-strategy from system property to environment variable and finally config files.
Every property can be overwritten by a system property prefixed with . If - for example - the key "updater.force" is to be read and a system property named "cloudstore.updater.force" is set, this system property is returned instead!
key
- the key identifying the property. Must not be null
.defaultValue
- the default value to fall back to, if neither this Config
's
internal Properties
nor any of its parents contains a matching entry or
if this entry's value is an empty String
.
May be null
.null
unless defaultValue
is null
.long getPropertyAsLong(String key, long defaultValue)
long getPropertyAsPositiveOrZeroLong(String key, long defaultValue)
int getPropertyAsInt(String key, int defaultValue)
int getPropertyAsPositiveOrZeroInt(String key, int defaultValue)
<E extends Enum<E>> E getPropertyAsEnum(String key, E defaultValue)
key
- the key identifying the property. Must not be null
.defaultValue
- the default value to fall back to, if neither this Config
's
internal Properties
nor any of its parents contains a matching entry or
if this entry's value does not match any possible enum value. Must not be null
.
If a null
default value is required, use getPropertyAsEnum(String, Class, Enum)
instead!null
.getPropertyAsEnum(String, Class, Enum)
,
getPropertyAsNonEmptyTrimmedString(String, String)
<E extends Enum<E>> E getPropertyAsEnum(String key, Class<E> enumClass, E defaultValue)
key
- the key identifying the property. Must not be null
.enumClass
- the enum's type. Must not be null
.defaultValue
- the default value to fall back to, if neither this Config
's
internal Properties
nor any of its parents contains a matching entry or
if this entry's value does not match any possible enum value. May be null
.null
unless defaultValue
is null
.getPropertyAsEnum(String, Enum)
,
getPropertyAsNonEmptyTrimmedString(String, String)
boolean getPropertyAsBoolean(String key, boolean defaultValue)
Date getPropertyAsDate(String key, Date defaultValue)
The date must be ISO8601
-parseable. If it is not parseable, a warning is logged and the
default value is returned.
key
- the key identifying the property. Must not be null
.defaultValue
- the default value to fall back to, if neither this Config
's
internal Properties
nor any of its parents contains a matching entry or
if this entry's value cannot be parsed as an ISO8601
-encoded date+time value.
May be null
.null
unless defaultValue
is null
.long getVersion()
It is not guaranteed to be incremented! Depending on the underlying change, a newer version number might be less than a previous version number! In most cases, however, the version number actually grows with each change. Code must not rely on this, but it is a helpful assumption for debugging.
Map<String,List<String>> getKey2GroupsMatching(Pattern regex)
Just like getProperty(String, String)
, this method takes inheritance into account:
It collects keys from the current Config
instance and all its parents, recursively.
Note, that Matcher.matches()
is used, i.e. the regex
must match the entire
config-key.
The given regex
may contain capturing groups, whose results are returned in the Map
's
values. Note, that the entire match (which is by convention the group 0) is ignored in the values,
because it is the Map
's key, already. Hence, the first entry in the Map
's values
(with index 0) corresponds to the first capturing group in the regular expression.
For example, let's say the regex is "ignore\[([^]]*)\]\.(.*)" and the following matching properties exist:
This leads to a resulting map with the following entries:
regex
- the regular expression to look for. Must not be null
.null
.Copyright © 2013–2019. All rights reserved.