Get OSGi samples running on your machine in 10 minutes

I've seen a few blogs that show how to get Apache Geronimo up and running, followed by how to install the Apache Aries Blog sample to use the neat OSGi functionality. However, that's typically where it stops!  So this post will hopefully be the end to end tutorial for a developer wanting to play with OSGi from scratch in about 10 minutes.

Let's start from scratch... We're going to Install the Apache Aries Blog sample on Apache Geronimo.  Not sure how many people already want to google 'Apache Aries' or 'Apache Geronimo', so I'll explain...

Apache Aries

Apache Aries is a set of Java components that can be added to an existing OSGi framework, such as equinox or felix, to provide an OSGi developer with Enterprise functionality, which a typical EE developer would be used to, such as JNDI, JPA, Transactions etc. To read more on Apache Aries, visit http://aries.apache.org

Apache Geronimo

The Apache Geronimo project produces an application server runtime that uses other open source components to create a rich application environment.  It provides application containers for Java EE applications and OSGi applications (via Apache Felix). One of the open source components it contains is Apache Aries. For more information about Geronimo, check out the project website http://geronimo.apache.org.

So our picture of Geronimo so far is as follows:

 

Our OSGi bundles essentially run in the Apache Felix framework.  However with the Apache Aries functionality that sits alongside the Felix framework, they are able to connect with some of the typical JEE functionality as well as use other OSGi application features.

You'll need a Java runtime installed on your machine (Make sure the JAVA_HOME and JRE_HOME system variables are set), but I assume you all mostly have this already.  So start your stopwatches... Download Geronimo v3.0 M1, as this has the Apache Aries functionality, from http://geronimo.apache.org/apache-geronimo-v30-m1-release.html you'll want one of the drivers from the "Non-Certified Web Container Releases" section.  You can choose which web container you wish to use, I chose Tomcat. 

Once your download (65MB ish) is complete, gunzip and extract your tar to an appropriate location on linux or just unzip somewhere in windows.  Your Geronimo server is ready to go! Simple as that (hopefully).  To start your server, go to the "geronimo-tomcat7-javaee6-3.0-M1/bin" directory or equivalent and type "./geronimo run". (Ensure you have root privileges)

You should see this screen:

Don't get too excited yet though, as it processes a little more before you should start playing. Wait till you get to this screen:

Right, at this stage our Geronimo Application server is up and running as you can see from the last line of output. Hit enter to get a prompt back.  We can see from this output that we have a few app modules installed including an EAR, a couple of RARs and some WAR files.  Let's now install our own OSGi application.

We need to install a datasource for the application, so firstly, download a rar file that is used to install the datasource here. This will be included in Geronimo in future versions.  Next download the actual data source descriptor here. Once those files have been downloaded, put them in the root directory of your extracted Geronimo server.  From a new command prompt, navigate to the geronimo rooot directory and run the following command, with the server running, to install the datasource:

./bin/deploy -u system -p manager deploy tranql-connector-derby-embed-xa-1.6.rar aries-datasource.xml

We're now ready to install the application.  Download the Apache Aries application binary from https://cwiki.apache.org/ARIES/downloads.html.  I downloaded the Blog JPA app. Click the 'eba' link to download.  With the .eba file in the root Geronimo directory, run the following command, again whilst the server is running:

./bin/deploy -u system -p manager deploy org.apache.aries.samples.blog.jpa.eba-0.2-incubating.eba

To view the blog sample, point your browser to http://localhost:8080/blog.  You should see the following:

Well, you've now got a running Geronimo server and Apache Aries Blog Sample running on your machine in (hopefully) about 10 minutes.  Feel free to have a play around with this sample - It's not massively interesting but is fit for purpose :o)  

Lets now look under the hood in the runtime :o)  From the Geronimo console, type 'list'.  This returns the full list of bundles in the Geronimo framework, including system bundles.  Quite a few, aren't there!  At the end you'll see the blog bundles we just installed:

What we see above is a quite a bit of info on each bundle we have in the environment.  Lets take the first bundle in the highlighted list and look at it in more detail. Important columns to mention are id, state and description columns. The first element is the bundle id.  This is a unique number given to every bundle in the framework so that we can use the number in commands, like stopping and starting a bundle.  The next element is the state of the bundle.  'Active' means the bundle has been started and can fully interact with other bundles.  The description column at the end is how to visually see which bundle is which.

So, now you can play :o)  hitting <tab> gets you a list of commands you can call from a geronimo prompt.  Commands of interest from an OSGi perspective include headers, list, refresh, restart, start, stop, update, exports and imports.  You can get more info about these commands by typing '--help' after the command, although they're all pretty straight forward.

Given this is quite a long post already, I'm going to leave it there :o) Well done for those that got this far!! I'll follow up very soon with a blog post which really plays around with the bundles and pulls apart the blog sample.


Please let me know how you got on (comment or tweet @sjmaple)