Please make sure you read the previous installments before you continue with this article…

To ensure greater flexibility, performance and encapsulation, we will be using OSGi fragments.

http://static.springsource.org/osgi/docs/1.1.3/reference/html/appendix-tips.html

OSGi fragments attach to “host” bundles and can be used to extend functionality, provide configuration and even extra manifest entries.

On the first part, we move our unit tests to fragments. This has the benefit of being able to separate tests from actual code as well as allowing us to deploy using a smaller footprint in situations where we don’t want test code such as production deployments.

If we start with the cache code we’ve got so far we need to separate the test code from two bundles: ‘com.calidos.dani.osgi.cache.provider.memory’ and ‘com.calidos.dani.osgi.cache.provider.memcached’. That is easy enough.

We create a new OSGi bundle fragment project like this:

We specify the bundle the new fragment is attaching to:

The next step is to move the JUnit code from the main bundle onto the fragment. If we run the test independently we see that it passes as the classpath of the host and fragment bundles is merged into one.

We then add the fragment to our existing run configuration and it will be loaded onto our environment. So far so good, but there is no way to run the tests outside our controlled Eclipse.

Slim Ouertani at Javalobby shows us how to run fragment tests from within the OSGi environment in a great article. His code uses the new bundle tracker feature to discover any test fragments and exposing functionality to be able to run the tests.

You can get the source at kenai: http://kenai.com/projects/testosgifragment

We read the article thoroughly, fetch the source and build test.extender using maven:


mvn install


The code works great but has a bug which is triggered when the code looks for the host of the fragment by reading the ‘Fragment-Host:’ header. If the value specifies any kind of version qualifier it fails. It also crashes when trying to test a bundle or a fragment that doesn’t have the ‘Unit-Test’ custom header.

The ‘Unit-Test’ custom header lives on the fragment manifest and is used by test.extender to control who is able to be tested and if tests are done manually or automatically.

If no ‘Unit-Test’ header is present or if its value is empty, test.extender will refuse to run any tests present on the bundle. If the value is ‘true’ then test.extender will run the tests automatically whenever the test fragment bundle is loaded. If the value is anything else the tests won’t run automatically but you can still run them using the ‘test’ and ‘testall’ commands.

I have patched the code to accept a version qualifier for the fragment host as well as giving out an informative error message when attempting to test the wrong bundle.

Once this is done, we play with the test.extender by obtaining the fragment bundle id and issuing ‘test <id>’ on the console:


osgi> test 80
Bundle : [80] : com.calidos.dani.osgi.cache.provider.memory.test
_
CLASS : [com.calidos.dani.osgi.cache.provider.memory.test.MemoryCacheTest]
___________________________________________________________________________
Method : [ testClear ] PASS
Method : [ testInit ] PASS
Method : [ testInitInt ] PASS
Method : [ testSize ] PASS
Method : [ testSet ] PASS
Method : [ testGet ] PASS
Method : [ testGetStatus ] PASS
___________________________________________________________________________
_


We can also use the ‘testall’ command which will look for all the testable fragment bundles and run the test there.

Having tested that functionality, we separate the tests from the memcached bundle and move them onto their own bundle.

Here you can download the two test fragments and the patch to modify test.extender, neat.

Ok then, we move onto the next thing that is looking closely at the Servlet Bridge and its behaviour. What we are interested in is what happens when the container deploys and inits the Web app itself, starting up the servlet bridge. The bridge uses the container temporary folder to deploy the OSGi environment in a subfolder, copying any bundles into that subfolder. If the subfolder exists and there are bundles that have the same names, they won’t be copied. I have found this behaviour to be very confusing for newbies to the platform and very annoying for veterans. I’m not entirely sure if this is deliberate and has performance reasons or what. Calling the framework controls to prevent that is not optimal and manually removing the temporary folder isn’t, either. One possible solution would be to use a building system that increments the micro number every time there is a build and remember to clear up the container temporary folder from time to time. That is not always desirable or possible but fortunately, the servlet bridge implementation provides a way to customize it to our heart’s content.

