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.