Introduction to OSGi – Modular Java

OSGi Alliance is the governing body of this stranded and it was started at 1999. their initial goal was create open stranded for network devices. Based on this idea this specification introduced for Java also. Eclipse was first in Java. they introduced OSGi based Eclipse IDE at 2004 June.

OSGi is way to define dynamic module in java. There are main three OSGi container implemented for Java,such as Apache Felix, Eclipse Equinox and Knopflefish.

Why OSGi? Because OSGi provide ability to divided application in to multiple module and those module easy to manage with other dependencies. other than that is very easy to install, update,stop and delete module without stop engine(Ex: Tomcat web application container). We can have multiple version of implementation with effecting to other references.

There are main 3 layers in web based Java framework(Presentation , Business layer and DAO layer). There we can divide it into three OSGi based module. then we can very easily fixed bug in one layer with out effecting to others and restarting our Web container. Just we need to update out module.

in OSGi world output is bundle, it can be either Jar or War file. A bundle consists of Java classes and other resources that with some additional metadata (providing services and packages to other bundles).

I am going to use Eclipse IDE for create my first bundle. Because Eclipse IDe has built in Equinox container(every eclipse plugins are OSGi bundles) .

Create Eclipse Plug-In-Project

• Go to New–> Other –> Plug-In-Project and click on Next then new project creation dialog will be appeared
• Provide project name and Target platform as below. and Click on Next

                 Project name     : com.chandana.Hello.HelloWorld
                 Target platform : select Stranded OSGi

• In next screen you can change bundle information(These information available in MANIFEST.MF  and I will give details information later) then click on Next button.

• After that OSGi project template selection dialog will be appear.There select  Hello OSGi Bundle and click on Finish

After few second Eclipse will generate Hello World Plug-In-Project(I had Not responding few second :) )

In my project structure is like this:

Activator.java

package com.chandana.hello.helloworld;
 
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
 
public class Activator implements BundleActivator {
 
 /*
  * (non-Javadoc)
  * @see org.osgi.framework.BundleActivator#start(org.osgi.framework.BundleContext)
  */
 public void start(BundleContext context) throws Exception {
  System.out.println("Hello World!!");
 }
  
 /*
  * (non-Javadoc)
  * @see org.osgi.framework.BundleActivator#stop(org.osgi.framework.BundleContext)
  */
 public void stop(BundleContext context) throws Exception {
  System.out.println("Goodbye World!!");
 }
 
}

Activator is class which implement BundleActivator interface. It has stop and start methods. Those methods are called when a bundle is started or stopped. This bundle activator class specify in MENIFEST.MF file(Bundle-Activator entry).

Start Method:
The OSGi container calls start method when bundle is starting. We can use this start method for initialized database connection, register a service for other bundle use.
Stop Method:
The OSGi container calls stop method when bundle is stopping. We can use this method for remove services form service registry like clean up process

MANIFEST.MF

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: HelloWorld
Bundle-SymbolicName: com.chandana.Hello.HelloWorld
Bundle-Version: 1.0.0.qualifier
Bundle-Activator: com.chandana.hello.helloworld.Activator
Bundle-Vendor: CHANDANA
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Import-Package: org.osgi.framework;version="1.3.0"

Bundle-ManifestVersion
Bundle-ManifestVersion header show the OSGi container that this bundle follows the rules of the OSGi specification. A value of 2 means that the bundle is compliant with OSGi specification Release 4; a value of 1 means that it is compliant with Release 3 or earlier.

Bundle-Name
Bundle-Name header defines a short readable name for bundle.

Bundle-SymbolicName
Bundle-SymbolicName header specifies a unique name for the bundle. This is the name you will use while referring a given bundle from other bundles.

Bundle-Version
Bundle-Version header is the version number of the bundle.

Bundle-Vendor
Bundle-Vendor header is description of the vendor(foe example it’s my name).

Import-Package
Import-Package is indicate what are the other Java bundle(OSGi) required for this bundle. what we called dependency.

Export-Package
Export-Package is indicate what are public packages in bundle and those Export-Package can import from other bundle.

Run the Bundle:

