In this article Scott Lewis go even further and showcase a Twitter user status service with GWT, OSGi and Amazon Web services:

Using several technologies, I’ve recently created a Twitter user status service…i.e. a web service that retrieves the latest user status for a given user.

Read the complete article here.

The OSGi HTTP Service provides a simple OSGi service to deploy servlets and resources at runtime; in this article I’ll focus on the first part, implementing and deploying a simple Servlet.

First of all, you will need an OSGi HTTP Service implementation. As usual, Apache Felix provides a framework-independent bundle; so, without further ado, you can download it and install it in your OSGi container, or simply type

$ pax-run.sh http://www.osgilook.com/static/samples/osgi-http-service.txt

(By the way: have a look at our OSGi Demos for other easy, pre-cooked, demos)

Let’s now develop a simple Servlet. You don’t need to make it OSGi dependent in any way, so the usual Hello World Servlet would work:

public class DateServlet extends HttpServlet
{
	@Override
	protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException
	{
           resp.getWriter().write("Hi, today is "+ new Date());
	}
}

Easy. Now let’s write the usual deployment descript… no way! We want to deploy it on the fly, and without any boring XML descriptor!
What we need is to get access to the OSGi HttpService, and declare the new servlet. We can do that, as usual, in the bundle activator.

public class Activator implements BundleActivator
{
   public void start(BundleContext context) throws Exception
   {
      ServiceReference sRef = context.getServiceReference(HttpService.class.getName());
      if (sRef != null)
      {
         HttpService service = (HttpService) context.getService(sRef);
         service.registerServlet("/date", new DateServlet(), null, null);
      }
   }

   public void stop(BundleContext context) throws Exception
   {
      ServiceReference sRef = context.getServiceReference(HttpService.class.getName());
      if (sRef != null)
      {
         HttpService service = (HttpService) context.getService(sRef);
         service.unregister("/date");
      }
   }
}

Now package your bundle (don’t forget to specify the Bundle-Activator) and deploy it in the running OSGi container. If everything works fine, you’ll be able to reach your servlet at http://localhost:8080/date.

There are a few things the OSGi HTTP Service can also do, like registering resources. I’ll talk about that in the next blog post.

You can find more details on his “Pax My Framework” blog.

Let’s take it for a test drive.

First of all, to install the Knopflerfish HTTP Console you will need:

• the OSGi Compendium Bundle: http://repository.ops4j.org/maven2/org/osgi/org.osgi.compendium/4.1.0/org.osgi.compendium-4.1.0.jar
• an OSGi HTTP Service Implementation: http://apache.prosite.de/felix/org.apache.felix.http.jetty-1.0.1.jar
• and of course the Knopflerfish HTTP Console jar: http://www.knopflerfish.org/repo/jars/httpconsole/httpconsole-2.0.1.jar

The other important thing you need is to set the org.osgi.service.http.port property value; in fact, by default, the Http Service will try to start at port on port 80, causing an exception of Unix systems.

Feeling lazy (every developer is lazy..)? I’ve prepared a Pax-Runner file for you. Assuming you have Pax Runner installed, just type

$ pax-run.sh http://osgilook.com/static/samples/kf-http-console.txt

and you are ready to rock!

Now opening your browser at http://localhost:8080/servlet/console you have access to the Knopflerfish console in all its glory.

The functionalities offered by this tool are pretty basic. There’s the Bundle View, where you can see its headers and services exposed:

It is possible to select a single service to display all its properties:

And it’s of course possible to install a bundle directly from the web interface:

In summary, the functionalities offered are just basic compared to the Apache Felix Web Console; however, being the user interface so simple (and usable also with small screens), it’s quite ideal if you want to check the status of your OSGi framework deployed on a mobile device.
Want to know more?

$ pax-run.sh http://osgilook.com/static/samples/kf-http-console.txt

Cannot be simpler than that!

OSGi of course is not immune to that problem; an OSGi bundle may run in any device supporting a R4 OSGi container, and therefore needs a well defined and portable mechanism to store application and user settings. That’s the business of the OSGi Preferences Service.

