How do I convert an existing jar file into an OSGi bundle?

Lucee 5 is completely OSGi based, OSGi is the defacto standard in most Java enterprise environments, to manage bundles (jar libraries) used by the environment.

This means all libraries used are managed by Lucee itself as OSGi bundles, but this does not end with 3rd party libraries. Lucee handles it’s own core as an OSGi bundle, Lucee archives (.lar files) and even our Java based extensions are all OSGi based.

From Lucee Docs

If you have a JAR you can no longer drop it into the server install and have it picked up – it needs to be converted to an OSGI bundle and placed in the ./bundles directory. While this is not a particularly difficult task it is nevertheless and extra step that poorly understood.

Before it gets lost I thought I’d quickly copy the Adobe CQ docs snippet that people have been referred to for converting JARs to OSGi bundles. Hopefully someone can expand to a more useful tutorial in time.

How do I convert an existing jar file into an OSGi bundle?


Here’s a very simple way of turning an existing jar file in an OSGi bundle, while keeping control on exported packages. The example creates an OSGi bundle from junit-4.4.jar.

Note: The method below only works in a scenario where the jar file has no dependencies on other external jar files.

Start by creating a the jar’s manifest file:

Manifest-Version: 1.0
Created-By: myself
Bundle-ManifestVersion: 2
Bundle-Name: JUnit 4.4 bundle
Bundle-Description: Package junit 4.4 in an OSGi bundle
Bundle-Version: 4.4.0
Bundle-ClassPath: .,junit-4.4.jar
Bundle-SymbolicName: org.junit.framework
Export-Package: junit.framework,junit.extensions,org.junit.runner,org.junit,junit.textui
  • Bundle-ClassPath header is set to allow embedding the original jar as is. Make sure its value matches the filename of the jar that you are going to embed in the bundle
  • Export-Package is a list of packages contained in the jar that you would like to make available to other bundles running in the OSGi Container

Jar file
Get the jar file, in our case from

Create the bundle jar file by running the following command:

jar cvfm junit-4.4-bundle.jar manifest.txt junit-4.4.jar 

Where manifest.txt is the name of the manifest file created above.

That’s it - the resulting jar file is an OSGi bundle the exports the packages listed in Export-Package above, using the classes of the embedded junit-4.4.jar.

Other links

@modius : @micstriit has a couple of scripts that can convert jars to bundles automatically in most cases. We discussed that he will put them up somewhere on Github.

here the script that converts jars to OSGi bundle. Please see the readme of the project for details.

This should be in the docs, and an extension created to do this… would also be great to have this added to commandbox, but if it’s in lucee admin then it will auto-magically make it to commandbox :wink: