Tuesday, November 3, 2009

OSGi Framework Launch

In this post I am going to look at the problems involved when you need to launch an OSGi Framework independent of the actual Framework implementation. There will be coverage of
  • Framework Launch API
  • OSGi Bootstrap abstraction
The Framework Launch API

Starting with Version 1.5 of the Framework API, which is part of the core r4v42 specification, OSGi comes with the ability to launch an OSGi Framework in an implementation agnostic manner. For this, clients interact with the classes in package org.osgi.framework.launch like this

// Load the framework factory
FrameworkFactory factory = loadFrameworkFactory();

// Load the framework configuration
Map config = loadFrameworkConfig();

// Create a new instance of the framework
Framework framework = factory.newFramework(config);
   // Start the framework

   // do stuff
   // Stop the framework

   // Wait for the framework to stop completely

As you can see, this API is fairly low level. The client provides code that loads the FrameworkFactory, as well as code that obtains the Framework configuration somehow. At this level, there is no API or standard config that defines initial bundle provisioning.

OSGi Bootstrap abstraction

If you are running on JDK-1.6 there is a ServiceLoader available that can be used to load the FrameworkFactory like this

// Load the framwork factory
ServiceLoader loader = ServiceLoader.load(FrameworkFactory.class);
FrameworkFactory factory = loader.iterator().next();

// Create a new instance of the framework
Framework framework = factory.newFramework(null);

Since this API might not be available in every environment, JBoss OSGi also provides a ServiceLoader as part of its Service Provider Interface (SPI). Conceptually very similar, here is how you would use this API

// Load the framework factoryFramework
Factory factory = ServiceLoader.load(FrameworkFactory.class);

// Create a new instance of the framework
Framework framework = factory.newFramework(null);

Both variants of the service loader provide you with an instance of FrameworkFactory from which you can now use to create a new Framework instance. The null parameter causes the Framework to use it's default configuration.

The JBoss OSGi SPI supports a Framework bootstrap process based on unified configuration files. In its most simple form the usage of this API would look like this

// Get the configured bootstrap provider
OSGiBootstrapProvider bootProvider = OSGiBootstrap.getBootstrapProvider();

// Get the configured framework from the boot provider
Framework framework = bootProvider.getFramework();

An OSGiBootstrapProvider is an abstraction of a provider that can somehow bootstrap an OSGi Framework. A concrete implementation and also the default that is used if no other provider is configured is the PropertiesBootstrapProvider. As the name suggests, this bootstrap provider can be configured using a plain java properties file. The default location of this file is a resource called jboss-osgi-framework.properties loadable from the bootstrap classpath.

An example of such a properties file is shown below

# Extra server specific properties

# Properties to configure the Framework

# Hot Deployement

# Bundles that need to be installed with the Framework automatically

# Bundles that need to be started automatically 
file://${osgi.home}/server/minimal/deploy/org.apache.felix.log.jar \
file://${osgi.home}/server/minimal/deploy/jboss-osgi-common.jar \

Noteworthy, are perhaps the properties that can be used for initial framework provisioning
and the extension point that allows to recursively split the properties over multiple files
All other properties are simply passed on the FrameworkFactory.newFramework(Map config) method.

We looked at the basic OSGi Framework launch API and have seen how to externalize Framework configuration to property files. Other bootstrap providers could work of your favourite XML dialect. For the Apache Felix JBossAS integration we use a jboss-beans.xml configuration.

With my next post I am going to start a series of Enterprise OSGi topics. There should be coverage of JTA, JMX, JNDI, WebApp and perhaps others.

May this be useful