Package org.apache.tomcat.dbcp.dbcp2
Database Connection Pool API.
Overview in Dialog FormQ: 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 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:
- A
ConnectionFactoryfrom which the actual databaseConnections will be obtained. - An empty and factory-less
ObjectPoolin which theConnections will be stored.
When you pass anObjectPoolinto thePoolableConnectionFactory, it will automatically register itself as thePooledObjectFactoryfor 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");
-
Interface Summary Interface Description BasicDataSourceMXBean Interface to keep API compatibility.ConnectionFactory Abstract factory interface for creatingConnections.DataSourceMXBean Defines the methods that will be made available via JMX.PoolableConnectionMXBean Defines the attributes and methods that will be exposed via JMX forPoolableConnectioninstances. -
Class Summary Class Description AbandonedTrace Tracks connection usage for recovering and reporting abandoned connections.BasicDataSource Basic implementation ofjavax.sql.DataSourcethat is configured via JavaBeans properties.BasicDataSourceFactory JNDI object factory that creates an instance ofBasicDataSourcethat has been configured based on theRefAddrvalues of the specifiedReference, which must match the names and data types of theBasicDataSourcebean properties with the following exceptions:connectionInitSqlsmust be passed to this factory as a single String using semicolon to delimit the statements whereasBasicDataSourcerequires a collection of Strings.Constants Constants.DataSourceConnectionFactory ADataSource-based implementation ofConnectionFactory.DelegatingCallableStatement A base delegating implementation ofCallableStatement.DelegatingConnection<C extends java.sql.Connection> A base delegating implementation ofConnection.DelegatingDatabaseMetaData A base delegating implementation ofDatabaseMetaData.DelegatingPreparedStatement A base delegating implementation ofPreparedStatement.DelegatingResultSet A base delegating implementation ofResultSet.DelegatingStatement A base delegating implementation ofStatement.DriverConnectionFactory ADriver-based implementation ofConnectionFactory.DriverManagerConnectionFactory ADriverManager-based implementation ofConnectionFactory.Jdbc41Bridge Defines bridge methods to JDBC 4.1 (Java 7) methods to allow call sites to operate safely (withoutAbstractMethodError) when using a JDBC driver written for JDBC 4.0 (Java 6).PoolableCallableStatement ADelegatingCallableStatementthat cooperates withPoolingConnectionto implement a pool ofCallableStatements.PoolableConnection A delegating connection that, rather than closing the underlying connection, returns itself to anObjectPoolwhen closed.PoolableConnectionFactory APooledObjectFactorythat createsPoolableConnections.PoolablePreparedStatement<K> ADelegatingPreparedStatementthat cooperates withPoolingConnectionto implement a pool ofPreparedStatements.PoolingConnection ADelegatingConnectionthat poolsPreparedStatements.PoolingDataSource<C extends java.sql.Connection> PoolingDriver PStmtKey A key uniquely identifyingPreparedStatements.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.SQLExceptionList An SQLException based on a list of Throwable causes.