Basically we have the following code in the bridge init() method:

	framework.init(getServletConfig());
	framework.deploy();
	framework.start();
	frameworkStarted = true;

In this case, ‘framework’ is a instance of the FrameworkLauncher class which is created just before this code snippet. The FrameworkLauncher is the class responsible for deploying and launching OSGi. We note that the object is created by default as a plain FrameworkLauncher instance. However, the class to be used can be customized by specifying it in the web.xml file using the ‘frameworkLauncherClass’ servlet initialization parameter. As long as that class is a subclass of FrameworkLauncher the appropriate contract is fulfilled.

This means we can override some behaviour and delete the framework deployment folders upon startup:

@Override
public void init() {

super.init();

File servletTemp = (File) context.getAttribute("javax.servlet.context.tempdir");
File platformDirectory = new File(servletTemp, "eclipse");

if (platformDirectory.exists()) {
	deleteDirectory(platformDirectory);
}

}

Cool, so we need to export this as a jar file named dani-frameworklauncher.jar into the package project lib folder:

Next we change the servletbridge web.xml configuration parameter to load the new framework launcher:


<init-param>
<param-name>frameworkLauncherClass</param-name>
<param-value>com.calidos.dani.osgi.servletbridge.FrameworkLauncher2</param-value>
</init-param>


To test, we can add a file onto the $APACHE_TOMCAT/work/Catalina/localhost//eclipse folder and restart Tomcat. Before this new launcher was in place, the file would be kept but now it is deleted alongside the rest. Any other methods can also be extended to customize the bridge behaviour without having to modify the launcher class.

Here you can download the framework launcher project, put it on the WEB-INF/lib folder alongside the servlet bridge and enjoy!

Please read the previous installments to get up to speed and see the source used in this post.

Firstly, we need to setup some kind of project to hold all that is going in the WAR archive. This can be done using the WTP (Web Tools Project) or just as a regular project.

In this case we do it using a plain-vanilla resource project but feel free to use WTP as the basics are the same.

So firstly we create a resources project to hold the stuff, named ‘com.calidos.dani.osgi.cache.package’ for instance.
Secondly, we create the folder structure we need to hold all the files that need to reside in the final WAR webapp, so we create a WEB-INF folder to hold all the classes, libraries metadata and configuration.

We also know we need a web.xml file to define all the servlets this webapp declares. This is where the Equinox Servlet Bridge kicks in. It provides a Servlet that loads up the environment as well as forwards any HTTP requests onto our OSGi-managed Servlet instances.

We check the Equinox in a servlet container article and learn what the bridge Servlet is called, what parameters it can take and any other web.xml details we need.

For instance, we declare that the webapp service class is our BridgeServlet class:

<servlet-class>org.eclipse.equinox.servletbridge.BridgeServlet</servlet-class>
<init-param>
<param-name>commandline</param-name>
<param-value>-console</param-value>
</init-param>
<init-param>
<param-name>enableFrameworkControls</param-name>
<param-value>true</param-value>
</init-param>


We also add two parameters (more information and additional options can be found on the FrameworkLauncher servlet bridge class and the Equinox documentation).

Next, we need this special servlet itself. I prefer to check out the servlet from CVS and compile it myself but you can also find it here (from the the Latest Release pick up the org.eclipse.equinox.servletbridge jar). In the case of using the source, the CVS connection data is the following:


Method: pserver
User: anonymous
Host: dev.eclipse.org
Repository path: /cvsroot/rt
CVS Module: org.eclipse.equinox/server-side/bundles/org.eclipse.equinox.servletbridge


Once we import the project into Eclipse it looks like this:

As we can see, there are just three classes which compose the servlet, a special classloader and finally a class that launches OSGi.

If we import the project into our workspace, we have compiled classes in the bin/ folder of the project but we really want them neatly packaged as a jar file. Therefore, we right-click on the project to export as a JAR java package:

