From APIDesign

Many systems store their configuration in some form of property files. Files which contain string key/value mappings. This is indeed an example from the APITypes, as changes to these values influence behaviour of those systems. This may seem much more trivial form of an API than Java classes and their signatures and in some way it is, however the rules of proper API Design are still applicable: one needs to keep BackwardCompatibility, be ready for API evolution, etc.

Bundle Manifest Troubles

One commonly used property file in Java is the JAR manifest. It contains tag/value mappings for one main and many per entry sections. Many systems including NetBeans Runtime Container or OSGi recognize values of their own tags and based on them prepare runtime environment for the classes contained in the JAR file. Recently I was playing a bit with Felix and was trying to create a bundle (a JAR with OSGi manifest) that will require another bundle:

Manifest-Version: 1.0
Require-Bundle: does.no.exists;bundle-version="[1.0,2.0)"
Export-Package: org.bar
Bundle-Version: 1.1.0
Bundle-SymbolicName: org.bar

As the bundle does.no.exists does not exists, I would expect the system to refuse to start the org.bar bundle. To my biggest surprise, my bundle was successfully started. I've spend few days trying to find out what is wrong. Did I make a typo? No. Did I read the OSGi specification incorrectly? Neither. Is Felix broken? Let's debug it! Or rather not, this is not cluelessness! I do not want to be an expert at Felix, I am just an OSGi API user! So what is wrong?

At the end I decided to email Richard Hall, Felix maintainer and send him my org.bar bundle. In a minute I got an answer back, as he spotted the problem immediately, the following tag was missing:

Bundle-ManifestVersion: 2

After adding it, everything started to behave as expected. The bundle is now rejected, as the Require-Bundle dependency cannot be satisfied. It is easy to use an API if you resolve your problems by asking author of the specification. However this is probably not really scalable and there seems to be something wrong with the OSGi manifest API.

Ready for Evolution

An important rule when designing an API is to prepare it for evolution. Why? Because first version is never perfect, you will always need to release subsequent ones to fix bugs and provide new enhancements.

It is sometimes hard to remind ourselves of the need for evolution, especially when we are about the release the first version. We feel we did our best. We believe we created the most ingenious API on the Earth. It is hard to remind ourselves that the same API is also supposed to be imperfect. This requires a little bit of Doublethink. Still we need to do it, otherwise we and our API users will be in deep problems in the future - as my OSGi manifest adventure shows.

When the OSGi team designed its first specification, it did the best possible job. It defined few manifest tags and described how they shall be interpreted, it also prescribed that unknown tags (for example those provided by other systems) shall be ignored. So far so good, it is always easy to create the first version...

However later they needed to add the Require-Bundle tag. At that point it became clear that there is need for evolution. It is necessary to indicate whether the API user wants to use new OSGi specification (which understands the enhanced set of tags) or the old one (where Require-Bundle has no meaning). What can we do? Well, we need to version the property/manifest file! That is why the specification now defines the Bundle-ManifestVersion tag. Since now, every new specification release which adds new tags will boost the manifest version number to let the API user properly indicate which set of tags shall be recognized.

However, it is too late! As the Bundle-ManifestVersion tag was not introduced in the first version of the specification, it can only be optional, not required. If it is missing, the OSGi framework cannot refuse the JAR, it needs to assume that it is old JAR written against the first version. Sometimes the assumption is wrong, and then poor users like me (who forget to add Bundle-ManifestVersion tag) cannot stop wondering what is going on!

If the specification was ready for evolution since its first version, it would require presence of

Bundle-ManifestVersion: 1

in each bundle. Without this tag, the bundle would be rejected. The API users would be forced to specify which version they are wanting to use and all my troubles described above would be prevented.

What is the takeaway? When you design an API based on PropertyFiles, don't forget to include a version identifier in it. Only then your API becomes ready for evolution.

Comments?

Wayne Beaton said ...

Richard S. Hall said ...

Richard S. Hall said ...

Chris Aniszczyk said ...

JaroslavTulach said ...

Ansgar Konermann said ...

Assovorge said ...