Fuse ESB Enterprise - Getting Started - 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 Spring XML file or 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 Fuse ESB Enterprise 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 ESBInstallDir/etc directory, which obeys the following naming convention:
```
ESBInstallDir/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:
- Using the Fuse Management Console UI tool.
- Using the fabric:profile-edit command in a container console (see Create Fabric Profiles).

Replace IP port with a property placeholder

As an example of how the OSGi Config Admin service might be used in practice, consider the IP port used by the PersonService Web service from the cxf-basic project. By modifying the Spring XML file that defines this Web service, you can make the Web service's IP port customisable through the OSGi Config Admin service.

The IP port number in the Spring 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.

Spring XML example

In the cxf-basic project, any XML files from the following location are treated as Spring XML files (the standard Maven location for Spring XML files):

cxf-basic/src/main/resources/META-INF/spring/*.xml

Edit the beans.xml file from the preceding directory and add the XML contents shown in Example 3.

Example 3. Configuring the Port Number in Spring XML

<?xml version="1.0" encoding="UTF-8"?>
<!-- Generated by Apache ServiceMix Archetype -->
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:jaxws="http://cxf.apache.org/jaxws"
    xmlns:osgix="http://www.springframework.org/schema/osgi-compendium"
    xmlns:ctx="http://www.springframework.org/schema/context"
    xsi:schemaLocation="
        http://www.springframework.org/schema/beans
          http://www.springframework.org/schema/beans/spring-beans.xsd
        http://cxf.apache.org/jaxws
          http://cxf.apache.org/schemas/jaxws.xsd
        http://www.springframework.org/schema/osgi
          http://www.springframework.org/schema/osgi/spring-osgi.xsd
        http://www.springframework.org/schema/context
          http://www.springframework.org/schema/context/spring-context.xsd
	    http://www.springframework.org/schema/osgi-compendium
          http://www.springframework.org/schema/osgi-compendium/spring-osgi-compendium.xsd">

    <!-- Configuration Admin entry -->
    <osgix:cm-properties id="cmProps" persistent-id="org.fusesource.example.get.started">
      <prop key="portNumber">8181</prop>
    </osgix:cm-properties>

    <!-- placeholder configurer -->
    <ctx:property-placeholder properties-ref="cmProps" />

    <jaxws:endpoint id="HTTPEndpoint"
        implementor="org.fusesource.example.PersonImpl"
        address="http://0.0.0.0:${portNumber}/PersonServiceCF"/>

</beans>

The highlighted text shows what is changed from the original beans.xml file, in order to integrate the OSGi Config Admin service. Apart from defining the osgix and ctx namespaces, the main changes are as follows:

The osgix:cm-properties 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 prop child elements specify default values for the properties (which are overridden, if corresponding settings can be retrieved from the OSGi Config Admin service).
The ctx:property-placeholder bean makes the properties from the osgix:cm-properties bean accessible as property placeholders. That is, a placeholder of the form ${PropName} will be replaced by the value of PropName at run time.
The ${portNumber} placeholder is used to specify the IP port number used by the PersonService Web service. Note the value of the address attribute is now specified as a full HTTP address (in contrast to the address shown in Example 2), which means that the WS endpoint gets deployed into a custom Jetty server (instead of the default Jetty server).

Blueprint XML example

To use blueprint configuration instead of Spring configuration, replace the Spring XML file by a blueprint XML file, where the blueprint file must be added to the following location in the cxf-basic project:

cxf-basic/src/main/resources/OSGI-INF/blueprint/*.xml

Create a beans.xml file in the preceding location and add the XML contents shown in Example 4.

Example 4. 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:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0">

    <!-- 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="HTTPEndpoint"
        implementor="org.fusesource.example.PersonImpl"
        address="http://0.0.0.0:{{portNumber}}/PersonServiceCF"/>

</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:

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).
The {{portNumber}} placeholder is used to specify the IP port number used by the PersonService Web service.

Note

	Note
If you want to try out 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]: []`.

If you want to try out 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:

Edit the Spring XML file, beans.xml, to integrate the OSGi Config Admin service, as described in Example 3.
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
```
Create the following configuration file in the etc/ directory of your Fuse ESB Enterprise installation:
```
ESBInstallDir/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
```
If you have previously deployed the get-started-basic feature (as described in Define a Feature for the Application), uninstall it now:
```
karaf@root> features:uninstall get-started-basic
```
Deploy the get-started-cxf feature, by entering the following console command:
```
karaf@root> features:install get-started-cxf
```

After waiting a few seconds for the bundles to start up, you can test the application by opening a command prompt, changing directory to get-started/cxf-basic, and entering the following command:

mvn -Pclient -Dexec.args="http://localhost:8182/PersonServiceCF"

	Important
	The URL in this command has a slightly different format from the URLs used in the previous client commands: the path part of the URL is `/PersonServiceCF`, instead of `/cxf/PersonServiceCF`.

To uninstall the feature, enter the following console command:
```
features:uninstall get-started-cxf
```