blob: 2bd50346044aef84b1a144418ed67a91164c4d30 [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
<chapter id="bundles">
<title>Working With Bundles</title>
<para>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 <literal>bundle</literal> element offers a very
easy way of executing actions on bundles based on the lifecycle of the application
<para>The <literal>bundle</literal> element defines a bean of type
<interfacename>org.osgi.framework.Bundle</interfacename>. 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
<literal>symbolic-name</literal> of the bundle you are interested
<programlisting language="xml"><![CDATA[<bundle id="aBundle" symbolic-name=""/>]]></programlisting>
<para>The bean <literal>aBundle</literal> can now be injected into any property of
type <interfacename>Bundle</interfacename>.</para>
<para>If the needed bundle is not installed, one can use <literal>location</literal> attribute
to indicate install or/and the <literal>action</literal>/<literal>destroy-action</literal> attributes
provide declarative control over the bundle's lifecycle. The <literal>location</literal> attribute is
used to specify a URL where the bundle jar file artifact can be found. The
<literal>action</literal> attribute specifies the lifecycle operation to
be invoked on the bundle object. The supported action values are
<literal>install</literal>, <literal>start</literal>,
<literal>update</literal>, <literal>stop</literal>, and
<literal>uninstall</literal>. These actions have the same semantics as the
operations of the corresponding names defined on the
<literal>Bundle</literal> interface (see the OSGi Service Platform Core
Specification), with the exception that pre-conditions are weakened to
allow for example a <emphasis>start</emphasis> action to be specified against a bundle that
is not currently installed (it will be installed first).</para>
<para>The following table shows how actions are interpreted for the given
Bundle states:</para>
<table id ="bundle-factory-actions" border="1" cellspacing="5" pgwide="1">
<title><![CDATA[<bundle>]]> <literal>action</literal> values</title>
<tgroup cols="4">
<entry>installs and starts the bundle</entry>
<entry>starts the bundle</entry>
<entry>no action taken, bundle already started</entry>
<entry>installs the bundle and then updates it (`Bundle.update()`)</entry>
<entry>updates the bundle</entry>
<entry>updates the bundle</entry>
<entry>no action taken</entry>
<entry>no action taken</entry>
<entry>bundle is stopped</entry>
<entry>no action taken</entry>
<entry>bundle is uninstalled</entry>
<entry>bundle is stopped and then uninstalled</entry>
<para>For example:</para>
<programlisting language="xml"><![CDATA[<!-- ensure this bundle is installed and started -->
<bundle id="aBundle" symbolic-name=""
<para>The 'start-level' attribute can be used to set the start level of
the bundle.</para>
<para>The following table lists the <literal>bundle</literal> element attributes names,
possible values and a short description for each of them:
<table id="bundle-options" pgwide="1">
<title><![CDATA[<bundle> attributes]]></title>
<tgroup cols="7">
<colspec colname="c1"/>
<colspec colname="c2" align="center"/>
<colspec colname="c3" align="center"/>
<colspec colname="c4" align="center"/>
<colspec colname="c5" align="center"/>
<colspec colname="c6" align="center"/>
<colspec colname="c7" align="justify"/>
<spanspec spanname="values" namest="c2" nameend="c6" align="justify"/>
<entry spanname="values">Values</entry>
<entry spanname="values">any valid symbolic-name String</entry>
<entry>The symbolic name of the bundle object. Normally used when interacting with an already
installed bundle.</entry>
<entry spanname="values">String that can be converted into an <literal>URL</literal></entry>
<entry>Location used to install, update or/and identify a bundle.</entry>
<entry>Lifecyle action to drive on the bundle. The action is executed at startup.</entry>
<entry spanname="values">(same as action)</entry>
<entry>Lifecyle action to drive on the bundle. The action is executed at shutdown.</entry>
<para>The samples that ship with the Gemini Blueprint project
include further support for a <literal>virtual-bundle</literal> element
that can be used to create and install OSGi bundles on the fly from
existing artifacts.</para>