Current specdiffs for JDBC 4.2

[Mark Rotteveel]

On 18-12-2012 17:53, Lance Andersen - Oracle wrote:
> Can be found at http://cr.openjdk.java.net/~lancea/8005080/specdiffs.00/.  Currently I am having issues pulling over the openjdk website to update so from talking with Alan this made the most sense to do.
>
> There will be additional changes for 310 in which will add a couple of methods to java.sql Date, Time, Timestamp to aid in moving to/from LocalDate, LocalDateTime, LocalTime.   This will be done as part of the 310 integration work.  When310 integration is done, updates will also be added to Types.java and JDBCTypes.java
>
> No support for SQL Interval or the 310 Period will happen in this release as it is not a priority and we have to think it out more as Period does not quite line up with what we need for SQL Interval (and this is not a big priority from JDBC vendors)
>
> Additional minor cleanup and clarifications will probably happen in some of the other methods before the end game as time permits

I see several textual things that are not clear to me:

http://cr.openjdk.java.net/~lancea/8005080/specdiffs.00/java/sql/CallableStatement-report.html#method:setObject(java.lang.String,%20java.lang.Object,%20int) 

(and other methods both in CallableStatement and PreparedStatement).

"The second parameter must be of type Object; therefore, the java.lang 
equivalent objects should be used for built-in types."

I know this sentence is used already used in Java 7 Javadoc (and 
probably older), but it is not really helpful. If you read this javadoc 
without the spec you have no idea what this actually means, additional 
clarification would really be helpful (to end-users of JDBC); especially 
as some of those objects aren't even in java.lang (eg java.sql.Timestamp)

http://cr.openjdk.java.net/~lancea/8005080/specdiffs.00/java/sql/CallableStatement-report.html#method:registerOutParameter(int,%20java.sql.SQLType)
(and other methods accepting java.sql.SQLType)

I think it is unfortunate that there are no methods accepting the 
java.sql.JDBCType enum directly (as an enum); it makes - as a driver 
implementer - only supporting the basic enum a bit more cumbersome.

http://cr.openjdk.java.net/~lancea/8005080/specdiffs.00/java/sql/DatabaseMetaData-report.html#method:supportsRefCursors()

What are REF CURSORs, and what are the semantics of a REF CURSOR; is 
this purely a change to support the Oracle concept of ref cursor, or are 
there other databases that support this (or a similar) concept (if so 
which databases)?

http://cr.openjdk.java.net/~lancea/8005080/specdiffs.00/java/sql/JDBCTypes-report.html#method:getName()

Will this simply return the enum name?

http://cr.openjdk.java.net/~lancea/8005080/specdiffs.00/java/sql/JDBCTypes-report.html#method:getVendor()
http://cr.openjdk.java.net/~lancea/8005080/specdiffs.00/java/sql/JDBCTypes-report.html#method:getVendorTypeNumber()

Out of curiosity: what would be returned for these methods in JDBCTypes, 
as they don't seem to be very useful (to be honest: I don't really see 
the added value of the SQLType interface in its current incarnation)

Will getVendorTypeNumber() return the value for the same type in 
java.sql.Types? And if so, shouldn't that be mentioned in the javadoc?

http://cr.openjdk.java.net/~lancea/8005080/specdiffs.00/java/sql/PreparedStatement-report.html#method:executeLargeUpdate()
(and similar methods in Statement etc returning large update counts)

What should a driver do or return if the database cannot return values 
larger than Integer.MAX_VALUE; should it throw 
SQLFeatureNotSupportedException, or should it simply return the same 
value as executeUpdate?

http://cr.openjdk.java.net/~lancea/8005080/specdiffs.00/java/sql/SQLType.html

"An object that is used to identify a generic SQL type, called a JDBC 
type or a vendor specific data type."

This description is not really helpful (and as a nitpick: it is not an 
object, but an interface). Also as I said above, at this time I don't 
really see the added value of this interface. What is it supposed to do, 
or how should it be used?

http://cr.openjdk.java.net/~lancea/8005080/specdiffs.00/java/sql/Statement-report.html#method:getLargeMaxRows()

Method should refer to setLargeMaxRows(long) instead of setMaxRows(int)

http://cr.openjdk.java.net/~lancea/8005080/specdiffs.00/java/sql/Statement-report.html#method:setEscapeProcessing(boolean)

"The Connection and DataSource property escapeProcessing may be used to 
change the default escape processing behavior. A value of true (the 
default) enables escape Processing for all Statement objects. A value of 
false disables escape processing for all Statement objects. The 
setEscapeProcessing method may be used to specify the escape processing 
behavior for an individual Statement object."

It is very easy to read this addition as if calling 
setEscapeProcessing(false) on a Statement will disable it on all 
Statement objects. It may need to be rewritten for clarification.

BTW: Is this escapeProcessing property new, and if so is it also in the 
spec?

http://cr.openjdk.java.net/~lancea/8005080/specdiffs.00/javax/sql/XADataSource.html

There is an asterisk after "(JNDI).", Javadoc formatting error?

Mark
-- 
Mark Rotteveel