Config
UBStore provides a configuration facility through the IConfig
interface. It can be used by UBStore components and applications
to implement configurable features without having to implement
your own config files, parsing, etc. Technically, it is an OSGi
service UBStore depends on.
Essentially, IConfig
provides a Map of String keys and values
that can be set by the user (i.e. the entity that runs the
application) and read by the application.
The default IConfig
implementation is named
SystemPropertiesConfig
and - as it name says - supports
configuration through system properties. It is included in the
UBStore core implementation (it does not reside in its own bundle),
since we think it is rarely necessary to replace it with an own
implementation.
The user perspective
Configuring UBStore is relatively straight forward for a user in the default UBStore core implementation. There are two ways of setting key value pairs:
Via System Properties
You can simply set a bunch of system
properties when launching the JVM (via the -D
parameter).
With a config file
Preferences can be set by placing aubstore.config.properties
file in the UBStore directory. The syntax is that of a regular
Java properties file.
If needed for some reason, the name and path of the UBStore
config properties file can actually be changed by setting the
the system property -Dubstore.config.propertyfile=some.otherfile
.
If a property is set in both the config file and via system property, the config file has precedence.
The developer perspective
Obtaining the IConfig
object
The IConfig
object can easily be obtained via the
IUBStore.getConfig()
method. It is initialized very
early in the UBStore boot process and hence should always
function properly when you have a reference to UBStore
itself (even / especially in the init(IUBStore)
methods
of IDataAccess
, IShepherd
and IRouter
).
Setting and getting configuration entries
The IConfig
object is pretty straight forward to use.
You can get config values by calling IConfig.get(key)
,
and you can set them with IConfig.set(key, value)
.
Defaults
IConfig
also supports a mechanism for setting
configuration defaults: you can set standard values for
configuration options with the IConfig.setDefault()
method.
Values that are set this way will only be returned if no other
value for that key has been configured in any way
(IConfig.set()
, system properties, config file).
The purpose of this is to be able to set configuration defaults that enable the application to run without the user having to configure anything.
Grouping configuration entries
It is recommended to prepend related configuration entries
with a common prefix. For example, an imaginary
AwesomeDataAccess
might have config parameters with
the same prefix like awesomedataaccess.awesomenesslevel
and awesomenessdataaccess.loglevel
, etc.
This avoids name clashes, for example if multiple components
have a logging
configuration entry.
Furthermore, it might be handy for debugging purposes:
The IConfig
interface provides a way for getting a set
of related configuration entries via the getKeysStartingWith(String)
method. As the name says, it returns a set of config keys that
have a certain prefix, making it easy to get (and maybe print
out) all the configuration entries belonging to one component.