Module metadata

OSGi modules (aka bundles), are described by metadata, located in a file called
MANIFEST.MF, in the META-INF directory.


1. Metadata syntax

OSGi bundles metadata is a list of header/values informations, following the following syntax :

  name: value(s)

 

More extensively this syntax allow 4 different elements :

• Header name : Property-Name:
• Property (header) value
• Attributes (arbitrary name/value pairs) : attr1=value
• Directives (alters the framework handling of the header information) : dir1:=value

Here is an example of a full header line :

  Property-Name: propValue; attr1=foo; dir1:=bar

1.1. Human readable headers
Some of the bundle's metadata headers are human readable informations, ignored by the framework, but useful for the developper :

• Bundle-Name
• Bundle-Description
• Bundle-DocURL
• Bundle-Category
• Bundle-Vendor
• Bundle-ContactAddress
• Bundle-Copyright

1.2. Bundle identification headers
Some other headers are used by the framework to identify a bundle :

• Bundle-SymbolicName (mandatory since OSGi R4)
• Bundle-Version (following the pattern major.minor.micro.qualifier, as in 1.1.0.alpha, the qualifier being optional) (not mandatory, defaults to 0.0.0)
• Bundle-ManifestVersion (2 means that the bundle manifest follows OSGI R4 specs, defaults to 1)

Bundle version order follows the rule described below :

1.3. Code visibility headers
Finally, some headers are used to describe a bundle's code visibility. They are :

• Bundle-ClassPath : defaults to . (root based) : an ordered, comma separated list of relative bundle jar files and class/resource lookup locations. If this header is used, the . must be mentionned, because it will not be included automatically. Allowed values are :
• . (the root classpath)
• path/subpath : another root to look into (useful for resources lookup like images, without having to specify the directory holding them, or even better to find resources like css, images, xml files, located in different directories, without having to use the directory in code.
• embedded.jar : the name of a jar embedded in the bundle
• Export-Package : a comma separated list of packages to expose for sharing with other bundles. It exposes all public classes of the specified packages.
• attribute discrimination : adding arbitrary attributes to an exported package allow packages importers (see Import-Package below) to discriminate bundles from which they get packages by adding the same attribute (more on that later).
• versionning : defines a version for the exported package. This attribute is not arbitrary, and can take a value following the pattern major.minor.micro. This attribute value defaults to 0.0.0 if not specified.
• Import-Package : used to import required packages (except java.*, provided by the framework).
• uses the same attributes discrimination.
• The version attribute can also be used but has a range meaning, as depicted in the following table:

 

1.4. Jar/Bundle comparison
A bundle is a jar, and can be used as such in a non OSGi framework (but only if in OSGi, it's bundle classpath was : .
A standard jar can be used as a bundle, but obviously will need at least an Export-Package declaration to be useful.