Package org.apache.commons.dbcp2

Database Connection Pool API.

See: Description

Interface Summary

Interface	Description
BasicDataSourceMXBean	Defines the methods that will be made available via JMX.
ConnectionFactory	Abstract factory interface for creating Connections.
PoolableConnectionMXBean	Defines the attributes and methods that will be exposed via JMX for PoolableConnection instances.

Class Summary

Class	Description
AbandonedTrace	Tracks db connection usage for recovering and reporting abandoned db connections.
BasicDataSource	Basic implementation of javax.sql.DataSource that is configured via JavaBeans properties.
BasicDataSourceFactory	JNDI object factory that creates an instance of BasicDataSource that has been configured based on the RefAddr values of the specified Reference, which must match the names and data types of the BasicDataSource bean properties with the following exceptions:
Constants	Constants for use with JMX.
DataSourceConnectionFactory	A DataSource-based implementation of ConnectionFactory.
DelegatingCallableStatement	A base delegating implementation of CallableStatement.
DelegatingConnection<C extends Connection>	A base delegating implementation of Connection.
DelegatingDatabaseMetaData	A base delegating implementation of DatabaseMetaData.
DelegatingPreparedStatement	A base delegating implementation of PreparedStatement.
DelegatingResultSet	A base delegating implementation of ResultSet.
DelegatingStatement	A base delegating implementation of Statement.
DriverConnectionFactory	A Driver-based implementation of ConnectionFactory.
DriverManagerConnectionFactory	A DriverManager-based implementation of ConnectionFactory.
PoolableCallableStatement	A DelegatingCallableStatement that cooperates with PoolingConnection to implement a pool of CallableStatements.
PoolableConnection	A delegating connection that, rather than closing the underlying connection, returns itself to an ObjectPool when closed.
PoolableConnectionFactory	A PooledObjectFactory that creates PoolableConnections.
PoolablePreparedStatement<K>	A DelegatingPreparedStatement that cooperates with PoolingConnection to implement a pool of PreparedStatements.
PoolingConnection	A DelegatingConnection that pools PreparedStatements.
PoolingDataSource<C extends Connection>	A simple DataSource implementation that obtains Connections from the specified ObjectPool.
PoolingDriver	A Driver implementation that obtains Connections from a registered ObjectPool.
PStmtKey	A key uniquely identifying PreparedStatements.
SwallowedExceptionLogger	Class for logging swallowed exceptions.
Utils	Utility methods.

Enum Summary

Enum	Description
PoolingConnection.StatementType	Statement types.

Exception Summary

Exception	Description
ListException	An exception wrapping a list of exceptions.

Package org.apache.commons.dbcp2 Description

Database Connection Pool API.

Overview in Dialog Form

Q: How do I use the DBCP package?

A: There are two primary ways to access the DBCP pool, as a Driver, or as a DataSource. You'll want to create an instance of PoolingDriver or PoolingDataSource. When using one of these interfaces, you can just use your JDBC objects the way you normally would. Closing a Connection will simply return it to its pool.

Q: But PoolingDriver and PoolingDataSource both expect an ObjectPool as an input. Where do I get one of those?

A: The ObjectPool interface is defined in Commons Pool. You can use one of the provided implementations such as GenericObjectPool, ProxiedObjectPool or SoftReferenceObjectPool or you can create your own.

Q: Ok, I've found an ObjectPool implementation that I think suits my connection pooling needs. But it wants a PooledObjectFactory. What should I use for that?

A: The DBCP package provides a class for this purpose. It's called PoolableConnectionFactory. It implements the factory and lifecycle methods of PooledObjectFactory for Connections. But it doesn't create the actual database Connections itself, it uses a ConnectionFactory for that. The PoolableConnectionFactory will take Connections created by the ConnectionFactory and wrap them with classes that implement the pooling behaviour.

Several implementations of ConnectionFactory are provided--one that uses DriverManager to create connections (DriverManagerConnectionFactory), one that uses a Driver to create connections (DriverConnectionFactory), one that uses a DataSource to create connections (DataSourceConnectionFactory).

Q: I think I'm starting to get it, but can you walk me though it again?

A: Sure. Let's assume you want to create a DataSource that pools Connections. Let's also assume that those pooled Connections should be obtained from the DriverManager. You'll want to create a PoolingDataSource.

The PoolingDataSource uses an underlying ObjectPool to create and store its Connection.

To create a ObjectPool, you'll need a PooledObjectFactory that creates the actual Connections. That's what PoolableConnectionFactory is for.

To create the PoolableConnectionFactory, you'll need at least two things:

1. A ConnectionFactory from which the actual database Connections will be obtained.
2. An empty and factory-less ObjectPool in which the Connections will be stored.
   When you pass an ObjectPool into the PoolableConnectionFactory, it will automatically register itself as the PooledObjectFactory for that pool.

In code, that might look like this:

 GenericObjectPool connectionPool = new GenericObjectPool(null);
 ConnectionFactory connectionFactory = new DriverManagerConnectionFactory("jdbc:some:connect:string", "userName",
         "password");
 PoolableConnectionFactory poolableConnectionFactory = new PoolableConnectionFactory(connectionFactory,
         connectionPool, null, null, false, true);
 PoolingDataSource dataSource = new PoolingDataSource(connectionPool);
 

To create a PoolingDriver, we do the same thing, except that instead of creating a DataSource on the last line, we create a PoolingDriver, and register the connectionPool with it. E.g.,:

 GenericObjectPool connectionPool = new GenericObjectPool(null);
 ConnectionFactory connectionFactory = new DriverManagerConnectionFactory("jdbc:some:connect:string", "userName",
         "password");
 PoolableConnectionFactory poolableConnectionFactory = new PoolableConnectionFactory(connectionFactory,
         connectionPool, null, null, false, true);
 PoolingDriver driver = new PoolingDriver();
 driver.registerPool("example", connectionPool);
 

Since the PoolingDriver registers itself with the DriverManager when it is created, now you can just go to the DriverManager to create your Connections, like you normally would:

 Connection conn = DriverManager.getConnection("jdbc:apache:commons:dbcp:example");