Setting up Spring Dynamic Modules (OSGi) with Eclipse – A step-by-step tutorial

I spend some time playing with Spring Dynamic Modules (Spring-DM) and Eclipse (resp. its underlying OSGi platform Equinox) the other day. I had some minor annoyances in the beginning concerning the initial setup, since i didn’t found any comprehensible source on the web on what bundles are needed at least and what else is necessary in order to run your own Spring-DM-ified bundles.

The following instructions will show you all the steps you have to accomplish in order to set up a minimalistic workspace in eclipse for creating or droping in and executig arbitrary Spring-DM bundles.
Note, that this post will only show you the necessary steps for a setup – it’s by way no tutorial about how to build bundles with Spring-DM (maybe in a future post) or about OSGi at all.

0 – Prerequisites

First you need a copy of Eclipse (i refer to version 3.3 in this tutorial, which you can download here) and Spring Dynamic Modules (i refer to the version 1.0.1 in this tutorial, which you can download here). That’s all you’ll need for the setup, since we will use only those artifacts that are shipped within that archives (no maven and additional builds or downloads to your local repository are needed)

Unpack both archives on an arbitrary place respectively.
In subsequent sections, i’ll use <Spring-DM-Root> in order to refer to the folder where you’ve unpacked Spring-DM.

1 – Start Eclipse

Start Eclipse with a new workspace. The workspace will carry all the bundles that are necessary for running your own Spring-DM based bundles (since those Spring-DM based bundles rely on some other bundles, provided by Spring-DM that we now have to import into our workspace).

2 – Import all necessary bundles

Those bundles that are offered by Spring-DM build the foundation for running our Spring-DM based bundles. Most important, Spring-DM provides the Extender bundle, which is responsible for detecting and managing the whole lifecycle of all Spring-DM based bundles (e.g. instantiating the Spring application contexts for those bundles).

In order to import the bundles, open the Import-Dialog (e.g. ‘File‘ -> ‘Import…‘)
Since we’ll import bundles, we have to choose ‘Plug-ins and Fragments‘ from category ‘Plug-in Development‘ (see image below)

Now we have to choose the location of the bundles to import. Since they come from an external source and to that effect not coming from the target platform (bundles provided by eclipse itself), we have to deselect the checkbox ‘The target platform (…)‘ and choose another ‘Plug-in location‘. In our case, we now have to ‘browse‘ and select the folder, where Spring-DM have stored its bundles, that is <Spring-DM-Root>/dist (see image below).

Next, we have to adopt all the bundles, that are (at least) necessary for detecting and running Spring-DM based bundles:

• org.springframework.bundle.osgi.core
• org.springframework.bundle.osgi.extender
• org.springframework.bundle.osgi.io

Select those bundles and add them to the ‘Plug-ins and Fragments to import‘ (see image below)

Since the imported Spring-DM bundles rely on some Spring bundles itself for proper functioning (the Spring framework itself is divided in a number of OSGi modules), we also have to import those bundles the same way like we did with the Spring-DM bundles. You will find them under <Spring-DM-Root>/lib.

Again, we want to keep the bundles to a minimum and therefore adopt only the at least needed core bundles:

• org.springframework.bundle.spring.core
• org.springframework.bundle.spring.context
• org.springframework.bundle.spring.beans
• org.springframework.bundle.spring.aop
• org.springframework.osgi.aopalliance.osgi

As before, choose the mentioned location, select those bundles and add them to the ‘Plug-ins and Fragments to import‘ (see images below)

3 – Ready for your Spring-DM bundles

We now have imported all necessary bundles, ready to run your own Spring-DM based bundles. You should come up with a workspace that’s filled with all the imported bundles, as seen in the image below.

You now could import your own bundles like we did with all those Spring-DM and Spring bundles or directly create a new bundle within Eclipse (‘File‘ -> ‘New‘ -> ‘Project…‘ -> ‘Plug-in Project‘).
As mentioned before, this tutorial is not about Spring DM and how to build a Spring-DM based bundle, so i’m not going to show how to build such a bundle in this post (this would fill a tutorial on its own that may be posted in the future, should there be some interests on that topic)

4 – Get up and running with Equinox

You now could run your bundles by starting Equinox, the underlying OSGi container. It’s best done by creating a new Start configuration for the ‘OSGi framework‘ and selecting all bundles that should be started when running the OSGi container.

Open the Run Dialog (‘Run‘ -> ‘Open Run Dialog…‘ ) and create a new ‘OSGi framework‘ configuration (on the left hand via context menu).

Select your own ‘application’ bundle and at least ‘org.springframework.bundle.osgi.extender‘ – the Spring-DM Extender bundle (as the case may be, all bundles are selected initially – first deselect all bundles, since we don’t want to run all bundles). Now if you click on ‘Add Required Bundles‘, all bundles that your application bundle and the Extender bundle rely on will also be selected automatically (you can check that all inter-bundle dependencies are resolved by clicking ‘Validate Bundles‘).

Side note: i deselected the ‘Target Platfrom‘ bundle ‘or.apache.log4j‘ since there are some class loader issues with that bundle. If you’re interested, you may take a deeper look about logging under OSGi here.

With all the selected and necessary bundles, you now could start Equinox and see your bundle in Action (via Button ‘Run‘).
As long as you’ve started Equinox with argument ‘-console‘ (see tab ‘Arguments‘ in your Start configuration), you can enter some commands via console e.g. in order to monitor the running OSGi container resp. the started bundles (see image below).

That’s it – have fun building your own Spring-DM based bundles within Eclipse … !