In our previous tutorial installments, we looked at how bundles can be started and stopped, and how they can interact with the framework and each other's lifecycle. But what are bundles really for?

Bundles are modules. They allow us to split apart our monolithic projects into manageable pieces which can be loaded individually into an OSGi runtime. The problem is, whether we like it or not, modules nearly always have dependencies on other modules. In plain old Jar files, there was never a reliable way to specify the dependencies on other Jars (no, the Class-Path entry in the manifest was not a reliable way of doing this). Therefore you never really knew for sure if the code in a Jar would work, or would throw ClassNotFoundException s at runtime.

OSGi fixed this problem very elegantly. But it's better to show you than tell you... so let's hurry up and get to the code. Unfortunately up until now we have been using the default package, but this won't work any more; we will need to start working with proper packages. So lets start off with a very simple JavaBean-style class, which you should copy into the file osgitut/movies/Movie.java :

package osgitut.movies;
 
public class Movie {
    private final String title;
    private final String director;
 
    public Movie(String title, String director) {
        this.title = title; this.director = director;
    }
    public String getTitle() { return title; }
    public String getDirector() { return director; }
}

Now we will create an interface in the same package. Create the file osgitut/movies/MovieFinder.java and copy in:

package osgitut.movies;
 
public interface MovieFinder {
    Movie[] findAll();
}

Now lets get these two classes into a bundle. Yes, our bundle will be ridiculously small and almost useless, but that's okay for now. As before we need to create a manifest file, so open up MoviesInterface.mf and copy in the following:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Movies Interface
Bundle-SymbolicName: MoviesInterface
Bundle-Version: 1.0.0
Export-Package: osgitut.movies;version="1.0.0"
 

There's a new line in here that we haven't seen before: Export-Package . This simply says that the package osgitut.movies is exported from the bundle. This may seem a little odd at first, because in plain old Java Jars, everything is exported. But haven't you ever wanted to put some code in a package which was only visible internally withing your Jar? Sure, you can make some classes private or protected, but then they're not visible to other packages within your Jar. So OSGi effectively has introduced a new code protection level: if a package in your bundle is not listed on the Export-Package header, then it is only accessible within your module.

You'll also notice that we attached a version number to the package. This is important as we will see later. It's not absolutely necessary to supply a version, by the way, but if you don't then OSGi will automatically assign the version "0.0.0" to your package. I think it's good practice to always add a version explicitly.

Now let's build this bundle:

> javac osgitut/movies/Movie.java osgitut/movies/MovieFinder.java
> jar -cfm MoviesInterface.jar MoviesInterface.mf osgitut/movies/*.class

We're not going to go right ahead and install that bundle into the runtime. First we're going to build another bundle that depends on it. We want to create a concrete implementation of the MovieFinder interface, so copy the following into osgitut/movies/impl/BasicMovieFinderImpl.java :

package osgitut.movies.impl;
 
import osgitut.movies.*;
 
public class BasicMovieFinderImpl implements MovieFinder {
  private static final Movie[] MOVIES = new Movie[] {
    new Movie("The Godfather", "Francis Ford Coppola"),
    new Movie("Spirited Away", "Hayao Miyazaki")
  };
 
  public Movie[] findAll() { return MOVIES; }
}

Now we need a manifest file, so create BasicMovieFinder.mf :

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Basic Movie Finder
Bundle-SymbolicName: BasicMovieFinder
Bundle-Version: 1.0.0
Import-Package: osgitut.movies;version="[1.0.0,2.0.0)"
 

Notice that we are importing the package osgitut.movies which was exported by the other bundle. We have also this time added a version range on the import. The framework uses the range at runtime to match up the import with an appropriate export. OSGi uses a syntax for version ranges that will be familiar to most mathematicias: the square bracket means "inclusive" and the round bracket means "exclusive". Effectively we have specified the version "1.x".

Again, adding the version constraint on the import wasn't particularly necessary in this case, it's just a good habit to adopt.

Now lets compile and build our second bundle of the day as follows:

> javac -classpath MoviesInterface.jar osgitut/movies/impl/BasicMovieFinderImpl.java 
> jar -cfm BasicMovieFinder.jar BasicMovieFinder.mf osgitut/movies/impl/*.class

Finally we're ready to try these bundles out in Equinox. I'm not going to give full instructions this time, as I think you should be getting the hang of it. Firstly install the BasicMovieFinder bundle, and run ss . You will find that the bundle is in INSTALLED state:

id      State       Bundle
0       ACTIVE      org.eclipse.osgi_3.3.0.v20070208
4       INSTALLED   BasicMovieFinder_1.0.0

(NB your bundle list may be starting to look a little different from mine, in particular the bundle ID will depend on how many times you installed and uninstalled the HelloWorld bundle from last time. You'll have to mentally translate the bundle IDs that follow).

INSTALLED just means that framework has got the bundle, but has not yet resolved its dependencies. One way to try to force Equinox to resolve our bundle is with the refresh command. So type refresh 4 and then ss and you should see this:

id      State       Bundle
0       ACTIVE      org.eclipse.osgi_3.3.0.v20070208
4       INSTALLED   BasicMovieFinder_1.0.0

The bundle still isn't resolved! Of course, we need to install the "interface" bundle which contains the Movie class and the MovieFinder interface. To confirm that this is the problem, type diag 4 to get diagnostic information:

file:BasicMovieFinder.jar [4]
  Missing imported package osgitut.movies_[1.0.0,2.0.0).

Yes, that was the problem: we can't import the package osgitut.movies because no bundle is currently exporting it. So now install the MoviesInterface.jar bundle and run ss . The listing will look like this:

id      State       Bundle
0       ACTIVE      org.eclipse.osgi_3.3.0.v20070208
4       INSTALLED   BasicMovieFinder_1.0.0
5       INSTALLED   MoviesInterface_1.0.0

The final step is to ask Equinox to try again to resolve the BasicMovieFinder bundle, by running refresh 4 . The output from ss will now show:

id      State       Bundle
0       ACTIVE      org.eclipse.osgi_3.3.0.v20070208
4       RESOLVED    BasicMovieFinder_1.0.0
5       RESOLVED    MoviesInterface_1.0.0

The BasicMovieFinder bundle is now RESOLVED ! This is an essential step, because until the bundle is RESOLVED it cannot be started, and it cannot supply dependencies to any other bundle.

Note that usually it's not necessary to do manual resolution like this. Normally bundles are automatically resolved when they are needed -- for example, notice that the MoviesInterface bundle is now RESOLVED even though we didn't explicitly refresh it.

That's it for now. For more fun things you can do with the Equinox console, take a look at Chris Aniszczyk's excellent article on IBM developerWorks . Stay tuned for the next installment, where we start to delve into OSGi services.

// Not sure which object gives you the getBundle method since
// I'm typing this from memory
Bundle bundle = Platform.getBundle("id.to.bundle");
// this will fail with a ClassCastException
PluginA a = (PluginA)bundle; 

Bundle bundle = context.getBundle(id);
String className = bundle.getHeaders().get("Bundle-Activator");
Class clazz = bundle.loadClass(className);

PluginA.getDefault().doSomething()

Bundle bundle = BundleContext.getBundle("PluginA.id");
// do something to the bundle to get PluginA Class
pluginA.doSomething();