Getting Started with OSGi Declarative Services

OSGi Declarative Services have been on my mental agenda for a while, and now I've started using them. I'm not going to write yet another tutorial on the subject, but there are some bits and pieces I could not find anywhere else that may be worth mentioning.

To get an overview of Declarative Services, have a look at Neil Bartlett's tutorial on EclipseZone, or at his more recent EclipseCon presentation. The former is based on Eclipse 3.2.2, the latter on the latest Eclipse 3.5 milestones, so there are some differences to the current release Eclipse 3.4.2. In particular, Eclipse 3.5 supports a newer version of the Declarative Services Specification (1.1 vs. 1.0 in Eclipse 3.4).

All of the following refers to Eclipse 3.4.2. For using Declarative Services with Equinox, you need the following bundles:

• org.eclipse.osgi
• org.eclipse.osgi.services
• org.eclipse.equinox.ds
• org.eclipse.equinox.util

The last two are not included in standard Eclipse distributions. Download them from the Equinox download area, or use the Eclipse update manager to install Equinox Bundles.

Follow the tutorials to implement a simple example. If you cannot figure out why your component does not start, enable console logging for the Service Component Runtime in your OSGi launcher by setting the following system properties.

• equinox.ds.debug=true
• equinox.ds.print=true

Make sure to include the OSGI-INF folder with your component descriptors into the binary build on the Build tab of the Eclipe manifest editor. This amounts to adding the folder to the bin.includes property in the build.properties.

Add a header Service-Component: OSGI-INF/components.xml to your manifest. (Choose any other filename if you like.)

Do not forget to specify the correct XML namespace http://www.osgi.org/xmlns/scr/v1.0.0 in your XML documents, or else your component definitions will not be recognized.

Seeing that Eclipse 3.4 has no graphical editors for the component descriptors, it is useful to install the Eclipse XML editor features and to work with XML validation on the component descriptors.

If your bundle contains more than one component, you can have one XML document per component and list them all in the manifest header, or you can have a single XML document containing all component descriptions, which is what I prefer.

To enable XML validation on a multi-component descriptor, write your own XML schema where the root element contains a sequence of 1..n component descriptors.

Here is an XML schema for this purpose:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
        xmlns:scr="http://www.osgi.org/xmlns/scr/v1.0.0" 
        targetNamespace="http://www.harmanbecker.com/anaconda/components" 
        xmlns:tns="http://www.example.org/components" 
        elementFormDefault="qualified">

   <import namespace="http://www.osgi.org/xmlns/scr/v1.0.0"/>

    <element name="components">
      <complexType>
        <sequence>        
          <element ref="scr:component" maxOccurs="unbounded"/>
        </sequence>
      </complexType>
    </element>
</schema>

Using this schema, a component descriptor for two components might look like this:

<?xml version="1.0" encoding="UTF-8"?>
<c:components xmlns:scr="http://www.osgi.org/xmlns/scr/v1.0.0"
      xmlns:c="http://www.harmanbecker.com/anaconda/components">


 <scr:component name="foo">              
   <implementation class="com.acme.foo.FooImpl"/>
   <service>
     <provide interface="com.acme.foo.Foo"/>
   </service>
 </scr:component>

 <scr:component name="bar">              
   <implementation class="com.acme.foo.BarImpl"/>
   <service>
     <provide interface="com.acme.bar.Bar"/>
   </service>
 </scr:component>

</c:components>