Introduction
Torque can use any connection pool implementing the
Torque provides factories to use the commons-dbcp as well as a general
factory that uses jndi to retrieve the
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
torque.database.bookstore.adapter=mysql The valid values are:
TorqueDataSourceFactoryThis 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. SharedPoolDataSourceFactoryThis 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
JndiDataSourceFactory
This factory is used if the
torque.dsfactory.bookstore.factory=org.apache.torque.dsfactory.JndiDataSourceFactory Using pre-configured poolIf 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
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
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
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/bindingIf 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
Catalina provides a default
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
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 |