# Package org.apache.commons.dbcp2

package org.apache.commons.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`, `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 behavior.

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.commons.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.commons.dbcp2.datasources
  This package contains two DataSources: `PerUserPoolDataSource` and `SharedPoolDataSource` which provide a database connection pool.
  org.apache.commons.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.