Attaching derby-5488-10-aa-metadataTypo.diff. This a simple candidate patch to change SCOPE_CATLOG to SCOPE_CATALOG. Regression tests pass cleanly on this patch.
Before discussing this patch and alternatives we might consider, I want to summarize my understanding of this problem:
A) The JDBC expert group regards this as fixing a typo in the javadoc. I believe that some other databases recognized the typo for what it was and always named the column SCOPE_CATALOG. Derby, however, hewed closely to the published javadoc and called the column SCOPE_CATLOG.
B) For those other databases, there is no functional change. A documentation typo has simply been corrected. For Derby, however, the change creates a backward incompatibility.
C) Derby must break one of its important constraints. There is no way that we can conform to the corrected JDBC javadoc and avoid a backward incompatibility.
D) I think that the backward incompatibility is quite minor, nevertheless. The column in question carries no meaning for Derby. The column only has meaning for databases which implement both catalogs and reference types. For Derby, the column always contains a null. I doubt that (m)any Derby users inspect this column at all, let alone by name.
Here are the user-visible effects of some possible solutions:
1) Based on engine version - The column is called SCOPE_CATALOG if DatabaseMetaData.getDatabaseMajorVersion() and DatabaseMetaData.getDatabaseMinorVersion() report that the engine is at Derby 10.9 or higher. Otherwise, the column is called SCOPE_CATLOG. This is the approach taken by this patch.
2) Based on client version - The column is called SCOPE_CATALOG if DatabaseMetaData.getDriverMajorVersion() and DatabaseMetaData.getDriverMinorVersion() report that the client is at Derby 10.9 or higher. Otherwise, the column is called SCOPE_CATLOG.
3) Based on JDBC driver version - The column is called SCOPE_CATALOG if DatabaseMetaData.getJDBCMajorVersion() and DatabaseMetaData.getJDBCMinorVersion() report that the driver is at JDBC 4.1 or higher. Otherwise, the column is called SCOPE_CATLOG.
Even fancier solutions are possible. They involve combinations of the JDBC and driver versions at the client and engine. I believe that the solutions listed above give rise to straightforward workarounds for applications affected by this change. They are easy to explain. The fancier solutions push more complexity into the application and/or involve backporting tricky code into older Derby branches.
Of the straightforward solutions, I opted for (1) because it was the easiest to implement. A casual look at options (2) and (3) suggests that they involve adding some potentially tricky code to our JDBC drivers. I did not think that this problem warranted the additional complexity.
But those are my opinions. I am open to arguments that we should solve this problem a different way.
Thanks in advance for your feedback.
Touches the following files:
Actual change to the JDBC metadata.
Corresponding change to the regression test for this metadata.