OSGi Bundle Manifest Files

Overview

Bundles are JAR files that contain resources and classes for providing a set of functionality. Bundles differ from standard JAR files in that they must contain an OSGi manifest describing the bundle and its dependencies. Bundles use the JAR file manifest format composed of name-value pairs. The metadata is in plain-text in the META-INF/MANIFEST.MF file.

Example

Example 2.1 shows the manifest file for the camel-osgi example. Also see Manifest file for the camel-osgi example bundle.

Example 2.1. Manifest File for the camel-osgi Example

Manifest-Version: 1.0
Built-By: cruise
Bundle-Activator: org.apache.camel.osgi.Activator
Created-By: Apache Maven Bundle Plugin
Bundle-License: http://www.apache.org/licenses/LICENSE-2.0.txt
Import-Package: javax.xml.bind,javax.xml.bind.annotation,org.apache.camel,org.apache.came
 l.impl,org.apache.camel.impl.converter,org.apache.camel.model,org.apache.camel.model.con
 fig,org.apache.camel.model.dataformat,org.apache.camel.model.language,org.apache.camel.m
 odel.loadbalancer,org.apache.camel.osgi;version="1.6.0.fuse",org.apache.camel.spi,org.ap
 ache.camel.spring,org.apache.camel.spring.handler,org.apache.camel.util,org.apache.commo
 ns.logging,org.osgi.framework,org.springframework.beans.factory.xml,org.springframework.
 osgi.context,org.springframework.osgi.util
Bnd-LastModified: 1233952200932
Export-Package: org.apache.camel.osgi;uses:="org.apache.camel.model.loadbalancer,org.osgi
 .framework,org.apache.camel.impl.converter,org.apache.camel.util,org.apache.camel.impl,o
 rg.apache.camel.spring.handler,org.apache.commons.logging,org.apache.camel.model.config,
 javax.xml.bind.annotation,org.apache.camel.model.dataformat,org.springframework.osgi.uti
 l,org.apache.camel.model.language,org.springframework.osgi.context,org.apache.camel.mode
 l,org.springframework.beans.factory.xml,org.apache.camel.spi,org.apache.camel,org.apache
 .camel.spring,javax.xml.bind";version="1.6.0.fuse"
Bundle-Version: 1.5.4.fuse
Bundle-Name: camel-osgi
Bundle-Description: Camel OSGi support
Build-Jdk: 1.5.0_12
Private-Package: !*
Bundle-DocURL: http://open.iona.com
Bundle-ManifestVersion: 2
Bundle-Vendor: IONA Open Source Community
Bundle-SymbolicName: org.apache.camel.camel-osgi
Implementation-Title: Apache Camel
Tool: Bnd-0.0.255
Implementation-Version: 1.5.4.0-fuse

OSGi bundle manifest metadata

The metadata for this example manifest file includes the following.

Table 2.1. Bundle Manifest Metadata

Header	Description
`Manifest-Version`	Required attribute for all JAR file manifests and must be the first entry.
`Bundle-Activator`	Specifies the name of the class used to start and stop the bundle.
`Created-By`	Defines the version and the vendor of the Java implementation on which this manifest file is generated. This attribute is generated by the JAR tool.
`Import-Package`	List of the Java packages that this bundle requires.
`Export-Package`	List of the Java packages that are visible from the bundle and available for import.
`Bundle-Version`	Version of the bundle, using the format, `X.X.X`.
`Bundle-Name`	Descriptive, human readable name for the bundle.
`Bundle-Description`	Short description of the bundle.
`Bundle-DocURL`	URL pointing to documentation about this bundle.
`Bundle-ManifestVersion`	Specifies the version of the OSGi manifest header syntax in the header. Bundles using this version of the Framework specification (or later) must specify this header. The syntax is: `Bundle-ManifestVersion ::= number`. Framework version 1.3 (or later) bundle manifest version must be ’2’. Version 2 bundle manifests do not have to specify the bundle version since this version header has a default value.
`Bundle-Vendor`	Human-readable description of the bundle vendor.
`Bundle-SymbolicName`	The only required attribute for OSGi manifests. Specifies a unique name for the bundle. With `Bundle-ManifestVersion` it allows a bundle to be uniquely identified in the Framework. A bundle with a given symbolic name and version is treated as equal to another bundle with the same (case sensitive) symbolic name and exact version. The `Bundle-Name` manifest header provides a human-readable name for a bundle and is therefore not replaced by this header.
`Implementation-Version`	Specifies the minimum extension implementation version number that is required by the applet. The Java plug-in will compare the value of this attribute with the `Implementation-Version` attribute of the installed extension to see if a more recent implementation must be downloaded.

