A DESCRIPTION OF THE PROBLEM :
1.)
It's not clear, if the creation of the physical connection and the Connection object should be established by ConnectionPoolDataSource#getPoolConnection() or PooledConnection#getConnection().
IMHO ConnectionPoolDataSource#getPoolConnection() should establish the physical connection and the Connection object, which can be retrieved from a data source by DataSource#getConnection() if connection pooling is being done, by initiating the the implemented connection pool manager to check out the Connection object, on invoking PooledConnection#getConnection().
It's conceivable, that PooledConnection#getConnection() creates the physical connection and the Connection object at the first invocation if lazy creation is desired.
2.)
It's not really clear, if a Connection object is actually a handle to a PooledConnection object or vice versa, and if the PooledConnection object or the Connection object represents the physical connection. What means 'is a handle of' against 'represents'?
3.)
It's not really clear, if a connection pool manager unregisters the ConnectionEventListener which is the handle from the PooledConnection object, after the Connection is closed and the PooledConnection object is returned to the pool of connections.

IMHO these ambiguities have lead to a wrong implementation of sun.jdbc.odbc.ConnectionPoolDataSource (see Review ID: 1000152)

I'm debugging Sun's JDBC-ODBC-bridge (see https://jdbc-odbc-enhanced.dev.java.net/). I must have clarity about this issue, to implement the correct behaviour.


EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
Header documentation of Interface PooledConnection should be clarified.

Method PooledConnection#getConnection():
Returns a Connection object that is a handle for the physical connection that this PooledConnection object represents. If lazy creation is desired, the physical connection and the Connection object can be created here at the first invocation.

Also synchronize the documentation of Interface ConnectionPoolDataSource to this.
ACTUAL -
1.)
Header documentation of Interface PooledConnection:
... If no PooledConnection object is available, the connection pool manager calls the ConnectionPoolDataSource method getPoolConnection to create a new physical connection. ...
Method documentation of getConnection():
Creates and returns a Connection object that is a handle for the physical connection that this PooledConnection object represents. ...
2.)
Header documentation of Interface PooledConnection:
... A PooledConnection object represents a physical connection ...
... that Connection object is actually a handle to a PooledConnection object, which is a physical connection.
... a Connection object that is a handle to that physical connection.
Method documentation of getConnection():
... a Connection object that is a handle to this PooledConnection object.
3.)
Header documentation of Interface PooledConnection:
... The connection pool manager deactivates the handle to the PooledConnection object ...


URL OF FAULTY DOCUMENTATION :
http://java.sun.com/javase/6/docs/api/javax/sql/PooledConnection.html