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:
<proxool>
<alias>jndi-test</alias>
<driver-url>jdbc:hsqldb:.</driver-url>
<driver-class>org.hsqldb.jdbcDriver</driver-class>
<driver-class>org.hsqldb.jdbcDriver</driver-class>
<driver-properties>
<property name="user" value="sa"/>
<property name="password" value=""/>
</driver-properties>
<jndi-name>/datasources/UserDB</jndi-name>
<jndi-java.naming.factory.initial>com.caucho.naming.InitialContextFactoryImpl</jndi-java.naming.factory.initial>
<jndi-java.naming.provider.url>localhost:1099</jndi-java.naming.provider.url>
</proxool>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):
<context>
<Resource
name="jdbc/mydatasource"
auth="Container"
type="javax.sql.DataSource"
factory="org.logicalcobwebs.proxool.ProxoolDataSource"
proxool.alias="hrs"
user="joe"
password="******"
delegateProperties="foo=bar"
proxool.driver-url="jdbc:oracle:thin:@127.0.0.1:1521:DB"
proxool.driver-class="oracle.jdbc.driver.OracleDriver"/>
</context>
6. Resources
|
