11.2. Using the Port Service

Overview

This section explains how to use the port service in you own applications, taking the example-camel-cxf profile as an example. There are two basic steps to configuring the port service in your application:
  • At development time—using the property placeholder service, replace a service's fixed port number by a key.
  • At deployment time—using the OSGi Config Admin service, specify the key value as a port range. For example, you can specify the key value as a PID property setting in a Fabric profile.
It is possible to configure the property placeholder in Blueprint XML, or in Java (using the relevant OSGi API).
Note
The property placeholder syntax in Spring XML is deprecated (it belongs to the deprecated Spring-DM component).

Demonstration code

This example is based on the example-camel-cxf profile. The source code for the example is taken from the fabric-camel-cxf example on Github, which is available from the following URL: 
https://github.com/fabric8io/fabric8/tree/1.x/fabric/fabric-examples/fabric-camel-cxf

Property placeholder in XML configuration

The following Spring XML configuration shows the definition of an endpoint for the greeter Web service (taken from the file, src/main/resources/OSGI-INF/blueprint/cxf.xml, in the fabric-camel-cxf demonstration): 
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:cxf="http://camel.apache.org/schema/blueprint/cxf"
           xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.1.0"
           xsi:schemaLocation="
           http://www.osgi.org/xmlns/blueprint/v1.0.0
           http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
           http://camel.apache.org/schema/blueprint/cxf
           http://camel.apache.org/schema/blueprint/cxf/camel-cxf.xsd">

    <cm:property-placeholder id="placeholder"
                             persistent-id="io.fabric8.examples.camel.cxf"
                             update-strategy="reload">
        <cm:default-properties>
            <cm:property name="greeterPort" value="9090"/>
        </cm:default-properties>
    </cm:property-placeholder>

    <cxf:cxfEndpoint id="greeterEndpoint"
                     address="http://localhost:${greeterPort}/greeter"
                     serviceClass="io.fabric8.examples.camelcxf.Greeter">
      <cxf:features>
        <bean class="io.fabric8.cxf.endpoint.ManagedApiFeature"/>
      </cxf:features>
    </cxf:cxfEndpoint>
    ...
</blueprint>
The CXF endpoint (which binds to a Camel route) is defined by the cxf:cxfEndpoint element. In the address attribute, the port number is specified by substituting the greeterPort key, ${greeterPort}. The property placeholder mechanism is configured by the cm:property-placeholder element, which specifies that the greeterPort property belongs to the io.fabric8.examples.camel.cxf PID. The property placeholder mechanism is integrated with the OSGi Config Admin service, which allows you to override the port number at deployment time.

Specifying a port range using OSGi Config Admin

At deployment time, you can override the default port number of the greeter Web service. In this particular example, where the deployment is described by the example-camel-cxf profile, the port number is integrated with the port service and specified as a port range.
Because the port range is defined at deployment time, it is not specified in the example source code, but is instead specified in the example-camel-cxf Fabric profile. You can see the configured port range by entering the following console command: 
JBossFuse:karaf@root> fabric:profile-display example-camel-cxf
In the output of this command, you should see the following configuration setting for the io.fabric8.examples.camel.cxf persistent ID: 
...
Configuration details
----------------------------
PID: io.fabric8.examples.camel.cxf
  greeterPort ${port:9090,9190}
...
The preceding output shows that the greeterPort key is set to ${port:9090,9190}.

Modifying the port range

If you want to modify the port range configured in the example-camel-cxf profile, you can do so using the fabric:profile-edit console command. For example, to change the value of greeterPort to the range, ${port:7070,7170}, you would enter the following console command: 
JBossFuse:karaf@root> fabric:profile-edit
  --pid io.fabric8.examples.camel.cxf/greeterPort=\$\{port:7070,7170\}
  example-camel-cxf
Where the $ sign and the curly braces, { }, must be escaped by the backslash character, \, as shown. Alternatively, if you prefer to edit the port range using the built-in text editor, you can enter the following console command instead: 
JBossFuse:karaf@root> fabric:profile-edit --pid io.fabric8.examples.camel.cxf example-camel-cxf