In this article I’m going to show how you can use the Preferences Service in your OSGi applications.

First of all, you need an implementation of the OSGi Preferences Service. Apache Felix provides, as usual, a portable implementation that you can download and use in any R4 container: you can download the jar here and check the documentation here.

After you have downloaded and installed the bundle in your OSGi container, accessing to the Preferences Service is as simple as using any other service in OSGi:

ServiceReference serviceref = context.getServiceReference(PreferencesService.class.getName());
if (serviceref != null)
{
   PreferencesService preferences = (PreferencesService) context.getService(serviceref);
   //store and retrieve your preferences here
}

Preferences are organized in a tree structure, so you can define quite complex preference models; the only limitation is give by the fact that you can store on “simple” values (boolan, double, float, int, long and strings) and not any type of Java object.

As mentioned before, the Preferences Service can be used to store application and user settings. To store application settings, you will place your settings under the system root.
Let’s see in the following example how an application can store the information gathered during the installation:

ServiceReference serviceref = context.getServiceReference(PreferencesService.class.getName());
if (serviceref != null)
{
   PreferencesService preferences = (PreferencesService) context.getService(serviceref);	

   //create a node 'installation' under the system root
   Preferences installationPreferences = preferences.getSystemPreferences().node("installation");
   installationPreferences.put("path", "/opt/myapp");   //path chosen by the user
   installationPreferences.put("license-key", "687-6GH-9JU-35H");   //license key
   installationPreferences.put("license-email", "hacker@hackerz.com");   //license owner...
}

Reading these settings is equally simple (note that every getter method has a second argument that specifies a default property value if the one required is not found):

ServiceReference serviceref = context.getServiceReference(PreferencesService.class.getName());
if (serviceref != null)
{
   PreferencesService preferences = (PreferencesService) context.getService(serviceref);	

   //retrieve the  'installation' node under the system root
   Preferences installationPreferences = preferences.getSystemPreferences().node("installation");
   String key = installationPreferences.get("license-key", null);   //get the license key
   String ownder = installationPreferences.get("license-email", null);   //get the license owner
}

Using the same API you can store and read user settings. Instead of accessing the System Root just access the User Root writing:

ServiceReference serviceref = context.getServiceReference(PreferencesService.class.getName());
if (serviceref != null)
{
   PreferencesService preferences = (PreferencesService) context.getService(serviceref);	

   //retrieve the  'installation' node under the system root
   Preferences installationPreferences = preferences.getUserPreferences("John");
}

Need more OSGi articles and tutorial? Check the OSGi Recipes section

In the previous article this week I described a simple project structure using the Apache Felix File Install bundle to allow hot deployment of new bundles.
Another interesting feature of the File Install bundle is its ability to load property files and send them to the OSGi ConfigurationAdmin service; that’s very useful if you want to be able to configure your applications just creating/deleting and updating properties file at runtime. In this post I’ll enhance the project presented in the previous article to include this new functionality.

The new project structure we want to build is represented in the picture.

The difference here is the additional config/application folder, that will be monitored by another instance of File Install; we will be able to create there new property files whose contents will be passed to the OSGi Configuration Admin Service.

First of all, we need an implementation of the OSGi Configuration admin service. We could download and store it in the bundle folder, and than add its path in the felix.auto.start property in the config.properties like we did in the previous article; but it much easier just to download it in the dropins folder… that’s why we created it!

$ cd dropins
$ wget http://apache.mirroring.de/felix/org.apache.felix.configadmin-1.0.10.jar

Now that the Configuration Admin bundle is in the dropins folder, we know that it will be automatically installed when we start up Felix.

To create another instance of File Install we will use… File Install. Just create a file called org.apache.felix.fileinstall-config.cfg in the dropins folder containing a single property:

felix.fileinstall.dir=config/application

Now start Felix

Welcome to Felix.
=================

