Developing OSGi Applications

Reactive Blocks has a feature that supports development of OSGi bundles. This article describes this feature from installation step to bundle creation and deployment.

There are a number of OSGi frameworks, for instance:

Bundles created by the Reactive Blocks SDK should run on all of these. In the following, we just pick Equinox to explain how to run an OSGi bundle.

Updates

If you have used Reactive Blocks for OSGi feature before, you simply need to update. Do the following steps: (Error markings during the update prosess are OK)

  • Choose Help → Check for Updates from the Eclipse menu.
  • Continue with the update as shown in Eclipse.
  • Delete the target-definition project in your workspace
  • Redo the development environment setup step.

If you have developed OSGi applications with Reactive Blocks before, you may need to rebuild them.

Install Reactive Blocks for OSGi

To install the Reactive Blocks for OSGi feature, do the following steps:

  • Choose Help → Eclipse Marketplace from the Eclipse menu.
  • Search for reactive blocks.
  • Choose button Install.
  • Select Reactive Blocks for OSGi feature and follow further instruction.

Development Environment Setup

We define a set of plug-ins that can be used to build and run OSGi bundles. It contains

  • minimal set of bundles to run the Equinox OSGi framework from Eclipse
  • bundles related to logging
  • Reactive Blocks runtime bundle
  • Reactive Blocks library bundles
  • Additional bundles that the libraries require

Since this definition changes the target platform in your Eclipse workspace, it is advisable to switch to a new workspace.

  • Download the zip file containg project target-definition.
  • Import the project into your Eclipse workspace (make sure you choose Existing Projects into Workspace in the Import Wizard).
  • In the project, open the file equinox-3.10.1.target.
  • Select the link Set as Target Platform on the top right.

Create an Application Block

Before making an OSGi bundle, we first create a Reactive Blocks plug-in project and an application block.

Developing an OSGi application means creating an application block. Invoke the new building block wizard and select Application Block as the block type.

Specify your application as usual, by connecting blocks and activity nodes. Import building blocks that you need from our collection. Verify your specification with the analysis and animation tools.

Note that a Plug-in project must contain maximal one application block.

Depending on your application, you might need to import packages from other bundles, like paho for MQTT. Read section About Dependency below to see how to add a bundle as project dependency.

Build an OSGi Application

  • Right click on the application block and select Build → Select Build Target Platform…

  • In the platform selection dialog, choose Java OSGi Bundle (Into Source Project)

  • Bundle version and name can be change in the Parameters dialog
  • A deployment package definition (.dpp file) can also be generated. This definition is used to generate a deployment package with the mToolkit plug-in.

When the build process is completed, you should see a new source folder gen containing generated code from your application.

Depending on your application, the generated code may also need dependency to other packages or bundles. Read section About Dependency below to see how to add a bundle as project dependency.

Run an OSGi Application

We provide a launch configuration to run OSGi bundles from within Eclipse.

  • In the target-definition project, find the launch configuration OSGi.launch inside the launch folder.
  • Right-click and select Run As → 1 OSGi.

You should see that the Equinox OSGi framework is running from the Console view.

To stop the OSGi framework, just use the red stop button on the Console view.

About Dependency

You may need to import other packages from external bundles, like paho for MQTT, in your application. Moreover, the generated code may require such dependency.

First, make sure the external bundles are available in your target platform.

  • Open the Eclipse Preferences
  • Find Target Platform preference
  • Select the active target platform and choose button Edit…

Thereafter, you can modify the manifest of the project that contains your application manually.

  • Open MANIFEST.MF in the META-INF folder of the project
  • Select the Dependencies page
  • Choose button Add… to specify a package you need for your project

Missing Dependency at Runtime

There are some indications that one or more bundles need to be installed in the OSGi framework:

  • When launching your OSGi framework, you see similar error message to the following:

    org.osgi.framework.BundleException: Could not resolve module: br.mqtt.sender [64]

  • The bundle containing your application is not in state active. For the Equinox OSGi framework, you can use commands ss and diag <bundle-id> as shown in the following figure.

The figure above shows that bundle br.mqtt.sender (bundle id 64) has an unresolved requirement. It needs to import package com.bitreactive.library.mqtt. This package is provided by bundle com.bitreactive.library.mqtt (bundle id 10). However, the provider bundle itself has an unresolved requirement. There is no bundle that can provide package org.eclipse.paho.client.mqttv3.

To solve this problem, you need to find a bundle that exports package org.eclipse.paho.client.mqttv3 and basically install the bundle in the OSGi framework.

If you are using an Eclipse launch configuration (see Run an OSGi Application section), do the following:

  • Ensure that the bundle is availabe in your target platform (see About Dependency section)
  • Do a right-click on the launch configuration (e.g., OSGi.launch) and select Run As → Run Configurations…
  • Tick the bundle and choose button Apply (or Run if you want to start the OSGi framework immediately)