# Package org.apache.tomcat.dbcp.dbcp2

Database Connection Pool API.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  BasicDataSourceMXBean | Defines the methods that will be made available via JMX.
  ConnectionFactory | Abstract factory interface for creating `Connection`s.
  PoolableConnectionMXBean | Defines the attributes and methods that will be exposed via JMX for `PoolableConnection` instances.

- Class Summary
  Class | Description
  --- | ---
  AbandonedTrace | Tracks db connection usage for recovering and reporting abandoned db 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 semi-colon to delimit the statements whereas `BasicDataSource` requires a collection of Strings.
  Constants | Constants for use with JMX
  DataSourceConnectionFactory | A `DataSource`-based implementation of `ConnectionFactory`.
  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`.
  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 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
  Enum | Description
  --- | ---
  PoolingConnection.StatementType | The possible statement types.

## Package org.apache.tomcat.dbcp.dbcp2 Description

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

Copyright © 2000-2017 Apache Software Foundation. All Rights Reserved.