How do you interpret this bit of Javadoc?

Question

In the documentation for isValid(int) from java.sql.Connection (an interface):

http://java.sun.com/javase/6/docs/api/java/sql/Connection.html#isValid(int)

it states that it will throw an "SQLException if the value supplied for timeout is less then 0".

Should implementors read this as "SQLException if and only if the value supplied for timeout is less then 0" or are they free to throw it for a bunch of other reasons too?

EDIT: I guess I'm confused / annoyed why they didn't use IllegalArgumentException. I expect SQLException to mean things like "the database appears to have melted", not "you've a basic misunderstanding of what this argument is".

Answer 1

I wouldn't read it as "if and only if" (although that's probably the case). If the timeout is less than 0, an exception will definitely be thrown, but that doesn't necessarily mean it won't be thrown in other cases. I think the developers intended it to be read as "if and only if", but I'm just speculating so you can't really be sure.

Answer 2

That method checks if the timeout is less than 0; if it is, it throws the Exception. However, it is still free to throw an unintended exception during execution of the algorithm.

If you are overriding it, then you should pbehave as your superclass, just with a different implementation. Due to olymorphism, your subclass can be instantiated, but referenced as the superclass. Therefore, if you throw an exception for a reason that the superclass does not document, then you can only create confusion and potentially buggy code.

Answer 3

i would interpret it as your former interpretation ("if and only if"). i would imagine a SQLException for any other reason would not be useful to the caller. if the isValid call fails for any other reason, a return response of "false" would seem the most appropriate.

Answer 4

I think it's rather safe to assume that "if the value supplied for timeout is less then 0" is the only case where Connection isValid will throw an SQLException, but I don't think it's safe to assume for every Class and every method in general that the documented throws condition is the only condition that will cause an exception to be thrown.

Answer 5

I completely understand your frustration with JDBC. It seems like the JDBC team didn't think they needed to conform to conventions established through the rest of the Java SE platform.

This has caused me much confusion in the past, e.g., their exception handling is not as standard as it could be, as you pointed out. I also wish SQLException were a runtime exception (or at least to have to database related exception hierarchies, one checked and one unchecked). And finally, my biggest pet peeve is that indexes in JDBC are 1 indexed, when things are generally 0 indexed in the rest of Java.

In this case, I think you're probably right to assume "if and only if." That said, are you trying to implement your own driver? If so what other exception condition are you anticipating?

Answer 6

Yes, it should throw the exception if and only if the timeout value is less than 0.

If there's a problem with the connection, then the method should return false.

Answer 7

Taken as a whole, I read the javadoc to be saying that if the connection is not valid (meaning not closed and usable), or if the timeout is exceeded it will return false.

If however, something else goes wrong with the query to the database about the validity of the connection, an SQLException may still be thrown. (Say for example, the query is against a required system table of the database that is missing, or the transaction is rolled back in the middle of checking).

An SQLException will always be thrown if the timeout value is less than zero.

That being said, there a ton of problems with (JDBC in general and) this spec in particular.

What defines an invalid connection? If a database error is thrown trying to find out, can we really say that we don't know if the connection is valid. It is likely broken anyway. The only thing I can think of is that the connection still needs to be closed whereas valid == false might mean that the connection is dead, no need to close it. This leads to the next problem:

Valid is not formally defined. It means not closed and something else. But that something else is kind of vague. It should mean usable, but what if it is not closed, but not usable?

And finally, why be so intolerant of a negative number? It is just as easy to say: A value of 0 or less indicates a timeout is not applied to the database operation.

And of course the spec on isClosed() wasn't updated to recognize the new isValid(int) method.

The JDBC API truly is a travesty in general.

On the other hand if the meaning is if and only if, it should have said that, and if SQLException cannot be thrown for any other reason, then this should be a runtime exception (IllegalArgumentException for example), because passing a negative value would just be a programming error. If, on the other hand, SQLException can be thrown for other reasons, then at least it is arguable that it wasn't worth introducing a separate exception when the checked exception had to be handled anyway. I'm not sure I agree with the argument, but at least it may have merit. (Note, I'm not writing that last paragraph as evidence that the spec doesn't mean if and only if, but rather as a further criticism if that is what it means.)