# Package org.apache.tomcat.dbcp.dbcp2

package org.apache.tomcat.dbcp.dbcp2

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` 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:

1. A `ConnectionFactory` from which the actual database `Connection`s will be obtained.
2. An empty and factory-less `ObjectPool` in which the `Connection`s 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");
    ObjectName oName = new ObjectName("MyTests:DataSource=test"); // or null to not use JMX
    PoolableConnectionFactory poolableConnectionFactory = new PoolableConnectionFactory(connectionFactory, oName);
    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");
    ObjectName oName = new ObjectName("MyTests:DataSource=test"); // or null to not use JMX
    PoolableConnectionFactory poolableConnectionFactory = new PoolableConnectionFactory(connectionFactory, oName);
    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");

Related Packages
Package
Description
org.apache.tomcat.dbcp.dbcp2.cpdsadapter
This package contains one public class which is a `ConnectionPoolDataSource` (CPDS) implementation that can be used to adapt older `Driver` based JDBC implementations.
org.apache.tomcat.dbcp.dbcp2.datasources
This package contains two DataSources: `PerUserPoolDataSource` and `SharedPoolDataSource` which provide a database connection pool.
org.apache.tomcat.dbcp.dbcp2.managed
This package provides support for pooling of ManagedConnections.
Class
Description
AbandonedTrace
Tracks connection usage for recovering and reporting abandoned 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: `connectionInitSqls` must be passed to this factory as a single String using semicolon to delimit the statements whereas `BasicDataSource` requires a collection of Strings.
BasicDataSourceMXBean
Interface to keep API compatibility.
ConnectionFactory
Abstract factory interface for creating `Connection`s.
Constants
Constants.
DataSourceConnectionFactory
A `DataSource`-based implementation of `ConnectionFactory`.
DataSourceMXBean
Defines the methods that will be made available via JMX.
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`.
Jdbc41Bridge
Defines bridge methods to JDBC 4.1 (Java 7 or above) methods to allow call sites to operate safely (without `AbstractMethodError`) when using a JDBC driver written for JDBC 4.0 (Java 6 or above).
ListException
An exception wrapping a list of exceptions.
PoolableCallableStatement
A `DelegatingCallableStatement` that cooperates with `PoolingConnection` to implement a pool of `CallableStatement`s.
PoolableConnection
A delegating connection that, rather than closing the underlying connection, returns itself to an `ObjectPool` when closed.
PoolableConnectionFactory
A `PooledObjectFactory` that creates `PoolableConnection`s.
PoolableConnectionMXBean
Defines the attributes and methods that will be exposed via JMX for `PoolableConnection` instances.
PoolablePreparedStatement<K>
A `DelegatingPreparedStatement` that cooperates with `PoolingConnection` to implement a pool of `PreparedStatement`s.
PoolingConnection
A `DelegatingConnection` that pools `PreparedStatement`s.
PoolingConnection.StatementType
Statement types.
PoolingDataSource<C extends Connection>
A simple `DataSource` implementation that obtains `Connection`s from the specified `ObjectPool`.
PoolingDriver
A `Driver` implementation that obtains `Connection`s from a registered `ObjectPool`.
PStmtKey
A key uniquely identifying `PreparedStatement`s.
SQLExceptionList
An SQLException based on a list of Throwable causes.
SwallowedExceptionLogger
Class for logging swallowed exceptions.
Utils
Utility methods.