Chapter 10. Working With Bundles

Gemini Blueprint offers a dedicated schema element for interacting with existing bundles or for installing new ones. While it is not intended to be used as a replacement for proper OSGi services, the bundle element offers a very easy way of executing actions on bundles based on the lifecycle of the application context.

The bundle element defines a bean of type org.osgi.framework.Bundle. It provides a simple way to work directly with bundles, including driving their lifecycle. In the simplest case all you need to do is specify the symbolic-name of the bundle you are interested in:

<bundle id="aBundle" symbolic-name="org.xyz.abundle"/>

The bean aBundle can now be injected into any property of type Bundle.

If the needed bundle is not installed, one can use location attribute to indicate install or/and the action/destroy-action attributes provide declarative control over the bundle's lifecycle. The location attribute is used to specify a URL where the bundle jar file artifact can be found. The action attribute specifies the lifecycle operation to be invoked on the bundle object. The supported action values are install, start, update, stop, and uninstall. These actions have the same semantics as the operations of the corresponding names defined on the Bundle interface (see the OSGi Service Platform Core Specification), with the exception that pre-conditions are weakened to allow for example a start action to be specified against a bundle that is not currently installed (it will be installed first).

The following table shows how actions are interpreted for the given Bundle states:

Table 10.1. <bundle> action values

ActionUNINSTALLEDINSTALLED/RESOLVEDACTIVE
STARTinstalls and starts the bundlestarts the bundleno action taken, bundle already started
UPDATEinstalls the bundle and then updates it (`Bundle.update()`)updates the bundleupdates the bundle
STOPno action takenno action takenbundle is stopped
UNINSTALLno action takenbundle is uninstalledbundle is stopped and then uninstalled

For example:

<!-- ensure this bundle is installed and started -->
<bundle id="aBundle" symbolic-name="org.xyz.abundle"
   location="http://www.xyz.com/bundles/org.xyz.abundle.jar"
   action="start"/>

The following table lists the bundle element attributes names, possible values and a short description for each of them:

Table 10.2. <bundle> attributes

NameValuesDescription
symbolic-nameany valid symbolic-name StringThe symbolic name of the bundle object. Normally used when interacting with an already installed bundle.
locationString that can be converted into an URLLocation used to install, update or/and identify a bundle.
actionstartstopinstalluninstallupdateLifecyle action to drive on the bundle. The action is executed at startup.
destroy-action(same as action)Lifecyle action to drive on the bundle. The action is executed at shutdown.

The samples that ship with the Gemini Blueprint project include further support for a virtual-bundle element that can be used to create and install OSGi bundles on the fly from existing artifacts.