OSGi DS Declarative Services example

In this post we will give a fair example of the workings of the OSGi DS services.

I suggest you read a good OSGi tutorial by Lars Vogel before moving further if you are not much confident with the OSGi specification.

We are working with the Equinox OSGi framework, which is part of the Eclipse IDE (for Java). The code can be launched either inside Eclipse or from a standalone OSGi framework; for the latter option, grab the following jar packages from under the plugins/ folder of our Eclipse installation:

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

and copy them in a folder of your choice.

Now open a command prompt, browse to that folder and type:

java -jar org.eclipse.osgi.jar -console

to make the OSGi prompt appear. From here you can issue a lot of commands to the OSGi framework, some of which are:

• help
• ss - shows the current status of the installed bundles
• install file:path - installs the bundle available at the specified path. It will be given an unique numeric ID
• uninstall ID
• start ID
• stop ID
• refresh - forces a framework refresh and update of the bundles state

The bundles can be in only one of the following states at a time:

• INSTALLED: the bundle has been successfully installed on the platform;

• RESOLVED: all of the bundle's dependencies are currently available, the bundle is ready to be started or it has just been stopped;

• STARTING: the bundle is starting, it is waiting for the method which takes care of the necessary start operations to return;

• ACTIVE: the bundle is up and running;

• STOPPING: the bundle is stopping, it is waiting for the method which takes care of the necessary stop operations to return.

There exists an additional state, UNINSTALLED, but it will never be shown by the framework.

In order for the DS component to work properly, you must install and start all the bundles copied before (org.eclipse.osgi excluded) inside the framework. 

Now we can begin our example.

Interfaces, implementations and clients should all reside in their own package, meaning you should create a new Plug-in project, without Activator or template inside Eclipse (with the RCP Plug-in developer resources plugin installed) for each of them.

Suppose we have two services: HappyService and SadService, their interfaces: IHappy and ISad and a client: Customer who declares a dependency on the services by pointing to their interfaces using the DS method.

When a component declares it provides a service, the OSGi framework stores that information in its internal registry.

Download here the example's source code. You should be able to import everything inside Eclipse as-is. Inside you will find:

Interface - IHappy.java

package it.eng.test.ds.happy;

public interface IHappy {
 public void imHappy();
}

Interface - ISad.java

package it.eng.test.ds.sad;

public interface ISad {
 public void imSad();
}

Implementation - HappyService.java

package it.eng.test.ds.happyservice;

import it.eng.test.ds.happy.IHappy;

public class HappyService implements IHappy{
 public void imHappy(){
  System.out.println("I'm happy :)");
 }
}

Implementation - SadService.java

package it.eng.test.ds.sadservice;

import it.eng.test.ds.sad.ISad;

public class SadService implements ISad{
 public void imSad(){
  System.out.println("I'm sad :(");
 }
}

If you inspect them, you will see that the two services offer a single, simple method which prints something on standard output.

Client - Consumer.java

package it.eng.test.ds.consumer;

import it.eng.test.ds.happy.IHappy;
import it.eng.test.ds.sad.ISad;

public class Consumer {
 private IHappy happy;
 private ISad sad;
 
 public synchronized void bindHappy(IHappy happy){
  this.happy = happy;
  happy.imHappy();
 }
 
 public synchronized void unbindHappy(IHappy happy){
  this.happy = null;
  sad.imSad();
 }
 
 public synchronized void bindSad(ISad sad){
  this.sad = sad;
  sad.imSad();
 }
 
 public synchronized void unbindSad(ISad sad){
  this.sad = null;
  happy.imHappy();
 }
 
 public void activate(){
  System.out.println("I'm here");
 }
 
}

The consumer declares the dependency on the two services by requiring their interfaces and has some methods of his own:

activate: this method is called as soon as the client bundle is started;
bind*: this method is called immediately after the required *Service becomes available on the framework;
unbind*: this method is called immediately after the required *Service becomes unavailable on the framework.

The framework knows that Consumer needs those particular services since he declared it in his XML configuration which must be put under the OSGI-INF/ folder:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" name="it.eng.test.ds.consumer">
   <implementation class="it.eng.test.ds.consumer.Consumer"/>
   <reference bind="bindHappy" cardinality="0..1" interface="it.eng.test.ds.happy.IHappy" name="IHappy" policy="dynamic" unbind="unbindHappy"/>
   <reference bind="bindSad" cardinality="0..1" interface="it.eng.test.ds.sad.ISad" name="ISad" policy="dynamic" unbind="unbindSad"/>
</scr:component>

In there the bundle is saying that the class it.eng.test.ds.consumer.Consumer dynamically and optionally depends on one of the possible it.eng.test.ds.happy.IHappy interface implementations and that when one of them becomes available or unavailable inside the framework, its bindHappy or unbindHappy method should be called.

The dynamically policy attribute means that the bundle is able to work properly even when the services are dynamically switched; the alternative would be static, which would require the DS to deactivate the component and create a new instance each time the required service changes.

The dependency is optional since the cardinality was set to 0..1, meaning the component can be started even if that particular dependency is not currently available, contrarily to 1..1 which means instead that it is mandatory. Another alternative would be 0..N, which would require the DS to invoke the associated method multiple times, one for each service instance currently available in the registry.

Furthermore, the name of the bind* and unbind* methods can be changed as pleased as long as it reflects the ones written in the java code.

On their side, the two services must declare their own XML configurations, listing the interface implementations offered and the classes implementing them:

HappyService XML:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" name="it.eng.test.ds.happyservice">
   <implementation class="it.eng.test.ds.happyservice.HappyService"/>
   <service>
      <provide interface="it.eng.test.ds.happy.IHappy"/>
   </service>
</scr:component>

SadService XML:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" name="it.eng.test.ds.sadservice">
   <implementation class="it.eng.test.ds.sadservice.SadService"/>
   <service>
      <provide interface="it.eng.test.ds.sad.ISad"/>
   </service>
</scr:component>

When we export our projects as Deployable plug-ins and fragment and install all the resulting bundles inside the same OSGi framework and start them, we see that Consumer prints on the standard output the string "I'm here" right after it is starts and then, alternatively depending on their service implementation bundle's state, the strings: "I'm happy :)" and "I'm sad :(".