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.
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:
|
|
|
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.
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.
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
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
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.
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.
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