Package org.apache.commons.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
,
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 Connection
s. But it doesn't create the actual database
Connection
s itself, it uses a
ConnectionFactory
for that.
The PoolableConnectionFactory
will take
Connection
s 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 Connection
s. Let's also assume that
those pooled Connection
s 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 Connection
s. That's what
PoolableConnectionFactory
is for.
To create the PoolableConnectionFactory
,
you'll need at least two things:
-
A
ConnectionFactory
from which the actual databaseConnection
s will be obtained. -
An empty and factory-less
ObjectPool
in which theConnection
s will be stored.
When you pass anObjectPool
into thePoolableConnectionFactory
, it will automatically register itself as thePooledObjectFactory
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 Connection
s,
like you normally would:
Connection conn = DriverManager.getConnection("jdbc:apache:commons:dbcp:example");
-
ClassDescriptionTracks db connection usage for recovering and reporting abandoned db connections.Basic implementation of
javax.sql.DataSource
that is configured via JavaBeans properties.JNDI object factory that creates an instance ofBasicDataSource
that has been configured based on theRefAddr
values of the specifiedReference
, which must match the names and data types of theBasicDataSource
bean properties with the following exceptions:Defines the methods that will be made available via JMX.Abstract factory interface for creatingConnection
s.Constants for use with JMXADataSource
-based implementation ofConnectionFactory
.A base delegating implementation ofCallableStatement
.DelegatingConnection<C extends Connection>A base delegating implementation ofConnection
.A base delegating implementation ofDatabaseMetaData
.A base delegating implementation ofPreparedStatement
.A base delegating implementation ofResultSet
.A base delegating implementation ofStatement
.ADriver
-based implementation ofConnectionFactory
.ADriverManager
-based implementation ofConnectionFactory
.ADelegatingCallableStatement
that cooperates withPoolingConnection
to implement a pool ofCallableStatement
s.A delegating connection that, rather than closing the underlying connection, returns itself to anObjectPool
when closed.APooledObjectFactory
that createsPoolableConnection
s.Defines the attributes and methods that will be exposed via JMX forPoolableConnection
instances.ADelegatingPreparedStatement
that cooperates withPoolingConnection
to implement a pool ofPreparedStatement
s.ADelegatingConnection
that poolsPreparedStatement
s.PoolingDataSource<C extends Connection>A key uniquely identifyingPreparedStatement
s.Class for logging swallowed exceptions.Utility methods.