docs/src/docbkx/appendix/appendix-tips.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">

<appendix id="appendix-tips">
    <title>Useful OSGi tips</title>
	
	<appendixinfo>This section describes several useful tips when running Gemini Blueprint in OSGi. Note that this is not a FAQ - please see the Gemini Blueprint 
	<ulink url="http://www.eclipse.org/gemini/blueprint">home page</ulink> for one.</appendixinfo>
	
	<section id="appendix-tips:fragments">
		<title>OSGi Fragments</title>
		<sidebar>
			<title>Check the target OSGi platform fragment support</title>
			<para>Before using fragments, make sure the target OSGi environment supports them (and to what degree). Out of the OSGi platforms on
			which Gemini Blueprint is tested upon, at the time of this writing, Apache Felix does not support fragments (it simply ignores them).</para>
		</sidebar>
		
		<para>Part of the OSGi R4 release, <emphasis>fragments</emphasis> are a very useful and powerful feature. A fragment is 
		<quote>a bundle that is <emphasis>attached</emphasis> to a <emphasis>host bundle</emphasis></quote>, adding content to the target bundle. 
		A fragment cannot have its own class loader nor a bundle activator and cannot override the information already present in the host. 
		In short, through fragments, bundles can be extender with resources, classes and even manifest entries. To quote the spec again, 
		a <quote>...key use case for fragments is providing translation files for different locales. This allows the translation files to be 
		treated and shipped independently from the main application bundle.</quote></para>
		
		<note>For a full description on fragments, please see the OSGi specification, section 3.14.</note>
		
		<para>In Gemini Blueprint, fragments are useful for configuring various components such as the extenders. To do that, simply bundle the resources as you
		normally would and add an extra entry to the bundle manifest:</para>
		
		<programlisting><![CDATA[Fragment-Host: <host bundle symbolic name>]]></programlisting>
		
		<para>This line indicates that the containing bundle is a fragment and that it should be attached to the host specified by a symbolic name. The fragment
		and host bundle symbolic name should be different. For example, to attach a fragment (with extra configuration) the Gemini Blueprint extender, one could use
		the following manifest:</para>
		 
		<programlistingco>
	    <areaspec>
	   	  <area id="appendix-tips:fragments.example.mv" coords="1"/>
          <area id="appendix-tips:fragments.example.bmv" coords="2"/>
          <area id="appendix-tips:fragments.example.fh" coords="3"/>
          <area id="appendix-tips:fragments.example.bsn" coords="4"/>
          <area id="appendix-tips:fragments.example.bn" coords="5"/>
          <area id="appendix-tips:fragments.example.bd" coords="6"/>
        </areaspec>
        
		<programlisting><![CDATA[Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Fragment-Host: org.eclipse.gemini.blueprint.extender
Bundle-SymbolicName: org.mydomain.project.fragment
Bundle-Name: my-fragment
Bundle-Description: Fragment attached to Gemini Blueprint extender
]]></programlisting>

		<calloutlist>
         <callout arearefs="appendix-tips:fragments.example.mv">
            <para>Manifest version.</para>
         </callout>
         <callout arearefs="appendix-tips:fragments.example.bmv">
            <para>OSGi bundle version. A value of <literal>1</literal> (which is also the default) indicates an OSGi Release 3 bundle so it's best to 
            specify <literal>2</literal> to indicate an OSGi Release 4 bundle.</para>
         </callout>
         <callout arearefs="appendix-tips:fragments.example.fh">
         	<para>The symbolic name of the bundle to which this fragment should be attached to. In this case, the value 
         	<literal>org.eclipse.gemini.blueprint.extender</literal> points to the <literal>spring-osgi-extender.jar</literal>.
         	<literal>Fragment-Host</literal> is the <emphasis>key</emphasis> entry which tells the OSGi platform that the containing bundle is a of a 
         	special kind - it's a fragment.</para>
         </callout>
         <callout arearefs="appendix-tips:fragments.example.bsn">
         	<para>The fragment symbolic name.</para>
         </callout>
         <callout arearefs="appendix-tips:fragments.example.bn">
         	<para>The bundle name - an optional yet useful header.</para>
         </callout>
         <callout arearefs="appendix-tips:fragments.example.bd">
         	<para>The bundle description - just like the name, this header is useful for humans not for the OSGi platform itself. However, it is
         	recommended that you define it to help identify the bundle purpose.</para>
         </callout>
         
        </calloutlist>
		</programlistingco>
	
		<note>The Manifest entries order does not matter, but they case sensitive.</note>
		
		<para>When multiple bundles with the same symbolic names are present, one can add the bundle version to make sure the proper wiring is done:</para>
		
		<programlisting><![CDATA[Fragment-Host: org.eclipse.gemini.blueprint.extender;bundle-version=1.1.0]]></programlisting>
		
		<para>The default value for <literal>bundle-version</literal> (when it's not specified) is <literal>[0.0.0,&#8734;)</literal></para>
		
	</section>
	
</appendix>