Introduction

Torque can use any connection pool implementing the DataSource . Torque expects a factory that can return a DataSource and can be configured using torque's configuration file.

Torque provides factories to use the commons-dbcp as well as a general factory that uses jndi to retrieve the DataSource . The jndi factory looks up a DataSource bound to jndi; it also provides a simple property file based way to configure and deploy most DataSource 's, though in many cases a pool may already be bound to jndi and torque only needs to use it.

Before going over how to configure the factories which will take up most the content of this document, there is one other configuration that needs covered: adapters.

Database Adapters

Previously, Torque provided an internal map between many Drivers and a set of adapter classes which are used to account for differences among databases. This arrangement is no longer possible using DataSource , so the adapter must be given in the configuration. In all examples that follow we will use the handle, bookstore. This is the name attribute that is used in the <database> tag in the schema.xml. If the name attribute is not used, then the handle would be 'default'. The adapter property is given as:

torque.database.bookstore.adapter=mysql

The valid values are:

  • as400
  • axion
  • db2app
  • db2net
  • cloudscape
  • hypersonic
  • interbase
  • instantdb
  • mssql
  • mysql
  • oracle
  • postgresql
  • sapdb
  • sybase
  • weblogic.

TorqueDataSourceFactory

This factory gives a DataSource version of the old deprecated built-in pool. TorqueDataSourceFactory provides an easy way to configure this pool and it assumes you will have a jdbc Driver class providing the physical database connections. First you must let torque know you are using this factory.

torque.dsfactory.bookstore.factory=org.apache.torque.dsfactory.TorqueDataSourceFactory

Then there are two sets of properties related to the pool configuration and settings for making the connection to the database.

torque.dsfactory.bookstore.pool.defaultMaxConnections=10
torque.dsfactory.bookstore.pool.maxExpiryTime=3600
torque.dsfactory.bookstore.pool.connectionWaitTimeout=10
torque.dsfactory.bookstore.connection.driver = org.gjt.mm.mysql.Driver
torque.dsfactory.bookstore.connection.url = jdbc:mysql://localhost:3306/bookstore
torque.dsfactory.bookstore.connection.user = root
torque.dsfactory.bookstore.connection.password = 1234

The TorqueClassicDataSource used with this factory has a few other configuration options which could be set above in the "pool" section, but the three shown are enough for most cases. Please see the javadoc for the class for more information.

SharedPoolDataSourceFactory

This factory uses the more full featured DataSource available in the commons-dbcp package. SharedPoolDataSourceFactory provides an easy way to configure this pool and it assumes you will have a jdbc Driver class providing the physical database connections. Again, you must let torque know you are using this factory.

torque.dsfactory.bookstore.factory= \
  org.apache.torque.dsfactory.SharedPoolDataSourceFactory

Then there are two sets of properties related to the pool configuration and settings for making the connection to the database.

torque.dsfactory.bookstore.pool.defaultMaxActive=30
torque.dsfactory.bookstore.pool.testOnBorrow=true
torque.dsfactory.bookstore.pool.validationQuery=SELECT 1
torque.dsfactory.bookstore.connection.driver = org.gjt.mm.mysql.Driver
torque.dsfactory.bookstore.connection.url = jdbc:mysql://localhost:3306/bookstore
torque.dsfactory.bookstore.connection.user = root
torque.dsfactory.bookstore.connection.password = 1234

Comparing this with the torque's old pool, you can see that this pool does not rely on expirying connections periodically to maintain their validity. The pool can be setup to test each connection before returning it to the application, so the likelihood of the application receiving a bad connection is much smaller than using TorqueClassicDataSource . Torque also includes a factory for the PerUserPoolDataSource . Please see the commons-dbcp javadoc for more info.

JndiDataSourceFactory

This factory is used if the DataSource is to be available via jndi. It is possible to use this factory to deploy a DataSource into jndi, but in many cases for using this factory the DataSource is already deployed. This factory is specified with the following property:

torque.dsfactory.bookstore.factory=org.apache.torque.dsfactory.JndiDataSourceFactory

Using pre-configured pool

If a pool is known to already be available via jndi, only one more property is required.

torque.dsfactory.bookstore.jndi.path=jdbc/bookstore

This line defines the string that will be used to lookup the DataSource within the default jndi InitialContext . If everything is configured and the default InitialContext contains the DataSource , this is all that is needed. The default InitialContext is chosen according to the rules given in the class's javadoc. If the default has not been configured, you can specify any other environment properties that are needed to instantiate the InitialContext as extra properties of the form, torque.jndi.<handle>.<env-var>. A couple examples are shown below:

torque.dsfactory.bookstore.jndi.java.naming.factory.initial = org.apache.naming.java.javaURLContextFactory
torque.dsfactory.bookstore.jndi.java.naming.factory.url.pkgs = org.apache.naming

Such environment settings will likely not be necessary when running within a J2EE container, but they are useful in other cases. One such case is when running torque's unit/run-time tests

Using torque to bind pool

Generally a J2EE environment such as a servlet engine or application server is expected to provide a jdbc2 compatible connection pool. If your application is not running within such an environment, or even if it is and torque is your only use of a connection pool, torque provides a simple properties file method of configuring a DataSource and deploying it via jndi. The one property that is necessary for all DataSource 's is the classname the DataSource implementation. Beyond that the properties are implementation specific. DataSource 's contain getters/setters for configuration. You can specify the values for these properties as shown below:

