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):

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).

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.

12 thoughts on “The simplest OSGi / Karaf hello, world demo I could come up with”

  1. Thanks for this posting. The initial paragraph reflects my experience perfectly. I was beginning to despair of ever picking up what seemed to be a straight-forward technology. You have restored my faith in OSGI – well, for the time being anyway 🙂

    Steve

    1. Thanks so much for the nice comment Steve!

      I should probably write an update to this post sometime. The guy who wrote the BND tool gave me a hard time on Twitter about this post explaining that the manifest really can’t be managed without some kind of tooling.

      That said, I took some Red Hat training a few weeks back with Scott England-Sullivan, one of the Karaf committers, and he completely sold me on declarative services as a much, much easier way to do this.

      If you can, search for his talk from Devnation 2014. If I had the link handy, I’d send it over.

  2. thank you! you have removed to a great deal, the cloud that surrounded osgi. I was so apprehensive about writing a simple project.

  3. HI michael,
    Thank you for the Great Article , I want do same thing using blueprint.xml can you please Guide me how to achieve?

    Regards,
    Santhosh

    1. Hi Santosh! Thanks for the comment. Unfortunately, it’s been a while since I did this so I’d have a hard time guiding you now. Good luck though

    1. Thanks for the vote of confidence, Michael! Not sure it’s fair to call the tooling “shaving the yak,” but I do like my beginning examples to be as clean cut as possible.

    1. Hey Tehmina,

      Sorry I’m just now replying. I think there are lots of great tutorials out there. My only goal was to do a really simple, stripped down example. It’s obviously not what you’d want to do in a production — but I hope it helps you learn!

  4. Sorry, but the post is awful.
    1. You should use correct artifact of osgi: org.osgi:org.osgi.framework
    2. You should never edit manifest.mf manually, the plugin org.apache.felix:maven-bundle-plugin is created specially for that.
    3. Using “karaf install” you are installing the bundle from local maven repository, but what if I do not put my jar in repository?
    You should notice that user must install artifact in the local maven repository (and karaf must reference to that repository), or user must install artifact to karaf system repository (mvn … -Durl=/system), or user should use hot deploy (via putting artifact in deploy directory).

    1. Hey Vasya,

      First of all, thanks for taking the time to post some good ideas. I hope future readers will benefit from them. I’m far removed from the platform these days, so I can’t engage you at a technical level.

      However, I do want to engage you on your unhelpful opinion that “the post is awful.” I don’t care what you say to me — I’ve been around a long time and, frankly, your comment reflects a lot more on you than it does me. What I don’t like is that you’re contributing to a toxic culture that does nothing but hold people back with comments like yours.

      Aside from people who’ve developed thick skin, like me, who would want to put their opinions out there with your immature reaction?

      What junior programmer with some awesome, but half-baked, idea will post it when they risk having to deal immature comments like yours?

      You do nothing but damage the industry in the process. I wrote a whole blog post on Tech Lead Daily about it. (So thank you for the material, I guess.)

      When you’re ready for it, I’m happy to offer you some free tech lead coaching. You’ve got good ideas, so let’s just work on that first sentence 😉

Leave a Reply

Your email address will not be published. Required fields are marked *