A composite bundle groups shared bundles
together into aggregates.
A composite bundle can either directly contain OSGi bundles, or reference bundles
that are hosted in the internal bundle repository.
You create a composite bundle when you want to ensure consistent behavior from
a set of shared bundles. You can use the composite bundle to wire that set of bundles
to an application. For example, a composite bundle provides a package at a specified
version to an application, even when another bundle with a later version
of that package is installed in the shared bundle space.
A composite bundle is packaged as a compressed archive file with a .cba file extension.
It contains a composite manifest, which is located at META-INF/COMPOSITEBUNDLE.MF and
which defines the composite bundle, and optionally some OSGi bundles with which
to seed the repository. The bundles that a composite bundle contains or references
are defined with exact versions, in contrast to an EBA, where bundles
can be defined with version ranges.
You install a composite bundle in the internal bundle repository.
If the composite bundle directly contains OSGi bundles, these bundles are installed
into the repository as though they are individually uploaded, and
the composite bundle is also added to the bundle repository. If the composite bundle references
OSGi bundles, these bundles must be present in the internal bundle
repository.
After a composite bundle is installed in the internal bundle repository, its
bundles are available to all applications that want to use them when
the application is resolved. If a required package or service is available
at the same version from both a bundle and a composite bundle, the provisioning
process selects the package or service from the composite bundle.
A composite bundle has the following differences from an enterprise bundle archive
(EBA) file:
- A composite bundle 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 composite bundle 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 composite bundle are visible in the repository, but bundles in
an EBA file are private to the application.
Composite manifest
The composite manifest
is located at META-INF/COMPOSITEBUNDLE.MF and
defines the composite bundle, and optionally some OSGi bundles with
which to seed the repository. All the versions in a composite manifest
are exact.
A composite
manifest can contain the following headers:
- Manifest-Version
- A version number for the manifest format.
- CompositeBundle-ManifestVersion
- The composite manifest version to which this manifest conforms.
- Bundle-Name
- A human-readable name of the composite bundle.
If you do not
specify a value, the default value is the composite bundle symbolic
name.
- Bundle-SymbolicName
- A name that identifies the composite bundle uniquely. The name
follows the same scheme as the Bundle-SymbolicName header
in an OSGi bundle.
- Bundle-Version
- A version number that identifies the version of the composite
bundle uniquely.
- Import-Package
- A list of packages that the contents of the composite bundle want
to use from the shared bundle space.
- Export-Package
- A list of packages that the contents of the composite bundle provide
to the shared bundle space.
- CompositeBundle-Content
- A list of bundles in the composite bundle. All bundles must be
available for deployment and must be contained in the .cba file,
or exist in the local bundle repository. Bundles must have exact version
numbers. If you require the same composite bundle with different versions
of its content, you require different versions of the composite bundle,
one version for each usage.
- 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.
The following shows an example of a composite
manifest:
Manifest-Version: 1.0
CompositeBundle-ManifestVersion: 1
Bundle-Name: Blog Application
Bundle-SymbolicName: com.ibm.ws.osgi.example.Blog
Bundle-Version: 1.0
CompositeBundle-Content:
com.ibm.ws.osgi.example.blog;version="[1.0,1.0]",
com.ibm.ws.osgi.example.blog.persistence;version="[1.0,1.0]"
Import-Package: com.ibm.ws.other.pkge;version=1.0.0
Export-Package: com.ibm.ws.osgi.example.blog;version=1.0.0
CompositeBundle-ExportService:
com.ibm.ws.osgi.example.blog.BloggingService;filter="(blog.type=community)"
CompositeBundle-ImportService:
com.ibm.ws.osgi.example.auth.UserAuthService