jdbc - jConnect4 pooled connection does not work as documented -

official sybase jconnect programmers reference suggests following way use pooled connections:

sybconnectionpooldatasource connectionpooldatasource = new sybconnectionpooldatasource(); ... connection ds = connectionpooldatasource.getconnection(); ... ds.close(); 

however getdatasource causes exception. decompiled sybconnectionpooldatasource , found method call explicitly generates error:

public connection getconnection() throws sqlexception {     errormessage.raiseerror("jz0s3", "getconnection()");     return null; } 

does have idea why documentation contradicts implementation?

i can't comment sybase because 1) don't use , 2) link doesn't work, can try give theory based on own experience maintaining jdbc driver (jaybird/firebird jdbc) , looking @ of other implementations do.

the connectionpooldatasource least understood part of jdbc api. contrary naming suggests , how has been implemented in jdbc implementations interface should not provide connection pooling , should not implement datasource (or @ least: doing can lead confusion , bugs; my own experience).

the javadoc of connectionpooldatasource not helpful, javax.sql package documentation provides little bit more info, need @ jdbc 4.1 specification, chapter 11 connection pooling idea how should work:

[...] jdbc driver provides implementation of connectionpooldatasource application server uses build , manage connection pool.

in other words: connectionpooldatasource isn't meant direct use developer, instead used application server connection pool; isn't connection pool itself.

the application server provides clients implementation of datasource interface makes connection pooling transparent client.

so connection pool made available user means of normal datasource implementation. user uses 1 doesn't provide pooling, , uses connections obtained if normal physical connection instead of 1 obtained connection pool:

when application finished using connection, closes logical connection using method connection.close. closes logical connection not close physical connection. instead, physical connection returned pool can reused.

connection pooling transparent client: client obtains pooled connection , uses same way obtains , uses non pooled connection.

this further supported documentation of pooledconnection (the object created connectionpooldatasource):

an application programmer not use pooledconnection interface directly; rather, used middle tier infrastructure manages pooling of connections.

when application calls method datasource.getconnection, gets connection object. if connection pooling being done, connection object handle pooledconnection object, physical connection.

the connection pool manager, typically application server, maintains pool of pooledconnection objects. if there pooledconnection object available in pool, connection pool manager returns connection object handle physical connection. if no pooledconnection object available, connection pool manager calls connectionpooldatasource method getpoolconnection create new physical connection. jdbc driver implementing connectionpooldatasource creates new pooledconnection object , returns handle it.

unfortunately, of jdbc drivers have created data sources provide connection pooling implementing both datasource , connectionpooldatasource in single class, instead of intent of jdbc spec of having datasource uses connectionpooldatasource. has resulted in implementations work if used normal datasource, break if used connectionpooldatasource (eg in connection pool of application server), or interface misunderstood , wrong methods used create connections (eg calling getpooledconnection().getconnection()).

i have seen implementations (including in jaybird) getpooledconnection() used access connection pool internal implementation, or connections obtained getconnection() of implementation work correctly, leading kinds of oddities , incorrect behavior when implementation used fill connection pool in application server using getpooledconnection().

maybe sybase did similar, , decided wasn't such idea changed datasource.getconnection() throw exception make sure wasn't used in way, @ same time maintaining api compatibility not removing methods defined datasource. or maybe extended normal datasource create physical connection (instead of wrapping normal one), don't want users use datasource.