Appendix C. Useful OSGi tips

C.1. OSGi Fragments

Part of the OSGi R4 release, fragments are a very useful and powerful feature. A fragment is “a bundle that is attached to a host bundle”, 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 “...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.

[Note]Note
For a full description on fragments, please see the OSGi specification, section 3.14.

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:

Fragment-Host: <host bundle symbolic name>

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:

Manifest-Version: 1.0                                                                    (1)
Bundle-ManifestVersion: 2                                                                (2)
Fragment-Host: org.eclipse.gemini.blueprint.extender                                     (3)
Bundle-SymbolicName: org.mydomain.project.fragment                                       (4)
Bundle-Name: my-fragment                                                                 (5)
Bundle-Description: Fragment attached to Gemini Blueprint extender                       (6)
1

Manifest version.

2

OSGi bundle version. A value of 1 (which is also the default) indicates an OSGi Release 3 bundle so it's best to specify 2 to indicate an OSGi Release 4 bundle.

3

The symbolic name of the bundle to which this fragment should be attached to. In this case, the value org.eclipse.gemini.blueprint.extender points to the spring-osgi-extender.jar. Fragment-Host is the key entry which tells the OSGi platform that the containing bundle is a of a special kind - it's a fragment.

4

The fragment symbolic name.

5

The bundle name - an optional yet useful header.

6

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.

[Note]Note
The Manifest entries order does not matter, but they case sensitive.

When multiple bundles with the same symbolic names are present, one can add the bundle version to make sure the proper wiring is done:

Fragment-Host: org.eclipse.gemini.blueprint.extender;bundle-version=1.1.0

The default value for bundle-version (when it's not specified) is [0.0.0,∞)