Many Jakarta projects support interaction with a relational database. Creating a new connection for each user can be time consuming (often requiring multiple seconds of clock time), in order to perform a database transaction that might take milliseconds. Opening a connection per user can be unfeasible in a publicly-hosted Internet application where the number of simultaneous users can be very large. Accordingly, developers often wish to share a "pool" of open connections between all of the application's current users. The number of users actually performing a request at any given time is usually a very small percentage of the total number of active users, and during request processing is the only time that a database connection is required. The application itself logs into the DBMS, and handles any user account issues internally.
There are several Database Connection Pools already available, both within Jakarta products and elsewhere. This Commons package provides an opportunity to coordinate the efforts required to create and maintain an efficient, feature-rich package under the ASF license.
The commons-dbcp
package relies on code in the
commons-pool
package to provide the underlying object pool
mechanisms that it utilizes.
Applications can use the commons-dbcp
component directly
or through the existing interface of their container / supporting framework.
For example the Tomcat
servlet container presents a DBCP DataSource as a JNDI Datasource.
James (Java Apache Mail Enterprise Server)
has integrated DBCP into the Avalon framework.
A Avalon-style datasource is created by
wrapping the DBCP implementation.
The pooling logic of DBCP and the configuration found in Avalon's excalibur
code is what was needed to create an integrated reliable DataSource.
The
JavaDoc API documents
are available online. In particular, you should
read the package overview of the
org.apache.commons.dbcp
package for an overview of how to use DBCP.
There are several examples of using DBCP available.