db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mpoes...@apache.org
Subject cvs commit: db-torque/xdocs configuration-howto.xml navigation.xml jdbc2pool-howto.xml
Date Tue, 19 Aug 2003 19:40:36 GMT
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="jmcnally@apache.org">John McNally</author>
    <author email="mpoeschl@marmot.at">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
  &lt;database&gt; 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.&lt;handle&gt;.&lt;env-var&gt;.  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 &lt;Context&gt; 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: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org


Mime
View raw message