OSGI Bundle Tutorial

OSGI Bundle Tutorial will drive you through – BND tools workspace creation, a sample OSGI bundle project and OSGI run time creation., we will see “How to develop OSGI Bundle”  and  this tutorial is intended for beginners who are about to start learning OSGI, before starting, just go through the tutorial:  OSGI Building blocks tutorial 

Installations:

What are required to start OSGI Project?

1. Eclipse IDE : Download latest Eclipse IDE that supports BND tools plugin version
2. BND Tools eclipse plugin :
   • provides templates, dependencies
   • OSGI run time environment to develop,manage and run OSGI bundles.
   • auto creates bundle and  MANIFEST.MF file
   • Install the BND tools from  http://bndtools.org/installation.html
   • Dependencies: BND workspace provides list of dependencies required for the project. you no need to worry about this
   • OSGI Run time:  BND tools provides run time templates and you need to create “Run Descriptor File”. OSGI Run time  is required to run OSGI bundles and below are popular OSGI container providers
     • Apache Felix – OSGi container implementation from the Apache Software Foundation.
     • Equinox  – Eclipse IDE is built on top of OSGI and RAP. Eclipse by default comes with OSGI container
     • Knopflerfish  – Knopflerfish is also OSGI container provider
     • Refer to section “How to run OSGI bundles”

Lets start developing simple OSGI bundle:

Bnd Workspace Creation:

• All BND based projects requires bnd workspace to get start
• Bnd workspace is different from  normal eclipse workspace and BND workspace contains all project dependencies and build configurations for  OSGI projects
• Bnd workspace groups all OSGI bundle projects along with  conf directory. It also provides Gradle build  support to build projects automatically.
• Let’s create Bnd workspace in the eclipse.
  • click File -> New -> Bnd Workspace
  • by default it creates in eclipse workspace, but always choose different folder.
  • Select create in and give bnd workspace folder location 
  • Select bndtools/workspace  (osgi/workspace provides huge number of OSGI external dependencies). For now, just use bndtools/workspace
    
  • It will create the cnf directory
  • Now Bnd workspace creation in completed. This entire bnd-workspace can be used as your Source Code Repository in SVN / GIT.

 OSGI Bundle Project Sample Tutorial.

• In Eclipse,  Click File->New->BND OSGI Project
• Select Project Template: In this section, select Empty Project
• What is Project Template? – BND provides list of project templates for web based project, REST/SOAP web services based project like Maven Archie type.
• Give Project name as “org.javasavvy.demo”. It is  always best practice to give project name as “package name” as OSGI bundles follows this specification.
• It will create the below project structure and each project will have bnd.bnd file that contains settings of the project
• bnd.bnd file is :
  • Contents and Description sections are used  to auto create MANIFEST.MF file
  • Build section is used manage project dependencies
  • Run section is used to Run the OSGI bundle, but we will create another file “run.bnd” to the bundle.
• Update OSGI dependencies :
  • Open bnd.bnd file and click on build tab.
  • Under build path,click on + icon.
  • It will open below path and search for osgi and add osgi.core bundle
  • Save the file and refresh the project. It will add osgi.core in the referenced libraries.
    
• Every OSGI Bundle project requires Custom Bundle Activator if you are not using Declarative annotations.
• Now create a DemoActivator that implements BundleActivator

  • public class DemoActivator implements BundleActivator{
     @Override
     public void start(BundleContext context) throws Exception {
      System.out.println("Bundle is about to start");
      }
     @Override
     public void stop(BundleContext context) throws Exception {
      System.out.println("Bundle is stopped");
      }
    }

• How to map BundleActivator in MANIFEST.MF? 
  • As I said above, BND tools will auto create MANIFEST file from bnd.bnd file. you just need to update the bnd.bnd with version and activator details
  • update version and activator details
  • You can also provide export package, import package details and all.
  • Just refresh the project and you can see the generated jar file in “generated”. you can directly deploy this jar file in OSGI container.

How to run OSGI Bundles?

OSGI Runtime creation: bnd.bnd file also has run configuration under Run tab, but  create new run.bndrun file for best practice.

1. Right click on Project and Select New Run Descriptor File
2. Select Felix4 + Run time environment
3. Create Run Configuration
4. Give file name as run under org.javasavvy.demo. it will create with extn .bndrun
5. Now Open the run.bndrun file in the project directory. It contains
   • Repositories
   • Run Requirements
   • Panel Run Blacklist – black list all bundles
   • Bundles  – This addes list of bundles at  OSGI runtime. Here you need to add “org.javasavvy.demo” bundle to run
   • Properties – you can add OSGI framework properties and launcher arguments JVM arguments
6. Click on + under Run Bundles and select “org.javasavvy.demo” from available bundles list 
7. Run the OSGI Bundle by clicking “Run OSGI” on top right corner
8. you can see in the logs ” Bundle is about to start”
9. give command “lb” to list the bundles

Click here to download the source code here

Hope this help. In next tutorial we will see the implementation of OSGI Services using declarative services