JNDI Datasource configuration is covered extensively in theJNDI-Resources-HOWTO. However, feedback fromtomcat-user hasshown that specifics for individual configurations can be rather tricky.
Here then are some example configurations that have been posted totomcat-user for popular databases and some general tips for db usage.
You should be aware that since these notes are derived from configurationand/or feedback posted totomcat-user YMMV :-). Please let usknow if you have any other tested configurations that you feel may be of useto the wider audience, or if you feel we can improve this section in anyway.
Please note that JNDI resource configuration changed somewhat betweenTomcat 5.0.x and Tomcat 5.5.x. You will most likely need to modify olderJNDI resource configurations to match the syntax in the example below in orderto make them work in Tomcat 6.x.x.
Also, please note that JNDI DataSource configuration in general, and this tutorial in particular, assumes that you have read and understood theContext andHost configuration references, includingthe section about Automatic Application Deployment in the latter reference.
java.sql.DriverManager supports theserviceprovider mechanism. This feature is that all the available JDBC driversthat announce themselves by providing a META-INF/services/java.sql.Driverfile are automatically discovered, loaded and registered,relieving you from the need to load the database driver explicitly beforeyou create a JDBC connection.However, the implementation is fundamentally broken in all Java versions fora servlet container environment. The problem is thatjava.sql.DriverManager will scan for the drivers only once.
The JRE Memory Leak Prevention Listenerthat is included with Apache Tomcat solves this by triggering the drivers scanduring Tomcat startup. This is enabled by default. It means that onlylibraries visible to the listener such as the ones in$CATALINA_BASE/lib will be scanned for database drivers.If you are considering disabling this feature, note thatthe scan would be triggered by the first web application that isusing JDBC, leading to failures when this web application is reloadedand for other web applications that rely on this feature.
Thus, the web applications that have database drivers in theirWEB-INF/lib directory cannot rely on the service providermechanism and should register the drivers explicitly.
The list of drivers in java.sql.DriverManager is alsoa known source of memory leaks. Any Drivers registeredby a web application must be deregistered when the web application stops.Tomcat will attempt to automatically discover and deregister anyJDBC drivers loaded by the web application class loader when the webapplication stops.However, it is expected that applications do this for themselves viaaServletContextListener.
The default database connection pool implementation in Apache Tomcatrelies on the libraries from theApache Commons project.The following libraries are used:
Commons DBCP
Commons Pool
These libraries are located in a single JAR at $CATALINA_HOME/lib/tomcat-dbcp.jar. However,only the classes needed for connection pooling have been included, and thepackages have been renamed to avoid interfering with applications.
A database connection pool creates and manages a pool of connectionsto a database. Recycling and reusing already existing connectionsto a database is more efficient than opening a new connection.
There is one problem with connection pooling. A web application hasto explicitly close ResultSet's, Statement's, and Connection's.Failure of a web application to close these resources can result inthem never being available again for reuse, a database connection pool "leak".This can eventually result in your web application database connections failingif there are no more available connections.
There is a solution to this problem. The Apache Commons DBCP can beconfigured to track and recover these abandoned database connections. Notonly can it recover them, but also generate a stack trace for the codewhich opened these resources and never closed them.
To configure a DBCP DataSource so that abandoned database connections areremoved and recycled add the following attribute to theResource configuration for your DBCP DataSource:
removeAbandoned="true"
When available database connections run low DBCP will recover and recycleany abandoned database connections it finds. The default isfalse.
Use the removeAbandonedTimeout attribute to set the numberof seconds a database connection has been idle before it is considered abandoned.
removeAbandonedTimeout="60"
The default timeout for removing abandoned connections is 300 seconds.
The logAbandoned attribute can be set to trueif you want DBCP to log a stack trace of the code which abandoned thedatabase connection resources.
Before you proceed, don't forget to copy the JDBC Driver's jar into $CATALINA_HOME/lib.
1. MySQL configuration
Ensure that you follow these instructions as variations can cause problems.
Create a new test user, a new database and a single test table.Your MySQL usermust have a password assigned. The driverwill fail if you try to connect with an empty password.
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);
Note: the above user should be removed once testing iscomplete!
Next insert some test data into the testdata table.
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>
2. Context configuration
Configure the JNDI DataSource in Tomcat by adding a declaration for yourresource to yourContext.
For example:
<Context>
<!-- maxActive: Maximum number of database connections in pool. Make sure you
configure your mysqld max_connections large enough to handle
all of your db connections. Set to -1 for no limit.
-->
<!-- maxIdle: Maximum number of idle database 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 database 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 username and password for database 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 database.
-->
<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"/>
</Context>
3. web.xml configuration
Now create a WEB-INF/web.xml for this test application.
That JSP page makes use of JSTL'sSQL and Core taglibs. You can get it fromApache Tomcat Taglibs - Standard Tag Libraryproject — just make sure you get a 1.1.x release. Once you have JSTL,copy jstl.jar and standard.jar to your web app'sWEB-INF/lib directory.
Finally deploy your web app into $CATALINA_BASE/webapps eitheras a warfile calledDBTest.war or into a sub-directory calledDBTest
Oracle requires minimal changes from the MySQL configuration except for theusual gotchas :-)
Drivers for older Oracle versions may be distributed as *.zip files ratherthan *.jar files. Tomcat will only use*.jar files installed in$CATALINA_HOME/lib. Therefore classes111.zipor classes12.zip will need to be renamed with a.jarextension. Since jarfiles are zipfiles, there is no need to unzip and jar thesefiles - a simple rename will suffice.
For Oracle 9i onwards you should use oracle.jdbc.OracleDriverrather thanoracle.jdbc.driver.OracleDriver as Oracle have statedthat oracle.jdbc.driver.OracleDriver is deprecated and supportfor this driver class will be discontinued in the next major release.
1. Context configuration
In a similar manner to the mysql config above, you will need to define yourDatasource in yourContext. Here we define aDatasource called myoracle using the thin driver to connect as user scott,password tiger to the sid called mysid. (Note: with the thin driver this sid isnot the same as the tnsname). The schema used will be the default schema for theuser scott.
Use of the OCI driver should simply involve a changing thin to oci in the URL string.
You can use the same example application as above (asuming you create the required DBinstance, tables etc.) replacing the Datasource code with something like
PostgreSQL is configured in a similar manner to Oracle.
1. Required files
Copy the Postgres JDBC jar to $CATALINA_HOME/lib. As with Oracle, thejars need to be in this directory in order for DBCP's Classloader to findthem. This has to be done regardless of which configuration step you take next.
2. Resource configuration
You have two choices here: define a datasource that is shared across all Tomcatapplications, or define a datasource specifically for one application.
2a. Shared resource configuration
Use this option if you wish to define a datasource that is shared acrossmultiple Tomcat applications, or if you just prefer defining your datasourcein this file.
This author has not had success here, although others have reported so.Clarification would be appreciated here.
Use this option if you wish to define a datasource specific to your application,not visible to other Tomcat applications. This method is less invasive to yourTomcat installation.
Create a resource definition for your Context.The Context element should look something like the following.
When accessing the datasource programmatically, remember to prependjava:/comp/env to your JNDI lookup, as in the following snippet ofcode. Note also that "jdbc/postgres" can be replaced with any value you prefer, providedyou change it in the above resource definition file as well.
InitialContext cxt = new InitialContext();
if ( cxt == null ) {
throw new Exception("Uh oh -- no context!");
}
DataSource ds = (DataSource) cxt.lookup( "java:/comp/env/jdbc/postgres" );
if ( ds == null ) {
throw new Exception("Data source not found!");
}
Whilst not strictly addressing the creation of a JNDI DataSource using the OCI client, these notes can be combined with theOracle and DBCP solution above.
In order to use OCI driver, you should have an Oracle client installed. You should have installedOracle8i(8.1.7) client from cd, and download the suitable JDBC/OCIdriver(Oracle8i 8.1.7.1 JDBC/OCI Driver) fromotn.oracle.com.
After renaming classes12.zip file to classes12.jarfor Tomcat, copy it into$CATALINA_HOME/lib. You may also have to remove the javax.sql.* classesfrom this file depending upon the version of Tomcat and JDK you are using.
Ensure that you have the ocijdbc8.dll or .so in your$PATH or LD_LIBRARY_PATH (possibly in $ORAHOME\bin) and also confirm that the native library can be loaded by a simple test program usingSystem.loadLibrary("ocijdbc8");
You should next create a simple test servlet or jsp that has thesecritical lines:
where database is of the form host:port:SID Now if you try to access the URL of your test servlet/jsp and what you get is aServletException with a root cause of java.lang.UnsatisfiedLinkError:get_env_handle.
First, the UnsatisfiedLinkError indicates that you have
a mismatch between your JDBC classes file andyour Oracle client version. The giveaway here is the message stating that a needed library file cannot befound. For example, you may be using a classes12.zip file from Oracle Version 8.1.6 with a Version 8.1.5Oracle client. The classeXXXs.zip file and Oracle client software versions must match.
A $PATH, LD_LIBRARY_PATH problem.
It has been reported that ignoring the driver you have downloded from otn and using the classes12.zip file from the directory$ORAHOME\jdbc\lib will also work.
Next you may experience the error ORA-06401 NETCMN: invalid driver designator
The Oracle documentation says : "Cause: The login (connect) string contains an invaliddriver designator. Action: Correct the string and re-submit."Change the database connect string (of the formhost:port:SID) with this one:(description=(address=(host=myhost)(protocol=tcp)(port=1521))(connect_data=(sid=orcl)))
Ed. Hmm, I don't think this is really needed if you sort out your TNSNames - but I'm not an Oracle DBA :-)
Tomcat runs within a JVM. The JVM periodically performs garbage collection(GC) to remove java objects which are no longer being used. When the JVMperforms GC execution of code within Tomcat freezes. If the maximum timeconfigured for establishment of a database connection is less than the amountof time garbage collection took you can get a database connection failure.
To collect data on how long garbage collection is taking add the-verbose:gc argument to yourCATALINA_OPTSenvironment variable when starting Tomcat. When verbose gc is enabledyour$CATALINA_BASE/logs/catalina.out log file will includedata for every garbage collection including how long it took.
When your JVM is tuned correctly 99% of the time a GC will take lessthan one second. The remainder will only take a few seconds. Rarely,if ever should a GC take more than 10 seconds.
Make sure that the db connection timeout is set to 10-15 seconds.For the DBCP you set this using the parametermaxWait.
These can occur when one request gets a db connection from the connectionpool and closes it twice. When using a connection pool, closing theconnection just returns it to the pool for reuse by another request,it doesn't close the connection. And Tomcat uses multiple threads tohandle concurrent requests. Here is an example of the sequenceof events which could cause this error in Tomcat:
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.
Here is an example of properly written code to use a database connectionobtained from a connection pool:
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;
}
}
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 theGlobalNamingResources section of the server configuration file. A resource placed in the GlobalNamingResources section will be shared among the Contexts of the server.
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>.
Int roductionJNDI Datasource configuration is covered extensively in theJNDI-Resources-HOWTO. However, feedback fromtomcat-user hasshown that specifics for individual configurations can