Appendix D: Change History

• Revised the description of transactions to remove references to the obsolete beginTransaction method (9.3).
  
  
• Fixed various minor spelling errors, miscapitalizations, and inconsistencies in method names, particularly in the DatabaseMetaData interface.
  
  
• Added methods to SQLWarning for managing chains.
  
  
• Specified that metadata methods should throw exceptions rather than returning null ResultSets if you try to retrieve catalog information that isn't available. (See comment at the head of DatabaseMetaData.java).
  
  
• Moved various historical notes from the main text to Appendix A.
  
  
• Added Statement.executeUpdate and modified Statement.execute. Broadly speaking, the execute method is intended for dynamic programming whereas executeQuery and executeUpdate are intended for simple statement execution.
  
  
• Rewrote Section 5.3 to clarify security requirements for JDBC driver implementors.
  
  
• Added DriverManager.println for logging to the JDBC log stream.
  
  
• Removed DriverManager.loadDriver and modified Section 6.6 to advise that you use Class.forName to load drivers (this reflects Java classloader implementation issues.)
  
  
• Clarifications in Section 11 but no interface changes.
  
  
• Removed ParameterMetadata. The contents were a subset of the information returned by DatabaseMetaData.getProcedureColumns and the latter interface is much more complete.
  
  
• Renamed Environment to DriverManager. This name better reflects the final functionality of this class.
  
  
• Stated that JDBC will do space padding for CHAR(n) fields (Section 8.3).
  
  
• Added section 7.4 to describe data truncation rules.
  
  
• Removed ResultSet.getRowNumber. This is easy for application to do themselves.
  
  
• Changed constant values for transaction isolation levels to be the same as ODBC.
  
  
• Removed ResultSet.getRowCount. Several reviewers had expressed concern that this was prohibitively expensive to implement.
  
  
• Removed ResultSet.getColumnCount. This method is unnecessary as there is already a ResultSetMetaData.getColumnCount method and programmers requiring to know the number of columns are also likely to require other column metadata.
  
  
• By popular demand added additional ResultSet methods to retrieve values by column name.
  
  
• Made ResultSet an abstract class (rather than an interface) so we could provide default implementations of the methods that take column names. (Note: we are nervous about the implications of this and are still reviewing this decision.)
  
  
• Added Statement.setCursorName
  
  
• Added Java "doc comment" stylized comments to many of the API descriptions.
  
  

Changes between 0.60 and 0.70

• Added separate ResultSet warning chain (and access methods) in addition to the Statement warning chain.
  
  
• Clarified the behaviour of getAscciStream and getUnicodeStream on ResultSets.
  
  
• Clarified the behaviour of setAsciiStream and setUnicodeStream on PreparedStatements.
  
  
• Stated explicitly that LONGVARCHAR and LONGVARBINARY are not supported for stored procedure OUT parameters (see 7.3.3 and 14.2).
  
  
• Removed getLongVarChar and getLongVarBinary from CallableStatement.
  
  
• Changed ResultSet back to an interface (rather than an abstract class). We now provide an specimen implementation of ResultSet.findColumn as reference material in Appendix C.
  
  
• Replaced ResultSet.isNull with ResultSet.wasNull. We prefer the isNull style, but early JDBC implementors discovered that it was impossible to implement isNull reliably on some databases for some data types. Unfortunately on these databases it is necessary to first attempt a read and then to check if the read returned null.
  
  
• Similarly replaced CallableStatement.isNull with CallableStatement.wasNull.
  
  
• Added Driver.jdbcCompliant to report if driver is fully JDBC COMPLIANT (tm).
  
  
• Added specification of jdbc:odbc sub-protocol URL syntax (6.3.6).
  
  
• Added LIKE escape characters (11.4).
  
  
• Added Driver.acceptURL and DriverManager.getDriver
  
  
• Stated that auto-close only applied to PreparedStatements, CallableStatements, and ResultSets and doesn't affect simple Statements (9.3).
  
  
• Added Driver.getPropertyInfo method and DriverPropertyInfo class to allow generic GUI applications to discover what connection properties a driver expects.
  
  
• Removed the SQLWarning type NullData. The wasNull method can be used to check if null data has been read.
  
  
• Clarified that ResultSet warnings are cleared on each call to "next".
  
  
• Clarified that Statement warnings are cleared each time a statement is (re)executed.
  
  
• Replaced all methods of the format getXXX or setXXX with analogous methods whose names are based on the Java type returned rather than the SQL type. Thus, for example, getTinyInt becomes getByte. See Section 7 and also Appendix A.10. This is a fairly substantial change which we made because of reviewer input that showed widespread confusion over the use of SQL types in the method names, and a widely stated preference for Java type names.
  
  
• Added additional getObject/setObject methods and extra explanatory text (14.2).
  
  
• Added sections to clarify when data conversions are and are not performed (7.1.1, 7.2.1, and 7.3.1).
  
  
• Added extra tables to clarify Java to SQL type mappings (Tables 3 and 5).
  
  

