Current specdiffs for JDBC 4.2

Tue Dec 18 12:02:00 PST 2012

See below for some initial comments will reply further later as I am off to a meeting
On Dec 18, 2012, at 2:18 PM, Mark Rotteveel wrote:

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

This dates back to JDBC 1.0 

built-in types are int, long, byte, etc so the javadocs is referring to using Integer, Long, Byte...

Could probably be better stated as a primitive data type
> 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)
Timestamp is not a built-in type
> 
> 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)?
See other email
> 
> http://cr.openjdk.java.net/~lancea/8005080/specdiffs.00/java/sql/JDBCTypes-report.html#method:getName()
> 
> Will this simply return the enum name?

in the case of JDBCTypes yes
> 
> 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?
it does say that for JDBCTypes

	 Returns:
An Integer representing the data type. For JDBCTypes, the value will be the same value as in Types for the data type.

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

This method is supported in all environments.  Today, the current methods cannot return an update count > Integer.MAX_VALUE.  Applications who care about this should migrate to the new methods.   the update count is the same
as for executeUpdate except that you can return update counts > Integer.MAX_VALUE +1 without overflow
> 
> 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)
Agree, thanks for catching the typo
> 
> 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?
Yes it is new and will be in the pdf spec
> 
> http://cr.openjdk.java.net/~lancea/8005080/specdiffs.00/javax/sql/XADataSource.html
> 
> There is an asterisk after "(JNDI).", Javadoc formatting error?
I will take a look
> 
> Mark
> -- 
> Mark Rotteveel

-------------- next part --------------

Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering 
1 Network Drive 
Burlington, MA 01803
Lance.Andersen at oracle.com