Experimental DataSource Implemetation
... SourceForge.net Logo
The latest version of Proxool is 0.9.1
You can donate to Proxool in the usual way:

Proxool DataSource support

1. Introduction
2. About the DataSource
3. DataSource deployment
4. ProxoolDataSource configuration
5. Configuration example for Tomcat
6. Resources

1. Introduction

Community feedback suggests that JDBC DataSource support has been the most sorely missed feature amongst Proxool users. The JDBC JavaDoc documentation also states that "the use of a DataSource object is the preferred means of connecting to a data source", so we have endeavoured to implement a simple DataSource implementation for Proxool.

Be warned:
ProxoolDataSource is a simple DataSource implementation. It does not currently implement PooledDataSource or support distributed transactions. Also, it does not integrate directly with your container, so do not use ProxoolDataSource if you are using Container Manged Persistance etc. unless your container explicitly allows you to swap to a third party DataSource implementation.

2. About the DataSource

Like the java.sql.DriverManager the javax.sql.DataSource is a factory for java.sql.Connection instances. The application must include specific configuration information about the data source (e.g. a connection url) when obtaining a connection from the DriverManger . This creates a somewhat explicit coupling between your application and the data source.

A DataSource however is configured outside of your application and retrieved through a naming service (JNDI). This makes the configuration of the DataSource completely decoupled from your code.

3. DataSource deployment

DataSources are normally deployed within a Servlet or J2EE container. The J2EE 1.4 specification recommends that the DataSources are placed in the 'jdbc' subcontext of the application component's JNDI environment (java:comp/env/). For example: the full JNDI name of a DataSource named 'UserDB' would be "java:comp/env/jdbc/UserDB". The specification also states that applications must declare the DataSources they are using in 'resource-ref' elements in their deployment descriptor.

The java:comp/env/ environment is read-only at runtime, and the spec states that the container vendor must "provide a deployment tool that allows the Deployer to set and modify the values of the application component's environment entries." This is where the spec ends and implementation specifics begin.

Most containers come with their own DataSource implementation that can be configured and deployed with a tool or through vendor specific configuration files. The support for plugging in a third party DataSource implementation like Proxool is extremely varied. Some vendors have direct support for this, while others make it almost impossible to deploy a foreign DataSource into the java:comp/env/jdbc/ namespace. Remember: this is outside of the spec and there is no common way to achieve it. Because of this we have made the ProxoolDataSource configurable in a number of different ways. The next section describes these ways.

4. ProxoolDataSource configuration

We have made it possible to configure ProxoolDatasource in three different ways to make it useful in as many deployment scenarios as possible.

ObjectFactory configuration

ProxoolDataSource implements the javax.naming.spi.ObjectFactory interface. This is the standard way of providing a factory for object implementations in JNDI. In such a scenario ProxoolDatasource functions as a ObjectFactory for DataSource instances. It is a practical way of deploying a ProxoolDataSource into the JNDI environment for containers that supports this idiom. You configure the ProxoolDataSource ObjectFactory by handing it the Proxool properties plus properties for the underlying JDBC Driver. The Proxool properties must be prefixed with 'proxool.'. Properties not prefixed with 'proxool.' will be passed on to the underlying JDBC driver ('delegate driver' in Proxool parlance).

JavaBean configuration

ProxoolDataSource exposes its configuration properties as JavaBean getters and setters. This is useful for containers that offer the posibility of configuring and deploying JavaBeans into the JNDI environment. It also makes it possible to deploy ProxoolDataSources through component frameworks like the Spring Framework. Since a lot of the Proxool propery names are illegal bean property names we have applied the following translation: '-<lower case letter>' is translated to <upper case letter>. E.g.:
'maximum-connection-count' becomes 'maximumConnectionCount'.

All properties that are to be passed to the underlying JDBC driver are set with the 'driverProperties' property as a comma separated property string. E.g.:
proxoolDataSource.setDriverProperties("user=testUser, password=testPassword, loglevel=WARN");

Self-deployed configuration

In this scenario Proxool itself instantiates ProxoolDataSources and binds them to JNDI names. This is the least standard-conformant way of deploying a ProxoolDataSource. It is also the only way that is garanteed to work in any setting as long as there is a writable JNDI name available for the Proxool process when it starts up. You configure Proxool as you would when using it through the DriverManager. In addition you use the new 'jndi-name' configuration property to tell Proxool to wrap a pool in a ProxoolDataSource and bind it to JNDI. In addition any properties you prefix with 'jndi-' will be passed on the JNDI InitialContext used to bind Proxool. E.g:

        <property name="user" value="sa"/>
        <property name="password" value=""/>

Make sure that jndi-name is actually writable. Remember that the java:comp/env/ environment is read-only at runtime, so your ProxoolDataSources need to go somewhere else in this configuration scenario.

Also remember that with this configuration option Proxool needs to be explicitly initialised, for example using the ServletConfigurator.

5. Configuration example for Tomcat

Configuration method: ObjectFactory

Configure a resource with ProxoolDataSource as the factory in server.xml (or the other places a context element can exist):



6. Resources