Changes between 0.70 and 0.95

• Changed the default mapping for SQL FLOAT to be Java double or Double (Tables 1, 2, 4).
  
  
• Changed the default mapping for Java float and Float to be SQL REAL (Tables 3, 5).
  
  
• Clarified that network protocol security is not a JDBC issue (Section 5).
  
  
• Renamed SQL Escape section, explaining extensions and clarifying relationship to SQL levels defined by ANSI and Microsoft's ODBC.
  
  
• Added sentence clarifying positioned updates (Section 10).
  
  
• Removed old Section 7.1 "Parameters and results in ODBC" and various other comparisons with ODBC. While this was useful for early reviewers, it's not terribly useful in the finished spec.
  
  
• Clarified that all JDBC compliant drivers must support CallableStatement but need not support the methods relating to OUT parameters (3.2, 12.1).
  
  
• Replaced disableAutoClose with setAutoClose
  
  
• Added Connection.getAutoClose and Connection.getAutoCommit
  
  
• Added Table 6 to document conversions in PreparedStatement.setObject.
  
  
• Removed the versions of ResultSet.getObject and CallableStatement.getObject that took a target SQL type. (We still retain the simpler getObject methods.) These methods were hard to implement and hard to explain and there appeared to be no real demand for them.
  
  
• Added advice on finalizers in Appendix C.2.
  
  

• Clarified that when retrieving ResultSet column values by column name then the first matching column will be returned in cases where there are several columns with the same name.
  
  
• Clarified that if you pass a Java null to one of the PreparedSattement.setXXX methods then this will cause a SQL NULL to be sent to the database.
  
  
• Added an extra column SQL_DATA_TYPE to the DatabaseMetaData.getColumns results.
  
  
• Removed the transaction isolation level TRANSCTION_VERSIONING
  
  
• Noted that if a stored procedure returns both ResultSets and OUT parameters then the ResultSets must be read and processed before the OUT parameters are read (7.3).
  
  
• Noted that for maximum portability the columns of a ResultSet should be retrieved in left-to-right order (7.1).
  
  
• Reworded some of the introduction that was written before we first released the spec.
  
  

• Removed getBinary for CHAR types from ResultSet conversion table. These were simply in error.
  
  
• Noted that the precision used for setXXX and setObject is a maximum precision value chosen by the driver.
  
  
• The description of the various SQL identifier case sensitivity and case storage modes were clarified and the JDBC driver requirements were adjusted.
  
  
• Added a note that JDBC java.io.stream.available() may return 0 whether or note data is available. JDBC drivers may not be able to provide an accurate count of available data.
  
  
• Statement.getMoreResults termination conditions were not documented correctly. This was corrected.
  
  
• Noted that Statement.executeUpdate implicitly closes the statement's current result set.
  
  
• The Driver comments were changed to note that a static section should create an instance and register it. This was a documentation error.
  
  
• Fixed parameters for getCrossReference. They were documented in error.
  
  
• Noted that a SQLException should be thrown if the driver does not support a DatabaseMetaData method.
  
  
• Noted that executeQuery never returns a null ResultSet ref
  
  
• Clarified the semantics of auto commit for the case of statements that return results.
  
  
• Removed ColumnName from the getTablePrivileges ResultSet; this was added in error.
  
  
• Noted that CallableStatement ResultSets and update counts should be processed prior to getting output parameter values.
  
  

The following changes have been made to JDBC 1.10. All of these changes are minor clarifications or additions. Unfortunately, although the removal of auto close and the java.sql.Numeric name change are minor they are not backward compatible. In particular, the name change requires that drivers must be updated to work with JDBC 1.1.

• Revised isolation level description
  
  
• Revised getTablePrivileges description to note that a privilege applies to one or more columns of the table.
  
  
• Revised preserve across commit/rollback metadata to specify positive case while allowing negative case result in partial preservation.
  
  
• Added NO ACTION and SET DEFAULT values for getImportedKeys, getExportedKeys and getCrossReference ON DELETE and ON UPDATE
  
  
• Added DEFERRABILITY attribute to getImportedKeys, getExportedKeys and getCrossReference
  
  
• Removed the auto close facility
  
  
• Rename java.sql.Numeric to java.lang.Bignum
  
  
• Note that for maximum portability values less than 256 should not be used for setMaxFieldSize
  
  
• Changed initialization of SQLState to null from "" to agree with initialization of reason.
  
  
• Clarify definition of Date, Time and Timestamp
  
  
• Added private constructor to DriverManager and Types to prevent instantiation.
  
  
• Added millis constructor for Date, Time and Timestamp
  
  
• Clarified default values for the SQLException, SQLWarning, DriverPropertyInfo and DataTruncation constructors.
  
  

• The java.lang.Bignum class was replaced by the java.math.BigDecimal class. All Bignum parameters were changed to BigDecimal; all operation names that included the term Bignum were changed to use BigDecimal.
  
  
• The driver property name was incorrect. The correct name is `jdbc.drivers'; it was incorrectly noted as `sql.drivers'.