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,
lib/thirdPartyEntities.jar!/META-INF/persistence.xml
Web-ContextPath: /contextRoot
Export-EJB:
Bundle-Blueprint: /blueprint/*.xml
The metadata in a
bundle manifest file includes the following headers:
- Bundle-SymbolicName
- A name that identifies the bundle uniquely.
- Bundle-Version
- This header describes the version of the bundle, and enables multiple
versions of a bundle to be active concurrently in the same framework
instance.
- Bundle-Activator
- This header notifies the bundle of lifecycle changes.
- Import-Package
- 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.
- Export-Package
- 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.
- Export-EJB
- 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.
Note: - 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.
- Meta-Persistence
- 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).
- Web-ContextPath
- 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.
- Bundle-Blueprint
- 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.