3.4. Bundle
A bundle is a form of packaging for services. It is also a functional unit with life cycle operations and class loading capability. Lastly, it contains well-defined “hooks” that allow it to be plugged into the framework.
3.4.1. A Bundle Is a Packaging Vehicle
A bundle is a JAR file that contains class files and resources such as images, HTML pages, and other data files. Bundles are usually delivery and deployment vehicles for services. For instance, a bundle that contains the music player service may also include a collection of MP3 files to play. Another bundle that contains a lighting control service may also come with a set of HTML pages and images that serve as its user interface. Packaging code together with data makes deployment very convenient. Figure 3.2 presents an internal layout of a bundle JAR file that contains the player service.
Figure 3.2. An internal structure of a bundle.
The contents of the bundle show that it contains the class files of the interface and implementation for the digital music player service as well as the resources of a sample MP3 tune and a user interface in HTML for the player.
3.4.2. A Bundle Is a Functional Module
A bundle is not just a static archive. It is associated with life cycle operations and it is self-contained with respect to class loading.
3.4.2.1. Bundle Life Cycle
A bundle can be installed, started, updated, stopped, and uninstalled by the framework. A detailed explanation of the life cycle operations is forthcoming in “Life within the Framework,” on page 39. Each of these actions moves the bundle to a new state. Figure 3.3 shows the bundle state transition.
Figure 3.3. Bundle state transition diagram
In the last chapter, we had a taste of the bundle life cycle operations when we installed, started, stopped, and uninstalled the “sweet home” bundle using the command console.
Once a bundle is started, it becomes active, meaning that it works according to the prescription of the design. For instance, after an HTTP bundle is started, it is ready to accept requests from Web browsers.
3.4.2.2. Bundle Class Loading
A bundle is self-contained. Each active bundle has its own class loader that, by default, can load classes only from within the bundle itself. Code within one bundle cannot refer to classes inside another bundle, let alone instantiate them or invoke their methods. This is how bundles achieve insulation from one another. The system classes or the classes on the CLASSPATH are exceptions, of course, and they are always available to all bundles.
This feature protects classes in one bundle from running into conflicts with those in another, and prevents code in one bundle from interacting with that in another in haphazard and potentially dangerous ways. For instance, if one bundle defines a class foo.Bar and another bundle happens to define a class with the same name but entirely different semantics, and the package foo is not exported and shared (see “Exporting and Importing Packages” on page 34), the two bundles can coexist, and both versions of foo.Bar can be loaded and executed without a problem within the Java virtual machine.
3.4.3. The “Hooks” to the Framework
Because bundles are to be installed into the framework, standard interfacing mechanisms are defined within each bundle from which the framework learns how to host the bundle. They are the manifest and the activator of the bundle.
3.4.3.1. The Manifest
The manifest file is a standard entry in a JAR file. It includes meta-information about the archive itself, such as the checksums and signatures of the individual files when the JAR file is digitally signed. An additional set of manifest headers have been defined in the OSGi Service Gateway Specification from which the framework can gain knowledge about the bundle to host it successfully. This file is shown as the META-INF/MANIFEST.MF entry (Figure 3.4) in the music player example presented earlier, and it may declare the following:
Figure 3.4. The internal structure of the bundle.
This declaration identifies to the framework that this bundle's activator (discussed in the next section) is the player.impl.Activator class. The bundle exports classes in the player.service package and requires the http.service package to be exported by another bundle.
3.4.3.2. The Bundle Activator
The activator is implemented by a bundle to perform customized operations at the time when the bundle is started and stopped. It implements the start and stop methods of the org.osgi.framework.BundleActivator interface, which is defined as follows:
public interface BundleActivator { public void start(BundleContext context); public void stop(BundleContext context); }
In the player example, player/impl/Activator.class is the activator included in the JAR file (Figure 3.4).
Recall from the previous chapter that the SweetHome class that we wrote is an implementation of a bundle activator.
Having introduced the various pieces, we illustrate the entire internal structure of a bundle in Figure 3.5.
Figure 3.5. The anatomy of a bundle
Because the interaction between bundles and the framework is standard, the bundles can be developed outside their hosting environment. The developers can focus on the service that the bundle is to provide, and they can do so off the target device. In principle, once the development work is completed, one can be assured that the resultant JAR file is ready for any OSGi-based framework from any vendor.