| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>Appendix C. 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 IV. Appendixes"><link rel="prev" href="appendix-pde-integration.html" title="Appendix B. Eclipse Plug-in Development integration"><link rel="next" href="appendix-roadmap.html" title="Appendix D. 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 C. 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. 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 |
| “<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>”, 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 “<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>”</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: <host bundle symbolic name></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,∞)</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> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="appendix-roadmap.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix B. Eclipse Plug-in Development integration </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"> Appendix D. Roadmap</td></tr></table></div></body></html> |