DEBUG: WIRE: 1.0 -> org.osgi.service.startlevel -> 0
DEBUG: WIRE: 1.0 -> org.osgi.framework -> 0
DEBUG: WIRE: 1.0 -> org.osgi.service.packageadmin -> 0
DEBUG: WIRE: 2.0 -> org.apache.felix.shell -> 1.0
DEBUG: WIRE: 2.0 -> org.osgi.framework -> 0
-> DEBUG: WIRE: 3.0 -> org.osgi.util.tracker -> 0
DEBUG: WIRE: 3.0 -> org.osgi.framework -> 0
DEBUG: WIRE: 3.0 -> org.osgi.service.packageadmin -> 0
felix.fileinstall.poll  (ms)   2000
felix.fileinstall.dir            /opt/myprojects/felix-1.8.0/dropins
felix.fileinstall.debug          -1
felix.fileinstall.bundles.new.start          true
Installed /opt/myprojects/felix-1.8.0/dropins/org.apache.felix.configadmin-1.0.10.jar
DEBUG: WIRE: 4.0 -> org.osgi.framework -> 0
DEBUG: WIRE: 4.0 -> org.osgi.service.cm -> 3.0
Started bundle: /opt/myprojects/felix-1.8.0/dropins/org.apache.felix.configadmin-1.0.10.jar
felix.fileinstall.poll  (ms)   2000
felix.fileinstall.dir            /opt/myprojects/felix-1.8.0/config/application
felix.fileinstall.debug          -1
felix.fileinstall.bundles.new.start          true

and we’re done! The log
felix.fileinstall.dir /opt/myprojects/felix-1.8.0/config/application
confirms that another instance of File Install is watching config/application

All happened too fast? Let’s summarize.

File Install looks for two types of files: .jar and .cfg. When it finds a jar file, tries to install it as a bundle in the OSGi container; when it finds a cfg files, it reads its content, and

• if the file name is something like [service-name]-[service-pid].cfg, it uses the ConfiguratioAdmin service to send the configuration to the ManagedServiceFactory whose service.pid is [service-name]
• if the file name does not contain a – (dash), it sends the configuration to the ManagedService whose service.pid is equal to the file name (without the .cfg extension)

So the trick here is that File Install is started by a ManagedServiceFactory with service.pid equal to org.apache.felix.fileinstall. So when File Install finds the file org.apache.felix.fileinstall-config.cfg in the dropins folder, it reads the contents and send it to its own ManagedServiceFactory that creates another instance of File Install watching the config/applications folder.

Now you are ready to experiment with this new project structure. I’ll leave you with some ideas to try out:

* Read this article explaining how to configure the Apache Felix HTTP service with the Configuration Admin Service; after that, download Felix HTTP servlet in the dropins folder and configure the HTTP port creating a file named org.apache.felix.http containing the property org.osgi.service.http.port

* Also the Felix Web Console exposes a ManagedService under the service.pid org.apache.felix.webconsole.internal.servlet.OsgiManager. Look in the Web Console documentation to find out the properties to change username and password, and create a configuration file in config/application to change the default hacker-friendly admin/admin credentials!

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.

• Putting OSGi to the Test with Pax Exam, introductory tutorial on Pax-Exam by Craig Walls
• Testing OSGi…Spring Style another Craig Walls article on Spring-DM’s testing support
• Lumins OSGi testing framework, documentation of the open source OSGi testing framework developed by Luminis
• junit4osgi quick start, tutorial to get started with Apache Felix Junit4osgi

In our introductory articles on the OSGi Configuration Admin Service, we explained how to programmatically access to the OSGi ConfigurationAdmin interface to send configuration dictionaries to bundles installed in your OSGi framework.
Of course that’s just one possible usage scenario of the Configuration Admin Service. In many cases, however, you want to give your customer (or the deployment team) the opportunity to configure your system directly, and writing some Java code is not the most practical solution. In these cases, there are some tools that make it easy to use the Configuration Admin Service.

The one we are talking about today is an handy extension of the Apache Felix (or Equinox) console developed by Luminis. Let’s see how we can use it to configure the Apache Felix HTTP service.

