OSGi fragments

An OSGi fragment is a Java™ archive file with specific manifest headers that enable it to attach to a specified host bundle or specified host bundles to function. Fragments are treated as part of the host bundles. Relevant definitions of the fragment are merged with the host bundles definitions before the host is resolved, provided the information does not conflict. Fragment dependencies are resolved if possible. If the fragment dependencies cannot be resolved, the fragment does not attach to the host bundle. A fragment cannot have its own class loader or bundle activator. It cannot override the information present in the host bundles. Fragments extend bundles with resources, classes, and permitted headers, which enable you to customize your bundles.

OSGi fragment manifest files

An OSGi fragment JAR file contains a fragment manifest file. This file contains metadata that enables the OSGi Framework to attach the fragment to a host bundle or host bundles.

The following code is an example of the contents of a bundle manifest file, META-INF/MANIFEST.MF:
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Fragment
Bundle-SymbolicName: Fragment
Bundle-Version: 1.0.0.qualifier
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Fragment-Host: WebBundle;bundle-version=1.0.0.qualifier
Import-Package: org.apache.commons.logging;version="1.0.4"
Export-Package: com.sample.myservice.api;version="1.0.0"
The metadata in this manifest file includes the following key properties:
Fragment-Host
Links the fragment to its potential bundle hosts.
Bundle-Version
Describes the version of the fragment and enables multiple versions of a bundle to be active concurrently in the same framework instance.
Bundle-Name
Provides a human readable name for the fragment.
Bundle-SymbolicName
Uniquely identifies the fragment in the framework. It does not replace the need for a Bundle-Name header.
Import-Package
Declares the external dependencies of the fragment that are used by the OSGi Framework for fragment resolution. Specific versions or version ranges for each package can be declared. In this example manifest file, the org.apache.commons.logging package is required at Version 1.0.4 or later.
Use this property to specify the names of any packages that you want your fragment to import from the run time. If you do not specify the package that your bundle needs in this property, you might get a NoClassDefFound exception and a compilation error when the bundle loads.
Note: You must also specify this package in the Export-Package property of the bundle that contains the package.
Restriction: If your bundle manifest file uses the Import-Package property to declare a bundle dependency for a bundle that is not in your workspace or your target platform, the editor marks the dependency as an error. To work around this limitation, make sure that all the bundles that you declare as a dependency are in your workspace, or use the quick fix to add the bundle to the target platform. To use the quick fix, switch to the Markers view and then right-click the error marker and select Quick Fix.
Important: When you specify bundle dependencies in your MANIFEST.MF file, use the property Import-Package instead of Require-bundle. If you use Require-bundle to specify bundle dependencies, your application does not deploy.
Import-Package is a more flexible way to declare dependencies:
  • You can declare dependencies on the functionality that you need rather than on the bundle where the functionality originated, as it does not add unnecessary dependencies on packages that are not required by your bundle but are included in the dependent bundle.
  • You can specify versions or version ranges for the declared package, therefore you do not have to react to changes in different versions of the bundle.
Export-Package
Declares the packages that are visible outside the fragment. Any package not declared here has visibility only within the fragment.
Use this property to specify the name of any package that you want your fragment to export to the run time. If you do not specify the packages that are required by other bundles in this property, the dependent bundles might not resolve.
Icon that indicates the type of topic Concept topic
Timestamp icon Last updated: July 17, 2017 21:58

File name: cbundlefragment.html