Introduction
The OSGi Configuration Admin service is the standard solution for providing bundles with a run-time configuration. Although the Configuration Admin service specification describes the interface to set and retrieve configuration data, the specification does not specify how the configuration data is persisted.
Since in Java the standard means for storing properties/configuration is by means of property files, the CM persister bundle handles the gap between property files and the Configuration Admin storage: it loads the configuration from property files into the Configuration Admin and updates this configuration if the property files change. Note that synchronization is one-way: updates to the configurations via the Configuration Admin interface are not persisted back into the property files.
Usage
The CM persister bundle looks for property files in a directory provided by the "cm.location" system property. Therefore this directory must be passed when starting the OSGi framework (via the standard Java -D option, like -Dcm.location=/home/configuration). The property files provided in the directory must contain standard property values in the following form:
PID..property=valuewhere "PID" is the persistence identity of the group of properties for a managed service and "property" is the property identifier. "Value" indicates the property value. Example:
com.acme.console..port=2001
indicates that for PID "com.acme.console" the property "port" must be set to 2001.
Restrictions and other usage hints:
- The files must have a ".properties" extension. Other files in the directory are ignored.
- If the property key does not contain the PID-property separator (the ".."), the prefix name of the file is assumed to be the PID (the file "com.acme.console.properties" will be assumed to have a default PID "com.acme.console").
- In case the "cm.location" system property does not point to a directory but to a file, it is assumed that that file is the only configuration file present.
- In case the "cm.location" system property is not set, no configuration is loaded at all.
- All configuration data for a PID must be present in one property file.
Dependencies
The bundle depends on the standard OSGi core and compendium interfaces. Furthermore, it needs a configuration admin service in the framework to load the configuration(s) in.