The simplest OSGi / Karaf hello, world demo I could come up with

I don’t know about you, but I almost gave up looking for quick and lightweight examples on how to get started creating and deploying an OSGi bundle. Everything I found used out of date or opaque Maven plugins, proprietary techniques specific to a platform, magic tooling called “bnd,” and all kinds of other chaos. I repeatedly hear that precisely this chaos slows down OSGi adoption and related technologies like Camel. I hope this post speeds you up a little.

First, let’s write some Hello, World code

This is the easiest part. I just wanted a simple example that prints hello, world to the console when the bundle starts. Here’s the code I came up with:

You probably noticed you’re going to need the OSGi framework on your classpath. Here are the dependencies I used (but I haven’t researched whether both are strictly necessary or not):

UPDATE (August 2019): Please see Paul’s comment below noting that the the artifacts I listed below are pretty old. He reported that he fixed the issue by adding a line to the manifest file: “fix[ed] this by adding ‘Bundle-ManifestVersion: 2’ to the MANIFEST.MF file.”

Hand craft a MANIFEST.mf file – You. Can. Do. It.

This was the big hurdle for me. It seems that most of the authors of the examples I found had some kind of allergy to hand writing the file, so they rely on various tooling to write it and bundle it. I suppose in real life I might get used to the tooling, but it just gets in the way of me learning. So here’s my hand crafted file:

Bundle-SymbolicName and Bundle-Version lets you describe what the bundle will look like to a user in Karaf (or whatever OSGi container, I suppose). For example:

simple-osgi-example-1

Import-Package is critical. In fact, it’s a core part of the OSGi concept that you must explicitly declare the services you’re depending on. Remember how we imported the OSGi dependencies in the hello, world Java code? You might have thought that installing a bundle would implicitly include the framework, but you’d be wrong. You have to explicitly declare it.

Export-Package is a similar concept. You need to expose your services to other bundles. Finally, Bundle-Activator is the class you want to fire up on start (the hello, world code above).

Also (Aug 2019 update): see note from above that now that those artifacts are getting a little old you may need to add a Bundle-ManifestVersion: 2 line as well, but I haven’t tried this for myself.

Structuring your project

I put my manifest file under src/main/resources/META-INF:

osgi-example-2

The wrinkle here is that Maven will overwrite your META-INF file unless you override the default behavior with this:

Finally. Now let’s install and start the bundle

I ran this in Karaf, so here’s what I did. First, run mvn install to get the artifact into your local repository. Next, start up Karaf and run this command:

osgi-example-3

Take note of the bundle ID. Mine was 95 in this example, but it varies each time. Now let’s start it with this command:

And you should see something like this:

osgi-example-4

The full example is here: https://github.com/mrice/osgi-demo Good luck out there.

Forgot that obscure command you issued in Karaf/ServiceMix/Fuse a few months ago? Try this

So here’s a handy feature in Apache Karaf. Very similar to your bash console, Karaf remembers your command history, which is critical when you’ve completely forgotten that obscure command with the fourteen parameters you issued last time you were prepping for a sprint demo.

Here’s how to get it: From your Karaf command line, type: history. Think you can remember that much?

karaf-history

Great. But do you have way too much history to even begin to consider scrolling through your history? Try typing CTRL-R so you can quickly search your history:

karaf-ctrl-r-history

Pro tip: So I wanted to search for my most recent “mvn” command to see the command I issued for my last Apache Karaf post. I had to hit CTRL-R a few times, which is important to know. Using the CTRL-R search just retrieves the first search result, so keep hitting CTRL-R to get the command you’re looking for.