We take this JAR archive and save it in our package project WEB-INF/lib folder. We also check the composition of the file to make sure it includes all the classes we need.

This takes care of the plain webapp side of things so we move onto actually loading OSGi and what configuration it needs.

As mandated by Equinox we add a launch.ini file to clear and possibly override System properties (please see the source for details on that).

We then create an eclipse folder, which the servlet bridge expects to find the OSGi platform jar and any bundles (including ours).

We select all our project bundles, right-click and select the ‘Export…:Deployable plug-ins and fragments’ option.

This leaves us with a list of bundles that compose our custom code:

com.calidos.dani.osgi.cache.controller_1.0.0.beta.jar
com.calidos.dani.osgi.cache.frontend.http_1.0.0.beta.jar
com.calidos.dani.osgi.cache.log4jconfig_1.0.0.beta.jar
com.calidos.dani.osgi.cache.provider.memcached_1.0.0.beta.jar
com.calidos.dani.osgi.cache.provider.memory_0.0.1.dev.jar


Good, as we know, there are some standard and some special bundle dependencies we need as well. Let’s go through them by groups. We get a bunch of basic OSGi bundles we should include in most projects:

org.eclipse.equinox.registry_3.4.100.v20090520-1800.jar
org.eclipse.osgi.services_3.2.0.v20090520-1800.jar
org.eclipse.osgi.util_3.2.0.v20090520-1800.jar
org.eclipse.osgi_3.5.1.R35x_v20090827.jar


There are several options to obtain these bundles:

For expediency, we can go to our Eclipse installation folder and look for them in the ‘plugins’ subfolder. We then copy them into our package ‘plugins’ folder and there you go.

The second option is to get them from the Equinox distribution.

Another option is to the prepackaged servlet bridge feature which can be picked from CVS as well:

Method: pserver
User: anonymous
Host: dev.eclipse.org
Repository path: /cvsroot/rt
CVS Module: org.eclipse.equinox/server-side/features/org.eclipse.equinox.servletbridge.feature

Once that is loaded onto our workspace, we open the feature.xml and select the ‘Export Wizard’ form the ‘Exporting’ section. This lets us export these minimum bundles and generate both the deployment ‘feature.xml’ file as well as the bundle listing (even though the wizard actually takes them from our Eclipse platform).

We also have some more dependencies related to doing HTTP and the logging platform:

org.apache.log4j_1.2.13.v200903072027.jar
org.eclipse.equinox.common_3.5.1.R35x_v20090807-1100.jar
org.eclipse.equinox.http.registry_1.0.200.v20090520-1800.jar
org.eclipse.equinox.http.servlet_1.0.200.v20090520-1800.jar
org.eclipse.equinox.registry_3.4.100.v20090520-1800.jar


These can also be obtained from the Eclipse plugins folder or Equinox distribution folder. One should note that modifying the feature.xml taken from the Eclipse CVS repository, adding any required plugins there and then running the Export Wizard.

Finally, we have two dependencies we need to pay special attention to:

org.eclipse.equinox.http.servletbridge_1.0.200.200911180023.jar
javax.servlet_2.4.0.200911240836.jar


In the first case, it’s a special minimal bundle that hooks the plain webapp servlet bridge with the OSGi ‘org.eclipse.equinox.http.servlet’ standard component which publishes a servlet service onto the OSGi platform.

This are the details to get it from CVS:

Method: pserver
User: anonymous
Host: dev.eclipse.org
Repository path: /cvsroot/rt
CVS Module: org.eclipse.equinox/server-side/bundles/org.eclipse.equinox.http.servletbridge

We export it as a deployable plug-in and add it to the mix. We can also download it from the Equinox distribution site as well.

In the second case, this bundle contains the basic servlet classes and interfaces and I have found problems of class signatures when using 2.5 along with the servlet bridge so unless all is compiled against 2.5 the safest bet is to go with 2.4.

