Enterprise bundle archives

An enterprise bundle archive (EBA) file contains a set of OSGi bundles that are deployed as a single OSGi application, and that are isolated from other OSGi applications.

Each OSGi application runs in its own isolated OSGi framework instance with its own OSGi service registry. Bundles in one OSGi application cannot see bundles, services, or packages that are defined in another OSGi application, unless the bundles, services, or packages are explicitly shared by both applications.

The bundles that are used by the OSGi application are either directly contained in the EBA file, or pulled in by reference from an OSGi bundle repository when the application is provisioned. Application metadata stored in the EBA file defines the isolation scope of the bundles that the OSGi application uses.

An EBA file is a compressed archive file with a .eba file extension. It contains an application manifest, and (optionally) a set of application modules. An application module can be either of the following types of resource: Application modules are contained in the root of the EBA file. These modules are directly contained in the OSGi application, whereas all other bundles are provided by reference.

The OSGi bundles in the EBA file share services with other OSGi applications by declaring them in an application manifest. Any external services and references that the OSGi application produces are exposed by declaring them in the manifest, and any external services and references that the application consumes are also declared in the manifest.

An OSGi application can also use metadata to permit some of its constituent bundles to be shared. Sharing in this way can reduce the memory and resource requirements of a system. Shared bundles must be provided by reference rather than contained directly in an application.

An OSGi application can also load packages and consume OSGi services from a shared bundle space, that is, the OSGi framework instance that is the parent of all the isolated framework instances of the OSGi applications.

Archive content

The archive content is used in two different ways, depending on whether an Application-Content header is defined in the application manifest.

If an Application-Content header is not defined, or there is no application manifest, the EBA file content defines the OSGi application content.

If an Application-Content header is defined, the EBA file content defines an initial bundle repository from which bundles can be provisioned.

Application manifest

The application manifest is located at META-INF/APPLICATION.MF and describes modularity at the application level. It uses configuration by exception, that is, you supply values only when you want to override the default. The default, when no application manifest is declared, is that the application content is the set of OSGi bundles contained in the OSGi application, and no external services or references are produced or consumed.

A developer provides an application manifest as part of the development process.

An application manifest can contain the following headers:
Manifest-Version
A version number for the manifest format.
Application-ManifestVersion
The application manifest version to which this manifest conforms.
Application-Name
A human-readable name of the application.

If you do not specify a value, the default value is the application symbolic name.

Application-SymbolicName
A name that identifies the application uniquely. The name follows the same scheme as the Bundle-SymbolicName header in an OSGi bundle.

If you do not specify a value, the default value is the name of the EBA file.

Application-Version
A version number that uniquely identifies the version of the application. The combination of the application symbolic name and version must be unique in an OSGi application runtime environment.

If you do not specify a value but the application name contains an underscore character "_" followed by a valid version value, this value is used. For example, for the application name com.ibm.ws.eba.example_1.2.3.eba, the default value is 1.2.3.

Otherwise, if you do not specify a value, the default value is 0.0.0.

Application-Content
A list of application modules that comprise the primary content of the application. These can be modules that are contained directly in the EBA file, or bundles that are provided by reference, that is, the core bundles to provision for the application.

If you do not specify a value, the default is the modules that are contained directly in the root of the EBA file.

The format is a comma-separated list of module declarations, where each module declaration uses the following format:
bundle_symbolic_name;version

The version format is the same as that used for OSGi import (for example, in the Import-Package syntax).

The Application-Content header has the following attribute:
version
The version of the module, specified using OSGi syntax for a version range. Typically, you specify the version of the module when the application is written, and the latest version to which the application can be upgraded.

In OSGi syntax for a version range, brackets [ ] mean include the corresponding lower or upper limit, and parentheses ( ) mean exclude the corresponding lower or upper limit. For example, [1.0.0,2.0.0) means version 1.0.0 and all later versions, up to, but not including, version 2.0.0.

The Application-Content header defines the important applications that compose the business services, but it does not define the full list of bundles in the application. If a bundle that is listed in the content uses a package that is not included in the application, a dependency analysis is performed when the application is deployed and other bundles can be provisioned. Any bundles that are provisioned cannot provide services external to the application and cannot have security applied to them. Such bundles are provisioned to the shared bundle space, rather than being provisioned for each isolated application.

