2.2. The “Home, Sweet Home” Bundle

Programming tutorials have traditionally begun with a “Hello, world” example since 1978. We are writing code for residential gateways, so home is the world for us. In this section we develop a bundle that simply displays “Home, sweet home” when it is activated, and “I'll be back” when it is deactivated.

A bundle is packaged as a Java archive (or JAR) file. A JAR file is essentially a ZIP file with a manifest, and it can be created, updated, and examined with the jar tool. More information can be found online (http://java.sun.com/j2se/1.3/docs/guide/jar/index.html).

The steps to develop the example bundle are

2.2.1. Create the Directory

Create a directory named home, change the directory to home, and save the files you are about to create there.

2.2.2. Define the Manifest

Use your favorite text editor to create a file named Manifest that contains only one line:

						Bundle-Activator: home.SweetHome

This file is a manifest stub, because at the time when the bundle JAR file is created, other meta-information will be appended to what we have just defined to form the real manifest as the META-INF/MANIFEST.MF entry in the JAR file. For the rest of the book, we just refer to this file as the manifest for the sake of brevity.

2.2.3. Write an Activator

Now create the file SweetHome.java as shown:

package home;
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

public class SweetHome implements BundleActivator {
   public void start(BundleContext ctxt) {
      System.out.println("Home, sweet home");
   }

   public void stop(BundleContext ctxt) {
      System.out.println("I'll be back");
   }
}

This class implements the BundleActivator interface, whose start and stop methods are called to perform operations when the bundle is started or stopped, respectively. In this case, they display some innocuous messages.

The parameter BundleContext ctxt is passed to the activator by the framework when the bundle is either activated or deactivated. From the bundle's perspective, it serves as the execution context for the bundle to interact with the underlying framework. In our simple example, we have no use for it.

2.2.4. Compile the Activator Class

Set your CLASSPATH environment variable to the JAR file containing the framework class library:

setenv CLASSPATH jes_path/lib/framework.jar[2]
					

^[2] We show commands in the C shell on the Solaris system. If you work in the Bourne or Korn shell, use the following to set the environment variables:

								
set CLASSPATH=jes_path/lib/framework.jar
export CLASSPATH

							

If you work on Windows platforms, use the backslash as the path separator, and set the environment variables as

								
set CLASSPATH=jes_pathlibframework.jar

							

Change to the directory a level above home, and compile the activator with

javac home/SweetHome.java

At this point, you should have the following files in the directory home:

home/Manifest
home/SweetHome.java
home/SweetHome.class

2.2.5. Pack Up

Finally, it's time to create the bundle JAR file:

						jar cmf home/Manifest home.jar home/*.class

The command option m in cmf indicates that the next argument on the command line is the manifest stub to be applied. home.jar is the bundle generated by the command. You can inspect its contents using

jar tf home.jar

which should report

META-INF/
META-INF/MANIFEST.MF
home/SweetHome.class

The META-INF directory and META-INF/MANIFEST.MF entry are standard to JAR files; the latter is the real manifest of the JAR file. Henceforth, we assume the home.jar bundle is placed at /home/joe/bundles/home.jar. Substitute it with the actual path where you save the JAR file.

The package name must correspond exactly to the directory structure, and it must be preserved in the bundle JAR file. In our example, the activator class belongs to the home package, and it is physically saved inside the directory home. This structure is also captured in the JAR file, as shown by the table-of-contents output from the jar tf home.jar command.