[DBCP] Managed Connection support

I just posted a patch JIRA which adds support for container managed  
connections to DBCP.  In an environment where you have an accessible  
transaction manger such as Tomcat (when installed), Geronimo or  
OpenEJB, this patch allows adds support for pooling managed  
connections to an XA or non-XA data base.

There are many libraries that use DBCP for non-managed environments,  
but when additional resources such as a JMS provider are added to the  
mix, they have to replace DBCP with something else.  If you search  
google for XA and DBCP, you will loads of painful direction on how to  
replace DBCP with something else.  I personally want to use DBCP in  
Tomcat with ActiveMQ.

Anyways, enough with motivation....

To use the new code, you need access to a TranactionManager (this  
code just creates a new Geronimo one).

         transactionManager = new TransactionManagerImpl();

Then you either create an XADataSource and  
DataSourceXAConectionFactory or as this code does, create a normal  
DBCP ConnectionFactory and wrap it with a LocalXAConectionFactory

         Properties properties = new Properties();
         properties.setProperty("user", "username");
         properties.setProperty("password", "password");
         ConnectionFactory connectionFactory = new  
DriverConnectionFactory(
                 new TesterDriver(),
                 "jdbc:apache:commons:testdriver", properties);

         // wrap it with a LocalXAConnectionFactory
         XAConnectionFactory xaConnectionFactory = new  
LocalXAConnectionFactory(
                 transactionManager,
                 connectionFactory);


Now you create a pool as normal (full reuse here).

         pool = new GenericObjectPool();
         pool.setMaxActive(getMaxActive());
         pool.setMaxWait(getMaxWait());

         // create the pool object factory
         PoolableConnectionFactory factory = new  
PoolableConnectionFactory(
                 xaConnectionFactory,
                 pool,
                 null,
                 "SELECT DUMMY FROM DUAL",
                 true,
                 true);
         pool.setFactory(factory);


Finally, you create a special ManagedDataSource using the pool above  
and the special TransactionRegistry object obtained from the  
XAConnectionFactory.

         ds = new ManagedDataSource(pool,  
xaConnectionFactory.getTransactionRegistry());
         ds.setAccessToUnderlyingConnectionAllowed(true);


That's it.  The data source and connections work as normal until you  
start a transaction using the TransactionManager.  When you use a  
connection while the transaction is active, the connection is  
enlisted in the transaction.  When the transaction is complete, the  
connection is committed (or rolledback) and the connection returns to  
normal.

Most of the new code extends existing classes or uses existing  
classes without modification.  The key to this reuse is the  
TransactionRegistry abstraction which maintains a map from the  
Connection to the XAResource for that connection.  The XAResource is  
needed to enlist a connection in a transaction.  The  
TransactionRegistry and associated TransationContext class  
encapsulate all interactions with the TransactionManager leaving the  
Connection implementation relatively simple (making reuse easier).

For now the code is contained in the org.apache.commons.dbcp.managed  
package, but I would suspect we may want to spread it out amongst the  
existing packages instead of creating a feature specific package.   
I'm also not sure what additional interfaces people may want such as  
equivalents of the BasicDataSource or BasicDataSourceFactory.

The code has tests and has javadoc, but it needs real world testing  
and some real docs.  I'm going try hooking it into OpenEJB and  
running it's massive test suite with a couple of opensource DBs.

Anyways, I hope you all like it and accept the patch.  I'm around to  
help with changes or whatever.  I also ran into a few bugs while  
working on this that are already reported in JIRA (like the close  
bugs) and am willing to help with those also.

-dain