Java API, Trade-Off Between Ugliness and Durability

In my previous post, I complained that JMX API was not consistent about the return types of DynamicMBean's getAttribute() and getAttributes() methods.

Eamonn McManus replied with a very good explanation on why getAttributes() is designed that way in order to be consistent with setAttributes(). This bit of "ugliness" in the API is a very good compromise. It requires some attention from the API user but it helps tremendously developers providing MBeans as they don't have to deal with the atomicity of setting different attribute values. I would still object that getAttribute() should have been consistent and return an Attribute instead of the value. But I can understand that the Attribute indirection has no purpose in that case.

I like JMX API for that reason: it's both simple and flexible. There are some parts which are ugly or require more work than I would like (writing an OpenMBean is a chore with too much information that should be handled by the JVM or JMX library) but I understand that JMX is widely used and backwards compatibility is a mandatory requirement. If every new release of Java was coming with a refined JMX API without a regard to backwards compatibility, I would not praise it like I do.

Writing an API both simple and empowering is hard. Support it over several releases is a tremendous task.In the Java world, Eclipse is the front leader on that task.

Several years ago, I developed a plug-in, eclipse-jmx, to manage JMX application inside Eclipse (it is also integrated into JBoss Tools as its JMX tool). And release after release, it is still supported by Eclipse without any changes to the API calls.

The last release of eclipse-jmx was written against Eclipse 3.2 and 3 years and 4 Eclipse releases later, eclipse-jmx still works fine, you can even install it using Eclipse Marketplace. I have a love/hate relationship with Eclipse as I use it everyday but I have only admiration for its developers who have been able to craft such a software and took on themselves to support APIs over long time and multiple versions instead of pushing all the work to the contributors to constantly update their plug-ins for each new release. The beauty of Eclipse APIs is in their durability and resiliency.

If you want to know how to write great Java API, the best resources to start are Eclipse and JMX.

On a similar topic, I am having a deep look at HTML5 and its various JavaScript APIs (WebSockets, geolocation, storage, canvas, etc.). I am curious to see how they will evolve and if lessons will have been learnt from the evolution (or lack of) of the DOM API...