3.5. Configure the Application

OSGi Config Admin service

The OSGi Config Admin service is a standard OSGi configuration mechanism that enables administrators to modify application configuration at deployment time and at run time. This contrasts the with settings made directly in a Blueprint XML file, because these XML files are accessible only to the developer.
The OSGi Config Admin service relies on the following basic concepts:
Persistent ID
A persistent ID (PID) identifies a group of related properties. Conventionally, a PID is normally written in the same format as a Java package name. For example, the org.ops4j.pax.web PID configures the Red Hat JBoss Fuse container's default Jetty Web server.
Properties
A property is a name-value pair, which always belongs to a specific PID.

Setting configuration properties

There are two main ways to customise the properties in the OSGi Config Admin service, as follows:
  • For a given a PID, PersistentID, you can create a text file under the InstallDir/etc directory, which obeys the following naming convention: 
    InstallDir/etc/PersistentID.cfg
    You can then set the properties belonging to this PID by editing this file and adding entries of the form: 
    Property=Value
  • Fuse Fabric supports another mechanism for customising OSGi Config Admin properties. In Fuse Fabric, you set OSGi Config Admin properties in a fabric profile (where a profile encapsulates the data required to deploy an application). There are two alternative ways of modifying configuration settings in a profile:

Replace TCP port with a property placeholder

As an example of how the OSGi Config Admin service might be used in practice, consider the TCP port used by the HelloWorld Web service from the cxf-basic project. By modifying the Blueprint XML file that defines this Web service, you can make the Web service's TCP port customisable through the OSGi Config Admin service.
The TCP port number in the Blueprint XML file is replaced by a property placeholder, which resolves the port number at run time by looking up the property in the OSGi Config Admin service.

Blueprint XML example

In the cxf-basic project, any XML files from the following location are treated as Blueprint XML files (the standard Maven location for Blueprint XML files): 
cxf-basic/src/main/resources/OSGI-INF/blueprint/*.xml
Edit the blueprint.xml file from the preceding directory and add the XML contents shown in Example 3.1, “Configuring the Port Number in Blueprint XML”.

Example 3.1. Configuring the Port Number in Blueprint XML

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:jaxws="http://cxf.apache.org/blueprint/jaxws"
           xmlns:cxf="http://cxf.apache.org/blueprint/core"
           xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.1.0"
           xsi:schemaLocation="
      http://cxf.apache.org/blueprint/core http://cxf.apache.org/schemas/blueprint/core.xsd
      http://cxf.apache.org/blueprint/jaxws http://cxf.apache.org/schemas/blueprint/jaxws.xsd">

    <cxf:bus>
        <!--
           In this example, we're enabling the logging feature.  This will ensure that both the inbound and outbound
           XML message are being logged for every web service invocation.
        -->
        <cxf:features>
            <cxf:logging/>
        </cxf:features>
    </cxf:bus>

    <!-- osgi blueprint property placeholder -->
    <cm:property-placeholder id="placeholder"
                             persistent-id="org.fusesource.example.get.started">
        <cm:default-properties>
            <cm:property name="portNumber" value="8181"/>
        </cm:default-properties>
    </cm:property-placeholder>

    <jaxws:endpoint id="helloWorld"
                    implementor="org.fusesource.example.HelloWorldImpl"
                    address="http://0.0.0.0:${portNumber}/cxf/HelloWorld">
    </jaxws:endpoint>

</blueprint>
The highlighted text shows the parts of the blueprint configuration that are relevant to the OSGi Config Admin service. Apart from defining the cm namespace, the main changes are as follows:
  1. The cm:property-placeholder bean contacts the OSGi Config Admin service and retrieves all of the property settings from the org.fusesource.example.get.started PID. The key-value pairs in the cm:default-properties/cm:property elements specify default values for the properties (which are overridden, if corresponding settings can be retrieved from the OSGi Config Admin service).
  2. The ${portNumber} placeholder is used to specify the TCP port number used by the HelloWorld Web service.
Note
For the Blueprint XML configuration, you must ensure that the instructions for the maven-bundle-plugin in the project's pom.xml file include the wildcard, *, in the packages listed in the Import-Package element (if the Import-Package element is not present, the wildcard is implied by default). Otherwise, you will get the error: Unresolved references to [org.osgi.service.blueprint] by class(es) on the Bundle-Classpath[Jar:dot]: [].

Deploying the configurable application

To deploy the configurable Web service from the cxf-basic project, perform the following steps:
  1. Edit the Blueprint XML file, blueprint.xml, to integrate the OSGi Config Admin service, as described in Example 3.1, “Configuring the Port Number in Blueprint XML”.
  2. Rebuild the cxf-basic project with Maven. Open a command prompt, change directory to the get-started/cxf-basic directory, and enter the following Maven command: 
    mvn clean install
  3. Create the following configuration file in the etc/ directory of your Red Hat JBoss Fuse installation: 
    InstallDir/etc/org.fusesource.example.get.started.cfg
    Edit the org.fusesource.example.get.started.cfg file with a text editor and add the following contents: 
    portNumber=8182
  4. If you have previously deployed the get-started-basic feature (as described in Section 3.4, “Define a Feature for the Application”), uninstall it now: 
    JBossFuse:karaf@root> features:uninstall get-started-basic
  5. Deploy the get-started-cxf feature, by entering the following console command: 
    JBossFuse:karaf@root> features:install get-started-cxf
  6. After waiting a few seconds for the bundles to start up, you can check the port used by the HelloWorld service, by entering the following console command: 
    JBossFuse:karaf@root> cxf:list-endpoints 
Name                      State      Address                                                      BusID                                   
[FabricResource         ] [Started ] [/fabric8                                                  ] [io.fabric8.fabric-rest-cxf250714502   ]
[HelloWorldImplPort     ] [Started ] [http://0.0.0.0:8182/cxf/HelloWorld                      ] [org.fusesource.example.cxf-basic-cxf1456001875]
    You can see from this that the HelloWorld service is listening on port 8182.
  7. If you want to run the Web client test against this Web service, you must customize the URL used by the client. Using a text editor, open the SoapTest.java file from the cxf-basic/src/test/java/org/fusesource/example directory, and change the connection URL as highlighted in the following fragment: 
    URLConnection connection = new URL("http://localhost:8182/cxf/HelloWorld").openConnection();
  8. You can then test the application by opening a command prompt, changing directory to get-started/cxf-basic, and entering the following command: 
    mvn -Ptest
  9. To uninstall the feature, enter the following console command: 
    features:uninstall get-started-cxf