## 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

Action | `UNINSTALLED` | `INSTALLED/RESOLVED` | `ACTIVE`
--- | --- | --- | ---
`START` | installs and starts the bundle | starts the bundle | no action taken, bundle already started
`UPDATE` | installs the bundle and then updates it (`Bundle.update()`) | updates the bundle | updates the bundle
`STOP` | no action taken | no action taken | bundle is stopped
`UNINSTALL` | no action taken | bundle is uninstalled | bundle 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

Name | Values | Description
--- | --- | ---
symbolic-name | any valid symbolic-name String | The symbolic name of the bundle object. Normally used when interacting with an already installed bundle.
location | String that can be converted into an `URL` | Location used to install, update or/and identify a bundle.
action | start | stop | install | uninstall | update | Lifecyle 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.

Prev | Home | Next
Chapter 9. The Service Registry | Sponsored by SpringSource | Chapter 11. Compendium Services