Dynamic http responses with OSGi

Posted: February 15th, 2011 | Author: | No Comments »

The benefits of OSGi are well-known and there are a lot of articles explaining how this technology can improve a system: modular development, pluggable architecture, dynamic services, etc.

I’m going to try to explain the basic concepts of OSGi by using a simple scenario. The idea of this example is very easy: to take a http request and to print the result applying a transformer over a text message. Dynamic behaviour appears with the differents transformers are not defined at the same time and in the same component of the core system. If you know how an OSGi container works, you’ve probably assumed that the example have at least two bundles (or plugins): one to accept the request and return the response, and another one to carry out its transformation over the message.

The example

As I said before, the example is very easy but I think that it represents the common uses of this technology. The system consists of two distinct components:

  1. Main bundle that captures http request, for example http://localhost/transform?to=xml, extracts the transformation type (xml, json, text, etc) from the request, looks for the appropiate transformer service that works with this type in the container and if it exists then returns the response transformed. For the http conversation this component uses a servlet through an extension provided by Equinox. Thanks to this feature it is very easy to program a servlet that listens a request by using Jetty as a servlet container. In addition, this component provides the interface that all transformers have to implement.
  2. Specific implementation of the transformer. When this bundle is actived  it sets to container what kind of transformation it can do, it’s like this bundle will say something similar to “hey! I can transform text to XML, so if you want this functionality, please call me :) ”.

Creating the project

The first step of this tutorial is to create the project using Eclipse. In this example I use a simple installation of Eclipse Helios and Equinox as an OSGi container. First of all, we’re going to create the first plugin which will have the responsability of dealing with http request. The steps are easy: File > New > Project … > Plug-in Project

As we can see in the image, the OSGi framework chosen is Equinox. We could choice easily another container such as Felix or Knopflerfish, but we need extensions for the servlet and this feature is only provided by Equinox.

Accept the wizard and the plugin project will be created in our workspace.

Setting dependencies

When the wizard is finished, we can explore the structure of this project. All OSGi bundles have similar structure. The most important file in an OSGi bundle is MANIFEST.MF, because this file stores the bundle name and the dependencies information and exported classes to be used for another bundles. If you click over this file, a special page shows how to configure the different options. At the moment we just need to set what dependencies this bundle needs: click to Dependencies tab and add the following ones:
org.eclipse.equinox.http.jetty, org.eclipse.equinox.http.servlet, org.eclipse.equinox.registry, org.eclipse.equinox.registry

Defining and exporting TransformerService interface

To allow the differents bundles with transformation services can integrate with this system, it’s necessary to define an interface with the methods that the custom transformers have to implement. The interface code is:

public interface TransformerService {

	 * Performs the transformation over message passed by parameter and returns the result
	 * @param message
	 * @return
	public String transform(String message);

	 * Indicates the type of transformation
	 * @return
	public String getType();


Methods are self explanatory :) . The next step is to export this interface to outside so the others bundle can see. This is configured in MANIFEST.MF file, in Runtime part. In this tab, in the Exported Packages section, you can specify what packages you want the others bundles can access. A good practice is to isolate the own functionallity of the bundle (in our case, the servlet class) and to export the classes and interfaces that they are part of the public API. About this, the book OSGi and Equinox propose to divide the package into subpackage named “api” and “internal” to separate exported packages of internal packages.

Activator and servlet

Eclipse generates a default class named Activator that is configured in the MANIFEST.MF file. This class has two important methods (start and stop) that they are called when the container activates (or deactivate) this bundle. Basicly these method receive the context and register (or unregister) the bundle. In this example, this bundle doesn’t provide any service to others, so you can remove this class and unset it in the Overview tab of MANIFEST.MF.

The next step is to implement the servlet. At this point, Equinox gives us a powerful way to declare dynamic services. This feature is named as Extension and, in this case, it allows us avoiding the web.xml file to declare our servlets classes. To configure it, in the Extensions tab we need to specify that our bundle will implement a servlet that requires a servlet container, so to perform this configuration we have to add the extension named as org.eclipse.equinox.http.registry.servlets and to fill the options:

Alias indicates which part of the url the servlet will be activated with, and class indicates what the servlet class will map this alias.

The next step is to create the servlet, the code is as a follow:

public class Servlet extends HttpServlet {

	 * Serial version UID
	private static final long serialVersionUID = 1L;

