Transform Java libraries into OSGi bundles

Unfortunately there are lots of Java libraries out there that are not OSGi-ready (yet). Although there are repositories like SpringSource EBR, Apache Felix OSGi Bundle Repository and some other OSGi bundle repositories that offer OSGi-ready versions of Java libraries it is likely that you get into a situation where no OSGi bundle for a particular library (or version of a library) is available (I regularly hit this problem when I am dealing with proprietary libraries). To be able to use such libraries as bundles it is necessary to add proper manifests to them. Lately I had a discussion with some people in the Virgo IRC channel about how to make Java libraries OSGi-ready and I realized that while BND is very well known to achieve that, a lot of people do not know that Eclipse PDE does also offer such functionality via a comfortable wizard. Therefore I would like to give a short introduction about that functionality.

First of all we need a Java library that is not available as an OSGi bundle. I decided to take the Saxonica libraries for this example but you can choose whatever library you like. Now please extract the artifacts (in my case saxon9ee.jar, saxon9ee-qc.jar, saxon9-sql.jar) to your local disk. Next, go to Eclipse – File – New – Project – Plug-in development – Plug-in from Existing JAR Archives.

In the following dialog click the Add External… button and select the aforementioned three artifacts (for this tutorial I decided to create one big bundle but for production usage I would recommend to split these jars into separate bundles) and click Next >.

In the last dialog define information like project name, bundle ID (plug-in ID) and the version. Then ensure that Analyze library contents and add dependencies is checked. With this option enabled Eclipse is going to check for dependencies and will add all needed packages to the Import-Package header. The second setting to pay attention to is the target platform. Unless you want to create an Eclipse-specific bundle select an OSGi framework and select standard in the drop-down box. This will tell Eclipse to create a generic OSGi bundle that has no Eclipse-specific extensions and will work with every OSGi framework. The last thing you have to be careful about is the Unzip the JAR archives into the project setting. Usually it is not necessary to unzip the classes so I would recommend to uncheck this option unless you really need this feature. Once you are done click Finish and wait until the project has been created.

Now some minor changes have to be done to the project. First of all Eclipse PDE does not add any version information to the exported packages. Therefore open the manifest editor and add a proper version to each of the exported packages.

Also update the imported packages if you have special requirements. Eclipse PDE will add version numbers for those packages for which it has bundles in the defined target platform. Those must not necessarily be the same as the ones deployed in your OSGi framework (especially if you are using something different to Eclipse Equinox like Eclipse Virgo or Apache Felix/Karaf). Once you are done editing the bundle it is now time to export the project as an OSGi bundle. Go to File – Export… – Plug-in Development – Deployable plug-ins and fragments.

In the following dialog check the project and select a directory into which the bundle should be exported and click Finish. Now an OSGi-ready bundle has been created that can be used in any OSGi framework.