container/webapps/docs/jndi-datasource-examples-howto.xml - tomcat55 - Git at Google

 <?xml version="1.0"?>
 <!DOCTYPE document [
   <!ENTITY project SYSTEM "project.xml">
 ]>
 <document url="jndi-datasource-examples-howto.html">

     &project;

     <properties>
         <author email="leslie.hughes@rubus.com">Les Hughes</author>
         <author email="david-tomcat@haraburda.com">David Haraburda</author>
         <author>Glenn Nielsen</author>
         <author email="yoavs@apache.org">Yoav Shapira</author>
         <title>JNDI Datasource HOW-TO</title>
     </properties>

 <body>

 <section name="Table of Contents">
 <p>
 <a href="#Introduction">Introduction</a><br />
 <a href="#Database Connection Pool (DBCP) Configurations">
 Database Connection Pool (DBCP) Configurations</a><br />
 <a href="#Non DBCP Solutions">Non DBCP Solutions</a><br />
 <a href="#Oracle 8i with OCI client">Oracle 8i with OCI client</a><br />
 <a href="#Common Problems">Common Problems</a><br />
 </p>
 </section>

 <section name="Introduction">

 <p>JNDI Datasource configuration is covered extensively in the
 JNDI-Resources-HOWTO however, feedback from <code>tomcat-user</code> has
 shown that specifics for individual configurations can be rather tricky.</p>

 <p>Here then are some example configurations that have been posted to
 tomcat-user for popular databases and some general tips for db useage.</p>

 <p>You should be aware that since these notes are derived from configuration
 and/or feedback posted to <code>tomcat-user</code> YMMV :-). Please let us
 know if you have any other tested configurations that you feel may be of use
 to the wider audience, or if you feel we can improve this section in anyway.</p>

 </section>

 <section name="Database Connection Pool (DBCP) Configurations">

 <p>DBCP provides support for JDBC 2.0.  On systems using a 1.4 JVM DBCP
 will support JDBC 3.0. Please let us know if you have used DBCP and its
 JDBC 3.0 features with a 1.4 JVM.
 </p>

 <p>See the <a href="http://jakarta.apache.org/commons/dbcp/api/index.html">
 DBCP Javadocs</a> BasicDataSource class for a complete list
 of configuration parameters.
 </p>

 <subsection name="Installation">
 <p>DBCP uses the Jakarta-Commons Database Connection Pool. It relies on
 number of Jakarta-Commons components:
 <ul>
 <li>Jakarta-Commons DBCP</li>
 <li>Jakarta-Commons Collections</li>
 <li>Jakarta-Commons Pool</li>
 </ul>
 These libraries are located in a single JAR at
 <code>$CATALINA_HOME/common/lib/naming-factory-dbcp.jar</code>.
 </p>

 </subsection>

 <subsection name="Preventing dB connection pool leaks">

 <p>
 A database connection pool creates and manages a pool of connections
 to a database. Recycling and reusing already existing connections
 to a dB is more efficient than opening a new connection.
 </p>

 <p>
 There is one problem with connection pooling.  A web application has
 to explicetely close ResultSet's, Statement's, and Connection's.
 Failure of a web application to close these resources can result in
 them never being available again for reuse, a db connection pool "leak".
 This can eventually result in your web application db connections failing
 if there are no more available connections.</p>

 <p>
 There is a solution to this problem.  The Jakarta-Commons DBCP can be
 configured to track and recover these abandoned dB connections.  Not
 only can it recover them, but also generate a stack trace for the code
 which opened these resources and never closed them.</p>

 <p>
 To configure a DBCP DataSource so that abandoned dB connections are
 removed and recycled add the following attribute to the
 <code>Resource</code> configuration for your DBCP DataSource:
 <source>
             removeAbandoned="true"
 </source>
 When available db connections run low DBCP will recover and recyle
 any abandoned dB connections it finds. The default is <code>false</code>.
 </p>

 <p>
 Use the <code>removeAbandonedTimeout</code> attribute to set the number
 of seconds a dB connection has been idle before it is considered abandoned.
 <source>
             removeAbandonedTimeout="60"
 </source>
 The default timeout for removing abandoned connections is 300 seconds.
 </p>

 <p>
 The <code>logAbandoned</code> attribute can be set to <code>true</code>
 if you want DBCP to log a stack trace of the code which abandoned the
 dB connection resources.
 <source>
             logAbandoned="true"
 </source>
 The default is <code>false</code>.
 </p>

 </subsection>

 <subsection name="MySQL DBCP Example">

 <h3>0. Introduction</h3>
 <p>Versions of <a href="http://www.mysql.com/products/mysql/index.html">MySQL</a> and JDBC drivers that have been reported to work:
 <ul>
 <li>MySQL 3.23.47, MySQL 3.23.47 using InnoDB,, MySQL 3.23.58,  MySQL 4.0.1alpha</li>
 <li><a href="http://www.mysql.com/products/connector-j">Connector/J</a> 3.0.11-stable (the official JDBC Driver)</li>
 <li><a href="http://mmmysql.sourceforge.net">mm.mysql</a> 2.0.14 (an old 3rd party JDBC Driver)</li>
 </ul>
 </p>

 <p>Before you proceed, don't forget to copy the JDBC Driver's jar into <code>$CATALINA_HOME/common/lib</code>.</p>

 <h3>1. MySQL configuration</h3>
 <p>
 Ensure that you follow these instructions as variations can cause problems.
 </p>

 <p>Create a new test user, a new database and a single test table.
 Your MySQL user <strong>must</strong> have a password assigned. The driver
 will fail if you try to connect with an empty password.
 <source>
 mysql&gt; GRANT ALL PRIVILEGES ON *.* TO javauser@localhost
     -&gt;   IDENTIFIED BY 'javadude' WITH GRANT OPTION;
 mysql&gt; create database javatest;
 mysql&gt; use javatest;
 mysql&gt; create table testdata (
     -&gt;   id int not null auto_increment primary key,
     -&gt;   foo varchar(25),
     -&gt;   bar int);
 </source>
 <blockquote>
 <strong>Note:</strong> the above user should be removed once testing is
 complete!
 </blockquote>
 </p>

 <p>Next insert some test data into the testdata table.
 <source>
 mysql&gt; insert into testdata values(null, 'hello', 12345);
 Query OK, 1 row affected (0.00 sec)

 mysql> select * from testdata;
 +----+-------+-------+
 | ID | FOO   | BAR   |
 +----+-------+-------+
 |  1 | hello | 12345 |
 +----+-------+-------+
 1 row in set (0.00 sec)

 mysql&gt;
 </source>
 </p>

 <h3>2. server.xml configuration</h3>
 <p>Configure the JNDI DataSource in Tomcat by adding a declaration for your
 resource to <code>$CATALINA_HOME/conf/server.xml</code>.</p>
 <p>Add this in between the <code>&lt;/Context&gt;</code> tag of the examples
 context and the <code>&lt;/Host&gt;</code> tag closing the localhost definition.<source>
 &lt;Context path="/DBTest" docBase="DBTest"
         debug="5" reloadable="true" crossContext="true"&gt;

   &lt;Logger className="org.apache.catalina.logger.FileLogger"
              prefix="localhost_DBTest_log." suffix=".txt"
              timestamp="true"/&gt;

     &lt;!-- maxActive: Maximum number of dB connections in pool. Make sure you
          configure your mysqld max_connections large enough to handle
          all of your db connections. Set to 0 for no limit.
          --&gt;

     &lt;!-- maxIdle: Maximum number of idle dB connections to retain in pool.
          Set to -1 for no limit.  See also the DBCP documentation on this
          and the minEvictableIdleTimeMillis configuration parameter.
          --&gt;

     &lt;!-- maxWait: Maximum time to wait for a dB connection to become available
          in ms, in this example 10 seconds. An Exception is thrown if
          this timeout is exceeded.  Set to -1 to wait indefinitely.
          --&gt;

     &lt;!-- username and password: MySQL dB username and password for dB connections  --&gt;

     &lt;!-- driverClassName: Class name for the old mm.mysql JDBC driver is
          org.gjt.mm.mysql.Driver - we recommend using Connector/J though.
          Class name for the official MySQL Connector/J driver is com.mysql.jdbc.Driver.
          --&gt;

     &lt;!-- url: The JDBC connection url for connecting to your MySQL dB.
          The autoReconnect=true argument to the url makes sure that the
          mm.mysql JDBC Driver will automatically reconnect if mysqld closed the
          connection.  mysqld by default closes idle connections after 8 hours.
          --&gt;

   &lt;Resource name="jdbc/TestDB" auth="Container" type="javax.sql.DataSource"
                maxActive="100" maxIdle="30" maxWait="10000"
                username="javauser" password="javadude" driverClassName="com.mysql.jdbc.Driver"
                url="jdbc:mysql://localhost:3306/javatest?autoReconnect=true"/&gt;

 &lt;/Context&gt;
 </source>
 </p>

 <h3>3. web.xml configuration</h3>

 <p>Now create a <code>WEB-INF/web.xml</code> for this test application.
 <source>
 &lt;web-app xmlns="http://java.sun.com/xml/ns/j2ee"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
 http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
     version="2.4"&gt;
   &lt;description&gt;MySQL Test App&lt;/description&gt;
   &lt;resource-ref&gt;
       &lt;description&gt;DB Connection&lt;/description&gt;
       &lt;res-ref-name&gt;jdbc/TestDB&lt;/res-ref-name&gt;
       &lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
       &lt;res-auth&gt;Container&lt;/res-auth&gt;
   &lt;/resource-ref&gt;
 &lt;/web-app&gt;
 </source>
 </p>

 <h3>4. Test code</h3>
 <p>Now create a simple <code>test.jsp</code> page for use later.
 <source>
 &lt;%@ taglib uri="http://java.sun.com/jsp/jstl/sql" prefix="sql" %&gt;
 &lt;%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %&gt;

 &lt;sql:query var="rs" dataSource="jdbc/TestDB"&gt;
 select id, foo, bar from testdata
 &lt;/sql:query&gt;

 &lt;html&gt;
   &lt;head&gt;
     &lt;title&gt;DB Test&lt;/title&gt;
   &lt;/head&gt;
   &lt;body&gt;

   &lt;h2&gt;Results&lt;/h2&gt;

 &lt;c:forEach var="row" items="${rs.rows}"&gt;
     Foo ${row.foo}&lt;br/&gt;
     Bar ${row.bar}&lt;br/&gt;
 &lt;/c:forEach&gt;

   &lt;/body&gt;
 &lt;/html&gt;
 </source>
 </p>

 <p>That JSP page makes use of <a href="http://java.sun.com/products/jsp/jstl">JSTL</a>'s SQL and Core taglibs. You can get it from Sun's <a href="http://java.sun.com/webservices/downloads/webservicespack.html">Java Web Services Developer Pack</a> or <a href="http://jakarta.apache.org/taglibs/doc/standard-doc/intro.html">Jakarta Taglib Standard 1.1</a> project - just make sure you get a 1.1.x release. Once you have JSTL, copy <code>jstl.jar</code> and <code>standard.jar</code> to your web app's <code>WEB-INF/lib</code> directory.

 </p>

 <p>Finally deploy your web app into <code>$CATALINA_HOME/webapps</code> either
 as a warfile called <code>DBTest.war</code> or into a sub-directory called
 <code>DBTest</code></p>
 <p>Once deployed, point a browser at
 <code>http://localhost:8080/DBTest/test.jsp</code> to view the fruits of
 your hard work.</p>

 </subsection>

 <subsection name="Oracle 8i">
 <h3>0.    Introduction</h3>
 <p><i>We would appreciate comments on this section as I'm not an Oracle DBA :-)</i></p>
 <p>Oracle requires minimal changes from the MySQL configuration except for the usual gotchas :-) Firstly
 by default, Tomcat will only use <code>*.jar</code> files installed in <code>$CATALINA_HOME/common/lib</code>
  therefore <code>classes111.zip</code> or <code>classes12.zip</code> will need to be renamed with a <code>.jar</code>
 extension. Since jarfiles are zipfiles, there is no need to unzip and jar these files - a simple rename will suffice.
 Also, you should be aware that some (early) versions of Tomcat 4.0 when used with JDK 1.4 will not load classes12.zip unless
 you unzip the file, remove the <code>javax.sql.*</code> class heirarchy and rejar.</p>
 <h3>1.    server.xml configuration</h3>
 <p>In a similar manner to the mysql config above, you will need to define your Datasource in your server.xml
 file. Here we define a Datasource called myoracle using the thin driver to connect as user scott, password tiger
 to the schema called myschema in the sid called mysid. (Note: with the thin driver this sid is not the same as the tnsname)</p>

 <p>Use of the OCI driver should simply involve a changing thin to oci in the URL string.
 <source>
 &lt;Resource name="jdbc/myoracle" auth="Container"
               type="javax.sql.DataSource" driverClassName="oracle.jdbc.driver.OracleDriver"
               url="jdbc:oracle:thin:myschema@127.0.0.1:1521:mysid"
               username="scott" password="tiger" maxActive="20" maxIdle="10"
               maxWait="-1"/&gt;
 </source>
 </p>

 <h3>2.    web.xml configuration</h3>
 <p>You should ensure that you respect the elemeent ordering defined by the DTD when you
 create you applications web.xml file.</p>
 <source>
 &lt;resource-ref&gt;
  &lt;description&gt;Oracle Datasource example&lt;/description&gt;
  &lt;res-ref-name&gt;jdbc/myoracle&lt;/res-ref-name&gt;
  &lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
  &lt;res-auth&gt;Container&lt;/res-auth&gt;
 &lt;/resource-ref&gt;
 </source>
 <h3>3.   Code example</h3>
 <p>You can use the same example application as above (asuming you create the required DB
 instance, tables etc.) replacing the Datasource code with something like</p>
 <source>
 Context initContext = new InitialContext();
 Context envContext  = (Context)initContext.lookup("java:/comp/env");
 DataSource ds = (DataSource)envContext.lookup("jdbc/myoracle");
 Connection conn = ds.getConnection();
 //etc.
 </source>
 </subsection>


 <subsection name="PostgreSQL">
 <h3>0.    Introduction</h3>
 <p>PostgreSQL is configured in a similar manner to Oracle. Again, highlighting the differences.
 These notes are untested as yet and we would appreciate feedback.</p>
 <h3>1.    server.xml configuration</h3>
 <source>
 &lt;Resource name="jdbc/postgres" auth="Container"
           type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
           url="jdbc:postgresql://127.0.0.1:5432/mydb"
           username="myuser" password="mypasswd" maxActive="20" maxIdle="10" maxWait="-1"/>
 </source>
 <h3>2.    web.xml configuration</h3>
 <source>
 &lt;resource-ref&gt;
  &lt;description&gt;postgreSQL Datasource example&lt;/description&gt;
  &lt;res-ref-name&gt;jdbc/postgres&lt;/res-ref-name&gt;
  &lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
  &lt;res-auth&gt;Container&lt;/res-auth&gt;
 &lt;/resource-ref&gt;
 </source>
 </subsection>
 </section>

 <section name="Non DBCP Solutions">
 <p>
 These solutions either utilise a single connection to the database (not recommended for anything other
 than testing!) or some other pooling technology.
 </p>
 </section>

 <section name="Oracle 8i with OCI client">
 <subsection name="Introduction">
 <p>Whilst not strictly addressing the creation of a JNDI DataSource using the OCI client, these notes can be combined with the
 Oracle and DBCP solution above.</p>
 <p>
 In order to use OCI driver, you should have an Oracle client installed. You should have installed
 Oracle8i(8.1.7) client from cd,  and download the suitable JDBC/OCI
 driver(Oracle8i 8.1.7.1 JDBC/OCI Driver) from <a href="http://otn.oracle.com/">otn.oracle.com</a>.
 </p>
 <p>
 After renaming <code>classes12.zip</code> file to <code>classes12.jar</code>
 for Tomcat, copy it into <code>$CATALINA_HOME/common/lib</code>.
 You may also have to remove the <code>javax.sql.*</code> classes
 from this file depending upon the version of Tomcat and JDK you are using.
 </p>
 </subsection>

 <subsection name="Putting it all together">
 <p>
 Ensure that you have the <code>ocijdbc8.dll</code> or <code>.so</code> in your <code>$PATH</code> or <code>LD_LIBRARY_PATH</code>
  (possibly in <code>$ORAHOME\bin</code>) and also confirm that the native library can be loaded by a simple test program
 using <code>System.loadLibrary("ocijdbc8");</code>
 </p>
 <p>
 You should next create a simple test servlet or jsp that has these
 <strong>critical lines</strong>:
 </p>
 <source>
 DriverManager.registerDriver(new
 oracle.jdbc.driver.OracleDriver());
 conn =
 DriverManager.getConnection("jdbc:oracle:oci8:@database","username","password");
 </source>
 <p>
 where database is of the form <code>host:port:SID</code> Now if you try to access the URL of your
 test servlet/jsp and what you get is a
 <code>ServletException</code> with a root cause of <code>java.lang.UnsatisfiedLinkError:get_env_handle</code>.
 </p>
 <p>
 First, the <code>UnsatisfiedLinkError</code> indicates that you have
 <ul>
 <li>a mismatch between your JDBC classes file and
 your Oracle client version. The giveaway here is the message stating that a needed library file cannot be
 found. For example, you may be using a classes12.zip file from Oracle Version 8.1.6 with a Version 8.1.5
 Oracle client. The classeXXXs.zip file and Oracle client software versions must match.
 </li>
 <li>A <code>$PATH</code>, <code>LD_LIBRARY_PATH</code> problem.</li>
 <li>It has been reported that ignoring the driver you have downloded from otn and using
 the classes12.zip file from the directory <code>$ORAHOME\jdbc\lib</code> will also work.
 </li>
 </ul>
 </p>
 <p>
 Next you may experience the error <code>ORA-06401 NETCMN: invalid driver designator</code>
 </p>
 <p>
 The Oracle documentation says : "Cause: The login (connect) string contains an invalid
 driver designator. Action: Correct the string and re-submit."

 Change the database connect string (of the form <code>host:port:SID</code>) with this one:
 <code>(description=(address=(host=myhost)(protocol=tcp)(port=1521))(connect_data=(sid=orcl)))</code>
 </p>
 <p>
 <i>Ed. Hmm, I don't think this is really needed if you sort out your TNSNames - but I'm not an Oracle DBA :-)</i>
 </p>
 </subsection>
 </section>

 <section name="Common Problems">
 <p>Here are some common problems encountered with a web application which
 uses a database and tips for how to solve them.</p>

 <subsection name="Intermittent dB Connection Failures">
 <p>
 Tomcat runs within a JVM.  The JVM periodically performs garbage collection
 (GC) to remove java objects which are no longer being used.  When the JVM
 performs GC execution of code within Tomcat freezes. If the maximum time
 configured for establishment of a dB connection is less than the amount
 of time garbage collection took you can get a db conneciton failure.
 </p>

 <p>To collect data on how long garbage collection is taking add the
 <code>-verbose:gc</code> argument to your <code>CATALINA_OPTS</code>
 environment variable when starting Tomcat.  When verbose gc is enabled
 your <code>$CATALINA_BASE/logs/catalina.out</code> log file will include
 data for every garbage collection including how long it took.</p>

 <p>When your JVM is tuned correctly 99% of the time a GC will take less
 than one second.  The remainder will only take a few seconds.  Rarely,
 if ever should a GC take more than 10 seconds.</p>

 <p>Make sure that the db connection timeout is set to 10-15 seconds.
 For the DBCP you set this using the parameter <code>maxWait</code>.</p>

 </subsection>

 <subsection name="Random Connection Closed Exceptions">
 <p>
 These can occur when one request gets a db connection from the connection
 pool and closes it twice.  When using a connection pool, closing the
 connection just returns it to the pool for reuse by another request,
 it doesn't close the connection.  And Tomcat uses multiple threads to
 handle concurrent requests. Here is an example of the sequence
 of events which could cause this error in Tomcat:
 <pre>
   Request 1 running in Thread 1 gets a db connection.

   Request 1 closes the db connection.

   The JVM switches the running thread to Thread 2

   Request 2 running in Thread 2 gets a db connection
   (the same db connection just closed by Request 1).

   The JVM switches the running thread back to Thread 1

   Request 1 closes the db connection a second time in a finally block.

   The JVM switches the running thread back to Thread 2

   Request 2 Thread 2 tries to use the db connection but fails
   because Request 1 closed it.
 </pre>
 Here is an example of properly written code to use a db connection
 obtained from a connection pool:
 <pre>
   Connection conn = null;
   Statement stmt = null;  // Or PreparedStatement if needed
   ResultSet rs = null;
   try {
     conn = ... get connection from connection pool ...
     stmt = conn.createStatement("select ...");
     rs = stmt.executeQuery();
     ... iterate through the result set ...
     rs.close();
     rs = null;
     stmt.close();
     stmt = null;
     conn.close(); // Return to connection pool
     conn = null;  // Make sure we don't close it twice
   } catch (SQLException e) {
     ... deal with errors ...
   } finally {
     // Always make sure result sets and statements are closed,
     // and the connection is returned to the pool
     if (rs != null) {
       try { rs.close(); } catch (SQLException e) { ; }
       rs = null;
     }
     if (stmt != null) {
       try { stmt.close(); } catch (SQLException e) { ; }
       stmt = null;
     }
     if (conn != null) {
       try { conn.close(); } catch (SQLException e) { ; }
       conn = null;
     }
   }
 </pre>
 </p>

 </subsection>

 <subsection name="Context versus GlobalNamingResources">
 <p>
   Please note that although the above instructions place the JNDI declarations in a Context
   element, it is possible and sometimes desirable to place these declarations in the
   <a href="config/globalresources.html">GlobalNamingResources</a> section of the server
   configuration file.  A resource placed in the GlobalNamingResources section will be shared
   among the Contexts of the server.
 </p>
 </subsection>

 <subsection name="JNDI Resource Naming and Realm Interaction">
 <p>
   In order to get Realms to work, the realm must refer to the datasource as
   defined in the &lt;GlobalNamingResources&gt; or &lt;Context&gt; section, not a datasource as renamed
   using &lt;ResourceLink&gt;.
 </p>
 </subsection>

 </section>

 </body>
 </document>
	<?xml version="1.0"?>
	<!DOCTYPE document [
	<!ENTITY project SYSTEM "project.xml">
	]>
	<document url="jndi-datasource-examples-howto.html">

	&project;

	<properties>
	<author email="leslie.hughes@rubus.com">Les Hughes</author>
	<author email="david-tomcat@haraburda.com">David Haraburda</author>
	<author>Glenn Nielsen</author>
	<author email="yoavs@apache.org">Yoav Shapira</author>
	<title>JNDI Datasource HOW-TO</title>
	</properties>

	<body>

	<section name="Table of Contents">
	<p>
	<a href="#Introduction">Introduction</a><br />
	<a href="#Database Connection Pool (DBCP) Configurations">
	Database Connection Pool (DBCP) Configurations</a><br />
	<a href="#Non DBCP Solutions">Non DBCP Solutions</a><br />
	<a href="#Oracle 8i with OCI client">Oracle 8i with OCI client</a><br />
	<a href="#Common Problems">Common Problems</a><br />
	</p>
	</section>

	<section name="Introduction">

	<p>JNDI Datasource configuration is covered extensively in the
	JNDI-Resources-HOWTO however, feedback from <code>tomcat-user</code> has
	shown that specifics for individual configurations can be rather tricky.</p>

	<p>Here then are some example configurations that have been posted to
	tomcat-user for popular databases and some general tips for db useage.</p>

	<p>You should be aware that since these notes are derived from configuration
	and/or feedback posted to <code>tomcat-user</code> YMMV :-). Please let us
	know if you have any other tested configurations that you feel may be of use
	to the wider audience, or if you feel we can improve this section in anyway.</p>

	</section>

	<section name="Database Connection Pool (DBCP) Configurations">

	<p>DBCP provides support for JDBC 2.0. On systems using a 1.4 JVM DBCP
	will support JDBC 3.0. Please let us know if you have used DBCP and its
	JDBC 3.0 features with a 1.4 JVM.
	</p>

	<p>See the <a href="http://jakarta.apache.org/commons/dbcp/api/index.html">
	DBCP Javadocs</a> BasicDataSource class for a complete list
	of configuration parameters.
	</p>

	<subsection name="Installation">
	<p>DBCP uses the Jakarta-Commons Database Connection Pool. It relies on
	number of Jakarta-Commons components:
	<ul>
	<li>Jakarta-Commons DBCP</li>
	<li>Jakarta-Commons Collections</li>
	<li>Jakarta-Commons Pool</li>
	</ul>
	These libraries are located in a single JAR at
	<code>$CATALINA_HOME/common/lib/naming-factory-dbcp.jar</code>.
	</p>

	</subsection>

	<subsection name="Preventing dB connection pool leaks">

	<p>
	A database connection pool creates and manages a pool of connections
	to a database. Recycling and reusing already existing connections
	to a dB is more efficient than opening a new connection.
	</p>

	<p>
	There is one problem with connection pooling. A web application has
	to explicetely close ResultSet's, Statement's, and Connection's.
	Failure of a web application to close these resources can result in
	them never being available again for reuse, a db connection pool "leak".
	This can eventually result in your web application db connections failing
	if there are no more available connections.</p>

	<p>
	There is a solution to this problem. The Jakarta-Commons DBCP can be
	configured to track and recover these abandoned dB connections. Not
	only can it recover them, but also generate a stack trace for the code
	which opened these resources and never closed them.</p>

	<p>
	To configure a DBCP DataSource so that abandoned dB connections are
	removed and recycled add the following attribute to the
	<code>Resource</code> configuration for your DBCP DataSource:
	<source>
	removeAbandoned="true"
	</source>
	When available db connections run low DBCP will recover and recyle
	any abandoned dB connections it finds. The default is <code>false</code>.
	</p>

	<p>
	Use the <code>removeAbandonedTimeout</code> attribute to set the number
	of seconds a dB connection has been idle before it is considered abandoned.
	<source>
	removeAbandonedTimeout="60"
	</source>
	The default timeout for removing abandoned connections is 300 seconds.
	</p>

	<p>
	The <code>logAbandoned</code> attribute can be set to <code>true</code>
	if you want DBCP to log a stack trace of the code which abandoned the
	dB connection resources.
	<source>
	logAbandoned="true"
	</source>
	The default is <code>false</code>.
	</p>

	</subsection>

	<subsection name="MySQL DBCP Example">

	<h3>0. Introduction</h3>
	<p>Versions of <a href="http://www.mysql.com/products/mysql/index.html">MySQL</a> and JDBC drivers that have been reported to work:
	<ul>
	<li>MySQL 3.23.47, MySQL 3.23.47 using InnoDB,, MySQL 3.23.58, MySQL 4.0.1alpha</li>
	<li><a href="http://www.mysql.com/products/connector-j">Connector/J</a> 3.0.11-stable (the official JDBC Driver)</li>
	<li><a href="http://mmmysql.sourceforge.net">mm.mysql</a> 2.0.14 (an old 3rd party JDBC Driver)</li>
	</ul>
	</p>

	<p>Before you proceed, don't forget to copy the JDBC Driver's jar into <code>$CATALINA_HOME/common/lib</code>.</p>

	<h3>1. MySQL configuration</h3>
	<p>
	Ensure that you follow these instructions as variations can cause problems.
	</p>

	<p>Create a new test user, a new database and a single test table.
	Your MySQL user <strong>must</strong> have a password assigned. The driver
	will fail if you try to connect with an empty password.
	<source>
	mysql> GRANT ALL PRIVILEGES ON . TO javauser@localhost
	-> IDENTIFIED BY 'javadude' WITH GRANT OPTION;
	mysql> create database javatest;
	mysql> use javatest;
	mysql> create table testdata (
	-> id int not null auto_increment primary key,
	-> foo varchar(25),
	-> bar int);
	</source>
	<blockquote>
	<strong>Note:</strong> the above user should be removed once testing is
	complete!
	</blockquote>
	</p>

	<p>Next insert some test data into the testdata table.
	<source>
	mysql> insert into testdata values(null, 'hello', 12345);
	Query OK, 1 row affected (0.00 sec)

	mysql> select * from testdata;
	+----+-------+-------+
	\| ID \| FOO \| BAR \|
	+----+-------+-------+
	\| 1 \| hello \| 12345 \|
	+----+-------+-------+
	1 row in set (0.00 sec)

	mysql>
	</source>
	</p>

	<h3>2. server.xml configuration</h3>
	<p>Configure the JNDI DataSource in Tomcat by adding a declaration for your
	resource to <code>$CATALINA_HOME/conf/server.xml</code>.</p>
	<p>Add this in between the <code></Context></code> tag of the examples
	context and the <code></Host></code> tag closing the localhost definition.<source>
	<Context path="/DBTest" docBase="DBTest"
	debug="5" reloadable="true" crossContext="true">

	<Logger className="org.apache.catalina.logger.FileLogger"
	prefix="localhost_DBTest_log." suffix=".txt"
	timestamp="true"/>

	<!-- maxActive: Maximum number of dB connections in pool. Make sure you
	configure your mysqld max_connections large enough to handle
	all of your db connections. Set to 0 for no limit.
	-->

	<!-- maxIdle: Maximum number of idle dB connections to retain in pool.
	Set to -1 for no limit. See also the DBCP documentation on this
	and the minEvictableIdleTimeMillis configuration parameter.
	-->

	<!-- maxWait: Maximum time to wait for a dB connection to become available
	in ms, in this example 10 seconds. An Exception is thrown if
	this timeout is exceeded. Set to -1 to wait indefinitely.
	-->

	<!-- username and password: MySQL dB username and password for dB connections -->

	<!-- driverClassName: Class name for the old mm.mysql JDBC driver is
	org.gjt.mm.mysql.Driver - we recommend using Connector/J though.
	Class name for the official MySQL Connector/J driver is com.mysql.jdbc.Driver.
	-->

	<!-- url: The JDBC connection url for connecting to your MySQL dB.
	The autoReconnect=true argument to the url makes sure that the
	mm.mysql JDBC Driver will automatically reconnect if mysqld closed the
	connection. mysqld by default closes idle connections after 8 hours.
	-->

	<Resource name="jdbc/TestDB" auth="Container" type="javax.sql.DataSource"
	maxActive="100" maxIdle="30" maxWait="10000"
	username="javauser" password="javadude" driverClassName="com.mysql.jdbc.Driver"
	url="jdbc:mysql://localhost:3306/javatest?autoReconnect=true"/>

	</Context>
	</source>
	</p>

	<h3>3. web.xml configuration</h3>

	<p>Now create a <code>WEB-INF/web.xml</code> for this test application.
	<source>
	<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
	http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
	version="2.4">
	<description>MySQL Test App</description>
	<resource-ref>
	<description>DB Connection</description>
	<res-ref-name>jdbc/TestDB</res-ref-name>
	<res-type>javax.sql.DataSource</res-type>
	<res-auth>Container</res-auth>
	</resource-ref>
	</web-app>
	</source>
	</p>

	<h3>4. Test code</h3>
	<p>Now create a simple <code>test.jsp</code> page for use later.
	<source>
	<%@ taglib uri="http://java.sun.com/jsp/jstl/sql" prefix="sql" %>
	<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>

	<sql:query var="rs" dataSource="jdbc/TestDB">
	select id, foo, bar from testdata
	</sql:query>

	<html>
	<head>
	<title>DB Test</title>
	</head>
	<body>

	<h2>Results</h2>

	<c:forEach var="row" items="${rs.rows}">
	Foo ${row.foo}<br/>
	Bar ${row.bar}<br/>
	</c:forEach>

	</body>
	</html>
	</source>
	</p>

	<p>That JSP page makes use of <a href="http://java.sun.com/products/jsp/jstl">JSTL</a>'s SQL and Core taglibs. You can get it from Sun's <a href="http://java.sun.com/webservices/downloads/webservicespack.html">Java Web Services Developer Pack</a> or <a href="http://jakarta.apache.org/taglibs/doc/standard-doc/intro.html">Jakarta Taglib Standard 1.1</a> project - just make sure you get a 1.1.x release. Once you have JSTL, copy <code>jstl.jar</code> and <code>standard.jar</code> to your web app's <code>WEB-INF/lib</code> directory.

	</p>

	<p>Finally deploy your web app into <code>$CATALINA_HOME/webapps</code> either
	as a warfile called <code>DBTest.war</code> or into a sub-directory called
	<code>DBTest</code></p>
	<p>Once deployed, point a browser at
	<code>http://localhost:8080/DBTest/test.jsp</code> to view the fruits of
	your hard work.</p>

	</subsection>

	<subsection name="Oracle 8i">
	<h3>0. Introduction</h3>
	<p><i>We would appreciate comments on this section as I'm not an Oracle DBA :-)</i></p>
	<p>Oracle requires minimal changes from the MySQL configuration except for the usual gotchas :-) Firstly
	by default, Tomcat will only use <code>*.jar</code> files installed in <code>$CATALINA_HOME/common/lib</code>
	therefore <code>classes111.zip</code> or <code>classes12.zip</code> will need to be renamed with a <code>.jar</code>
	extension. Since jarfiles are zipfiles, there is no need to unzip and jar these files - a simple rename will suffice.
	Also, you should be aware that some (early) versions of Tomcat 4.0 when used with JDK 1.4 will not load classes12.zip unless
	you unzip the file, remove the <code>javax.sql.*</code> class heirarchy and rejar.</p>
	<h3>1. server.xml configuration</h3>
	<p>In a similar manner to the mysql config above, you will need to define your Datasource in your server.xml
	file. Here we define a Datasource called myoracle using the thin driver to connect as user scott, password tiger
	to the schema called myschema in the sid called mysid. (Note: with the thin driver this sid is not the same as the tnsname)</p>

	<p>Use of the OCI driver should simply involve a changing thin to oci in the URL string.
	<source>
	<Resource name="jdbc/myoracle" auth="Container"
	type="javax.sql.DataSource" driverClassName="oracle.jdbc.driver.OracleDriver"
	url="jdbc:oracle:thin:myschema@127.0.0.1:1521:mysid"
	username="scott" password="tiger" maxActive="20" maxIdle="10"
	maxWait="-1"/>
	</source>
	</p>

	<h3>2. web.xml configuration</h3>
	<p>You should ensure that you respect the elemeent ordering defined by the DTD when you
	create you applications web.xml file.</p>
	<source>
	<resource-ref>
	<description>Oracle Datasource example</description>
	<res-ref-name>jdbc/myoracle</res-ref-name>
	<res-type>javax.sql.DataSource</res-type>
	<res-auth>Container</res-auth>
	</resource-ref>
	</source>
	<h3>3. Code example</h3>
	<p>You can use the same example application as above (asuming you create the required DB
	instance, tables etc.) replacing the Datasource code with something like</p>
	<source>
	Context initContext = new InitialContext();
	Context envContext = (Context)initContext.lookup("java:/comp/env");
	DataSource ds = (DataSource)envContext.lookup("jdbc/myoracle");
	Connection conn = ds.getConnection();
	//etc.
	</source>
	</subsection>


	<subsection name="PostgreSQL">
	<h3>0. Introduction</h3>
	<p>PostgreSQL is configured in a similar manner to Oracle. Again, highlighting the differences.
	These notes are untested as yet and we would appreciate feedback.</p>
	<h3>1. server.xml configuration</h3>
	<source>
	<Resource name="jdbc/postgres" auth="Container"
	type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
	url="jdbc:postgresql://127.0.0.1:5432/mydb"
	username="myuser" password="mypasswd" maxActive="20" maxIdle="10" maxWait="-1"/>
	</source>
	<h3>2. web.xml configuration</h3>
	<source>
	<resource-ref>
	<description>postgreSQL Datasource example</description>
	<res-ref-name>jdbc/postgres</res-ref-name>
	<res-type>javax.sql.DataSource</res-type>
	<res-auth>Container</res-auth>
	</resource-ref>
	</source>
	</subsection>
	</section>

	<section name="Non DBCP Solutions">
	<p>
	These solutions either utilise a single connection to the database (not recommended for anything other
	than testing!) or some other pooling technology.
	</p>
	</section>

	<section name="Oracle 8i with OCI client">
	<subsection name="Introduction">
	<p>Whilst not strictly addressing the creation of a JNDI DataSource using the OCI client, these notes can be combined with the
	Oracle and DBCP solution above.</p>
	<p>
	In order to use OCI driver, you should have an Oracle client installed. You should have installed
	Oracle8i(8.1.7) client from cd, and download the suitable JDBC/OCI
	driver(Oracle8i 8.1.7.1 JDBC/OCI Driver) from <a href="http://otn.oracle.com/">otn.oracle.com</a>.
	</p>
	<p>
	After renaming <code>classes12.zip</code> file to <code>classes12.jar</code>
	for Tomcat, copy it into <code>$CATALINA_HOME/common/lib</code>.
	You may also have to remove the <code>javax.sql.*</code> classes
	from this file depending upon the version of Tomcat and JDK you are using.
	</p>
	</subsection>

	<subsection name="Putting it all together">
	<p>
	Ensure that you have the <code>ocijdbc8.dll</code> or <code>.so</code> in your <code>$PATH</code> or <code>LD_LIBRARY_PATH</code>
	(possibly in <code>$ORAHOME\bin</code>) and also confirm that the native library can be loaded by a simple test program
	using <code>System.loadLibrary("ocijdbc8");</code>
	</p>
	<p>
	You should next create a simple test servlet or jsp that has these
	<strong>critical lines</strong>:
	</p>
	<source>
	DriverManager.registerDriver(new
	oracle.jdbc.driver.OracleDriver());
	conn =
	DriverManager.getConnection("jdbc:oracle:oci8:@database","username","password");
	</source>
	<p>
	where database is of the form <code>host:port:SID</code> Now if you try to access the URL of your
	test servlet/jsp and what you get is a
	<code>ServletException</code> with a root cause of <code>java.lang.UnsatisfiedLinkError:get_env_handle</code>.
	</p>
	<p>
	First, the <code>UnsatisfiedLinkError</code> indicates that you have
	<ul>
	<li>a mismatch between your JDBC classes file and
	your Oracle client version. The giveaway here is the message stating that a needed library file cannot be
	found. For example, you may be using a classes12.zip file from Oracle Version 8.1.6 with a Version 8.1.5
	Oracle client. The classeXXXs.zip file and Oracle client software versions must match.
	</li>
	<li>A <code>$PATH</code>, <code>LD_LIBRARY_PATH</code> problem.</li>
	<li>It has been reported that ignoring the driver you have downloded from otn and using
	the classes12.zip file from the directory <code>$ORAHOME\jdbc\lib</code> will also work.
	</li>
	</ul>
	</p>
	<p>
	Next you may experience the error <code>ORA-06401 NETCMN: invalid driver designator</code>
	</p>
	<p>
	The Oracle documentation says : "Cause: The login (connect) string contains an invalid
	driver designator. Action: Correct the string and re-submit."

	Change the database connect string (of the form <code>host:port:SID</code>) with this one:
	<code>(description=(address=(host=myhost)(protocol=tcp)(port=1521))(connect_data=(sid=orcl)))</code>
	</p>
	<p>
	<i>Ed. Hmm, I don't think this is really needed if you sort out your TNSNames - but I'm not an Oracle DBA :-)</i>
	</p>
	</subsection>
	</section>

	<section name="Common Problems">
	<p>Here are some common problems encountered with a web application which
	uses a database and tips for how to solve them.</p>

	<subsection name="Intermittent dB Connection Failures">
	<p>
	Tomcat runs within a JVM. The JVM periodically performs garbage collection
	(GC) to remove java objects which are no longer being used. When the JVM
	performs GC execution of code within Tomcat freezes. If the maximum time
	configured for establishment of a dB connection is less than the amount
	of time garbage collection took you can get a db conneciton failure.
	</p>

	<p>To collect data on how long garbage collection is taking add the
	<code>-verbose:gc</code> argument to your <code>CATALINA_OPTS</code>
	environment variable when starting Tomcat. When verbose gc is enabled
	your <code>$CATALINA_BASE/logs/catalina.out</code> log file will include
	data for every garbage collection including how long it took.</p>

	<p>When your JVM is tuned correctly 99% of the time a GC will take less
	than one second. The remainder will only take a few seconds. Rarely,
	if ever should a GC take more than 10 seconds.</p>

	<p>Make sure that the db connection timeout is set to 10-15 seconds.
	For the DBCP you set this using the parameter <code>maxWait</code>.</p>

	</subsection>

	<subsection name="Random Connection Closed Exceptions">
	<p>
	These can occur when one request gets a db connection from the connection
	pool and closes it twice. When using a connection pool, closing the
	connection just returns it to the pool for reuse by another request,
	it doesn't close the connection. And Tomcat uses multiple threads to
	handle concurrent requests. Here is an example of the sequence
	of events which could cause this error in Tomcat:
	<pre>
	Request 1 running in Thread 1 gets a db connection.

	Request 1 closes the db connection.

	The JVM switches the running thread to Thread 2

	Request 2 running in Thread 2 gets a db connection
	(the same db connection just closed by Request 1).

	The JVM switches the running thread back to Thread 1

	Request 1 closes the db connection a second time in a finally block.

	The JVM switches the running thread back to Thread 2

	Request 2 Thread 2 tries to use the db connection but fails
	because Request 1 closed it.
	</pre>
	Here is an example of properly written code to use a db connection
	obtained from a connection pool:
	<pre>
	Connection conn = null;
	Statement stmt = null; // Or PreparedStatement if needed
	ResultSet rs = null;
	try {
	conn = ... get connection from connection pool ...
	stmt = conn.createStatement("select ...");
	rs = stmt.executeQuery();
	... iterate through the result set ...
	rs.close();
	rs = null;
	stmt.close();
	stmt = null;
	conn.close(); // Return to connection pool
	conn = null; // Make sure we don't close it twice
	} catch (SQLException e) {
	... deal with errors ...
	} finally {
	// Always make sure result sets and statements are closed,
	// and the connection is returned to the pool
	if (rs != null) {
	try { rs.close(); } catch (SQLException e) { ; }
	rs = null;
	}
	if (stmt != null) {
	try { stmt.close(); } catch (SQLException e) { ; }
	stmt = null;
	}
	if (conn != null) {
	try { conn.close(); } catch (SQLException e) { ; }
	conn = null;
	}
	}
	</pre>
	</p>

	</subsection>

	<subsection name="Context versus GlobalNamingResources">
	<p>
	Please note that although the above instructions place the JNDI declarations in a Context
	element, it is possible and sometimes desirable to place these declarations in the
	<a href="config/globalresources.html">GlobalNamingResources</a> section of the server
	configuration file. A resource placed in the GlobalNamingResources section will be shared
	among the Contexts of the server.
	</p>
	</subsection>

	<subsection name="JNDI Resource Naming and Realm Interaction">
	<p>
	In order to get Realms to work, the realm must refer to the datasource as
	defined in the <GlobalNamingResources> or <Context> section, not a datasource as renamed
	using <ResourceLink>.
	</p>
	</subsection>

	</section>

	</body>
	</document>