OSGI MANIFEST.MF Header 小结

1 MANIFEST 文件

Bundle Manifest Headers, META-INF/MANIFEST.MF

1.1 Java JAR format:

http://download.oracle.com/javase/1.4.2/docs/guide/jar/jar.html#JAR%20Manifest

Manifest Specification :

1.        manifest-file:                    main-section newline *individual-section

2.        main-section:                    version-info newline *main-attribute

3.        version-info:                      Manifest-Version : version-number

4.        version-number :               digit+{.digit+}*

5.        main-attribute:                 (any legitimate main attribute) newline

6.        individual-section:             Name : value newline *perentry-attribute

7.        perentry-attribute:            (any legitimate perentry attribute) newline

 

1.2 Bundle-ActivationPolicy: lazy

The Bundle-ActivationPolicy specifies how the framework should activate the bundle once started.

If the activation fails because the Bundle Activator start method has thrown an exception, the bundle must be stopped without calling the Bundle Activator stop method.

1.2.1 Lazy Activation Policy

A lazy activation policy indicates that the bundle, once started, must not be activated until it receives the first request to load a class.

Step to activate:

• A Bundle Context is created for the bundle.

• The bundle state is moved to the STARTING state.

• The LAZY_ACTIVATION event is fired.

• The system waits for a class load from the bundle to occur.

• The normal STARTING event is fired.

• The bundle is activated.

• The bundle state is moved to ACTIVE .

• The STARTED event is fired.

 

Starting with eager activation versus lazy activation

 

1.2.2 Activate Rule:

By default, any class loaded from the bundle can trigger the lazy activation, however, resource loads must not trigger the activation. The lazy activation policy can define which classes cause the activation with the following directives:

• include – A list of package names that must trigger the activation when a class is loaded from any of these packages. The default is all package names present in the bundle.

• exclude – A list of package names that must not trigger the activation of the bundle when a class is loaded from any of these packages. The default is no package names.

For example:

Bundle-ActivationPolicy: lazy; «

include:="com.acme.service.base,com.acme.service.help"

1.3 Bundle-Activator

The Bundle-Activator header specifies the name of the class used to start and stop the bundle.

A bundle is activated by calling its Bundle Activator object, if one exists. The BundleActivator interface defines methods that the Framework invokes when it starts and stops the bundle.

To inform the OSGi environment of the fully qualified class name serving as its Bundle Activator, a bundle developer must declare a Bundle-Activator manifest header in the bundle’s manifest file. The Framework must instantiate a new object of this class and cast it to a BundleActivator instance. It must then call the BundleActivator.start method to start the bundle

Activator 可有可无，在一些 Library bundle 里面可以没有 activator 。

1.4 Bundle-Category:

The Bundle-Category header holds a comma-separated list of category names.

1.5 Bundle-ClassPath

The Bundle-ClassPath header defines a comma-separated list of JAR file path names or directories (inside the bundle) containing classes and resources. The period (’.’) specifies the root directory of the bundle’s JAR. The period is also the default.

Container ， entries ， search order ， entry path ， bundle class path

Example ：

Bundle-ClassPath : lib/ant-antlr.jar,

  lib/ant-apache-log4j.jar,

  lib/ant.jar,

  .

1.6 Fragment-Host

The Fragment-Host header defines the host bundles for this fragment

Fragment-Host ::= bundle-description

bundle-description ::= symbolic-name

(';' parameter ) *

 

When a fragment bundle is attached to a host bundle, it logically becomes part of it. All classes and resources within the fragment bundle must be loaded using the class loader (or Bunde object) of its host bundle. The fragment bundles of a host bundle must be attached to a host bundle in the order that the fragment bundles are installed, which is in ascending bundle ID order.

 

About Fragment

All class or resource loading of a fragment is handled through the host’s class loader or Bundle object, a fragment must never have its own class loader, it therefore fails the class and resource loading methods of the Bundle object. Fragment bundles are treated as if they are an intrinsic part of their hosts.

Though a fragment bundle does not have its own class loader, it still must have a separate Protection Domain when it is not an extension fragment. Each fragment can have its own permissions linked to the fragment bundle’s location and signer.

A host bundle’s class path is searched before a fragment’s class path. This implies that packages can be split over the host and any of its fragments. Searching the fragments must be done in ascending bundle ID order. This is the order that the fragment bundles were installed.

1.7 Bundle-Name

1.8 Bundle-SymbolicName

引用名

The Bundle-SymbolicName manifest header is a mandatory header. The bundle symbolic name and bundle version identify a unique bundle.

 

