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
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.