<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>Chapter&nbsp;10.&nbsp;Working With Bundles</title><link rel="stylesheet" href="css/html.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"><link rel="start" href="index.html" title="Eclipse Gemini Blueprint Reference Guide"><link rel="up" href="reference.html" title="Part&nbsp;II.&nbsp;Reference Documentation"><link rel="prev" href="service-registry.html" title="Chapter&nbsp;9.&nbsp;The Service Registry"><link rel="next" href="compendium.html" title="Chapter&nbsp;11.&nbsp;Compendium Services"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="bundles"></a>Chapter&nbsp;10.&nbsp;Working With Bundles</h2></div></div></div><p>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 <code class="literal">bundle</code> element offers a very
    easy way of executing actions on bundles based on the lifecycle of the application
    context. 
    </p><p>The <code class="literal">bundle</code> element defines a bean of type
    <code class="interfacename">org.osgi.framework.Bundle</code>. 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
    <code class="literal">symbolic-name</code> of the bundle you are interested
    in:</p><pre class="programlisting">&lt;<span class="hl-tag">bundle</span> <span class="hl-attribute">id</span>=<span class="hl-value">"aBundle"</span> <span class="hl-attribute">symbolic-name</span>=<span class="hl-value">"org.xyz.abundle"</span>/&gt;</pre><p>The bean <code class="literal">aBundle</code> can now be injected into any property of 
    type <code class="interfacename">Bundle</code>.</p><p>If the needed bundle is not installed, one can use <code class="literal">location</code> attribute
    to indicate install or/and the <code class="literal">action</code>/<code class="literal">destroy-action</code> attributes
    provide declarative control over the bundle's lifecycle. The <code class="literal">location</code> attribute is 
    used to specify a URL where the bundle jar file artifact can be found. The
    <code class="literal">action</code> attribute specifies the lifecycle operation to
    be invoked on the bundle object. The supported action values are
    <code class="literal">install</code>, <code class="literal">start</code>,
    <code class="literal">update</code>, <code class="literal">stop</code>, and
    <code class="literal">uninstall</code>. These actions have the same semantics as the
    operations of the corresponding names defined on the
    <code class="literal">Bundle</code> interface (see the OSGi Service Platform Core
    Specification), with the exception that pre-conditions are weakened to
    allow for example a <span class="emphasis"><em>start</em></span> action to be specified against a bundle that
    is not currently installed (it will be installed first).</p><p>The following table shows how actions are interpreted for the given
    Bundle states:</p><div class="table"><a name="bundle-factory-actions"></a><p class="title"><b>Table&nbsp;10.1.&nbsp;&lt;bundle&gt; <code class="literal">action</code> values</b></p><div class="table-contents"><table summary="<bundle&gt; action values" width="100%" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Action</th><th><code class="literal">UNINSTALLED</code></th><th><code class="literal">INSTALLED/RESOLVED</code></th><th><code class="literal">ACTIVE</code></th></tr></thead><tbody><tr><td><code class="literal">START</code></td><td>installs and starts the bundle</td><td>starts the bundle</td><td>no action taken, bundle already started</td></tr><tr><td><code class="literal">UPDATE</code></td><td>installs the bundle and then updates it (`Bundle.update()`)</td><td>updates the bundle</td><td>updates the bundle</td></tr><tr><td><code class="literal">STOP</code></td><td>no action taken</td><td>no action taken</td><td>bundle is stopped</td></tr><tr><td><code class="literal">UNINSTALL</code></td><td>no action taken</td><td>bundle is uninstalled</td><td>bundle is stopped and then uninstalled</td></tr></tbody></table></div></div><br class="table-break"><p>For example:</p><pre class="programlisting">&lt;<span class="hl-comment">!-- ensure this bundle is installed and started --</span>&gt;
&lt;<span class="hl-tag">bundle</span> <span class="hl-attribute">id</span>=<span class="hl-value">"aBundle"</span> <span class="hl-attribute">symbolic-name</span>=<span class="hl-value">"org.xyz.abundle"</span>
   <span class="hl-attribute">location</span>=<span class="hl-value">"http://www.xyz.com/bundles/org.xyz.abundle.jar"</span>
   <span class="hl-attribute">action</span>=<span class="hl-value">"start"</span>/&gt;</pre><p>The following table lists the <code class="literal">bundle</code> element attributes names, 
    possible values and a short description for each of them:
    </p><div class="table"><a name="bundle-options"></a><p class="title"><b>Table&nbsp;10.2.&nbsp;&lt;bundle&gt; attributes</b></p><div class="table-contents"><table summary="<bundle&gt; attributes" width="100%" border="1"><colgroup><col><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="justify"></colgroup><thead><tr><th>Name</th><th colspan="5" align="justify">Values</th><th align="justify">Description</th></tr></thead><tbody><tr><td>symbolic-name</td><td colspan="5" align="justify">any valid symbolic-name String</td><td align="justify">The symbolic name of the bundle object. Normally used when interacting with an already 
             installed bundle.</td></tr><tr><td>location</td><td colspan="5" align="justify">String that can be converted into an <code class="literal">URL</code></td><td align="justify">Location used to install, update or/and identify a bundle.</td></tr><tr><td>action</td><td align="center">start</td><td align="center">stop</td><td align="center">install</td><td align="center">uninstall</td><td align="center">update</td><td align="justify">Lifecyle action to drive on the bundle. The action is executed at startup.</td></tr><tr><td>destroy-action</td><td colspan="5" align="justify">(same as action)</td><td align="justify">Lifecyle action to drive on the bundle. The action is executed at shutdown.</td></tr></tbody></table></div></div><br class="table-break"><p>The samples that ship with the Gemini Blueprint project
    include further support for a <code class="literal">virtual-bundle</code> element
    that can be used to create and install OSGi bundles on the fly from
    existing artifacts.</p></div><div xmlns:fo="http://www.w3.org/1999/XSL/Format" class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="service-registry.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="compendium.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;9.&nbsp;The Service Registry&nbsp;</td><td width="20%" align="center"><span style="color:white;font-size:90%;"><a href="http://www.SpringSource.com/" title="SpringSource - Spring from the Source">Sponsored by SpringSource
                                        </a></span></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;11.&nbsp;Compendium Services</td></tr></table></div></body></html>