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, you must first consider your database handles and adapters.
A database handle is the name attribute that was used in the
<database> tag of the schema.xml file. If the name
attribute is not used, then the handle would be 'default'.
In all examples that follow we will use the handle 'bookstore'. As Torque has the ability to use multiple databases you can tell it which one to use by default thus:
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.
The adapter property is given as:
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.
Then there are two sets of properties related to the pool configuration and settings for making the connection to the database.
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.
Then there are two sets of properties related to the pool configuration and settings for making the connection to the database.
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:
If a pool is known to already be available via jndi, only one more property is required.
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:
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
One of the advantages of jndi is that it supports changing
the DataSource on the fly. On the other hand this means that the
actual DataSource object must be looked up in the context with
every database operation. To avoid this, the factory provides a simple
caching mechanism, which stores the DataSource object for a
configurable amount of time (im ms). The time between two
lookups is specified as follows:
This property is optional. If not specified, it defaults to 0 (no caching).
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:
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:
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:
In web.xml. Elements must be given in the order of the dtd described in the servlet specification:
Catalina deploys all objects configured similarly to above within the java:comp/env namespace so the jndi path given in Torque.properties would be
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.