Manage your OSGi application with Apache Felix File Install
Check also the second article on File Install: Dynamic Configurations
A while ago we introduced in this blog a little interesting bundle called Apache Felix File Install. This bundle has actually gone a long way since then, and now it’s even part of Sun Microsystem open source application server Glassfish.
The reason this simple bundle is quite interesting to OSGi developers is that it provides a simple mechanism to give your application an extensible and updatable structure. In fact, once installed, this bundle starts watching a specified folder; every time it detects new bundles there, it installs them. Likewise, when a bundle file is updated in the watched folder, the correspondent bundle in the OSGi container is updated.
Let’s see now how we can structure an OSGi application using the Apache Felix File Install.
What we want to achieve is an application with the following structure:
The main difference between the bundles and the dropins folder is that the first contains the fundamentals OSGi bundles of the application, the ones that defines the “platform” and that are only exceptionally updated; on the other side the dropins folder contains additional elements, like user-created plugins or application customizations. The application owner can deploy, undeploy and modify bundles in such folder at any time, and the modifications are installed at runtime without the need to restart the OSGi container.
Let’s create now this project structure with Apache Felix. First of all we need the main Felix distribution: we can download it, for example, following this link (check the download page if it doesn’t work). Once we have the distribution, simply unzip it and check its folder structure:
$ ls -la -rw-r--r-- 11358 26 Apr 23:20 LICENSE -rw-r--r-- 1095 26 Apr 23:20 LICENSE.kxml2 -rw-r--r-- 932 11 Mag 01:08 NOTICE drwxr-xr-x 102 26 Apr 23:20 bin drwxr-xr-x 170 26 Apr 23:20 bundle drwxr-xr-x 102 26 Apr 23:20 conf drwxr-xr-x 578 26 Apr 23:20 doc
As you can see, it is very close to what we want to achieve. Let’s now create the dropins folder.
$ mkdir dropins
Now that all the folders are in place, let’s see the contents of the bundle folder.
$ cd bundle/ $ ls -al -rw-r--r-- 146568 26 Apr 23:20 org.apache.felix.bundlerepository-1.4.0.jar -rw-r--r-- 59114 26 Apr 23:20 org.apache.felix.shell-1.2.0.jar -rw-r--r-- 12455 26 Apr 23:20 org.apache.felix.shell.tui-1.2.0.jar
This folder already contains the basic bundles distributed with Felix; let’s donwload the Apache File Install Bundle here.
$ wget http://www.mirrorservice.org/sites/ftp.apache.org/felix/org.apache.felix.fileinstall-1.2.0.jar $ ls -al -rw-r--r-- 146568 26 Apr 23:20 org.apache.felix.bundlerepository-1.4.0.jar -rw-r--r-- 59114 26 Apr 23:20 org.apache.felix.shell-1.2.0.jar -rw-r--r-- 12455 26 Apr 23:20 org.apache.felix.shell.tui-1.2.0.jar -rw-r--r-- 33138 17 Ago 12:12 org.apache.felix.fileinstall-1.2.0.jar
The final step is to configure Felix to start File Install and watch the dropins folder. To do that let’s open the config/config.properties file.
First of all we need to add the org.apache.felix.fileinstall-1.2.0.jar bundle in the felix.auto.start list. That will tell Felix to automatically install and startup the bundle.
felix.auto.start.1= file:bundle/org.apache.felix.shell-1.2.0.jar \ file:bundle/org.apache.felix.shell.tui-1.2.0.jar \ file:bundle/org.apache.felix.bundlerepository-1.4.0.jar \ file:bundle/org.apache.felix.fileinstall-1.2.0.jar
The second step is to set the felix.fileinstall.dir property to tell File Install the directory to watch. Simply add the following line at the end of the config/config.properties file.
felix.fileinstall.dir=dropins
That’s it!
Now go back to the main folder, and launch felix with the usual command:
$ java -jar bin/felix.jar Welcome to Felix. ================= -> felix.fileinstall.poll (ms) 2000 felix.fileinstall.dir /private/tmp/felix-1.8.0/dropins felix.fileinstall.debug -1 felix.fileinstall.bundles.new.start true ->
As you can see from the logs, Apache Felix File Install has been started and it is watching the dropins folder. Let’s try it now simply copying a bundle in the dropins folder.
While Felix is running, open another terminal window and copy a bundle in the dropins folder, for instance:
$ cd dropins/ $ wget http://www.mirrorservice.org/sites/ftp.apache.org/felix/org.apache.felix.configadmin-1.0.10.jar
Going back to the Felix console you will see something like:
-> Installed /private/tmp/felix-1.8.0/dropins/org.apache.felix.configadmin-1.0.10.jar -> Started bundle: /private/tmp/felix-1.8.0/dropins/org.apache.felix.configadmin-1.0.10.jar ->
Well done! You can experiment a bit with this simple project; you can update (a simple Unix touch would work) or delete the bundle, and Felix will update or uninstall the bundle in the OSGi container.
Final note: Apache Felix File Install works in every OSGi compliant container; if you are an Equinox user, you can very easily create the same project structure with your favorite OSGi framework.
If you enjoyed this post, please consider to leave a comment or subscribe to the feed and get future articles delivered to your feed reader.
Nice illustration. The current enhancements happening in fileinstall will make it even more compelling.