# 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");
     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");

Interface Summary
BasicDataSourceMXBean: Interface to keep API compatibility.
ConnectionFactory: Abstract factory interface for creating `Connection`s.
DataSourceMXBean: Defines the methods that will be made available via JMX.
PoolableConnectionMXBean: Defines the attributes and methods that will be exposed via JMX for `PoolableConnection` instances.

Class Summary
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:
Constants: Constants.
DataSourceConnectionFactory: A `DataSource`-based implementation of `ConnectionFactory`.
DelegatingCallableStatement: A base delegating implementation of `CallableStatement`.
DelegatingConnection<C extends java.sql.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) methods to allow call sites to operate safely (without `AbstractMethodError`) when using a JDBC driver written for JDBC 4.0 (Java 6).
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.
PoolablePreparedStatement<K>: A `DelegatingPreparedStatement` that cooperates with `PoolingConnection` to implement a pool of `PreparedStatement`s.
PoolingConnection: A `DelegatingConnection` that pools `PreparedStatement`s.
PoolingDataSource<C extends java.sql.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.
SwallowedExceptionLogger: Class for logging swallowed exceptions.
Utils: Utility methods.

Enum Summary
PoolingConnection.StatementType: Statement types.

Exception Summary
ListException: An exception wrapping a list of exceptions.
SQLExceptionList: An SQLException based on a list of Throwable causes.