First of all we need to start up Apache Felix. If you have downloaded the main Felix distribution, you need to type

java -jar bin/felix.jar

to start the OSGi container.

If you prefer using Pax-Runner, you’ll just type

pax-run.sh

In both cases, the usual Apache Felix console will be displayed

Welcome to Felix.
=================

->

Now you need to install two bundles

• the Apache Felix Configuration Admin Service
• the Lumins OSGi Configuration Admin command line client

Installing them is straightforward, just type the following commands in the console:

-> install http://mirrors.dedipower.com/ftp.apache.org/felix/org.apache.felix.configadmin-1.0.10.jar
Bundle ID: 4
-> install https://opensource.luminis.net/wiki/download/attachments/2031635/net.luminis.cmc-0.2.3.jar?version=1&modificationDate=1240778068150
Bundle ID: 5
-> start 4 5
-> ps
START LEVEL 6
   ID   State         Level  Name
[   0] [Active     ] [    0] System Bundle (1.8.1)
[   1] [Active     ] [    1] osgi.compendium (4.1.0.build-200702212030)
[   2] [Active     ] [    1] Apache Felix Shell Service (1.2.0)
[   3] [Active     ] [    1] Apache Felix Shell TUI (1.2.0)
[   4] [Active     ] [    5] Apache Felix Configuration Admin Service (1.0.10)
[   5] [Active     ] [    5] luminis Configuration Admin command line client (0.2.3)

With the two additional bundles installed, we have added several new commands to the Apache Felix shell. Let’s see them typing cm help

-> cm help
Usage:
 cm help                  print this help message
 cm list                  list all known configurations
 cm get <pid>             show configuration for service <pid>
 cm getv <pid>            verbose get (shows value types also)
 cm put <pid> key value   set string value for service <pid>
 cm puts <pid> key value  set "simple" value for service <pid>: value is "true", "false",
                          a char in single quotes, an int, or a number, with appended:
                          i (Integer), l (Long), f (Float), d (Double), b (Byte), s (Short)
 cm del <pid>             deletes configuration for service <pid>

The help is pretty self-explaining, but let’s proceed with a simple example installing the Apache Felix HTTP service. This Felix subproject implements the OSGi HTTP Service specification, and embeds a Jetty servlet container. This internal Jetty server can be configured using the OSGi Configuration Admin Service.

Let’s start by installing the Apache Felix HTTP service.

-> install http://mirror.lividpenguin.com/pub/apache/felix/org.apache.felix.http.jetty-1.0.1.jar
Bundle ID: 6

The web page of this bundle lists all the configurations that you can set; for instance, you can use the org.osgi.service.http.port property to set the HTTP port Jetty is listening to.

To do that, first of all you need to create a configuration instance for the Apache Felix HTTP bundle, set the property and then start the Jetty bundle (in our case it’s bundle ID 6)

-> cm create org.apache.felix.http
-> cm put org.apache.felix.http org.osgi.service.http.port 8888
-> start 6

If everything is ok, you should see the Jetty bundle starting; now try to connect to http://localhost:8888 and see the nice 404 page! If you see that, you have successfully configured your bundle; the 404 error is normal, since you haven’t installed any web application yet.

Of course you can now set additional properties, or even change the one just set. New configurations will be read on the fly, and the Jetty instance updated accordingly.
In every moment, you can see the list of the existing configurations typing cm list

-> cm list
Configuration list:
org.apache.felix.http     http://mirror.lividpenguin.com/pub/apache/felix/org.apache.felix.http.jetty-1.0.1.jar

or display the list of properties for a given configuration typing cm get [service pid]

-> cm get org.apache.felix.http

