Declarative Services can also be used to register properties with the service when it is registered. These properties can be sourced either from the services XML file or an external properties file.

To add the service.ranking property to the registered service, add the following into the services document:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0"
 name="TimeZonesProvider">
  ...
  <property name="service.ranking" type="Integer" value="2"/>
</scr:component>

When the application is restarted, the services console command will show that the service.ranking property is associated with the TimeZonesService:

osgi> services | grep timezones
{com.packtpub.e4.timezones.TimeZonesService}=
 {service.ranking=2,
  component.name=TimeZonesProvider,
  component.id=0,
  service.id=48,
  service.bundleid=11,
  service.scope=bundle}

The property types can be one of:

Additionally, arrays of elements can be specified by placing them in the body of the element instead of as an attribute:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0"
 name="TimeZonesProvider">
  ...
  <property name="compass.point" type="String">
    NORTH
    EAST
    SOUTH
    WEST
  </property>
</scr:component>

As well as hard-coded values, it is also possible to set up references to services in DS. The service implementation can have bind and unbind methods, which are called when a service becomes available or goes away.

These can be mandatory or optional; if the dependency is mandatory then the service is not presented until its dependencies are available. If they are optional, the service can come up and be assigned later. They can also be single-valued or multi-valued. These are encoded in the relationships cardinality:

This can be used to inject a LogService (from the org.osgi.service.log package; it may be necessary to add this as an imported package to the bundle) into the component. Modify the TimeZonesProvider to accept an instance of the LogService by adding a setLog and unsetLog method:

private LogService logService;
public void setLog(LogService logService) {
  this.logService = logService;
}
public void unsetLog(LogService logService) {
  this.logService = null;
}

This can be used to report on how many time zones are loaded in the getTimeZones method of the TimeZonesProvider class:

if (logService != null) {
  logService.log(LogService.LOG_INFO,
   "Time zones loaded with " + timeZones.size());
}

To configure DS to provide a log service, the following must be added to the timezones.xml file:

<scr:component name="TimeZonesProvider"
 xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0">
 ...
 <reference interface="org.osgi.service.log.LogService"
  cardinality="0..1" name="log" 
  bind="setLog" unbind="unsetLog"/>
</scr:component>

This tells DS that the log service is optional (so it will bring the service up before a LogService is available), and that setLog(log) will be called when it is available. DS also provides an unbind method which can be used to remove the service if it goes away. The instance is provided for both the setLog and unsetLog method, which may look strange—but when setting multiple elements the methods are typically called addThing and removeThing, which may be more appropriate.

Although this seems to imply that an XML file can only contain one component, in fact an XML parent element can be defined with multiple scr namespaced children. Since all elements outside the scr namespace are ignored, it is possible to embed an XHTML document with an scr namespaced element inside, and still have it picked up by Declarative Services:

<xhtml>
  <h1>Example HTML file with SCR elements</h1>
  <h2>Component One</h2>
  <scr:component name="One" xmlns:scr="http://...">
    …
  </scr:component>
  <h2>Component Two</h2>
  <scr:component name="Two" xmlns:scr="http://...">
    …
  </scr:component>
</xhtml>

Note that many developers will use a one-to-one mapping between service components and corresponding XML files; it is rare to see a single XML file with multiple service components. It is recommended to only put one component per XML file for ease of maintenance.

If using Maven Tycho to build bundles, it is possible to add a Maven plug-in to generate the service xml files from components. Maven Tycho is covered in more detail in Chapter 12, Automated Builds with Tycho.

To configure the maven-scr-plugin to a build, first add the following dependency to the pom.xml file:

<dependencies>
  <dependency>
    <groupId>org.apache.felix</groupId>
    <artifactId>org.apache.felix.scr.ds-annotations</artifactId>
    <version>1.2.8</version>
    <scope>compile</scope>
  </dependency>
</dependencies>

This both provides the org.osgi.service.component.annotations classes as well as the processing engine necessary to generate the components. Note that even if other dependencies are given (say, osgi.enterprise or equinox.ds) this isn't sufficient on its own to generate the service.xml files.

Next the plugin needs to be added to the pom.xml file:

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.felix</groupId>
      <artifactId>maven-scr-plugin</artifactId>
      <version>1.22.0</version>
      <configuration>...</configuration>
      <executions>...</executions>
    </plugin>
  </plugins>
  <sourceDirectory>src</sourceDirectory>
</build>

The source directory needs to be specified to match the value of the source attribute of the build.properties file (which is used by eclipse-plugin instead of sourceDirectory), as otherwise the maven-scr-plugin cannot find the source files.

The plug-in needs to be configured specifically for eclipse-plugin projects. Firstly, the supported projects default to jar and bundle for the maven-scr-plugin, so it needs to be given additional configuration to permit processing eclipse-plugin projects.

Secondly the service files are written to target/classes/ by default. Although this will work, it makes for more difficult debugging in Eclipse. Instead, the maven-scr-plugin can be configured to write it to the project root, which will place the service files under OSGI-INF. This permits the code to be tested in Eclipse as well as exported using the standard build tools:

<configuration>
  <supportedProjectTypes>
    <supportedProjectType>eclipse-plugin</supportedProjectType>
  </supportedProjectTypes>
  <outputDirectory>${basedir}</outputDirectory>
</configuration>

Finally, to hook it in with the standard build process, add the following to the build:

<executions>
  <execution>
    <id>generate-scr</id>
    <goals>
      <goal>scr</goal>
    </goals>
  </execution>
</executions>

Now when the package is built, the service descriptor xml file will be automatically be regenerated based on the annotations. The file name is derived from the class name.