docs/src/docbkx/reference/bundles.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

  <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
    context. 
    </para>
        
    <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
    in:</para>

    <programlisting language="xml"><![CDATA[<bundle id="aBundle" symbolic-name="org.xyz.abundle"/>]]></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">
         <thead>
          <row>
           <entry>Action</entry>
           <entry><literal>UNINSTALLED</literal></entry>
           <entry><literal>INSTALLED/RESOLVED</literal></entry>
           <entry><literal>ACTIVE</literal></entry>
         </row>
        </thead>
        <tbody>
         <row>
            <entry><literal>START</literal></entry>
            <entry>installs and starts the bundle</entry>
	        <entry>starts the bundle</entry>
	        <entry>no action taken, bundle already started</entry>
    	</row>

    	<row>
	        <entry><literal>UPDATE</literal></entry>
	        <entry>installs the bundle and then updates it (`Bundle.update()`)</entry>
	        <entry>updates the bundle</entry>
	        <entry>updates the bundle</entry>
       </row>

       <row>
          <entry><literal>STOP</literal></entry>
	      <entry>no action taken</entry>
	      <entry>no action taken</entry>
	      <entry>bundle is stopped</entry>
      </row>

      <row>
        <entry><literal>UNINSTALL</literal></entry>
        <entry>no action taken</entry>
        <entry>bundle is uninstalled</entry>
        <entry>bundle is stopped and then uninstalled</entry>
      </row>
     </tbody>
     </tgroup>      
    </table>

    <para>For example:</para>

    <programlisting language="xml"><![CDATA[<!-- 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"/>]]></programlisting>

    <!-- 
    <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:
    </para>
   	
   	<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"/>
       	 
         <thead>
           <row>
             <entry>Name</entry>
             <entry spanname="values">Values</entry>
             <entry>Description</entry>
           </row>
         </thead>
         <tbody>
           <row>
             <entry>symbolic-name</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>
           </row>
           <row>
             <entry>location</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>
           </row>
           <row>
             <entry>action</entry>
             
             <entry>start</entry>
             <entry>stop</entry> 
             <entry>install</entry> 
             <entry>uninstall</entry>
             <entry>update</entry>
             
             <entry>Lifecyle action to drive on the bundle. The action is executed at startup.</entry>
           </row>
           <row>
             <entry>destroy-action</entry>
             <entry spanname="values">(same as action)</entry>
             <entry>Lifecyle action to drive on the bundle. The action is executed at shutdown.</entry>
           </row>
         </tbody>
       </tgroup>
    </table>

    <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>
  </chapter>