Example: OSGi bundle manifest file

An OSGi bundle, which can be a JAR or web application archive (WAR) file, contains a bundle manifest file META-INF/MANIFEST.MF. In addition to the headers that can be defined for a non-OSGi JAR or WAR file, the bundle manifest file for an OSGi bundle contains OSGi-specific headers. The metadata that is specified in these headers enables the OSGi Framework to process the modular aspects of the bundle.

Eclipse tools provides convenient editors for the manifest file.

Here is an example bundle manifest file, META-INF/MANIFEST.MF; the headers highlighted in bold text are mandatory:
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: MyService bundle
Bundle-SymbolicName: com.sample.myservice
Bundle-Version: 1.0.0
Bundle-Activator: com.sample.myservice.Activator
Import-Package:  org.apache.commons.logging;version="1.0.4"
Export-Package:  com.sample.myservice.api;version="1.0.0"
Meta-Persistence: entities/persistence.xml, 
Web-ContextPath: /contextRoot
Bundle-Blueprint: /blueprint/*.xml
The metadata in a bundle manifest file includes the following headers:
A name that identifies the bundle uniquely.
This header describes the version of the bundle, and enables multiple versions of a bundle to be active concurrently in the same framework instance.
This header notifies the bundle of lifecycle changes.
This header declares the external dependencies of the bundle that the OSGi Framework uses to resolve the bundle. 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.
This header declares the packages that are visible outside the bundle. If a package is not declared in this header, it is visible only within the bundle.
The presence of this header identifies this bundle as an EJB bundle, and causes any enterprise beans in the bundle to be loaded and run by the EJB container. The value of this header declares the enterprise beans that you want to export as OSGi services.
The Export-EJB header can have any of the following values:
  • A single space character: export all enterprise beans in the bundle.
  • A comma-separated list of the class names of the enterprise beans that you want to export. If an enterprise bean is not included in this list, it is still loaded and run, but it is not exposed in the OSGi service registry.
  • NONE: do not export any enterprise beans.
  • Only session enterprise beans that are not stateful are exported.
  • The most straightforward way for a client to use an enterprise bean that is exposed as a service is to import the package that contains the EJB business interface. For a client to be able to import the required package, that package must be declared in the Export-Package header of this bundle, or any other bundle.

If this bundle is a web application bundle, and you are using Version 3.0 of the Java™ Servlet Specification, the bundle can contain enterprise beans. In this case, if you specify a Web-ContextPath header then any enterprise beans in the bundle are loaded and run by the EJB container, but none are exposed in the OSGi service registry. This configuration is equivalent to specifying "Export-EJB: NONE". To export one or more enterprise beans from a web application bundle into the OSGi service registry, specify an Export-EJB header in addition to the Web-ContextPath header. The value of the Export-EJB header determines which enterprise beans are exposed.

An exported enterprise bean is registered in the OSGi service registry with the following service properties:
  • ejb.name: the name of the enterprise bean.
  • ejb.type: the EJB type; the value of this property is either "Stateless" or "Singleton". For more information about EJB types, see Enterprise beans and Developing session beans.
  • service.exported.interfaces: the enterprise bean is registered with this property only if it has a remote interface; the value is the EJB interface name. This property configures the enterprise bean as being suitable for remote access from outside the application, through Service Component Architecture (SCA) for example. For more information, see the description of the Application-ExportService header in the application manifest file.
If your application uses the Java Persistence API (JPA), and this bundle is a persistence bundle, then the bundle manifest also contains a Meta-Persistence header. For more information, see JPA and OSGi Applications.
This header lists all the locations of persistence.xml files in the persistence bundle. When this header is present, the default location, META-INF/persistence.xml, is added by default. Therefore, when the persistence.xml files are in the default location, the Meta-Persistence header must be present, but its content can be empty (a single space).
The presence of this header identifies this bundle as a web application bundle.

This header specifies the default context from which the web content is hosted.

This header specifies the location of the blueprint descriptor files in the bundle. For more information, see Section 121.3.4 of the OSGi Service Platform Release 4 Version 4.2 Enterprise Specification.