Composite bundles

A composite bundle groups shared bundles together into aggregates. It provides one or more packages at specific versions to an OSGi application. You can also extend a deployed application by adding one or more composite bundles to the composition unit for the application.

A composite bundle is packaged as a composite bundle archive (CBA) file. This file is a compressed archive file with a .cba file extension. If the composite bundle is part of an enterprise OSGi application, the CBA file can be directly contained within the enterprise bundle archive (EBA) file for the application, or pulled in by reference from the internal bundle repository or from an external repository that can process composite bundles. A composite bundle can directly contain bundles in its CBA file. It can also include by reference bundles that are hosted alongside the CBA file within the same EBA file, or bundles that are installed in the same bundle repository.

A composite bundle has the following differences from an enterprise OSGi application:

The bundles that a composite bundle contains or references are defined with exact versions. The bundles in an enterprise OSGi application can be defined with version ranges.
A composite bundle has a composite bundle manifest, which is a modularity statement that asserts that bundles can be deployed, not that they will resolve. An enterprise OSGi application has an application manifest, which is a provisioning statement.
A composite bundle can import or export packages. An enterprise OSGi application cannot do this.
An enterprise OSGi application does not need to fully define its content. When the application is deployed, dependencies are analyzed and additional bundles are provisioned.

There are two main uses for a composite bundle:

When you want to ensure consistent behavior from a set of shared bundles in an OSGi application, you use a composite bundle to provide that set of bundles to the application. 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.
When you want to extend a deployed business-level application that contains an OSGi application, and you do not want to stop the application or modify the underlying EBA asset, you add one or more composite bundles to the composition unit.

After you import the enterprise bundle archive (EBA) file for your OSGi application as an asset, you can update versions of existing bundles but you cannot add extra bundles to the asset. By adding one or more composite bundles to the composition unit, you can extend a business-level application without having to redevelop and redeploy the underlying OSGi application. When you save the changes to the composition unit, the associated business-level application is updated to use the new configuration. If the business-level application is running, the bundle and configuration updates are applied immediately.

An OSGi application can include a composite bundle just like any other bundle, either directly or by reference. If you want to include the composite bundle by reference, or use the composite bundle to extend a deployed application, the composite bundle must be available in the internal bundle repository or in an external repository that can process composite bundles. If you install a composite bundle in a bundle repository, and the composite bundle includes bundles by reference, you must ensure that the referenced bundles are also available in the same repository. If you use the internal bundle repository, and the composite bundle directly contains bundles, the contained bundles are not listed separately and are only available as part of the composite bundle.

For users who are moving from a previous version:

In the WebSphere® Application Server Version 7 Feature Pack for OSGi Applications and Java™ Persistence API 2.0, when you add a composite bundle to the internal bundle repository, and that composite bundle directly contains bundles (in compressed files in the root directory of the composite bundle archive file), those bundles are added to the internal bundle repository both as part of the composite bundle and as individually-available bundles. If you later delete the composite bundle from the repository, the individually-available copies of the bundles are not deleted. You might have used this mechanism as a convenient way to upload sets of bundles to the repository.
In the current version, when you add to the repository a composite bundle that directly contains bundles, those bundles are not also added individually. If you want to add sets of bundles to the internal bundle repository, you package each set as a compressed archive file with a .zip file extension, then add the archive file to the repository. The system expands the file, and all the bundles in its root directory are added individually to the repository.