1.        singleton – Indicates that the bundle can only have a single version resolved. A value of true indicates that the bundle is a singleton bundle . The default value is false . The Framework must resolve at most one bundle when multiple versions of a singleton bundle with the same symbolic name are installed. Singleton bundles do not affect the resolution of non-singleton bundles with the same symbolic name.

2.        fragment-attachment – Defines how fragments are allowed to be attached, see the fragments in Fragment Bundles on page 69. The following values are valid for this directive:

Ø  always – (Default) Fragments can attach at any time while the host is resolved or during the process of resolving.

Ø  never – No fragments are allowed.

Ø  resolve-time – Fragments must only be attached during resolving.

 

1.9 Bundle-RequiredExecutionEnvironment

1.10 Require-Bundle

The Require-Bundle header specifies that all exported packages from another bundle must be imported, effectively requiring the public interface of another bundle.

1.11 Bundle-Version

1.12 Provided-Capability

1.13 Require-Capability

1.14 Bundle-Localization

国际化相关

1.15 Export-Package

The Export-Package header contains a declaration of exported packages.

The header allows many packages to be exported. An export definition is the description of a single package export for a bundle.

 

Export directives are:

• uses – A comma-separated list of package names that are used by the exported package. Note that the use of a comma in the value requires it to be enclosed in double quotes. If this exported package is chosen as an export, then the resolver must ensure that importers of this package wire to the same versions of the package in this list. See Package Constraints on page 46.

• mandatory - A comma-separated list of attribute names. Note that the use of a comma in the value requires it to be enclosed in double quotes. A bundle importing the package must specify the mandatory attributes, with a value that matches, to resolve to the exported package.

• include – A comma-separated list of class names that must be visible to an importer. Note that the use of a comma in the value requires it to be enclosed in double quotes.

• exclude -A comma-separated list of class names that must be invisible to an importer. Note that the use of a comma in the value

1.16 Import-Package

The Import-Package header declares the imported packages for this bundle.

The header allows many packages to be imported. An import definition is the description of a single package for a bundle. The syntax permits multiple package names, separated by semi-colons, to be described in a short form.

An error aborts an installation or update when:

• A directive or attribute appears multiple times, or

• There are multiple import definitions for the same package, or

• The version and specification-version attributes do not match.

1.17 Bundle-ContactAddress

1.18 Bundle-Copyright

1.19 Bundle-Description

1.20 Bundle-DocURL:

1.21 Bundle-Icon

1.22 Bundle-License

1.23 Bundle-ManifestVersion: 2

1.24 Bundle-NativeCode

1.25 Bundle-UpdateLocation

1.26 Bundle-Vendor

1.27 DynamicImport-Package

1.28 Export-Service

1.29 Import-Service

1.30 其他

1.30.1 Custom Headers

The manifest an excellent place to provide metadata belonging to a bundle. This is true for the OSGi Alliance but it is also valid for other organizations. For historic reasons, the OSGi Alliance claims the default name space, specifically headers that indicate OSGi related matters like names that contain Bundle, Import, Export, etc. Organizations that want to use headers that do not clash with OSGi Alliance defined names or bundle header names from other organizations should prefix custom headerswith x- , for example x-LazyStart .

Example ：

Eclipse-SourceBundle: org.eclipse.ui.ide;version="3.6.2.M20101201-0800

  ";roots:="."

1.30.2 Common Header Syntax

Many Manifest header values share a common syntax. This syntax consists of:

header ::= clause ( ’,’ clause ) *

clause ::= path ( ’;’ path ) *( ’;’ parameter ) *

A parameter can be either a directive or an attribute . A directive is an instruction that has some implied

1.30.3 Version

version ::=

major( '.' minor ( '.' micro ( '.' qualifier )? )? )?

major ::= number // See 1.3.2

minor ::= number

micro ::= number

qualifier ::= ( alphanum | ’_’ | '-' )+

A version must not contain any white space. The default value for a version is 0.0.0.

1.30.4 Version Ranges

The syntax of a version range is:

version-range ::= interval | atleast

interval ::= ( '[' | '(' ) floor ',' ceiling ( ']' | ')' )

atleast ::= version

floor ::= version

ceiling ::= version

 

Example	Predicate
[1.2.3, 4.5.6)	1.2.3 <= x < 4.5.6
[1.2.3, 4.5.6]	1.2.3 <= x <= 4.5.6
(1.2.3, 4.5.6)	1.2.3 < x < 4.5.6
(1.2.3, 4.5.6]	1.2.3 < x <= 4.5.6
1.2.3	1.2.3 <= x