Application-ImportService
A remotable service can be accessed outside the application. This header contains a list of service interface names, and an optional filter, that identify remotable services that the application wants to consume from outside the application.

If you do not specify this header, no services are imported. If you do not specify a value, the default is no values.

The format is a comma-separated list of services, in the form of a service interface name, followed by the filter attribute; this attribute specifies an OSGi service filter.

For example:
Application-ImportService: com.myclub.security.authenticationService; filter="(security=strong)"

Any services that match the Application-ImportService header are made available for integration, but to actually do the integration you must use Service Component Architecture (SCA). See Using OSGi applications as SCA component implementations.

Your remotable service must support pass-by-value semantics. To match against services that are imported by the Application-ImportService header, your service references must look for the service.imported property.This prevents accidental exposure or use of services that only support local calls and expect pass-by-reference semantics.

Application-ExportService
A remotable service can be accessed outside the application. This header contains a list of service interface names, and an optional filter, that identify remotable services that the application provides.

If you do not specify this header, no services are exported. If you do not specify a value, the default is no values.

The format is a comma-separated list of services, in the form of a service interface name, followed by the filter attribute; this attribute specifies an OSGi service filter.

For example:
Application-ExportService: com.myclub.memberService; filter="(level=silver)"

Any services that match the Application-ExportService header are made available for integration, but to actually do the integration you must use Service Component Architecture (SCA). See Using OSGi applications as SCA component implementations.

Your remotable service must support pass-by-value semantics. To match against services that are exported by the Application-ExportService header, your service must be configured as remotable (that is, registered with the service.exported.interfaces property).This prevents accidental exposure or use of services that only support local calls and expect pass-by-reference semantics.

Use-Bundle
A list of bundles or composite bundles to use to satisfy the package dependencies of bundles in the Application-Content list. Each bundle or composite bundle in the Use-Bundle list must provide at least one package to at least one bundle in the Application-Content list. These bundles will be provisioned into the shared bundle space at run time.

Often, you do not require a Use-Bundle header, but there are some situations where it is useful. You can use it to restrict the level at which sharing is possible. For example, you can ensure that an application uses the same bundle for package imports that it was tested with. Alternatively, you can ensure that two applications use the same bundle for package imports. By setting the restriction at application level, the bundle can remain flexible.

The following shows an example of an application manifest:
Manifest-Version: 1.0
Application-ManifestVersion: 1.0
Application-Name: Example Blog
Application-SymbolicName: com.ibm.ws.eba.example.blog.app
Application-Version: 1.0
Application-Content: com.ibm.ws.eba.example.blog.api;version=1.0.0,
 com.ibm.ws.eba.example.blog.persistence;version="[1.0.0,1.1.0]",
 com.ibm.ws.eba.example.blog.web;version="[1.2.0,1.2.5)"
 com.ibm.ws.eba.example.blog;version="(1.2.0,2.0.0)"
Use-Bundle: com.ibm.json.java;version="[1.0.0,2.0.0)"

Deployment manifest

When you install an OSGi application, the application manifest specifies the bundles that form the primary content of the application. The application manifest might specify an allowed version range for some bundles. Bundles that are listed in the content might use a package that is not included in the application, and therefore require other bundles to be pulled in.

A deployment manifest, META-INF/DEPLOYMENT.MF, is created automatically when you install the EBA asset. It enumerates all the bundles at specific versions that make up the application, including bundles that are determined following dependency analysis. This is the set of bundles that will run each time the application is started. The deployment manifest ensures that each time an application server starts, the bundles that make up the application are the same.

You cannot edit a deployment manifest directly. The following information describes the headers in a generated deployment manifest, but developers and administrators do not need to manipulate this file.