	 * Retrieves the transformer service that matches with the filter
	 * passed by parameter
	 * @param type
	 * @return TransformerService
	private TransformerService lookupService(String type) {
		BundleContext context = Activator.getContext();
		ServiceReference[] references;
		String filter = "(type=" + type + ")";
		try {
			references = context.getAllServiceReferences(TransformerService.class.getName(), filter);
		} catch (InvalidSyntaxException e) {
			return null;

		if(references != null){
			return (TransformerService) context.getService(references[0]);
		} else {
			return null;

	 * (non-Javadoc)
	 * @see javax.servlet.http.HttpServlet#doGet(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)
	protected void doGet(HttpServletRequest req, HttpServletResponse resp)
			throws ServletException, IOException {

		PrintWriter out = resp.getWriter();
		String type = req.getParameter("to");

		TransformerService service = lookupService(type);
		if(service != null){
			out.append(service.transform("Testing message"));
		} else {
			out.append("Sorry, but there isn't any services to transform to " + type);


The doGet method captures the value of parameter “to” (for example “xml” for http://localhost/transform?to=xml) and calls to method lookupService with this value. If there isn’t any instance of this service the servlet prints an error message or prints the result of calls the transform method with test message if there is.
The lookupService method obtains the context through Activator class and returns the TransformerService instance in the container that matches with the condition “type=xml”. Pay attention to how an instance is filtered according to their properties; the method getAllServiceReferences take the interface name and a string with the filter of its properties. The filter syntax is based on LDAP search, in this link you can get more information about this.

First transformer bundle

So far, we have been working in the same project, which take the request and look for the right transformer, but where is the transformer code? This is precisely the power of OSGi: the service definition can be separted of its implementation using differents bundles, even the bundles can be in differents machines (distributed OSGi). According to this development model, we’re going to create a new plugin project for this first transformer following the steps defined above. In this case, the transformer will take the message and it will transform it to simple XML.

Once the project is created, the next step is to configure the MANIFEST.MF by setting the previous project (which contains the servlet) as a required plug-in:

Thanks to this dependency, we can access to TransformerService interface from this bundle. So, we have to implement our version of the transformer for xml.

public class XMLTransformerService implements TransformerService {

	public String transform(String message) {
		return "<message>" + message + "</message>";

	public String getType() {
		return "xml";


This transformation is too ligth, simply wraps the message using a tag. Now, the last step is to define how this bundle will register its transformation services. To this end, just write the registration code into start method in Activator class and unregister the service in stop method. The Activator code is something like this:

public class Activator implements BundleActivator {

	private ServiceRegistration registration;

	public void start(BundleContext bundleContext) throws Exception {
		TransformerService service = new XMLTransformerService();
		Dictionary<String, String> props = new Hashtable<String, String>();
		props.put("type", service.getType());

		registration = bundleContext.registerService(TransformerService.class.getName(), service, props);

	public void stop(BundleContext bundleContext) throws Exception {


The start method creates an instance of XMLTransformerService and registers with a property. This property is created by using a dictionary where the type of transformation is specified, and is useful when the other bundle wants to obtain an implementation that match with the type it is looking for.

Running the example

Ok, that’s all, you have created a simple dynamic scenario where OSGi can show you its potential. The last step is to run the example into Equinox container. This step is very easy, just click Run As – Run Configurations… through the contextual menu over any project. Then click new OSGi Framework and select what bundle you want to start up. Finally, you have to specify what bundles the container needs to, so click in Add Required Bundle and in the target area a few bundles are checked automatically.

If you are working with Linux you should add a VM parameter, because by default Jetty starts on port 80, and in this operating system this port is protected.
The parameters is -Dorg.eclipse.equinox.http.jetty.http.port=8080 and you have to put it in the VM Arguments, in Arguments tabs.

When you click Run button, Equinox will start and the bundles will be loaded inside the container, invoking each start method in its Activator class (the order of the loading of each bundle is also configurable). Once Equinox is running, you can interact with the container shell through the console view. This console allows you to start bundles, to see what services are availables, to extract some information from the containet, etc. If you type “help” in the console, the list basic commands will be shown.

Now, you can perform a http request with your favourite browser to http://localhost:8080/transform?to=xml and see what is the response. Also you can try another request, for example http://localhost:8080/transform?to=json and see how the system can’t find a transformer service for this type.

At this point, it’s very interesting that you are able to create a new bundle with new implementation transformer service and to play around with differentes commands to start bundles and stop them and to understand the real dynamic scenario. :)

Tags: , , , , ,