Configuration for service (pid) "org.apache.felix.http"
(bundle location = http://mirror.lividpenguin.com/pub/apache/felix/org.apache.felix.http.jetty-1.0.1.jar)

key                          value
------                       ------
service.pid                  org.apache.felix.http
org.osgi.service.http.port   8888

pax-run.sh --profiles=web http://myrepository/web.txt

in all the nodes of your cluster.     


Want to learn more on Pax-Runner?
Read
Starting with OSGi? Try Pax-Runner!

Let’s start by saying that a provisioning file can be as simple as a list of bundles. Let’s make a useful example building a provisioning file to install the Apache Felix Application Demo. These bundles are not available for download in the Felix website, so I uploaded a copy of them in the OSGi Look server.
Now just open any text file and type:

http://www.osgilook.com/static/samples/servicebased.circle-1.0.0.jar
http://www.osgilook.com/static/samples/servicebased.host-1.0.0.jar
http://www.osgilook.com/static/samples/servicebased.square-1.0.0.jar
http://www.osgilook.com/static/samples/servicebased.trapezoid-1.0.0.jar
http://www.osgilook.com/static/samples/servicebased.triangle-1.0.0.jar

Save the file as felix-demo.txt.

Now go back to your console, and type pax-run.sh file:///path/to/felix-demo.txt.

pax-run.sh file:////tmp/demo.txt
    ______  ________  __  __
   / __  / /  __   / / / / /
  /  ___/ /  __   / _\ \ _/
 /  /    /  / /  / / _\ \
/__/    /__/ /__/ /_/ /_/

Pax Runner (1.1.1) from OPS4J - http://www.ops4j.org
----------------------------------------------------

 -> Using config [classpath:META-INF/runner.properties]
 -> Using only arguments from command line
 -> Scan bundles from [file:////tmp/demo.txt]
 -> Scan bundles from [scan-file:file:////tmp/demo.txt]
 -> Provision bundle [http://www.osgilook.com/static/samples/servicebased.circle-1.0.0.jar, at default start level, bundle will be started, bundle will be loaded from the cache]
 -> Provision bundle [http://www.osgilook.com/static/samples/servicebased.host-1.0.0.jar, at default start level, bundle will be started, bundle will be loaded from the cache]
 -> Provision bundle [http://www.osgilook.com/static/samples/servicebased.square-1.0.0.jar, at default start level, bundle will be started, bundle will be loaded from the cache]
 -> Provision bundle [http://www.osgilook.com/static/samples/servicebased.trapezoid-1.0.0.jar, at default start level, bundle will be started, bundle will be loaded from the cache]
 -> Provision bundle [http://www.osgilook.com/static/samples/servicebased.triangle-1.0.0.jar, at default start level, bundle will be started, bundle will be loaded from the cache]
 -> Preparing framework [Felix 1.8.1]
 -> Downloading bundles...
 -> http://www.osgilook.com/static/samples/servicebased.circle-1.0.0.jar : 12051 bytes @ [ 45kBps ]
 -> http://www.osgilook.com/static/samples/servicebased.host-1.0.0.jar : 386419 bytes @ [ 51kBps ]
 -> http://www.osgilook.com/static/samples/servicebased.square-1.0.0.jar : 10705 bytes @ [ 40kBps ]
 -> http://www.osgilook.com/static/samples/servicebased.trapezoid-1.0.0.jar : 12018 bytes @ [ 89kBps ]
 -> http://www.osgilook.com/static/samples/servicebased.triangle-1.0.0.jar : 11993 bytes @ [ 65kBps ]
 -> Using execution environment [J2SE-1.6]
 -> Runner has successfully finished his job!

Welcome to Felix.
=================
->

The logs show that all the bundles listed in the provisioning file are installed and started in your Felix container. And after a few seconds, you will be able to play with the Apache Felix Demo application!

Provisioning from a URL

If you want to use your provisioning file to startup multiple instances of an application, the best thing you can do is to upload it in a HTTP server. For instance, you can find the provisioning file we have just written at http://www.osgilook.com/static/samples/felix-demo.txt.

You can try now to type pax-run.sh http://www.osgilook.com/static/samples/felix-demo.txt: as a result, you will create a Felix container and automatically download all the bundles defined at that URL.

Advanced features

Pax-Runner provides many advanced features; you can for instance set start levels, use different protocols (Maven) and set system properties. Please refer to the documentation for a complete overview.