|Name||Modified||Size||Downloads / Week|
|Totals: 8 Items||2.4 MB||0|
_____________________________________ ................................. ..(c3p0)......................... ............a.........fresh...... ....coat.......of........stucco.. .........over.......that.....old. ...jdbc........driver............ ................................. ------------------------------------- version 0.8 15-April-2001 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 database Connections. * 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 naming services. * 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 strategies. * 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! Requirements ------------ c3p0 requires a level 1.3 or better Java Runtime Environment, and the JDBC 2.x javax.sql libraries. Installation ------------ 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! Use --- 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, examples. Known Shortcomings ------------------ * 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 maxPoolSize property. * 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. Unknown Shortcomings -------------------- 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! Performance ----------- 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 negligibly small. 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. Feedback -------- Please provide any and all feedback to <email@example.com>! Thank you for trying c3p0!!!