mpoeschl 2003/08/19 12:40:36
Modified: xdocs navigation.xml
Added: xdocs configuration-howto.xml
Removed: xdocs jdbc2pool-howto.xml
Log:
rename jdbc2pool-howto to configuration-howto and upgrade
Revision Changes Path
1.10 +1 -1 db-torque/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/db-torque/xdocs/navigation.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- navigation.xml 26 Jun 2003 21:41:36 -0000 1.9
+++ navigation.xml 19 Aug 2003 19:40:36 -0000 1.10
@@ -28,7 +28,7 @@
<menu name="Howto Guides">
<item name="Caching Howto" href="/managers-cache.html"/>
<item name="Criteria Howto" href="/criteria-howto.html"/>
- <item name="JDBC2 Pool Howto" href="/jdbc2pool-howto.html"/>
+ <item name="Pool-config Howto" href="/configuration-howto.html"/>
<item name="Maven Howto" href="/maven-howto.html"/>
<item name="Peers Howto" href="/peers-howto.html"/>
</menu>
1.1 db-torque/xdocs/configuration-howto.xml
Index: configuration-howto.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Pool Configuration</title>
<author email="[EMAIL PROTECTED]">John McNally</author>
<author email="[EMAIL PROTECTED]">Martin Poeschl</author>
</properties>
<body>
<section name="Introduction">
<p>
Torque can use any connection pool implementing the <code>DataSource</code>.
Torque expects a factory that can return a <code>DataSource</code> and can
be configured using torque's configuration file.
</p>
<p>
Torque provides factories to use the commons-dbcp as well as a general
factory that uses jndi to retrieve the <code>DataSource</code>.
The jndi factory looks up a <code>DataSource</code> bound to jndi; it
also provides a simple property file based way to configure and deploy most
<code>DataSource</code>'s, though in many cases a pool may already be
bound to jndi and torque only needs to use it.
</p>
<p>
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.
</p>
</section>
<section name="Database Adapters">
<p>
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 <code>DataSource</code>, 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:
</p>
<source><![CDATA[
torque.database.bookstore.adapter=mysql
]]></source>
<p>
The valid values are:
</p>
<table align="center">
<tr>
<td>
<ul>
<li>as400</li>
<li>axion</li>
<li>db2app</li>
<li>db2net</li>
<li>cloudscape</li>
</ul>
</td>
<td>
<ul>
<li>hypersonic</li>
<li>interbase</li>
<li>instantdb</li>
<li>mssql</li>
<li>mysql</li>
</ul>
</td>
<td>
<ul>
<li>oracle</li>
<li>postgresql</li>
<li>sapdb</li>
<li>sybase</li>
<li>weblogic.</li>
</ul>
</td>
</tr>
</table>
</section>
<section name="TorqueDataSourceFactory">
<p>
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.
</p>
<source><![CDATA[
torque.dsfactory.bookstore.factory=org.apache.torque.dsfactory.TorqueDataSourceFactory
]]></source>
<p>
Then there are two sets of properties related to the pool configuration and
settings for making the connection to the database.
</p>
<source><![CDATA[
torque.dsfactory.bookstore.pool.defaultMaxConnections=10
torque.dsfactory.bookstore.pool.maxExpiryTime=3600
torque.dsfactory.bookstore.pool.connectionWaitTimeout=10
]]></source>
<source><![CDATA[
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
]]></source>
<p>
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.
</p>
</section>
<section name="SharedPoolDataSourceFactory">
<p>
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.
</p>
<source><![CDATA[
torque.dsfactory.bookstore.factory= \
org.apache.torque.dsfactory.SharedPoolDataSourceFactory
]]></source>
<p>
Then there are two sets of properties related to the pool configuration and
settings for making the connection to the database.
</p>
<source><![CDATA[
torque.dsfactory.bookstore.pool.defaultMaxActive=30
torque.dsfactory.bookstore.pool.testOnBorrow=true
torque.dsfactory.bookstore.pool.validationQuery=SELECT 1
]]></source>
<source><![CDATA[
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
]]></source>
<p>
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 <code>TorqueClassicDataSource</code>.
Torque also includes a factory for the <code>PerUserPoolDataSource</code>.
Please see the commons-dbcp javadoc for more info.
</p>
</section>
<section name="JndiDataSourceFactory">
<p>
This factory is used if the <code>DataSource</code> is to be available via
jndi. It is possible to use this factory to deploy a <code>DataSource</code>
into jndi, but in many cases for using this factory the <code>DataSource</code>
is already deployed. This factory is specified with the following property:
</p>
<source><![CDATA[
torque.dsfactory.bookstore.factory=org.apache.torque.dsfactory.JndiDataSourceFactory
]]></source>
<subsection name="Using pre-configured pool">
<p>
If a pool is known to already be available via jndi, only one more property
is required.
</p>
<source><![CDATA[
torque.dsfactory.bookstore.jndi.path=jdbc/bookstore
]]></source>
<p>
This line defines the string that will be used to lookup the
<code>DataSource</code> within the default jndi <code>InitialContext</code>.
If everything is configured and the default <code>InitialContext</code>
contains the <code>DataSource</code>, this is all that is
needed. The default <code>InitialContext</code> 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 <code>InitialContext</code> as extra properties of the form,
torque.jndi.<handle>.<env-var>. A couple examples are shown below:
</p>
<source><![CDATA[
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
]]></source>
<p>
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
</p>
</subsection>
<subsection name="Using torque to bind pool">
<p>
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 <code>DataSource</code> and deploying it via jndi.
The one property that is necessary for all <code>DataSource</code>'s is the
classname the <code>DataSource</code> implementation. Beyond that the properties
are implementation specific.
<code>DataSource</code>'s contain getters/setters for configuration. You
can specify the values for these properties as shown below:
</p>
<source><![CDATA[
torque.dsfactory.bookstore.datasource.classname=org.apache.torque.pool.TorqueClassicDataSource
torque.dsfactory.bookstore.datasource.dataSourceName=jdbc/DBbookstore
torque.dsfactory.bookstore.datasource.defaultMaxConnections=10
]]></source>
<source><![CDATA[
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
]]></source>
<p>
In the above example two objects are being configured. One is a
<code>DataSource</code> that is used by the application (torque). The other is
a <code>ConnectionPoolDataSource</code> 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 <code>Driver</code> based drivers. Another alternative is
provided in commons-dbcp where <code>BasicDataSource</code> provides a
<code>DataSource</code> frontend, and has properties to directly configure
a jdbc1 <code>Driver</code>. But regardless of the implementation torque
uses commons-beanutils package to call the setters on the object using
reflection.
</p>
<p>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:
</p>
<source><![CDATA[
torque.dsfactory.bookstore.jndi.path=jdbc/bookstore
torque.dsfactory.DBbookstore.jndi.path=jdbc/DBbookstore
]]></source>
<p>
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.
</p>
</subsection>
<subsection name="Tomcat example of external configuration/binding">
<p>
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.
</p>
<p>In server.xml, the following would be added to the <Context> for your
webapp:
</p>
<source><![CDATA[
<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>
]]></source>
<p>In web.xml. Elements must be given in the order of the dtd described in
the servlet specification:
</p>
<source><![CDATA[
<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>
]]></source>
<p>
Catalina deploys all objects configured similarly to above within the
<strong>java:comp/env</strong> namespace so the jndi path given in
Torque.properties would be
</p>
<source><![CDATA[
torque.dsfactory.bookstore.jndi.path=java:comp/env/jdbc/bookstore
]]></source>
<p>
Remember that jdbc2 pools expect a
<code>ConnectionPoolDataSource</code>
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.
</p>
<p>
Catalina provides a default <code>DataSource</code> that can be used as well
and it is configured similarly, but detailed information on that
implementation is <a
href="http://jakarta.apache.org/tomcat/tomcat-4.1-doc/jndi-resources-howto.html";>here</a>.
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.
</p>
</subsection>
<subsection name="An example configuration from scarab">
<p>
The following example shows a complete torque configuration from
scarab, an issue tracking application, running under catalina, but using torque
to deploy the <code>DataSource</code>. It is here to
put together some of the details shown above.
</p>
<source><![CDATA[
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
]]></source>
</subsection>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