• For Run this project click on Run –> Run Configuration , In OSGi Framework Right click and create new Run Configuration.

Source Code

Next i will describe how to create dependency based OSGi bundle.

An OSGi Service is a java object instance which is registered with OSGi framework with set of attributes. Services can be accessed via service registry(performed via the class BundleContext). BundleActivator is to be invoked on start and stop. When BundleActivator call start method we are going to register our service. After that any bundle can access that service.

Service Bundle:

In service bundle you need to export your service and need to register it via service registry. When we are exporting service we export interface package only. As usual that is to hide the implementation from the other bundles.

I have created a sample OSGi project called HelloService

MANIFEST.MF

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: HelloService
Bundle-SymbolicName: com.chandana.hello.HelloService
Bundle-Version: 1.0.0
Bundle-Activator: com.chandana.hello.helloservice.Activator
Bundle-Vendor: CHANDANA
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Import-Package: org.osgi.framework;version="1.3.0"
Export-Package: com.chandana.hello.service
Bundle-ActivationPolicy: lazy

Service Interface:

public interface  HelloService {    
    public String helloMethods();
}

Service Implementation:

public class HelloServiceImpl implements HelloService {
    @Override
    public String helloMethods() {
        String retValue = "Inside Hello Service method";
        return retValue;
    }
}

Boundle Activator:

public class Activator implements BundleActivator {
    ServiceRegistration serviceRegistration;
    /*
     * (non-Javadoc)
     * @see org.osgi.framework.BundleActivator#start(org.osgi.framework.BundleContext)
     */
    public void start(BundleContext context) throws Exception {
        System.out.println("Bundle Started.....!!!!!");
        HelloService service = new HelloServiceImpl();
        serviceRegistration = context.registerService(HelloService.class.getName(), service,null);
    }
     
    /*
     * (non-Javadoc)
     * @see org.osgi.framework.BundleActivator#stop(org.osgi.framework.BundleContext)
     */
    public void stop(BundleContext context) throws Exception {
        System.out.println("Bundle Stoped.....!!!!!");
        serviceRegistration.unregister();
    }
}

When we are using published services, we can import it from another Bundle. So need to create another Plug-In-Project for HelloClient

Bundle Context

Bundle context is the context of a single bundle within the OSGi runtime and it is created when Bundle get started. Bundle context can be used to Install new bundles, Obtain registered services by other bundles and Register services in the framework.

MANIFEST.MF

Import-Package: org.osgi.framework;version="1.3.0",com.chandana.hello.service

After importing the bundle, you can access the service. Important thing is service can be accessed only through bundle context. You can get actual service object via BundleContext.getService() method .

Activator class:

public class Activator implements BundleActivator {
     ServiceReference serviceReference;     
    /*
     * (non-Javadoc)
     * @see org.osgi.framework.BundleActivator#start(org.osgi.framework.BundleContext)
     */
    public void start(BundleContext context) throws Exception {
        serviceReference= context.getServiceReference(HelloService.class.getName());
        HelloService helloService =(HelloService)context.getService(serviceReference);
        System.out.println(helloService.helloMethods());
    }
     
    /*
     * (non-Javadoc)
     * @see org.osgi.framework.BundleActivator#stop(org.osgi.framework.BundleContext)
     */
    public void stop(BundleContext context) throws Exception {
        context.ungetService(serviceReference);
    }
}

context.getServiceReference() method return the HelloService OSGi service reference and Using that service reference can access the actual service object.

For Run this project click on Run –> Run Configuration , In OSGi Framework Right click and create new Run Configuration. Make sure HelloService and HelloClient .

Issues:
What happened if the service is not started when client is accessing the service?
What happened if you have stopped the service bundle?

Code Repo:
http://code.google.com/p/osgi-world/source/browse/#svn/trunk/com.chandana.hello.HelloService
http://code.google.com/p/osgi-world/source/browse/#svn/trunk/com.chandana.hello.HelloClient

Reference: Introduction to OSGi(Java Modular) & Introduction to OSGi – 2 (OSGi Services) from our JCG partner Chandana Napagoda at the Chandana Napagoda blog.