Thursday, 29 November 2012

Enabling the Felix Web Console in a WAS Liberty Profile OSGi Application

UPDATE: Since writing this blog Liberty has added the Felix Web Console as a first-class feature.  See:

The full profile WebSphere Application Server (WAS) has supported the deployment of applications written using OSGi for many years now.  The latest version, 8.5, has support for both a command line console and a web-based console as part of the WebSphere Admin Console.  Both consoles are very useful for tracking down dependency and lifecycle problems within an application, but unfortunately, these capabilities are not available in the Liberty profile of WAS and so determining what is happening inside your OSGi application can be a bit of a challenge.  And now for what might seem like a slight digression...

Over the years, I've heard quite a bit of interest in using the OSGi Http Service for developing and deploying Web applications to WAS.  WAS does not directly support this model, but instead supports the Web Application Bundle model standardized in the Enterprise OSGi specification.  This lack of support for the Http Service did not stop Ralf Zahn of ARS getting the Eclipse Equinox implementation of the Http Service running in WAS by deploying it as part of a Web Application Bundle.  The details of what he did, including a little demo, can be found on his blog, here.  OK, back to the console topic...

The Felix Web Console provides a nice set of console capabilities for OSGi runtimes and there are also some plugins to augment the out-of-the-fox support.  It just so happens that the only mandatory pre-requisite service (other than an OSGi Framework, of course) is the Http Service.  So, I wondered if we could combine the approach taken by Ralf to enable the Felix Web Console and thus get useful insights into what's going on inside an OSGi application running on the Liberty Profile.  Well, not surprisingly, the answer is "yes".

Before I go into the details, first the disclaimer:
  1. You need to add four bundles to your OSGi application and so it's not the most elegant solution in the world (note, I used Felix Web Console 3.1.8. which has a distribution that includes its pre-req's.  If you use the latest Web console (4.0), or the 'bare' distribution you will need to also add its pre-req's to the application).
  2. The Felix Web Console is for managing OSGi frameworks and so it lets you modify the life-cycle of individual bundles  This is not advisable for OSGi applications, where the OSGi application runtime manages the life-cycles of these bundle for you.
The four bundles are as follows:

Bundle Purpose
org.apache.felix.webconsole The Felix Web Console.  This can be downloaded from here.
gcc.samples.httpservice.wab The Web Application Bundle that registers the Equinox HttpServiceServlet. It's this servlet that provide the Http Service implementation. The WAB has a default context route of /httpservice.  This can be downloaded from here.  It contains no code, simply web.xml configuration for the HttpServiceServlet. Provides the APIs for the Http Service implementation. This can be downloaded from here.
org.eclipse.equinox.http.servlet Provides the HttpServiceServlet implementation.  This can be downloaded from here.  For some reason this jar is not available in later equinox releases, but I believe that to be a infrastructure mistake, not a sign it was removed, so I'd hope that will be fixed soon.

The application definition that uses these bundles should look something like this (note, this one does not contain any application bundles, only those required to enable the Web console):

Application-Name: Application with Web Console
Application-SymbolicName: web.console-3.1.8.eba
Application-ManifestVersion: 1.0
Application-Version: 1.0.0
Application-Content: gcc.samples.httpservice.wab;version="[1.0.0, 1.1.0)",
  org.apache.felix.webconsole;version="[3.1.8, 3.2)",
  org.eclipse.equinox.http.servlet;version="[1.1,1.2)",;version="[3.3, 3.4)"
Manifest-Version: 1.0

The documentation for the Felix Web Console can be found here.

If you use the bundles as-is, without changing the context route, you should be able to point your browser at http://<server>:<port>/httpservice/system/console (as described on the Web Console documentation).  Log in with "admin" & "admin" and the console should be displayed.  From the bundles view, you can see bundle status, package imports/exports, navigate package dependencies.  There's a services view where you can see the registered services, who's providing them, who's using them, and so on - all the sorts of things you need to be able to do to track down problems.

The following is an example screenshot of the Web Console for the above application definition.

Bundles 2-5 are the bundles we configured in the application definition.  Bundle 0 is the system bundle and bundle 1 is the bundle providing imports into the application.  If you drill down on this you'll see it provided the servlet packages required by the Web Application Bundle.

I hope you find this useful.