[Bug 70164] New: The description of testOnBorrow is incorrect

https://bz.apache.org/bugzilla/show_bug.cgi?id=3D70164

            Bug ID: 70164
           Summary: The description of testOnBorrow is incorrect
           Product: Tomcat 11
           Version: 11.0.24
          Hardware: PC
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Documentation
          Assignee: [email protected]
          Reporter: [email protected]
  Target Milestone: -------

There appears to be an error in the description of `testOnBorrow` in the
official Tomcat JDBC Pool documentation.

The current documentation states:

> testOnBorrow
> (boolean) The indication of whether objects will be validated before bein=
g borrowed from the pool. If the object fails to validate, it will be dropp=
ed from the pool, and we will attempt to borrow another. In order to have a=
 more efficient validation, see validationInterval. Default value is false

https://tomcat.apache.org/tomcat-11.0-doc/jdbc-pool.html#Common_Attributes

The description states that "and we will attempt to borrow another" but in
reality, it does not attempt to borrow a different connection object
(PooledConnection instance). Instead, it attempts to reconnect using the sa=
me
connection object and if the reconnection attempt also fails, an SQLExcepti=
on
is thrown. This description appears to have been quoted directly from Commo=
ns
DBCP, but the behavior differs between
`org.apache.tomcat.dbcp.pool2.impl.GenericObjectPool` and
`org.apache.tomcat.jdbc.pool.ConnectionPool`.

The behavior of `org.apache.tomcat.jdbc.pool.ConnectionPool` is:

1. validate -> invalid
https://github.com/apache/tomcat/blob/11.0.24/modules/jdbc-pool/src/main/ja=
va/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L861

2. reconnect
https://github.com/apache/tomcat/blob/11.0.24/modules/jdbc-pool/src/main/ja=
va/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L880

3. release
https://github.com/apache/tomcat/blob/11.0.24/modules/jdbc-pool/src/main/ja=
va/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L901

4. throw SQLException
https://github.com/apache/tomcat/blob/11.0.24/modules/jdbc-pool/src/main/ja=
va/org/apache/tomcat/jdbc/pool/ConnectionPool.java#L904

--=20
You are receiving this mail because:
You are the assignee for the bug.=