Example: OSGi application manifest file

The OSGi bundles in an enterprise bundle archive (EBA) file share services with other OSGi applications by declaring them in an application manifest file, META-INF/APPLICATION.MF. 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.

The application manifest describes modularity at the application level. It uses configuration by exception, that is, you supply values only when you want to override the default. An EBA file does not have to contain an application manifest file. 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.

The application manifest specifies the bundles that form the primary content of the application. A bundle that is listed in the primary content might use a package that is not included in the application, and therefore require other bundles to be pulled in. The application manifest might also specify an allowed version range for some bundles; this range defines the initial version of the application, and the latest version to which it can be upgraded.

Eclipse tools provides convenient editors for the manifest file.

Here is an example application manifest file, META-INF/APPLICATION.MF:
Manifest-Version: 1.0
Application-ManifestVersion: 1.0
Application-Name: My Club
Application-SymbolicName: com.myclub.app
Application-Version: 1.0
Application-Content: 
  com.myclub.api; version=1.0.0,
  com.myclub.persistence; version=1.0.0,
  com.myclub.web; version="[1.2.0,1.2.5)",
  com.myclub.common; version="(1.2.0,2.0.0)"
Application-ImportService: com.myclub.security.authenticationService; filter="(security=strong)"
Application-ExportService: com.myclub.memberService
Use-Bundle: com.clubs.utils; version="[1.0.0,1.1.0)"
The metadata in an application manifest file includes 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. The value must not be the same as the value of the Bundle-SymbolicName header for any bundle or composite bundle in the application, as listed in the Application-Content header.

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, dependencies are analyzed when the application is deployed and other bundles are 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.

Important: If your application contains web application bundles, EJB bundles, or persistence bundles, you must list these bundles in the Application-Content header. If you do not list these bundles in the Application-Content header, they are provisioned to the shared bundle space, and they can continue to provide packages, but their contents are not be processed by web, EJB or JPA containers, and they will therefore not function correctly.
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 only 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 only 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.