OSGi and Start Levels

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:

lc1 300x159 OSGi and Start Levels

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

lc2 300x145 OSGi and 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:

startlevels 300x205 OSGi and Start Levels

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!

You may also like...

Share this Post

Twitter20
Google+0
LinkedIn
Facebook

Tags

8 Responses to “OSGi and Start Levels”

  1. ekke says:

    chris,
    a great article – it will surely help people to understand start level better.
    for me the first rule about using start levels is:
    “Try to avoid setting of start-levels and let OSGI framework decide when to start a bundle”
    of course there are exceptions ;-)
    * Logging: if you want to catch all log events from different log frameworks / log services then perhaps the bundle managing this should be started early – otherwise some log events could fall into a black hole
    * if DS need ConfigurationAdminService then the ConfigurationAdmin bundle must be started earlier then DS (bugzilla 276003)
    ekke

  2. Jawher says:

    Hi,
    This feature will come in real handy for server side development, thanks :)

    @ekke: and also for any frameworks using the extender pattern, like Spring DM for example.

    cheers

  3. Wim Jongman says:

    Hi Chris,

    Thanks for the article. I have a question about the dynamics of DS. In the 3.5M6 New and Noteworthy there is this information:

    The Eclipse rich client platform now includes an implementation of OSGi declarative services (DS). This allows a lazy-starting plug-in to make OSGi services available to other plug-ins before it has been started.

    In your blog you state:

    An OSGi service is ONLY available when the bundle is in the ACTIVE state

    Can you elaborate on that a bit more?

    Thanks,

    Wim Jongman

  4. Sure Wim. In OSGi, services are only available when a bundle is started (in the ACTIVE state).

    In the latest DS specification (1.1), DS can look at bundles in the STARTING state (Bundle-ActivationPolicy: Lazy). So effectively, to take advantage of DS and lazy bundles, you just need to mark your bundles to be lazy and DS can start them when needed. In the past, DS would only work if the services were available via the ACTIVE state.

    Does this make sense?

  5. Funny, just last night I noticed the start levels in the 3.5 release. Very nice. I don’t know much about Linux Kernel start levels, but it seems similar.

    Something that seems obvious, but merits asking: start levels and OSGI dependencies can totally screw up start levels if you are not careful, yes?

  6. It’s similar in concept to kernel start levels.

    In response to “start levels and OSGI dependencies can totally screw up start levels if you are not careful, yes?”

    The short answer is that start levels have no impact on bundle resolution.

    In the end, it shouldn’t matter. Start levels are really a configuration issue. Your bundle should work whether any services are available or not… this is what we call coding for dynamics.

    However, you have inspired me to do some more investigation about start levels. I am not 100% sure what would happen if you had three bundles A,B,C and the active start level was 20. B depended on C. C had a start level of 100 and was lazy start.

  7. Great article,

    Cant wait for the new Eclipse to be finally released with P2.

    Graham

  8. Nice Article with important content,

    Yes, we in WSO2 also believe that a bundle should never depend on start levels. A bundle should be able to handle the dynamic behavior of OSGi services.

    In order to solve this problem, we have used OSGi Declarative Services (DS) extensively. That worked very well for us.

    Sameera

8 responses so far

Written by . Published in Categories: Planet Eclipse