OSGi bundles

An OSGi bundle is a Java™ archive file that contains Java code, resources, and a manifest that describes the bundle and its dependencies. The bundle is the unit of deployment for an application.

Types of bundles

Application bundles

Application bundles are bundles that you create specifically for your application. They are instance-specific or isolated; that is, they are not intended to be shared. They are referenced in the application manifest in the Application-Content header.

Shared bundles

Shared bundles are not application-specific. A single instance of a package from a shared bundle can be used by many applications. Shared bundles cannot import packages or services from application bundles. Shared bundles in an application must be provided by reference rather than contained directly in an application.

Shared bundles are further subdivided into use bundles and provision bundles:

Use bundles: A use bundle is a shared bundle that provides at least one package to an application bundle. Use bundles are referenced in the application manifest in the Use-Bundle header.
Provision bundles: A provision bundle is a shared bundle that provides at least one package or service to an application bundle, a use bundle, or another provision bundle. Provision bundles are not referenced in the application manifest, and your application does not know how the requirement for each provision bundle is satisfied.

OSGi bundles can be stored in any of the following locations:

The enterprise bundle archive (EBA) file for the application.
A server internal OSGi bundle repository.
External OSGi bundle repositories.

Application bundles can be stored either in the EBA file or in a repository. Shared bundles are stored in a repository (otherwise they cannot be shared).

The process of getting bundles from the repositories is known as provisioning. For provisioning purposes, the following terminology is used for bundles:

Referenced bundles: A referenced bundle is a bundle that is referenced in the application manifest, and stored in a repository.
Dependency bundles: A dependency bundle is a bundle that is not referenced in the application manifest, but that is used by bundles that are referenced in the application manifest, or by other dependency bundles.

Application bundles that are not directly contained in the EBA file are instance-specific referenced bundles. Use bundles are shared referenced bundles. Provision bundles are shared dependency bundles.

OSGi bundle manifest file

An OSGi bundle JAR file contains a JAR manifest file. This file contains metadata that enables the OSGi Framework to process the modular aspects of the bundle.

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: 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-EJB: ExampleBean
Export-Package: com.sample.myservice.api;version="1.0.0"

The metadata in this manifest file includes the following key properties:

Bundle-Version

Describes the version of the bundle and enables multiple versions of a bundle to be active concurrently in the same framework instance.

Bundle-Name

Provides a human readable name for a bundle.

Bundle-SymbolicName

Uniquely identifies a bundle in the framework. It does not replace the need for a Bundle-Name header.

Bundle-Activator

Receives notification from the framework about the bundle lifecycle changes. This property specifies the class that implements the org.osgi.framework.BundleActivator interface.

Import-Package

Declares the external dependencies of the bundle that are used by the OSGi Framework for bundle 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 bundle to import from the run time. If you do not specify the package that your bundle needs in this property, you might get 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-EJB:

If an EJB project is converted to an OSGi bundle, and Export-EJB section is added to the manifest. Use this section to list EJBs that you want to expose. EJBs can be added to this section by editing manually or by right-clicking a converted EJB project and selecting OSGi > Manage EJB exports.

Export-Package

Declares the packages that are visible outside the bundle. Any package not declared here has visibility only within the bundle.

Use this property to specify the name of any package that you want your bundle 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.

Bundle lifecycle

The framework manages the lifecycle of bundles. As you install and run a bundle, it goes through various states.

The possible states of a bundle are:

INSTALLED: The bundle is installed, but not all of the dependencies of the bundle have been met. The bundle requires packages that have not been exported by any currently installed bundle.
RESOLVED: The bundle is installed and the dependencies of the bundle have been met, but it is not running. If a bundle is started and all of the dependencies of the bundle are met, the bundle skips this state.
STARTING: A temporary state that the bundle goes through while the bundle is starting.
ACTIVE: The bundle is running.
STOPPING: A temporary state that the bundle goes through while the bundle is stopping.
UNINSTALLED: The bundle no longer exists in the framework.