A deployment manifest contains the following headers:
Manifest-Version
A version number for the manifest format.
Application-SymbolicName
A name that identifies the application uniquely. The name follows the same scheme as the Bundle-SymbolicName header in an OSGi bundle. This matches the Application-SymbolicName value in the associated application manifest.
Application-Version
A version number that uniquely identifies the version of the application. This matches the Application-Version value in the associated application manifest.
Deployed-Content
A comma-separated list of symbolic names of bundles, with the exact version numbers, that comprise the core content of the application.

The list includes all the bundles that are listed in the Application-Content header in the application manifest. An administrator can update bundles that are mapped into the Deployed-Content list from the Application-Content list after application deployment.

Deployed-Use-Bundle
A list of bundles or composite bundles that satisfy the package dependencies of bundles in the Deployed-Content list. Each element in the Deployed-Use-Bundle list must provide at least one package to at least one bundle in the Deployed-Content list. The Deployed-Use-Bundle list is an exact subset of the Use-Bundle list. These bundles will be loaded into the shared bundle space at run time. Each bundle or composite bundle in the Deployed-Use-Bundle list is guaranteed to be wired to its dependent bundles in the Deployed-Content list at run time. An administrator can update bundles that are mapped into the Deployed-Use-Bundle list from the Use-Bundle list after application deployment.
Provision-Bundle
A list of additional bundles and composite bundles that are required as a result of resolving the OSGi application. Each bundle or composite bundle is loaded into the shared bundle space at run time, but are not necessarily used. An administrator cannot update bundles in the Provision-Bundle list after application deployment.
Import-Package
A list of the packages that the bundles in the Deployed-Content list consume from the bundles and composite bundles in the Deployed-Use-Bundle and Provision-Bundle lists. For packages that are consumed from the Deployed-Use-Bundle list, the package import has ;bundle-symbolic-name and ;bundle-version attributes.

If a package is imported from both a bundle in the Deployed-Content list and an object in the Deployed-Use-Bundle or Provision-Bundle lists, a ResolverException exception is generated.

Importing or exporting a deployment manifest

A deployment manifest is generated automatically and you cannot edit it directly. However, you can export the current deployment manifest from an EBA asset. If required, you can import a suitable deployment manifest into an EBA asset to use instead of the generated deployment manifest.

This is useful during application development when the application is fully tested and moves to a production environment. You can ensure that the bundles, and their versions, that make up the application in the production environment are exactly the same as the bundles that made up the application in the test environment. To do this, you export the deployment manifest from the EBA asset in the test environment, and import that deployment manifest into the EBA asset in the production environment.

The file to import must be a valid deployment manifest file, using the naming format file_name.MF, for example DEPLOYMENT_TEST.MF. When you import the deployment manifest into the EBA asset, the file is renamed to DEPLOYMENT.MF.

When you import a deployment manifest into an EBA asset, the content of the deployment manifest must correspond with the existing application manifest in the EBA asset. The following content is checked:
  • The Application-SymbolicName and Application-Version in the deployment manifest must match the corresponding entries in the application manifest.
  • The list of bundles in the Deployed-Content header in the deployment manifest must be the same as the list of bundles in the Application-Content header in the application manifest.
  • The version of each bundle that is listed in the Deployed-Content header in the deployment manifest must be within the version range for the corresponding bundle that is listed in the Application-Content header in the application manifest.
  • All bundles that are listed in the Deployed-Use-Bundle header in the deployment manifest must be in the list of bundles in the Use-Bundle header in the application manifest. (The Use-Bundle header can list more bundles than the Deployed-Use-Bundle header).
  • The version of each bundle that is listed in the Deployed-Use-Bundle header in the deployment manifest must be within the version range for the corresponding bundle that is listed in the Use-Bundle header in the application manifest.

The application resolving process checks whether the deployment manifest contains all the required bundles. It should not need to pull in extra bundles to resolve the EBA asset.

When a deployment manifest is imported successfully, it is used the next time that the application starts.


Icon that indicates the topic type Concept topic

Terms and conditions for information centers | Feedback


Timestamp icon Last updated: Saturday, 20 October 2012
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=v700osgijpa&product=was-nd-mp&topic=ca_about_eba

Copyright IBM Corporation 2009, 2012.
This information center is powered by Eclipse technology. (http://www.eclipse.org)