| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>Chapter 10. 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 II. Reference Documentation"><link rel="prev" href="service-registry.html" title="Chapter 9. The Service Registry"><link rel="next" href="compendium.html" title="Chapter 11. 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 10. 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"><<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>/></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 10.1. <bundle> <code class="literal">action</code> values</b></p><div class="table-contents"><table summary="<bundle> 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"><<span class="hl-comment">!-- ensure this bundle is installed and started --</span>> |
| <<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>/></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 10.2. <bundle> attributes</b></p><div class="table-contents"><table summary="<bundle> 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> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="compendium.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 9. The Service Registry </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"> Chapter 11. Compendium Services</td></tr></table></div></body></html> |
