OSGi and Start Levels

June 10, 2009 | 4 min Read

I’ve been working with OSGi for quite awhile and have recently been helping someone fight some start level issues. The problem turned out to be a misunderstanding of how start levels work in OSGi and its inspired me to write a little bit about how start levels work so others don’t repeat the same mistakes.

Let’s start with the basics first.

A start level is simply a non-negative integer value. The Framework has an ‘active start level’ that is used to decide which bundles can be started. Bundles themselves have an associated ‘bundle start level’ which is used to determine when a bundle is started. The bundles at a given start level will all have their start method completely executed before any bundles at a higher level are started. When booted, the Framework monotonically goes through each start level and starts relevant bundles (all the way until the active start level is met).

It’s also important to treat start levels as a management issue. In one system, a bundle could be running at start level 1 and in another system it could be at start level 42. This all depends on who is in control of deploying your bundle… so this means you shouldn’t worry about start levels at development time!

In the end, start levels are there to simply determine the start order of bundles.

Here are a few tidbits about start levels:

  • Start order within the start level is indeterminate!
  • The active start level is controlled by the ‘osgi.startLevel’ property and within Equinox, it defaults to a value of 6
  • A bundle start level of 0 is associated with the system bundle and can’t be changed

To illustrate things a bit better, let’s use a sample config from Equinox:

osgi.bundles=
 org.eclipse.equinox.common@2:start,
 org.eclipse.core.runtime@start 

osgi.startLevel=10
osgi.bundles.defaultStartLevel=4

The following will be true about this particular configuration:

  • org.eclipse.equinox.common will start at startlevel 2 (via @2:start)
  • org.eclipse.core.runtime will start at startlevel 4 (via default value)
  • the framework startlevel will get set to 10

In Eclipse land, we’ve always had an interesting dance with start levels. For the longest time, we hid the whole concept from people. For example, the old Eclipse Application launch configuration looked like this:

In Eclipse 3.5, we updated the launch configuration to include information about start levels:

The main reason this was done was due to the introduction of OSGi Declarative Services (DS) in the Eclipse SDK. When working with OSGi services, having the ability to start bundles is important due to the life cycle of a OSGi service. An OSGi service is ONLY available when the bundle is in the ACTIVE state. If you were writing Eclipse-based applications and using OSGi services… not having access to set start level related information was painful. During the Eclipse 3.5 development cycle, we realized this and now have made it easier to tweak start level information. Besides launch configurations, here are some the other areas to set start level information that is more useful at deployment time:

p2 Touchpoint Actions (p2.inf)

You can place a p2.inf (in the root of a feature or within the META-INF directory of a bundle) file with touchpoint instructions to set the start level of a bundle (amongst various other things). An example p2.inf file may look like this if you wanted your bundle to be started:

instructions.configure =
       setStartLevel(startLevel:4);
       markStarted(started: true);

Product Definitions

Another way is to use product definitions. In Eclipse 3.5, we added support so you can specify start level information via the Configuration page:

This information can be used to generate proper p2 metadata so your bundles will have the right start level information when you go to deploy your product.

Ok, I think that’s enough of me talking about start levels. On the whole, when working with start levels, never depend on start order. Think about start levels as a management issue, not a development time issue.

Hope this helps! helps!