A bundle is very much like a regular JAR, archived in a standard ZIP format.
The main difference between an OSGi bundle and a regular JAR is the additional headers in the manifest file that describe the bundle, providing the framework bundle information such as identity, version, and so on; as well as instructions relating to what this bundle provides as functionality and what it requires from the other bundles on the framework.
A bundle holds the resources that are needed for it to provide functionality such as Java classes, HTML files, images, embedded JARs, and so on. It also holds its OSGi header entries in the JAR manifest file. The manifest file is found under META-INF/MANIFEST.MF.
The optional OSGI-OPT/ directory can be used to store additional resources that are not needed for the proper functioning of the bundle: resources such as source code and additional documentation. The framework may choose to throw this content away, if it needs to save storage space.
Another standard OSGi directory that can also be present in a bundle archive is the OSGI-INF/ directory. This is typically used to hold bundle-related configuration and properties, used by other framework bundles when processing this bundle's registration. For example, declarative services' configurations may be placed in this directory.
As we'll see in a bit, among the OSGi manifest header entries are directives for which packages are to be exported and made available to other bundles. The other packages are private and can only be seen and used within the bundle.
The bundle uses its manifest meta-data to provide the framework with identity information, description of its content, and directives on how the framework should use this content.
When an OSGi framework attempts to resolve a bundle, it will read and process its header entries. Headers follow strict naming and format rules, the framework will ignore headers that are unknown.
The remainder of this section quickly covers the OSGi headers, stopping on a few for a more detailed description. Many of the headers described in the following sections allow optional parameters, or directives, in their syntax. Those directives are mentioned in some situations, but may have been omitted for simplicity. It is recommended that you refer to the OSGi Core Specifications documentation to get the complete syntax description.
The minimal set of headers required by an OSGi framework to correctly register a bundle is the Bundle-ManifestVersion and the Bundle-SymbolicName.
The Bundle-ManifestVersion specifies the version of the manifest header syntax. For the scope of this book, we're following version 4 of the Core Specifications. This header will have the value 2:
Bundle-ManifestVersion: 2
Combined with the bundle version, the Bundle-SymbolicName uniquely identifies the bundle within a framework.
Although not required, it is recommended that the symbolic name be based on the reverse domain name of the bundle provider. For example, the Felix Shell Service bundle, a Felix sub-project which is a project of the Apache Foundation (apache.org), has the symbolic name org.apache.felix.shell.
The Bundle-SymbolicName may also include optional parameters, or directives, such as singleton and fragment-attachment, which we won't describe here.
Some headers define the bundle requirement from the service platform, for example, the Bundle-RequiredExecutionEnvironment declares the list of execution environments this bundle requires to be present on the platform.
During the wiring process, information provided by headers such as Import-Package and Export-Package is used to know the capabilities and requirements of the bundle.
For example, the Import-Package header declares the packages that the bundle imports, that is, the packages that it needs from other bundles. The Require-Bundle header is used to declare that this bundle imports all packages exported by the specified, comma-separated, and bundle symbolic names.
The lifecycle layer allows the bundle to take part in the activation process. By providing a class as a Bundle-Activator. The bundle activator is given the execution control when (the bundle) is starting. The Bundle-ActivationPolicy specifies whether the framework should activate the bundle in a lazy manner once started or in an eager manner. Eager activation is signified by omitting the header.
The Bundle-Version header specifies the version of this bundle. A version is composed of a major part, optionally followed by a minor, micro, and qualifier parts. Those parts are dot separated. When not specified, the version of a bundle is set to 0.0.0.
We'll talk a little more about versions in Chapters 4, Let's Get Started: The Bookshelf Project, and Chapter 5,The Book Inventory bundle.
Fragments are bundles that attach to other bundles, called hosts, to extend their host with manifest headers and bundle content. They are typically used to add resources such as localization files, graphical themes, and so on. Fragments declare the host that they wish to attach with the Fragment-Host header.
Other headers are given for information purposes. They provide additional information to the bundle consumer.
For example, the Bundle-Name and Bundle-Description headers provide a human-readable name and a short description for the bundle. The Bundle-Category header tags this bundle with a set of category names. It is a comma-separated list of category names.
The Bundle-ContactAddress header provides the contact address of the vendor, and the Bundle-Copyright header contains the copyright specification for the bundle.
Many other information headers have not been listed here. The core specification is a good place to get a full listing along with a description of their usage.