Getting Started with OSGi: Introducing Declarative Services

Welcome to the much-delayed next installment of the "Getting Started with OSGi" series. This installment is quite exciting, because we're going to start experimenting with Declarative Services.

The Declarative Services (or "DS") specification is one of the newest parts of OSGi, and it came about as a result of some of the issues with wiring together service across bundles. It's not that this task is difficult – as I hope my previous tutorials showed – but it does require a fair amount of boilerplate code. It also requires you to be cautious about threading issues, which means you can easily shoot yourself in the foot.

An early attempt to resolve this problem was a tool called Service Binder, developed by Humberto Cervantes and Richard Hall . Service Binder introduced automated service dependency management , allowing developers to focus on the job of writing their services. The wiring between services was handled declaratively, and the declarations were made in XML.

The Declarative Services specification evolved from Service Binder, and it is now a standard part of OSGi versions 4.0 and above. So, lets see what it can do for us.

As I mentioned in the previous installment of the tutorial, I'm tired of doing everything on the command line: from this point onwards, we will use the Eclipse SDK. Please remember though that none of what I'm introducing really depends on Eclipse. Although Eclipse helps a lot with what we're about to do, there's no black magic going on, so anything you see here is perfectly possible in NetBeans, IntelliJ or even good old vi.

The first thing we need to do is download the Equinox implementation of Declarative Services. Assuming you're using the current stable version of Eclipse, which is 3.2.2 at time of writing, the direct link is here . If you're using a different version, you need to find that version from the top-level Equinox download page here and get the file org.eclipse.equinox.ds_x.x.x_xxxxx.jar . Once it's downloaded, drop it into the plugins directory of your Eclipse installation, and restart Eclipse. Actually if you know a little about Eclipse plug-in development already, you should put this JAR into your Target Platform folder. If you don't know what a "Target Platform" is, then don't worry about it, just drop the JAR into the plugins folder.

Now we'll create a new bundle. To do this, we create a project in Eclipse using the Plug-in Project wizard:


   1. From the main menu, select File -> New -> Project.

   2. Select Plug-in Project and hit Next.

   3. Enter the name of the project, SampleExporter .

   4. At the bottom, below the text "This plug-in is targeted to run with", select "an OSGi framework" and then select "standard" from the drop-down. This step isn't absolutely essential, it just prevents us from accidentally using features that are not available out-of-the-box on other OSGi framework implementations.

   5. Click Next. On the following page of the wizard, deselect "Generate an activator...", if it is checked. Then click Finish.



We now have an empty bundle project, so we need to add some code. To keep things as simple as possible, we're going to offer a service using an interface that's already available on every Java runtime: java.lang.Runnable . Using a handy little Eclipse shortcut, just copy the following code from your browser, and then select the src folder inside the SampleExporter project and hit Edit -> Paste. Eclipse will create the package and source file for you.

package org.example.ds;
 
public class SampleRunnable implements Runnable {
 
	public void run() {
		System.out.println("Hello from SampleRunnable");
	}
 
}

So far we haven't seen anything new, but here's where it gets interesting: we're going to create an XML file to declare SampleRunnable as a service. Create a folder at the top level of the project called OSGI-INF and copy the following into a file in that folder called samplerunnable.xml :

<?xml version="1.0"?>
<component name="samplerunnable">
	<implementation class="org.example.ds.SampleRunnable"/>
	<service>
		<provide interface="java.lang.Runnable"/>
	</service>
</component>

This is one of the simpler declarations we will see with DS. It says that there is a component called "samplerunnable" which provides a service to the OSGI Service Registry under the interface java.lang.Runnable , and the component is implemented by the class org.example.ds.SampleRunnable .

The final step is to tell the Declarative Services runtime about the existence of this XML file. We do this by adding a field to the MANIFEST.MF for the bundle. So, open the manifest (try right-clicking on the project and selecting PDE Tools -> Open Manifest) and in the editor, skip to the tab labeled "MANIFEST.MF", as this allows us to edit the text contents of the manifest directly. Add the following line:

Service-Component: OSGI-INF/samplerunnable.xml

Then save the file. As in previous installments, the blank line at the end of the manifest is VERY important, but unlike previously, you will now get an error message from Eclipse if you forget.

Before going any further, lets run Equinox to check that this works. Go to the Run menu and select "Run...". When the dialog opens, select "Equinox OSGi Framework" in the tree on the left, and then hit the New button. If you're an experienced Eclipse user but have not done OSGi development, this launcher dialog might look a little bit strange. The first tab, labeled Bundles, allows us to choose which bundles should be included in the launch configuration, and whether they should be initially started or not. To get the minimal set, click Deselect All and then place a tick next to the following bundles only:


    * SampleExporter (underneath Workspace)

    * org.eclipse.equinox.ds (underneath Target Platform)



These are the bundles we are interested in, but they do have dependencies, so click Add Required Bundles to add those dependencies back in. Also it's a good idea to select "Validate bundles automatically prior to launching". Finally, click Run, and in a few moments the osgi> prompt should appear in the Eclipse console. The OSGi framework is running, and you can interact with it using the same commands you learned previously.

So is our service registered? We can check by typing the command services . Somewhere in the list of services – probably the bottom – you should see the following:

{java.lang.Runnable}={component.name=samplerunnable, component.id=1, service.id=22}
  Registered by bundle: initial@reference:file:..../SampleExporter/ [5]
  No bundles using service.



Yes, it's registered! And notice one important thing: it appears to have been registered by our bundle, not by the Declarative Services bundle. In fact DS has registered it on behalf of our bundle. We'll look at how it does that a little later on, but for the purposes of this lesson, it's enough to note that consumers of our service don't need to do anything special, in fact they need not even know that we are using Declarative Services. Those consumers can use Declarative Services as well if they wish to, but they can also use straightforward OSGi code.

Another thing to note is that in our bundle, there is no OSGi-specific Java code. In other words, the class we wrote is a POJO, and this is a major feature of Declarative Services.

That's enough for this installment, and I'm sorry that this lesson is a little basic. Next time we'll look at how to consume services in various ways with DS, which should really start to show the power and convenience that it offers.