OSGi Fragments

Appendix E. Useful OSGi tips

E.1. OSGi Fragments

Check the target OSGi platform fragment support

Before using fragments, make sure the target OSGi environment supports them (and to what degree). Out of the OSGi platforms on which Spring-DM is tested upon, at the time of this writing, Apache Felix does not support fragments (it simply ignores them).

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
	For a full description on fragments, please see the OSGi specification, section 3.14.

In Spring-DM, 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 Spring-DM extender, one could use the following manifest:

Manifest-Version: 1.0                                                                    
Bundle-ManifestVersion: 2                                                                
Fragment-Host: org.springframework.bundle.osgi.extender                                  
Bundle-SymbolicName: org.mydomain.project.fragment                                       
Bundle-Name: my-fragment                                                                 
Bundle-Description: Fragment attached to Spring-DM extender                              

	Manifest version.
	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.
	The symbolic name of the bundle to which this fragment should be attached to. In this case, the value org.springframework.bundle.osgi.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.
	The fragment symbolic name.
	The bundle name - an optional yet useful header.
	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
	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.springframework.bundle.osgi.extender;bundle-version=1.1.0

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