torque.dsfactory.bookstore.datasource.classname=org.apache.torque.pool.TorqueClassicDataSource
torque.dsfactory.bookstore.datasource.dataSourceName=jdbc/DBbookstore
torque.dsfactory.bookstore.datasource.defaultMaxConnections=10
torque.dsfactory.DBbookstore.datasource.factory=org.apache.commons.dbcp.cpdsadapter.DriverAdapterCPDS
torque.dsfactory.DBbookstore.datasource.driver = org.gjt.mm.mysql.Driver
torque.dsfactory.DBbookstore.datasource.url = jdbc:mysql://localhost:3306/bookstore
torque.dsfactory.DBbookstore.datasource.user = root
torque.dsfactory.DBbookstore.datasource.password = 1234

In the above example two objects are being configured. One is a DataSource that is used by the application (torque). The other is a ConnectionPoolDataSource that is provided as part of a jdbc2 driver. If the jdbc driver implementation you are using does not fully implement the jdbc2 specification. commons-dbcp provides an adapter for older Driver based drivers. Another alternative is provided in commons-dbcp where BasicDataSource provides a DataSource frontend, and has properties to directly configure a jdbc1 Driver . But regardless of the implementation torque uses commons-beanutils package to call the setters on the object using reflection.

Torque uses the jndi path properties to know where to deploy the configured objects. So you would have the two following properties in addition to the datasource props:

torque.dsfactory.bookstore.jndi.path=jdbc/bookstore
torque.dsfactory.DBbookstore.jndi.path=jdbc/DBbookstore

The second handle, DBbookstore, has no relevance to torque, other than to uniquely identify this group of properties as belonging together. Any unique handle may be used.

Tomcat example of external configuration/binding

If you have other parts of your application that need to use the same connection pool and torque cannot be guaranteed to be initialized in time for these other uses, or if you just want to follow your j2ee environment's standard jndi deployment pattern, torque can just make use of these externally deployed pools. Here is an example using catalina of deploying the pool that used to come with torque, but is now part of commons-jdbc2pool.

In server.xml, the following would be added to the <Context> for your webapp:

 <Resource name="jdbc/ScarabDB" auth="Container"
            type="org.apache.torque.pool.TorqueClassicDataSource"/>
  <ResourceParams name="jdbc/bookstore">
    <parameter>
      <name>factory</name>
      <value>org.apache.torque.pool.TorqueClassicDataSource</value>
    </parameter>
    <parameter>
      <name>dataSourceName</name><value>java:comp/env/jdbc/DBbookstore</value>
    </parameter>
    <parameter>
      <name>defaultMaxConnections</name><value>30</value>
    </parameter>
    <parameter>
      <name>maxExpiryTime</name><value>3600</value>
    </parameter>
    <parameter>
      <name>connectionWaitTimeout</name><value>10</value>
    </parameter>
    <parameter>
      <name>logInterval</name><value>0</value>
    </parameter>

  </ResourceParams>

In web.xml. Elements must be given in the order of the dtd described in the servlet specification:

<resource-ref>
  <description>
    Resource reference to a factory for java.sql.Connection
    instances that may be used for talking to a particular
    database that is configured in the server.xml file.
  </description>
  <res-ref-name>
    jdbc/bookstore
  </res-ref-name>
  <res-type>
    org.apache.torque.pool.TorqueClassicDataSource
  </res-type>
  <res-auth>
    Container
  </res-auth>
</resource-ref>

Catalina deploys all objects configured similarly to above within the java:comp/env namespace so the jndi path given in Torque.properties would be

torque.dsfactory.bookstore.jndi.path=java:comp/env/jdbc/bookstore

Remember that jdbc2 pools expect a ConnectionPoolDataSource available via jndi under the name given in the dataSourceName, so you will need entries in server.xml and web.xml for this object as well.

Catalina provides a default DataSource that can be used as well and it is configured similarly, but detailed information on that implementation is here . Note that the "type attribute/ref-type element" value of "javax.sql.DataSource" appears to be reserved for catalina's default implementation, which is why the implementation classname is used in our configuration example.

An example configuration from scarab

The following example shows a complete torque configuration from scarab, an issue tracking application, running under catalina, but using torque to deploy the DataSource . It is here to put together some of the details shown above.

torque.database.scarab.adapter=mysql

# Jndi location
torque.dsfactory.scarab.jndi.path=jdbc/scarab
torque.dsfactory.DBscarabDB.jndi.path=jdbc/DBscarabDB

# Connection properties for the pooling DataSource
# These properties will vary from one datasource to another, see the class
# javadoc for a description of which properties can be set.
torque.dsfactory.scarab.datasource.classname=org.apache.torque.pool.TorqueClassicDataSource
torque.dsfactory.scarab.datasource.dataSourceName=jdbc/DBscarabDB
torque.dsfactory.scarab.datasource.defaultMaxConnections=30
torque.dsfactory.scarab.datasource.maxExpiryTime=3600
torque.dsfactory.scarab.datasource.connectionWaitTimeout=10
torque.dsfactory.scarab.datasource.logInterval=0

# Connection properties for the ConnectionPoolDataSource
torque.dsfactory.DBscarabDB.datasource.classname=org.apache.commons.dbcp.cpdsadapter.DriverAdapterCPDS
torque.dsfactory.DBscarabDB.datasource.driver=org.gjt.mm.mysql.Driver
torque.dsfactory.DBscarabDB.datasource.url=jdbc:mysql://localhost:3306/scarab
torque.dsfactory.DBscarabDB.datasource.user=xxx
torque.dsfactory.DBscarabDB.datasource.password=yyy


# Determines if the quantity column of the IDBroker's id_table should
# be increased automatically if requests for ids reaches a high
# volume.

torque.idbroker.clever.quantity=false

# Determines if IDBroker should prefetch IDs or not.  If set to false
# this property has the effect of shutting off the housekeeping thread
# that attempts to prefetch the id's.  It also sets the # of id's grabbed
# per request to 1 regardless of the settings in the database.
# Default: true

torque.idbroker.prefetch=true