OSGi life cycle

Instant OSGi Starter

January 2013


The essential guide to modular development with OSGi

(For more resources related to this topic, see here.)

OSGi applications are described as living entities; by this we mean that these applications appear to evolve as the lifecycles of their constituent bundles are lived. The lifecycle layer facilitates this functionality.

OSGi bundles are dynamically installed, resolved, started, updated, stopped, and uninstalled. The framework enforces the transitions between states, one cannot directly install a bundle and jump to an Active state without first passing through the resolved and starting states. The transitions between each state are illustrated in the following figure:


Bundles came into existence in an OSGi framework in the installed state. A bundle in this state cannot be immediately started, as the preceding diagram depicts that there is no direct transition from the installed state to the starting state. An installed bundle is also not active. There are three possible transitions: the bundle may become resolved, uninstalled, or refreshed.

Apache Karaf command

To install a bundle in Karaf, issue the osgi:install (bundle:install on Karaf 3.x) command, as follows: karaf@root> osgi:install URLs

Having a bundle installed to the OSGi framework does not mean it is ready to be used; next we must resolve its dependencies.


Entering the resolved state requires the framework to ensure that all the dependencies of a bundle have been met. Upon having its dependencies ensured, the bundle is now a candidate to be transitioned to the starting state. A resolved bundle may be refreshed, transitioning the bundle back to the installed state. A resolved bundle may also be transitioned to the uninstalled state. A resolved bundle is not active; however, it is ready to be activated.

Apache Karaf command

To resolve an installed bundle in Karaf, issue the osgi:resolve (bundle:resolve on Karaf 3.x) command, as follows: karaf@root> osgi:resolve BundleID


A resolved bundle may be started. The starting state is transitory; the framework is initializing the resolved bundle into a running active state. In fact, the transition from the starting to active state is implicit.

Apache Karaf command

To start a resolved bundle in Karaf, issue the osgi:start (bundle:start on Karaf 3.x) command, as follows: karaf@root> osgi:start BundleID


The bundle is fully resolved, providing and consuming services in the OSGi environment. To perform any more transitions on an active bundle, it must first be stopped.


Bundle updates occur when the framework is instructed to re-evaluate a bundle's dependencies; this action is synonymous with refreshing a bundle. When this action occurs, all of the wiring to and from the bundle is broken, so care must be taken before refreshing to avoid starting a bundle storm (one bundle refreshing causes a domino effect of other bundles refreshing).

Apache Karaf command

To update a bundle in Karaf, issue the osgi:update (bundle:update on Karaf 3.x) command, as follows: karaf@root> osgi:update BundleID [location]

The location option allows you to update the bundle via its predefined updated location or to specify a new location to find bundle updates.


Stopping a bundle transitions it from the active to the resolved state. The bundle can be restarted while it remains in the resolved state.

Apache Karaf command

To stop an active bundle in Karaf, issue the osgi:stop (bundle:stop on Karaf 3.x) command, as follows: karaf@root> osgi:stop BundleID


Uninstalling a bundle transitions an installed or resolved bundle out of the OSGi environment; however, the bundle is not removed from the environment! Why is this? While the bundle is no longer available for use, references to the bundle may still exist and used for introspection.

To help leverage these states in your bundles, the OSGi specification provides a hook into your bundle state via the Activator interface.

Apache Karaf command

To uninstall a bundle in Karaf, issue the osgi:uninstall (bundle:uninstall on Karaf 3.x) command, as follows: karaf@root> osgi:uninstall BundleID


bundle may optionally declare an Activator class implementing the org.osgi.framework.BundleActivator interface. This class must be referenced in the bundle manifest file via the BundleActivator header. Implementing the activator allows the bundle developer to specify actions to be performed upon starting or stopping a bundle. Generally, such operations include gaining access to or freeing resources, and registering and unregistering services.

The entry in manifest.mf will appear as follows:

Bundle-Activator: com.packt.osgi.starter.sample.Activator

When building with maven-bundle-plugin, the following configuration instruction is added:

<Bundle-Activator> com.packt.osgi.starter.sample.Activator </Bundle-Activator>

The process can be seen in the following screenshot:


This article covered the various states involved in the OSGi lifecycle. We also learnt about the transitions from one state to another.

Resources for Article :

Further resources on this subject:

Books to Consider

comments powered by Disqus