(Check http://www.eclipse.org/equinox/documents/quickstart.php for more info).

Next, Equinox requires an XML file to define some metadata about the loaded bundles and make our configuration easier. The file sits in a folder called ‘features’ plus a subfolder with a reverse DNS name and is called feature.xml.

The structure is quite simple (though it can be created using the Eclipse Feature Export Wizard) and mainly holds a list of plugins, their version data and some more fields:

We complete the list with all our bundles, fully knowing that we can extend our environment on the fly once it’s loaded if we need it.

Next, we create the config.ini file which really tells equinox which of the bundles stated in the feature file to start, at which start level and lets us add even more bundles (though we need to specify where the actual file is located and the full filename in that case). It also lets us configure the environment pretty thoroughly.

The resulting config.ini file looks like this:


#Eclipse Runtime Configuration File
osgi.bundles=org.eclipse.equinox.common@1:start, org.apache.log4j@start, org.eclipse.osgi.util@start, org.eclipse.osgi.services@start, org.eclipse.equinox.http.servlet@start, \
org.eclipse.equinox.servletbridge.extensionbundle, \
org.eclipse.equinox.http.servletbridge@start, \
javax.servlet@start, org.eclipse.equinox.registry@start, org.eclipse.equinox.http.registry@start, org.eclipse.equinox.servletbridge.extensionbundle \
org.eclipse.equinox.http.servlet@start, org.eclipse.equinox.common@start, com.calidos.dani.osgi.cache.log4jconfig, \
com.calidos.dani.osgi.cache.provider.memcached@3:start, com.calidos.dani.osgi.cache.provider.memory, com.calidos.dani.osgi.cache.controller@4:start, \
com.calidos.dani.osgi.cache.frontend.http@5:start

osgi.bundles.defaultStartLevel=4


We decide not to start the in memory bundle as it only works reliably in a single instance deployment scenario. Otherwise, in a multiple server setup the in-memory cache data would become inconsistent.

Also, be sure to check the Equinox quickstart guide and documentation for more information.

Once all is is done, the project looks like this:

Time to right-click on the project and select ‘Export:Archive file’ to save it in zip format and rename it to .war. Ready to deploy! Remember to access it using the URL //cache/. In web.xml the ‘-console 6666′ parameter means that doing a telnet on port 6666 of the machine initiates a session within the OSGi console. WARNING: there is absolutely NO SECURITY so disable, firewall or ACL that port NOW.

As usual, here you can find the source and the completed WAR though they are one and the same.

In this post, we will add another cache provider implementation to the mix as well as provide an HTTP front-end so the whole application can be tested.

First of all, let’s present a conceptual diagram of all the bundles and fragments involved so far.

Read on for more…

We start with providing the extra implementation. We will be making a memcached cache provider using the excellent memcached-spy java library (MIT licensed).

As usual, we create a new plug-in project and name it accordingly (com.calidos.dani.osgi.cache.provider.memcached). We firstly create source folders named ’src’ and ‘test’ to hold any unit tests. Secondly, we download the spy memcached library from here.

We create a ‘lib’ folder on the project to hold the library and modify the classpath of the plug-in so its code is able to see the memcached client classes (but not the bundle clients!). In the runtime section of the MANIFEST.MF editor we select the library like this:

We also add the controller as a dependency so we can properly implement the CacheProvider service interface.

Secondly, we “copy” the unit testing code from the Memory cache bundle as all tests will be quite similar (as both bundles basically fulfil the same contract).

When doing all this work, we discover that the memcached system doesn’t have some functionality other cache systems might have. For instance, the number of elements in the cache can’t be counted (not easily and cheaply). Additionally, the cache can’t really be cleared without restarting all memcached instances.

So it makes sense to add the UnsupportedOperationException exception to the interface, acknowledging the fact that some cache implementations might not provide all the facilities of the service. Other strategies would be to use subclassing, specialise the providers, etc In this case, we opt for adding the exceptions where it makes sense. That is, in the case of the get and set operations we can’t allow a service that doesn’t let you manage its elements. That’s not our definition of “cache”.

We adjust the code and tests in the Memory cache if necessary to adapt to the new interface and implement the mecached client (the unit tests will need some modification).

The memcached bundle in the project view ends looking like this:

We make sure tests pass on this new bundle, to do that we need to tweak the test code a little bit (to capture new exceptions being thrown).

Next, we register the Cache service proper from the core controller tracker like this:

controller = new CacheControllerCore();
controller.addCacheProvider(cacheProvider);

//we have a provider, we can start publishing our service
registration = context.registerService(Cache.class.getName(),controller,null);

Note that we register the Cache service once we have added the first provider backend. This ensures that at least a backend is available as soon as the main service is registered.

At this point, things are looking good on backend implementation bits so we can move to providing a nice HTTP front-end for the cache so it can be used.

Therefore, we create a new bundle and call it something appropriate, such as ‘com.calidos.dani.osgi.cache.frontend.http’. The main function of this bundle is to glue together a HTTP Service being made available in the context to the business logic Cache service (provided by the core controller bundle). In this manner, the controller bundle does not need to know anything about HTTP or Servlet implementation. Moreover, this bundle only uses the Cache and doesn’t know about providers or implementation details.

We need to import a few packages and require the equinox http bundle to be present:

As an HTTP provider we can use the one provided by Jetty (that is bundled with Equinox).

Following the same model that on the controller bundle, we register two trackers one for the http service and another for the Cache service. Once both are made available we can create the servlet and glue them together.

There is a method to register the servlet on a particular URL:

cacheHttpFrontend.setCacheService(cacheService);
httpService.registerServlet("/cache", cacheHttpFrontend, null, null);

From that moment onwards we are sending any ‘/cache’ URLs onto the servlet instance, which will use ‘/cache’ as the key.

The servlet can implement the usual methods ‘doPost’ and ‘doPut’ to add data onto the cache and doGet to retrieve it. These method calls translate into the appropriate Cache calls. Any exceptions or null values can be translated into equivalent HTTP errors or responses. For example, we can return a 500 if an unrecoverable exception is thrown from the cache or a 400 if the path is simply ‘/cache’ (which means no key is provided).

As a result of thinking in HTTP terms, we come to realise we need some metadata about the contents of the cache. At least, we need to store the mime type of the data so we can properly serve multimedia and any content other than text. Moreover, we could store some more metadata to tune up the cache, do automatic refreshing of the content, etc.

One possible strategy is to ask the Cache to store a POJO instance that holds the metadata as well as the cached content itself. This seems the simplest approach at the moment so this is what we do. The Cache is still a generic service and as long as we prefix the HTTP caches accordingly at the app level we will be fine with using it in other clients (and these might revert to MIME as their way to tag content types as well).

We can create a custom class POJO but that means that any backend that does POJO serialisation needs access to this class so it can create one. To avoid that class and encapsulation break we just use a plain vanilla serialisable class (Map). In any case, we need to make a not of this problem of the design so it is addressed in the future.

NOTE: it could be addressed in a simple enough manner. The cache entry object interface could be formalised and exported by the controller. In this manner, the front-end and the providers could make use of it and serialise it properly.

We create the cache entry Map instance in a simple enough manner:

HashMap httpCacheEntry = new HashMap(2);
httpCacheEntry.put(ENTRY_BODY_KEY, body);
httpCacheEntry.put(ENTRY_MIME_KEY, contentType);
cache.set(key,httpCacheEntry);

In this manner, we can recover the appropriate metadata (in this case MIME type) from the entry cache whenever we do a get() operation. This doesn’t mean we expect all requested entries to have that structure (principle of robustness), it just means we will use it if it’s there, setting the HTTP response MIME type accordingly.

With these enhancements and a few more small code refactors we can stabilise our code and call it a day. To summarise what we have done in this post:

• Created a new CacheProvider implementation using memcached
• Added a bundle that provides a frontend of the system using HTTP and a Servlet
• Devised a way to store some metadata on the cache
• Done some code cleanup and refactoring.

As usual, you can download the code here. Thanks!

A fundamental problem that this technology solves is being able to load an OSGi environment on a servlet server. That is a relatively costly operation that needs to be done only once and be persistent on the server in between client requests. After that point, state is maintained and bundles can be deployed and managed as needed. Creating, loading and destroying the environment for each request would just be unacceptable. One interesting functionality is then being able to serve client requests, specially HTTP requests, uploads, provide REST interfaces, etc.

Eclipse provides a number of projects to load the environment, register servlets, handle http requests, etc. Of particular interest is the ‘org.eclipse.equinox.servletbridge’ project, which initally starts the framework, loads the appropriate framework bundles, etc.

Looking at the code, you can start by checking out the main class, which has a number of interesting responsabilities:

/**
 * The BridgeServlet provides a means to bridge the servlet and
OSGi runtimes. This class has 3 main responsibilities:
 * 1) Control the lifecycle of the associated FrameworkLauncher
in line with its own lifecycle
 * 2) Provide a servlet "hook" that allows all servlet requests
to be delegated to the registered servlet
 * 3) Provide means to manually control the framework lifecycle
 */

I personally like classes that have a small set of responsabilities, but one can argue that the three are so related that they are expressions of the same one. The first responsability described is actually managing the lifecycle of the OSGi framework FrameworkLauncher class.

Basically, the Servlet Container will load the bridge web application, create an instance of ServletBridge and call its init method (defined by the HttpServlet interface which it implements). In that method the OSGi environment will be created and loaded by the following code:

framework.init(getServletConfig());
framework.deploy();
framework.start();
frameworkStarted = true;

The attribute ‘framework’ is an instance of the ‘FrameworkLauncher’ class, which encapsulates the OSGi environment management logic. The ‘init’ method pulls information from the servlet configuration (such as the name of the ‘WEB-INF’ folder) and calls an overloaded empty init method that could be exploited by specialised subclasses (more on this later).

After that, the framework is “deployed”. The method in question declares the following contract:

/**
* deploy is used to move the OSGi framework libraries into a location
   suitable for execution.
* The default behavior is to copy the contents of the webapp's
   WEB-INF/eclipse directory to the webapp's temp directory.
*/

And that’s right, the code is quite straightforward and goes along the lines of:

File servletTemp = (File) context.getAttribute("javax.servlet.context.tempdir");
platformDirectory = new File(servletTemp, "eclipse");
if (!platformDirectory.exists()) {
	platformDirectory.mkdirs();
}
File plugins = new File(platformDirectory, "plugins");
copyResource(resourceBase + "plugins/", plugins);

Which copies the bundles you want to deploy onto the OSGi environment onto the Servlet Container temporary folder (the ‘work’ folder in the case of Apache Tomcat).

After that the framework is started, reading .ini configuration options, command line switches, bundle list, run levels and so forth. We have not been able to get bundles started automatically unless we specify the bundle filename, complete with ‘.jar’ extension and all. One interesting option is the ability to fire up a standard OSGi console that uses the STDIN/OUT of the Servlet Container process.

Using the very same servlet bridge, there are a number of URLs that can be hit do control the framework, start, stop, undeploy, etc.

After that, one can register servlets as extension points or listen for services named “org.osgi.service.http.HttpService” and adding servlets with code going along these lines:

public Object addingService(ServiceReference reference) {
	HttpService httpService = (HttpService) context.getService(reference);
	httpService.registerServlet(url, servlet, null, null);
}

All is well and good. However, in working with the bridge code we have found a glitch in the startup code. Whenever the bridge app is started anew, it does the framework deployment and startup as expected but if there are any bundles that have any changes they will not be read by the environment unless the redeploy url is hit. This is fine in development environments but not on production, where you want to keep things  as smooth as possible.

Behold the power of OSS, we took a look at the code and submitted a bug entry complete with a working patch that fixes the problem. It is not pretty but it works (it has some code duplication).

Server-side OSGi is proving to be the place to be, or at least it is quite promising. Give it a try.