OSGi Bundles, Apache Felix and Versioning

I recently had an experience while working with a customer that has prompted me once again to post about what it taught me. The requirement that drove this experience was the necessity for a Maven/AntHill build and deploy automation for CQ package and OSGi bundle deployments. In order to make sure that all our code (bundles, jsp and design) was deployed simultaneously, we decided to take advantage of the “install” directory that can be located as a child of an “/apps/myApp” directory in CQ. This “install” directory is treated as a watched directory by the OSGi installer, and so any jars in that directory will be auto-installed upon installation of the package…or so we thought…

It turns out that Felix has an interesting logic behind the install directory, definitely logic with a purpose, but nevertheless something to be mindful of. The logic is this: if the bundle version is less than or equal to the version that has already been installed, Felix ignores the new bundle and does not install it. Makes perfect sense actually: why install a bundle that A) you already installed, or B) is older than the installed version. Easy enough to fix right? Our version numbers are a part of the final file-name of the jar, so we simply increment those in the file name and…voila…problem solved…except that didn’t really work so well either…in fact we had the same issue as before.

So I dug in a bit and decided to explore the “META-INF” directory of an exploded OSGi bundle. I soon noticed that within this directory is a file called “MANIFEST.MF” that contains all the pertinent bundle meta-data that Felix pays attention to. I also noticed a property in this file called “Bundle-Version” that was not getting updated when our bundle was built. To resolve this, we added the following to our “pom.xml” within the <plugin></plugin> block used to build our jar:

<configuration>
  <archive>
    <manifestEntries>
      <Implementation-Version>{version}</Implementation-Version>
      <Manifest-Version>{version}</Manifest-Version>
      <Bundle-Version>{version}</Bundle-Version>
    </manifestEntries>
  </archive>
</configuration>

This did the trick…as long as we incremented our version, our bundle would be picked up and installed properly, overriding any previous versions of the bundle. Since OSGi versions follow the same formats as Maven versions (X.X.X), we were able to achieve this behavior simply by incrementing the last number in the version. This gave us the flexibility we needed in order to avoid incrementing our major version number until we really wanted to, thus closing the book on this particular issue.

Since dealing with this issue, I’ve noticed several vendors that we are pursuing implementation with (and I’ll not mention names) who are getting the same behavior…although it seems they may be unaware of it. Thus I decided to post this here in the hopes that it becomes helpful to people who might be struggling with the same issue.

The moral of the story: don’t worry about the version being reflected in your file-name (although this is best practice), more importantly, make sure your full version is reflected in the “Bundle-Version” notation within your “MANIFEST.MF” file.

Leave a Reply

You must be logged in to post a comment.