Current specdiffs for JDBC 4.2

[Lance Andersen - Oracle]

On Dec 19, 2012, at 3:48 AM, Mark Rotteveel wrote:

> On Tue, 18 Dec 2012 15:02:00 -0500, Lance Andersen - Oracle
> <Lance.Andersen at oracle.com> wrote:
>>> 
> 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
> 
> Ah, now I get how I need to read that sentence :) Isn't that comment made
> unnecessary with the introduction of auto-boxing?

Probably a fair point.  I will think about it as I would have to troll through the other setobject methods.  I might want to wait and do this as part of JDBC 4.3
> 
>>> 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
> 
> Yes, I didn't grasp its meaning; I read 'built-in types' as 'standard JDBC
> types supported by the database'.

Easy to overlook and I agree there are lots of places, especially in older APIs such as JDBC, which many methods date back to 1996, that could be clarified but it takes time to reach consensus with the JDBC Driver
vendors that have been around for a long time as we have to balance what we can clarify and make consistent vs. what has been so grey for so long that it is difficult to find a middle ground.

We continue to try and appreciate your input as sometimes you are too close to the wording you cannot see the forest through the trees :-)

We did a lot of clean-up in JDBC 4.0 and not we still have more work but it takes time.
> And so with 'equivalent' I was thinking
> of the JDBC conversion matrix listed in appendix D (?) of the spec.
> 
>>> 
> 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.
> 
> Missed that part, thanks.
> 
> What is the design reason to return an Integer here and not an int?

No specific reason, could just as easy been an int vs an Integer.
> 
>>> 
> 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
> 
> For confirmation: if the database is not capable of returning update
> counts larger than Integer.MAX_VALUE, then the methods returning large
> update counts should still be implemented by the driver, not throw an
> SQLFeatureNotSupported, and simply return the same value(s) as returned by
> the 'normal' update count equivalent methods (if so, maybe an additional
> note in the Javadoc would be good)

Yes all drivers should implement this method (with the exception of the flavors that support auto generated keys if a driver does not support it)

Application developers who  need the update count and are not sure of the number of rows that will be returned should use the new methods in place of the older methods
> 
> To account for this maybe DatabaseMetaData should get a method boolean
> supportsLargeUpdateCounts() which should return true if the database/driver
> is capable of returning an update count larger than Integer.MAX_VALUE, and
> false if it is not capable (with the added requirement that the large
> update count methods must be implemented anyway).

We talked about this but did not feel the real need as if you use executeUpdate or executeLargeUpdate and return 10 rows, the update count will be the same.  So really no reason to not use the new method for new applications.


Best
Lance
> 
> Mark

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