java.sql.

Connection

Initialization: Step 4 (DBCP)

Methods: addObject() borrowObject() clear() close() invalidateObject() returnObject() setFactory() getNumActive() getNumIdle()

Initialization: Step 3 (Pooling)

Create an instance of some ObjectPool implementation, e.g. a GenericObjectPool. This Pool will hold the instances of java.sql.Connection.

Create an instance of some PoolableObjectFactory. In this case, as we want to pool Connections, a DBCP PoolableConnectionFactory. The instance is given all it needs to create java.sql.Connections, in particular a reference to the ConnectionFactory created earlier, as well as a reference to the Pool created earlier

Methods: activateObject() destroyObject() makeObject() passivateObject() validateObject()

org.apache.commons.dbcp.AbandonedTrace (deprecated)

extends org.apache.commons.pool. ObjectPool reference org.apache.commons.pool. PoolableObjectFactory org.apache.commons.dbcp.DelegatingConnection

implements

implements

com.mysql.jdbc.Connection

implements

reference, set through ObjectPool.setFactory() in constructor of PoolableConnectionFactory

implements

extends

reference (alternatively, a reference to a PoolingConnection if we want the Connection to keep Statements in a Pool)

reference, set a construction

org.apache.commons.dbcp.PoolableConnection

ObjectPool implementation e.g. org.apache.commons.pool. GenericObjectPool

org.apache.commons.dbcp. PoolableConnectionFactory This class encapsulates the 'raw' Connection. Its close() method makes it return to its pool instead of actually close the connection to the database.

reference _stmtPoolFactory (may be null)

org.apache.commons.pool. KeyedObjectPoolFactory

Application: Step 5
Call 'borrowObject()' on the Pool and cast it to a java.sql.Connection

reference _connFactory

Method: createConnection()

Initialization: Step 2 (DBCP)

org.apache.commons.dbcp. ConnectionFactory You need some factory to create your java.sql.Connection instances inside of the Jakarta Commons Pooling framework. Create a DriverManagerConnectionFactory, passing it the connectURI-prefix of the Drivers you are interested in: "jdbc:mysql:", as well as username, password and/or other stuff, i.e. all the things needed to create a java.sql.Connection.

Application: Step 6
Borrowing an Object from the Pool may cause a call to 'makeObject()' to the underlying Factory. This will cause a call to ConnectionFactory.createConnection() implements

implements implements

Application: Step 7
createConnection() delegates the task of creating a java.sql.Connection to the DriverManager, using its _connectUri to get the correct Driver (the one for "jdbc:mysql:" URIs). It then slaps a PoolableConnection around it and returns that. org.apache.commons.dbcp. DriverManagerConnectionFactory This is the java.sql.DriverManagerbased implementation of ConnectionFactory

Initialization: Step 5 (DBCP)

I order to make the Pool of Connections to "jdbc:mysql://127.0.0.1/mabase" available to n the PoolingDriver, you have to explicitly register the ObjectPool instance under the key "dbc:mysql://127.0.0.1/mabase" using the following code (the fact that we are using an j instance is unimportant: the Map is static to PoolingDriver!!) PoolingDriver poolingDriver = new PoolingDriver(); poolingDriver.registerPool("jdbc:mysql://127.0.0.1/mabase",pool) Do NOT generalize the URI to jdbc:mysql: for example as this is a pool of Connections to a precise database! (But you knew that, didn't you?) Note: you CANNOT directly check whether a Pool to that URI has already been registered. That would be a nice to have.

reference _connectUri

"jdbc:mysql:" This the java.sql.Driverbased implementation of ConnectionFactory This is the javax.sql.DataSourcebased implementation of ConnectionFactory

org.apache.commons.dbcp. DriverConnectionFactory

org.apache.commons.dbcp. DataSourceConnectionFactory

reference: _driver

ref: _source

Map of explicitly registered ObjectPoolinstances (static) jdbc:mysql://127.0.0.1/mabase Internal list of registered Driver instances. When asked for a Connection through DriverManager.getConnection(uri), the DriverManager asks the Drivers whether they are able to handle the passed URI by calling their Driver.acceptsURL(URL) methods. reference acceptsURL(URI) returns true if URI starts with "jdbc:mysql:"

java.sql.Driver

javax.sql.DataSource

Application: Step 8
We finally get a Connection from the com.mysql.jdbc.Driver implements

com.mysql.jdbc.jdbc2.optional. MysqlDataSource java.sql.Driver

java.sql.Driver

reference acceptsURL(URI) returns true if URI starts with "jdbc:apache:commons:dbcp:"

implements

implements reference to some internal list of Driver instances

com.mysql.jdbc.Driver

ref:_pools

org.apache.commons.dbcp. PoolingDriver

Initialization: Step 1b (DBCP)

Class.forName(corg.apache.commons.dbcp.PoolingDriver) will autoregister a PoolingDriver instance into DriverManager using DriverManager.registerDriver(Driver)

java.sql.DriverManager (singleton instance, associated to current Classloader)

Initialization: Step 1a (MySQL)

Class.forName(com.mysql.jdbc.Driver) will autoregister a Driver instance using DriverManager.registerDriver(Driver)

Application: Step 4
The pool that is associated to the right substring of the connectionURI for which "jdbc:apache:commons:dbcp:" has been removed on the left is fetched. In this case, "jdbc:mysql://127.0.0.1/mabase". Actually, if no appropriate pool exists, PoolingDriver tries to instantiate a new ObjectPool using a .jocl config file for which it looks in the CLASSPATH

Application: Step 3
All requests for new Connections with a connectionURI starting with "jdbc:apache:commons:dbcp:" are delegated by the java.sql.DriverManager to the registered org.apache.commons.dbcp.PoolingDriver.

Simple (and incomplete) diagram showing the structure set up by the org.apache.commons.dbcp/org.apache.commons.pool packages
The diagram also shows: What steps must be taken to set up the structure in the first place. What happens when a new java.sql.Connection is requested Assumptions: We assume that we are using org.apache.commons.dbcp.DriverManagerConnectionFactory to create the java.sql.Connections (instead of org.apache.commons.dbcp.DataSourceConnectionFactory for example). We also assume that we use the MySQL database and the com.mysql.jdbc.Driver to connect to it.

Application: Step 1
Define your new poolingConnectionURI as "jdbc:apache:commons:dbcp:" + your non-pooling connectionURI. For example, instead of "jdbc:mysql://127.0.0.1/mabase" use "jdbc:apache:commons:dbcp:jdbc:mysql://127.0.0.1/mabase"

Application: Step 2
To obtain a new Connection to your database, just call DriverManager.getConnection(poolingConnectionURI,properties), where your poolingConnectionURI is, e.g. "jdbc:apache:commons:dbcp:jdbc:mysql://127.0.0.1/mabase"

Application: Step 9
To return the Connection to its pool, call Connection.close(). As the Connection is really a org.apache.commons.dbcp.PoolableConnection, it will just return to its pool

Author and current maintainer: d.tonhofer@m-plify.com

Version 1.0, 2004-04-11