APIs and versioning

Creating good, reusable APIs is hard, really hard, you just won't believe how vastly hugely mindbogglingly hard it is. You just need to look at the Java API to realize this. The Java API is probably the main reason that Java has taken off and been the success that it is. It contains a wealth of utilities that ease and speed up development.

While there are a huge number of wonderful things about the Java API it has some examples of truly terrible API design. You can probably find that somewhere it breaks every rule in the "Effective Java" book (for sale on amazon.com and amazon.co.uk, and cheaper in the UK than the US for a change).

One example is the java.util.Properties. A properties object is supposed to be a set of keys and values (like a map) where the key and value are both strings. The problem is it extends Hashtable which means you can pass it to anything that takes a Dictionary, or Hashtable. While this may seem useful it means that you can use non-string values. This can cause problems if the getProperty method is later used.

This kind of problem is inevitable because API design is so hard. So what can we do to "fix" things in the future? There are (at least) two ways to cope:

1. Maintain the API forever. This is probably the most common solution. Java is full of old, deprecated, or discouraged APIs. Hashtable, Dictionary and Vector have been replaced with Map, HashMap, List and ArrayList, most of the Date class has been deprecated.
   
   The problem with this approach is that people often still use these older APIs, even though there are better alternatives.
   
2. Version the API. A non software example of what I am thinking of the PS2 contained the old PS chip as an I/O controller and the PS games were run on that.
   
   Java does not support versioning itself, but can be supported by making use of OSGi. OSGi is a modularity system that is built on top of Java. OSGi is split into a core and a set of optional services. The core is implemented by Eclipse Equinox, Apache Felix among others. Running an application inside of OSGi allows you to provide two different, and incompatible versions of the API in the same JVM and allow the user to select the version they work with.
   

I plan on blogging some more about OSGi in the future. WAS has been built on top of OSGi since version 6.1, and I was part of the team that made this happen. While I thought that I would be done when we shipped 6.1 as an expert in the Hursley development lab I keep being dragged back, so I thought I would start blogging about my thoughts on the subject.

Alasdair