What is it?
c3p0 is an easy-to-use library for making traditional JDBC drivers
"enterprise-ready" by augmenting them with functionality defined by
the jdbc3 spec and the optional extensions to jdbc2. In particular,
c3p0 provides several useful services:
* Classes which adapt traditional DriverManager-based JDBC
drivers to the new javax.sql.DataSource scheme for acquiring
* Transparent pooling of Connection and PreparedStatements
behind DataSources which can "wrap" around traditional
drivers or arbitrary unpooled DataSources.
The library tries hard to get the details right:
* Referenceable and Serializable implementations of DataSources
are provided, suitable for bining to a wide-variety of JNDI
* Statement and ResultSets are carefully cleaned up when pooled
Connections and Statements are checked it, to prevent resource-
exhaustion when clients use lazy but common resource-management
* The library adopts the approach and uses the internal interfaces
defined by the JDBC 2 and 3 specification (even where these
conflict with the current author's preferences...). DataSources
are written in the JavaBean style, offering all the required and
most of the optional properties (as well as some non-standard ones),
and no-arg constructors.
c3p0 hopes to provide DataSource implementations more than suitable for
use by high-volume "J2EE enterprise applications". Version 0.8 is the
first public release of the library. Please provide feedback, bug-fixes,
etc. to help achieve this goal!
c3p0 requires a level 1.3 or better Java Runtime Environment, and
the JDBC 2.x javax.sql libraries.
Put the file c3p0-0.8.jar and the aforementioned required libraries
somewhere in your CLASSPATH (or any other place where your application's
classloader will find it). That's it!
From a users' perspective, c3p0 simply provides standard jdbc2 DataSource
objects. When acquiring these DataSources, users can control pooling-related,
naming-related, and other properties. Most users need only acquaint themselves
with two classes: DriverManagerDataSourceFactory & PoolBackedDataSourceFactory
See the api docs for more information, and the examples directory for, um,
* Connections and Statements are pooled on a per-authentication basis.
So, if one pool-backed DataSource is used to acquire Connections both
for [user=alice, password=secret1] and [user=bob, password=secret2],
there will be two distinct pools, and the DataSource might in the
worst case manage twice the number of Connections specified by the
* The overhead of Statement Pooling is too high. For drivers that
do not perform significant preprocessing of PreparedStatements, the
pooling overhead outweighs any savings. Statement Pooling is thus
turned off by default. If your driver does preprocess PreparedStatements,
especially if it does so via IPC with the RDBMS, you will probably
see a performance gain by turning StatementCaching on. (Do this by
defining a value for maxStatements greater than zero.);
* jdbc3 conformance is incomplete. Transparent Statement pooling has been
implemented, but most new API has not.
This is the first release of c3p0, and it has undergone very little testing!
It should be considered alpha quality software. Please try it out, and provide
feedback to <firstname.lastname@example.org> about what sucks!
Enhanced performance is the goal of Connection and Statement pooling, and a
major goal of the c3p0 library. For most applications, Connection pooling
will provide a significant performance gain, especially if you are acquiring
an unpooled Connection for each client Thread. If you are letting a single,
shared Connection serve many clients to avoid Connection acquisition overhead,
you may suffer performance issues and problems managing transactions when
your Connection is under concurrent load; Connection pooling will enable you
to switch to a one Connection-per-client-thread model with little or no cost.
If you are writing Enterprise Java Beans, you may be tempted to acquire a
Connection once and not return it until the bean is about to go away (or enter
the "does not exist" state). But this can be resource-costly, as dormant pooled
beans use Connection resources. Connection pooling permits beans to only "own"
a Connection while they are using it.
But, there are performance costs to c3p0 as well. In order to implement
automatic cleanup of unclosed ResultSets and Statements when parent resources
are returned to pools, all client-visible Connections, ResultSets, Statements
are really wrappers around objects provided by an underlying unpooled DataSource
or "traditional" JDBC driver. Thus, there is some extra overhead to all JDBC calls.
Some attention has been paid to minimizing the "wrapper" overhead of c3p0. In
my environment, the wrapper overhead amounts to several hundreths to several
thousandths of the cost of Connection acquisition, so unless you are making
many, many JDBC calls while managing a client, there will be a net performance
gain. Significantly, the overhead associated with ResultSet operations (where
one might iterate through a table with thousands of records) appears to be
A major performance question is how c3p0's performance will scale under heavy
concurrent load. At present, a Connection pool and all of its associated Statement
pools share threads for internal resource management tasks (one or two, depending
on whether a nonzero maxIdleTime for Connections has been set). These threads
perform slow, non-CPU intensive tasks (acqiring / closing DB resources): it may be
useful to diminish the degree of thread sharing and provide greater concurrency.
Also, when Statement caching is performed, all cache operations provoke bookkeeping
operations on a single resource manager (StatementCacheManager), access to which
is synchronized. In real-world heavy load, will this become a significant contention
bottleneck? Any help in resolving these questions would be greatly appreciated.
Please provide any and all feedback to <email@example.com>! Thank you
for trying c3p0!!!