On the JDBC API incompatibility in Java 6 / JDBC 4.0

I updated the venerable avalon logkit for JDBC 4.0 / Java 6 today. I had to do this because that API breaks backwards compatibility for implementers.

Note that the incompatibility is very subtle – it is a source incompatibility only. As long as you don’t recompile your DataSource against the java 6 codebase, you won’t notice any problem.

The cost of API incompatibility

Spring and DBCP had to make roughly the same change 2 years or so ago, as no doubt 100s of other projects have done over the years – everyone that implements DataSource and wanted it to compile against java 6 / JDBC 4.0. Of course the pain is not over, since all those projects still want to maintain backward compatibility even when the JDBC spec did not. A recent thread about commons-dbcp is a good example.

The majority of the API incompatibilities between java 1.4 and java 6 are in fact due to the new JDBC 4.0 package. (Other significant breakages include changes to javax.net.ssl.SSLSession and org.w3c.dom.) Of all the API breakage, the changes in JDBC 4.0 probably have had by far the biggest impact, since the JDBC interfaces are explicitly designed for implementation by third parties, and are implemented in many different places.

Incompatibility by accident

This slipped through even though the relevant JSR explicitly states in its proposal:

Ensure JDBC backward compatibility

Many applications and deployments have significant investments in the JDBC technology and any improvements to the API, the provision of utility class methods and the ability to utilize meta data facilities and generics will maintain backward compatibility to all previous JDBC specifications.

And the final draft spec says something similar:

Maintain backward compatibility with existing applications and drivers

Existing JDBC technology-enabled drivers ( JDBC drivers) and the applications that use them must continue to work in an implementation of the Java virtual machine that supports the JDBC 4.0 API. Applications that use only features defined in earlier releases of the JDBC API will not require changes to continue running. It should be straightforward for existing applications to migrate to JDBC 4.0 technology.

The spec doesn’t mention the incompatibility in its revision history or in the overview of the new features.

The expert group was led by someone from Sun, and there was participation from IBM, BEA, Oracle, MySQL, and many others. The executive committee for the JCP (which includes Apache, Google, HP, and others) unanimously approved the JDBC 4.0 API several times.

Even though JSRs have to have extensive TCKs (Technology Compatibility Kits), and even though the spec was co-authored and reviewed by a large sampling of vendors of JDBC technology, and even though Sun has extensive QA processes, this change still slipped through.

I wish I could read through the mailing list archives or the bug tracker for the JSR expert group’s work, to see if its possible to figure out if anyone found this problem before they released the spec. It’s obvious (to me) now that they made a mistake here, but I wonder if they were aware of the impact of this change back then. Alas, that data is not available.

Preventing incompatibility by automation

Something like this could have trivially been avoided if someone had bothered to run JAPI, the API comparison tool that Kaffe uses, or if someone had put the JDBC 4.0 draft API into a large-scale integration tool like gump.

It seems pretty obvious to me that doing spec development and API evolution in the open is a really good way to increase quality of the specification. This is a good concrete example of why doing open development matters.