Current specdiffs for JDBC 4.2

[Lance Andersen - Oracle]

On Dec 18, 2012, at 3:02 PM, Lance Andersen - Oracle wrote:

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

If a JDBCType such as JDBCTYPES.INTEGER is passed you can still use as an enum

We had lengthy discussions on this in 2010 and early 2011 on this and it was felt that passing an enum was too restrictive.  
>> 
>> 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()

JDBCTypes will return  java.sql (see the javadoc for JDBCTypes)
>> 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?

One of the problems that we had was a collision of integer values being used by vendors for their own data types and this caused problems and we had a firedrill right before Java SE 6 shipped as one of the Integer values we chose for JDBC 4.0 was used by a large database vendor with their JDBC Driver.  As you cannot extend an enum directly this pattern gives you some of that benefit and removes the chance of a potential collision.
>> 
>> 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

Best
Lance
>> 
>> Mark
>> -- 
>> Mark Rotteveel
> 
> 
> 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
> 

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