OSGi composite bundles
Composite bundles group bundles into aggregates to ensure consistent behavior. A composite bundle contains bundles or references to bundles outside of the workspace or target platform. A composite bundle ensures consistent behavior from a set of shared bundles at a specific version.
A composite bundle archive (CBA) groups shared bundles together into aggregates. A CBA can contain OSGi bundles or reference bundles that are hosted in the internal bundle repository. Create a CBA when you want to ensure consistent behavior across a set of shared bundles. You can use the CBA to wire that set of bundles, at a specific version, to an application.
A CBA is an archive file with a .cba file extension. It contains a composite manifest META-INF/COMPOSITEBUNDLE.MF, which defines the CBA, and optionally some OSGi bundles with which to seed the repository. The bundles that a CBA contains or references are defined with exact versions, in contrast to an EBA, where bundles are defined with version ranges.
A composite bundle is installed in the internal bundle repository of the run time. If the CBA directly contains OSGi bundles, these bundles are installed into the repository as though they were individually uploaded. The CBA is also added to the bundle repository. If the CBA references OSGi bundles, these bundles must be present in the internal bundle repository.
After a CBA is installed in the internal bundle repository, its bundles are available to all applications that want to use the bundles when the application is resolved. If a required package or service is available at the same version from both a bundle and a CBA, the provisioning process selects the package or service from the CBA.
- A CBA has a composite manifest, which is a modularity statement that asserts that bundles can be deployed, not that they will resolve. An EBA file has an application manifest, which is a provisioning statement.
- A CBA can import or export packages, but an EBA file cannot.
- An EBA file does not need to fully define its content. When the application is deployed, a dependency analysis is performed and additional bundles can be provisioned.
- An EBA file can define that bundles in its content are shared.
- Bundles in a CBA are visible in the repository, but bundles in an EBA file are private to the application.
OSGi composite bundle manifest file
- Manifest-Version
- Describes the version of the manifest file.
- CompositeBundle-ManifestVersion
- Describes the version of the composite bundle.
- Bundle-Name
- Provides a human readable name for a composite bundle.
- If you do not specify a value, the default value is the composite bundle symbolic name.
- Bundle-SymbolicName
- Uniquely identifies a composite bundle in the framework. It does not replace the need for a Bundle-Name header.
- Bundle-Version
- Describes the version of the composite bundle and enables multiple versions of a composite bundle to be active concurrently in the same framework instance.
- CompositeBundle-Content
- A list of bundles and bundle fragments in the composite bundle. All bundles and fragments must be available for deployment and must be contained in the cba file, or exist in the local bundle repository. Bundles and fragments must have exact version numbers. If you require the same composite bundle with different versions of its content, you need to create different versions of the composite bundle, one version for each use.
- The format is a comma-separated list of module declarations, where
each module declaration uses the following format:
<module identifier>;<directives>;<attributes>
- The CompositeBundle-Content header has the following attribute:
- version
- The version of the module is specified using OSGi syntax for a version range. The version must be specified as an exact range, for example "[1.0.0,1.0.0]".
- 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.
- 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 your bundle needs in this property, you might get a NoClassDefFound exception when the bundle loads.
- Note: You must also specify the package that you want to import (by using Import-Package) in the Export-Package property of the bundle that contains the package.
- 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.
- CompositeBundle-ExportService
A list of service interface names and optional filters that identify services that are present in the composite bundle and that can be exported for use outside the composite bundle. The interfaces that an exported service implements are usable outside the composite bundle if those interfaces are visible outside the composite bundle.
The format is a comma-separated list of services, in the form of a service interface name, followed by attributes or directives. The CompositeBundle-ExportService header has the following attribute:- filter
- An OSGi service filter.
- CompositeBundle-ImportService
A list of service interface names and optional filters that identify services that the contents of the composite bundle want to use from outside the composite bundle. At least one such service must exist at run time.
The format is a comma-separated list of services, in the form of a service interface name, followed by attributes or directives. The CompositeBundle-ImportService header has the following attribute:- filter
- An OSGi service filter.