<?xml version="1.0" encoding="ISO-8859-1"?>
 <!--
   Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
  -->
<document>

 <properties>
  <title>Overview</title>
  <author email="dev@commons.apache.org">Commons Documentation Team</author>
 </properties>

 <body>

<section name="The DBCP Component">

<p>Many Apache 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.</p>

<p>There are several Database Connection Pools already available, both
within Apache 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.</p>

<p>The <code>commons-dbcp</code> package relies on code in the
<code>commons-pool</code> package to provide the underlying object pool
mechanisms that it utilizes.</p>

<p>DBCP now comes in two different versions, one to support JDBC 3
and one to support JDBC 4.  Here is how it works:
<ul>
<li>DBCP 1.4 compiles and runs under JDK 1.6 only (JDBC 4)</li>
<li>DBCP 1.3 compiles and runs under JDK 1.4-1.5 only (JDBC 3)</li>
</ul>
</p>
<p>DBCP 1.4 binaries should be used by applications running under JDK 1.6.</p>
<p>DBCP 1.3 should be used when running under JDK 1.4 or 1.5.</p>

<p>There is no difference in the codebase supporting these two
versions, other than that the code implementing methods added
to support JDBC 4 has been filtered out of the DBCP 1.3 sources.</p>

</section>

<section name="Releases">
    <p>
       See the <a href="downloads.html">downloads</a> page for information on obtaining releases.
    </p>
</section>

<section name="Documentation">

<p>The 
<a href="apidocs/index.html">JavaDoc API documents</a> 
are available online.  In particular, you should
read the package overview of the 
<code><a href="apidocs/org/apache/commons/dbcp/package-summary.html#package_description">org.apache.commons.dbcp</a></code>
package for an overview of how to use DBCP.</p>

<p>There are 
<a href="http://svn.apache.org/viewvc/commons/proper/dbcp/trunk/doc/">several examples</a> 
of using DBCP available.</p>

</section>

</body>
</document>
