A DESCRIPTION OF THE REQUEST :
The JDBC 3.0 API documentation differs from the JDBC 3.0 Specification when it comes to describing the side effects of setAutoCommit() on the Connection interface.
The API states : -
"NOTE: If this method is called during a transaction, the transaction is committed."

While the JDBC 3.0 Specification document, section 10.1.1 states : -
"If the value of auto-commit is changed in the middle of a transaction, the current transaction is committed."

The API documentation should be changed to be compliant with the Specification.

JUSTIFICATION :
JDBC Driver developers are incorrectly implementing the specification. For example, jTDS, an open source Microsoft SQL Server Type 4 driver, has implemented setAutoCommit as per the API documentation. As such, using this driver within Oracle Application server 10g (9.0.4) results in updates being commited to the database within a JTS transaction, because oracle's resource manager classes calls setAutoCommit(false) every time it reuses the same connection to, for example, prepare a statement. While calling setAutoCommit(false) multiple times on the same connection might not be the best logic, I assume the developers at Oracle did not expect setAutoCommit(false) to commit the transaction when autoCommit was already false.

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
setAutoCommit() should be documented in the JDBC API documentation as per the specification, so calling setAutoCommit(false) when the current value of autoCommit is false, has no side effects.
ACTUAL -
The API documentation specifies that ANY call to setAutoCommit(), regardless of current and new value of autoCommit, results in a commit.

---------- BEGIN SOURCE ----------
N/A as this is a documentation problem
---------- END SOURCE ----------