There seems to be a significant amount of mysticism surrounding OSGi. Recent it showed up in the, what is analogous to “use at own risk”, column of a the ThoughtWorks emerging technology radar. However, its been a mature technology for quite some time. It possible this is due to the lack of understanding and tutorials on the subject, or the fact that dependency injection fundamentals are needed as base knowledge to understand how OSGi improves application construction.
So whats Apache Felix then? Apache Felix is a mature product that implements the OSGi framework, however its not the only implementation of OSGi. It is, however, relatively easy to get started with as shown in this tutorial.
What To Know Before Starting
It’s important to understand modular programming before diving to deep. Not to be a resident expert by any means, but understand it generally. By modular, think plugin or applications that can have parts removed or added while it is running.
It’s also helpful, though not entirely accurate, to think of Apache Felix as a running server or container that you deploy things too. It won’t stop running once its started and you install and uninstall parts of an application with it running. You may have heard that OSGi is another injection framework, but this is where the “just another dependency injection framework” argument dies. The application or applications (plural) never stop running, instead you add and remove modules dynamically.
Installing Apache Felix
Apache Felix is pretty easy to get started with regardless of discipline of development. The first step is to get the binary, which at time of writing is found at the following URL:
http://felix.apache.org/downloads.cgi
For these examples use the zip version since it will translate regardless of what operating system that’s being used.
These labs were designed to mimic the framework seen most often in applications like Adobe CQ and Apache Sling, which is why Apache Felix is so prevalent. There are, however, a plethora of OSGi frameworks available for downloading. Keep in mind, while some of the other frameworks will make things considerably easier, they may in fact, deviate from the OSGi Alliance’s original specifications and have subtle differences.
Installation
Make a directory where work can be done as a scratchpad. I typically move my files from the Download directory so they don’t get lost in the mass of downloads that end up in there. I usually do something like:
$HOME/projects/apache-felix
Once that structure is set up, mv the file (or copy) from the Downloads directory to your new location and unzip it. Mileage may vary on Windows devices, but on MacOS set up can be accomplished by issuing the following commands:
cd $HOME/projects mkdir apache-felix cd apache-felix/ cp /Users/<<me>>/Downloads/org.apache.felix.main.distribution-4.2.1.zip . unzip org.apache.felix.main.distribution-4.2.1.zip
Start It Up
After its unzipped there will be a felix-framework-x-x-x folder (depending on the distribution), go ahead and cd into that directory and start up Felix with:
java -jar bin/felix.jar
If everything is ok, a friendly welcome message will greet us with:
____________________________ Welcome to Apache Felix Gogo g!
By default all that comes with Felix, as far as administration is concerned, is a console. Don’t get the wrong impression, this is one powerful console, it just doesn’t seem like it right now (especially since the prompt indicates its some sort of strange dance style).
The Gogo shell (the dance style in question), is a standard Apache shell seen in both Apache Felix and Apache Karaf. Karaf doe have a ANSI color one which makes it a little more exciting (and by exciting I mean 1990’s IRC exciting).
The g! prompt is the surefire mechanism to recognize this shell over the others.
Send Some Commands To Gogo
We came all this way, we might as well issue some commands. Type in the following to the shell:
felix:lb
The command felix:lb is a command for listing all of the bundles installed in the framework. The “felix” prefix to the command is basically a namespace qualifier (called a scope). It exists in case two different command bundles use the same command name (eg: felix:lb and other:lb), which is highly possible. The felix scoped commands are special in that they can be used without the scope at all. So typing just lb will work on the console as well.
As far as instructions go, let’s always prefix the command with felix.
The output of our felix:lb command should have resembled the following:
g! felix:lb
START LEVEL 1
ID|State |Level|Name
0|Active | 0|System Bundle (4.2.1)
1|Active | 1|Apache Felix Bundle Repository (1.6.6)
2|Active | 1|Apache Felix Gogo Command (0.12.0)
3|Active | 1|Apache Felix Gogo Runtime (0.10.0)
4|Active | 1|Apache Felix Gogo Shell (0.10.0)
g!
Note: For those of you that have browsed another Felix installation, possibly Sling or Adobe CQ, you probably are saying “Yeah right, where are the other 200+ bundles?”. Well this is it for the default Felix framework. It manages to operate on these 5 bundles and doesn’t need much else when starting out. You can start developing right now on just these bundles.
Getting Help
So, what else can you do on the console? Well type help in the console and you should get back a list of all of the available commands out of the box. The console should happily respond:
... some stuff ... felix:install felix:lb felix:log felix:ls felix:refresh felix:resolve felix:start felix:stop ... more stuff ...
Before you try these out, it’s important to note that the help system can also give you some pretty detailed information on each command. For instance type help felix:ls and look at the output:
g! help felix:ls
ls - get current directory contents
scope: felix
parameters:
CommandSession automatically supplied shell session
ls - get specified path contents
scope: felix
parameters:
CommandSession automatically supplied shell session
String path with optionally wildcarded file name
g!
Then give it a try:
g! felix:ls /Users/Me/ExternalLibraries/apache-felix-bare/felix-framework-4.2.1/bin /Users/Me/ExternalLibraries/apache-felix-bare/felix-framework-4.2.1/bundle /Users/Me/ExternalLibraries/apache-felix-bare/felix-framework-4.2.1/conf /Users/Me/ExternalLibraries/apache-felix-bare/felix-framework-4.2.1/DEPENDENCIES /Users/Me/ExternalLibraries/apache-felix-bare/felix-framework-4.2.1/doc /Users/Me/ExternalLibraries/apache-felix-bare/felix-framework-4.2.1/felix-cache /Users/Me/ExternalLibraries/apache-felix-bare/felix-framework-4.2.1/LICENSE /Users/Me/ExternalLibraries/apache-felix-bare/felix-framework-4.2.1/LICENSE.kxml2 /Users/Me/ExternalLibraries/apache-felix-bare/felix-framework-4.2.1/NOTICE g!
That is the brief overview of the Gogo shell. There is a web based console (strategically named WebConsole) that we can employ to make working with Felix a little easier.
To do that we first need to learn to install things into Felix. Let’s take a look at the help documentation on the felix:install command.
Install A Web Console
After executing a help felix:install, notice that the command takes a multiple arguments. This means if we really wanted to, we could install multiple things at once.
Secondly, note it takes a URL to a file and not just a file path. This means it’s capable of installing over the internet. Let’s take advantage of the that to install the web console and a http server toi display it into the framework. In the console issue the command:
felix:install http://mirror.cc.columbia.edu/pub/software/apache//felix/org.apache.felix.webconsole-4.2.2.jar
the web console requires a web server so lets install jetty
felix:install http://mirror.cc.columbia.edu/pub/software/apache/felix/org.apache.felix.http.jetty-2.3.0.jar
Once the download and install is completed, the console should return back a Bundle ID: X response (where X is a number). This represents the bundle id that you just installed. We use this in other commands to tell the bundle to do stuff. Now do an felix:lb and look at your list. You should have two new bundles in the installed state.
In order to start up our console we will first need to start the Jetty bundle then our Web Management Console bundle. To do that type the command felix:start x (where x is the number of the Jetty bundle).
g! lb
START LEVEL 1
ID|State |Level|Name
0|Active | 0|System Bundle (4.2.1)
1|Active | 1|Apache Felix Bundle Repository (1.6.6)
2|Active | 1|Apache Felix Gogo Command (0.12.0)
3|Active | 1|Apache Felix Gogo Runtime (0.10.0)
4|Active | 1|Apache Felix Gogo Shell (0.10.0)
6|Installed | 1|Apache Felix Web Management Console (All In One) (4.2.0.all)
7|Installed | 1|Apache Felix Http Jetty (2.2.0)
g! felix:start 7
g! [INFO] Started jetty 6.1.x at port(s) HTTP:8080
g! felix:start 6
g!
Do the same for the Web Management Console.
Testing The Web Console
Go to http://localhost:8080 and look for a standard Jetty 404 ERROR. Believe it or not, this 404 is actually a good sign. It tells us Jetty is running and we have no pages on the root. We do, however, have servlets in the path /system/console now. So try going to this URL using a username of admin and a password of admin:
http://localhost:8080/system/console/bundles
After logging in, you should land on the bundles page. This page is probably the most important of the pages on the web console and you will use it more than the others in you quest to become a master bundle developer. The reasoning is simple, this is where you go to upload, start, stop and examine bundles.
Practice Adding More Bundles
There are other bundles that can be used to enhance Apache Felix. You can find them at:
http://felix.apache.org/downloads.cgi towards the bottom.
Spend some more time installing and see if you can install the following bundles:
- configadmin
- log
- metatype
- dependencymanager
- eventadmin
- deploymentadmin
- webconsole.plugins.event
- webconsole.plugins.packageadmin
- scr
- webconsole.plugins.ds
These should give you a solid development environment to build applications upon.
Summary
Congratulations, you have built an Apache Felix environment and ran it. Now we can learn how to make bundles, like the ones you’ve been installing, and run them in the environment.
Code Affectionado 
sometimes “lb” is not displaying result then when I type felix:lb then it started working for both now !! Why ?