OSGi system and bundle start levels

OSGi has a concept of start levels. This is fairly well documented in the r4 core spec but there seems to be some confusion around how they work so here is a quick summary for my own reference (and in case it helps anyone else).

Start Levels determine the start order of bundles (not services). There are two types of start levels in an OSGi system. The system start level and the bundle start level (set for each bundle). The default start level of an OSGi system will be 1 (this is called the beginning start level and can be configured) and the bundles installed in an OSGi system will use the default start level when they are installed unless this is changed manually. An OSGi system has a current level (called the active start level) which determines the bundles which are allowed to be started. If a bundle has a start level higher than the active start level it will not start when the OSGi system starts up and it will not start if given a manual start command. If the active start level increases to be greater than or equal to the level of the bundle it will be started. Likewise, if the active start level changes to be below the level of a bundle, it will be shutdown.

Here are a few points about start levels that were not completely obvious to me:

• The bundles at a given start level will all have their start() method completely executed before any bundles at a higher level are started. Start order within the start level is indeterminate.
• When the active start level is changed, the system will move in increments of 1 until the desired level is reached. For example, from 5 to 10 means the system will do 6, 7, 8, 9, and finally 10.
  
• If the start level is changed many times rapidly it must completely reach all requested levels in sequence. The system will not give up on level 3 if it was requested and has not been reached yet just because level 15 was requested while it was moving to level 3.
  
• The system bundle is always located at start level 0. This cannot be changed.
• Start level should NOT be used as a way to control service startup order. This is considered a programming error in OSGi as service start orders are not guaranteed and services may come and go at will.
• Start level can be used as a way to reduce load on a system by setting non-critical parts as high start levels. This allows the level to be reduced in order to reduce the load and shutdown non-critical services and bundles.
• OSGi has a compatibility mode which forces all bundles to use start level 1 (this is a good way to check to make sure you are not depending on the start levels as a way to ensure service start order).

NOTE: If you are working with apache felix 1.6.0 there is a confusing error in the default config file. The system start level property is commented out as org.osgi.framework.startlevel but the correct value is org.osgi.framework.startlevel.beginning.

The OSGi spec (section 8, page 2o3) has more details about start levels.