<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>Appendix&nbsp;C.&nbsp;Useful OSGi tips</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="appendixes.html" title="Part&nbsp;IV.&nbsp;Appendixes"><link rel="prev" href="appendix-pde-integration.html" title="Appendix&nbsp;B.&nbsp;Eclipse Plug-in Development integration"><link rel="next" href="appendix-roadmap.html" title="Appendix&nbsp;D.&nbsp;Roadmap"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="appendix-tips"></a>Appendix&nbsp;C.&nbsp;Useful OSGi tips</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="appendix-tips:fragments"></a>C.1.&nbsp;OSGi Fragments</h2></div></div></div><div class="sidebar"><p class="title"><b>Check the target OSGi platform fragment support</b></p><p>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).</p></div><p>Part of the OSGi R4 release, <span class="emphasis"><em>fragments</em></span> are a very useful and powerful feature. A fragment is 
		&#8220;<span class="quote">a bundle that is <span class="emphasis"><em>attached</em></span> to a <span class="emphasis"><em>host bundle</em></span></span>&#8221;, 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 &#8220;<span class="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.</span>&#8221;</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/admons/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">For a full description on fragments, please see the OSGi specification, section 3.14.</td></tr></table></div><p>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:</p><pre class="programlisting">Fragment-Host: &lt;host bundle symbolic name&gt;</pre><p>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:</p><div class="programlistingco"><pre class="programlisting">Manifest-Version: 1.0                                                                    <span class="co"><img src="images/callouts/1.png" alt="(1)"></span>
Bundle-ManifestVersion: 2                                                                <span class="co"><img src="images/callouts/2.png" alt="(2)"></span>
Fragment-Host: org.eclipse.gemini.blueprint.extender                                     <span class="co"><img src="images/callouts/3.png" alt="(3)"></span>
Bundle-SymbolicName: org.mydomain.project.fragment                                       <span class="co"><img src="images/callouts/4.png" alt="(4)"></span>
Bundle-Name: my-fragment                                                                 <span class="co"><img src="images/callouts/5.png" alt="(5)"></span>
Bundle-Description: Fragment attached to Gemini Blueprint extender                       <span class="co"><img src="images/callouts/6.png" alt="(6)"></span>
</pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><img src="images/callouts/1.png" alt="1" border="0"></td><td valign="top" align="left"><p>Manifest version.</p></td></tr><tr><td width="5%" valign="top" align="left"><img src="images/callouts/2.png" alt="2" border="0"></td><td valign="top" align="left"><p>OSGi bundle version. A value of <code class="literal">1</code> (which is also the default) indicates an OSGi Release 3 bundle so it's best to 
            specify <code class="literal">2</code> to indicate an OSGi Release 4 bundle.</p></td></tr><tr><td width="5%" valign="top" align="left"><img src="images/callouts/3.png" alt="3" border="0"></td><td valign="top" align="left"><p>The symbolic name of the bundle to which this fragment should be attached to. In this case, the value 
         	<code class="literal">org.eclipse.gemini.blueprint.extender</code> points to the <code class="literal">spring-osgi-extender.jar</code>.
         	<code class="literal">Fragment-Host</code> is the <span class="emphasis"><em>key</em></span> entry which tells the OSGi platform that the containing bundle is a of a 
         	special kind - it's a fragment.</p></td></tr><tr><td width="5%" valign="top" align="left"><img src="images/callouts/4.png" alt="4" border="0"></td><td valign="top" align="left"><p>The fragment symbolic name.</p></td></tr><tr><td width="5%" valign="top" align="left"><img src="images/callouts/5.png" alt="5" border="0"></td><td valign="top" align="left"><p>The bundle name - an optional yet useful header.</p></td></tr><tr><td width="5%" valign="top" align="left"><img src="images/callouts/6.png" alt="6" border="0"></td><td valign="top" align="left"><p>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.</p></td></tr></table></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/admons/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top">The Manifest entries order does not matter, but they case sensitive.</td></tr></table></div><p>When multiple bundles with the same symbolic names are present, one can add the bundle version to make sure the proper wiring is done:</p><pre class="programlisting">Fragment-Host: org.eclipse.gemini.blueprint.extender;bundle-version=1.1.0</pre><p>The default value for <code class="literal">bundle-version</code> (when it's not specified) is <code class="literal">[0.0.0,&#8734;)</code></p></div></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="appendix-pde-integration.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="appendix-roadmap.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix&nbsp;B.&nbsp;Eclipse Plug-in Development integration&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;Appendix&nbsp;D.&nbsp;Roadmap</td></tr></table></div></body></html>