2.3. Using OSGi Configuration Properties

Overview

The OSGi Configuration Admin service defines a mechanism for passing configuration settings to an OSGi bundle. You do not have to use this service for configuration, but it is typically the most convenient way of configuring applications deployed in Red Hat JBoss Fuse.

Persistent ID

In the OSGi Configuration Admin service, a persistent ID is a name that identifies a group of related configuration properties. In JBoss Fuse, every persistent ID, PersistentID, is implicitly associated with a file named PersistentID.cfg in the ESBInstallDir/etc/ directory. If the corresponding file exists, it can be used to initialize the values of properties belonging to the PersistentID property group.
For example, the etc/org.ops4j.pax.url.mvn.cfg file is used to set the properties associated with the org.ops4j.pax.url.mvn persistent ID (for the PAX Mvn URL handler).

Blueprint example

Example 2.1, “Using OSGi Configuration Properties in Blueprint” shows how to pass the value of the prefix variable to the constructor of the myTransform bean in blueprint XML, where the value of prefix is set by the OSGi Configuration Admin service.

Example 2.1. Using OSGi Configuration Properties in Blueprint

<blueprint
    xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
 xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    ... >
    ...
    <cm:property-placeholder persistent-id="org.fusesource.example">
        <cm:default-properties>
            <cm:property name="prefix" value="Blueprint-Example"/>
        </cm:default-properties>
    </cm:property-placeholder>

    <bean id="myTransform" class="org.example.camel.MyTransform">
        <property name="prefix" value="${prefix}" />
    </bean>

</blueprint>
The syntax, {{prefix}}, substitutes the value of the prefix variable into the blueprint XML file. The OSGi properties are set up using the following XML elements:
cm:property-placeholder
This element gives you access to the properties associated with the specified persistent ID. After defining this element, you can use the syntax, {{PropName}}, to substitute variables belonging to the specified persistent ID.
cm:property-placeholder/cm:default-properties
You can optionally specify default values for properties by defining cm:property elements inside the cm:default-properties element. If the corresponding etc/PersistentID.cfg file defines property values, however, these will be used instead.

Using multiple property placeholders in Blueprint

It is legal to define multiple property placeholders in a Blueprint XML file (that is, defining multiple cm:property-placeholder elements that reference different persistent IDs). One thing that you need to be aware of, however, is that there can be a clash if two properties from different property placeholders have the same name. In this case, the following rules determine which property takes precedence:
  1. Explicitly defined property settings (for example, defined in a etc/PersistentID.cfg file) take precedence over default property settings (defined in a cm:default-properties element).
  2. If there is more than one explicit setting for a given property, the setting from the last property placeholder in the Blueprint file takes precedence.
  3. Default property settings (defined in a cm:default-properties element) have the lowest priority.