Developing OSGi Applications with Apache Aries

Yesterday I blogged on how to get the free OSGi Applications tools from IBM Rational working on Eclipse 3.6 Classic. Having got the tools created the next step is to define a target platform. A target platform is the set of bundles you want to build and run your application with. Since Eclipse is a big OSGi application it already comes with a built in target platform for developing eclipse plugins. Since we are trying to create an enterprise OSGi application this isn't any good. We need a new one, but the tools don't come with one for free. In this post I will go through the steps involved in setting up a target platform for developing OSGi applications.

Before going on you'll need maven. You may have it already, but if not you can get it from the Apache Maven download page.

1. The first step is to get a "runtime" from somewhere. The quickest way to get something quickly and easily is to build the Apache Aries Blog sample assembly. This can be downloaded from subversion here. Download it into an empty directory.
2. In the empty directory run mvn. This will download all the bundles required to run the Apache Aries Blog sample. The bundles will be in the target subdirectory.
3. In eclipse you need to open the preferences pane and navigate to Plug-in Development > Target Platform. Click the Add button.
4. This opens a wizard with 4 radio buttons. You want to start with the first option titled Nothing.
   
   
   
5. The next page is the target platform configuration panels. The first step is to choose a name. I have gone with Apache Aries.
   
   
   
6. Right now the target platform has no bundles, so we need to add the directory of bundles we got from step 2. Click the Add button. A wizard will appear with 4 options, select the Directory option and click next. Then browse to the target directory generated in step 2.
   
7. We now have bundles we can build against, but this isn't going to help run any tests. Some of the Apache Aries bundles depend on javax.transaction. The problem is javax.transaction exists in the JVM, but only contains a few exceptions from the package which causes bundles wanting to use javax.transaction problems. to fix that we need to configure the target platform. This is fixed by going to the Arguments tab and adding the following as a vm argument:
   
   -Dorg.osgi.framework.system.packages.extra= javax.transaction;version=1.1.0,  javax.transaction.xa;version=1.1.0  -Xbootclasspath/p: ${target_home}/geronimo-jta_1.1_spec-1.1.1.jar

   This does two things. The first is it tells the OSGi framework to export the JTA packages at version 1.1, which is the version expected by Apache Aries, and the second thing it does is add the extra classes onto the JVM boot classpath.
   Note: I added some spaces into the example to ensure it wraps on the blog. The only space that should exist when copied into the dialog is the one before -Xbootclasspath.
   
   
   
8. Now you are done and can click the Finish button. The last thing to do is to make the new Target Platform the active platform. You can do this by checking the checkbox next to the platform you just created.
   
   
   
   Note: If you add or remove a bundle from the platform directory you will want to come back and hit the reload button to get Eclipse to notice.

Now you are ready to start developing your bundles, and when you want to test your application you can use the OSGi Framework Run configuration in eclipse. If you want to add more bundles to the runtime just drop them into the directory from step 2 and then reload the platform.

I'll blog another time about using the tooling to create a simple application.
Alasdair