For more information on the headers in this manifest file, see Configuring the bundle headers in Enterprise Integration Patterns. To use the Maven bundle plug-in to generate the bundle headers automatically, see Maven bundle plug-in in Enterprise Integration Patterns.

For other manifest headers and syntax details, see the OSGi Service Platform Core Specification and the JAR File Specification.

Importing and exporting packages

Bundles learn about registered service bundles through manifest files, which include references for importing and exporting packages. The client bundle manifest typically imports the service component package, while the service bundle manifest exports its own package.

Each bundle lists the classes (or bundles) it requires using import statements in the MANIFEST.MF. For Import-Package you list the Java packages that this bundle requires. (Only java.* packages are imported by default. All other packages must be explicitly imported.)

Bundles can also list the classes they export. For Export-Package, you list the Java packages that are visible from the bundle. (All packages are hidden unless explicitly exported.) Some packages are exported, meaning they can be used by other bundles. Others are private and only visible within a specific bundle. Packages exported by one bundle can be imported by another.

You must separate packages with commas and continue long manifest lines on the next line with a leading space.

The runtime throws errors if the imports and exports are not explicitly declared or the import and export definitions do not match.

Using the packages subshell commands

The packages subshell of the FUSE ESB Kernel console provides commands for showing all packages imported and exported by the OSGi bundles currently installed. See Packages Console Commands in Console Reference Guide for a detailed listing of the commands.

Bundle versioning

OSGi provides versioning of bundles for each new deployment. Therefore, you can track the history of bundle creation and changes. The combination of graph based class-loading with versioned bundles means that the same JVM can host different versions of the same bundle.

Bundles can export packages, specifying a version for each package, and import packages, specifiying a range of versions the bundle is compatible with. At runtime, the OSGi framework resolves these dependencies. This means that you can keep implementations private and only expose APIs.

Bundles are versioned using the Bundle-Version tag in the MANIFEST.MF file, for example, Bundle-Version: 1.2.3. When a bundle imports classes from another bundle, it can specify the version number, for example, Import−Package: com.mycompany.stuff;version="1.2.3”.

Alternatively, the tag can specify a range of compatible versions, for example, Import−Package: com.mycompany.stuff;version=”[1.2.3,1.2.5)”.

Bracket choice is important:

‘[‘ or ‘]’ means to include this lower (or upper) limit.
‘(‘ or ‘)’ means to exclude this lower (or upper) limit.
[1.2.3,1.2.5) means version 1.2.3 or 1.2.4, but not 1.2.5.

Bundle resolution

The OSGi framework performs bundle resolution to match imported and exported packages and resolve versioning. The Module layer has strict rules for sharing java packages between bundles and hiding packages from other bundles. On activation, the OSGi framework resolves dependencies, connecting a bundle to dependent bundles. If the resolution step fails, an appropriate error is reported and the bundle fails to activate.

Bundles share only their interface packages. There is automatic wiring based on version ranges. The Framework must resolve bundles and wire importers to exporters. A wire is an actual connection between an exporter and an importer, which are both bundles. A wire is associated with a number of constraints that are defined by the importer’s and exporter’s manifest headers. A valid wire is a wire that has satisfied all its constraints. Bundle resolution satisfies any constraints and takes place before any code from a bundle can be loaded or executed.