The Apache Tomcat 5.5 Servlet/JSP Container: JNDI Datasource HOW-TO
The Apache Tomcat 5.5 Servlet/JSP Container: JNDI Datasource HOW-TO
The Apache Tomcat 5.5 Servlet/JSP Container: JNDI Datasource HOW-TO
5 Servlet/JSP
Container
print-friendly
version
Introduction
JNDI Datasource configuration is covered extensively in the JNDI-Resources-HOWTO.
However, feedback from tomcat-user has shown that specifics for individual configurations
can be rather tricky.
Here then are some example configurations that have been posted to tomcat-user for popular
databases and some general tips for db useage.
You should be aware that since these notes are derived from configuration and/or feedback
posted to tomcat-user 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.
Please note that JNDI resource configuration has changed somewhat between Tomcat 5.0.x
and Tomcat 5.5.x. You will most likely need to modify your JNDI resource configurations to
match the syntax in the example below in order to make them work in Tomcat 5.5.x.
Also, please note that JNDI DataSource configuration in general, and this tutorial in particular,
assumes that you have read and understood the Context and Host configuration references,
including the section about Automatic Application Deployment in the latter reference.
removeAbandoned="true"
When available db connections run low DBCP will recover and recyle any abandoned dB
connections it finds. The default is false.
Use the removeAbandonedTimeout attribute to set the number of seconds a dB connection has
been idle before it is considered abandoned.
removeAbandonedTimeout="60"
logAbandoned="true"
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 user must have a
password assigned. The driver will fail if you try to connect with an empty password.
mysql>
2. Context configuration
Configure the JNDI DataSource in Tomcat by adding a declaration for your resource to your
Context.
For example:
<!-- 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.
-->
</Context>
3. web.xml configuration
Now create a WEB-INF/web.xml for this test application.
<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>
4. Test code
Now create a simple test.jsp page for use later.
<%@ taglib uri="http://java.sun.com/jsp/jstl/sql" prefix="sql" %>
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
<html>
<head>
<title>DB Test</title>
</head>
<body>
<h2>Results</h2>
</body>
</html>
That JSP page makes use of JSTL's SQL and Core taglibs. You can get it from Sun's Java Web
Services Developer Pack or Jakarta Taglib Standard 1.1 project - just make sure you get a 1.1.x
release. Once you have JSTL, copy jstl.jar and standard.jar to your web app's WEB-
INF/lib directory.
Finally deploy your web app into $CATALINA_HOME/webapps either as a warfile called
DBTest.war or into a sub-directory called DBTest
Once deployed, point a browser at http://localhost:8080/DBTest/test.jsp to view the
fruits of your hard work.
2. web.xml configuration
You should ensure that you respect the element ordering defined by the DTD when you create
you applications web.xml file.
<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>
3. Code example
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
PostgreSQL
0. Introduction
PostgreSQL is configured in a similar manner to Oracle.
1. Required files
Copy the Postgres JDBC jar to $CATALINA_HOME/common/lib. As with Oracle, the jars
need to be in this directory in order for DBCP's Classloader to find them. 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 Tomcat applications, 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 across multiple Tomcat
applications, or if you just prefer defining your datasource in this file.
This author has not had success here, although others have reported so. Clarification would be
appreciated here.
3. web.xml configuration
<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>
if ( ds == null ) {
throw new Exception("Data source not found!");
}
Non-DBCP Solutions
These solutions either utilise a single connection to the database (not recommended for anything
other than testing!) or some other pooling technology.
DriverManager.registerDriver(new
oracle.jdbc.driver.OracleDriver());
conn =
DriverManager.getConnection("jdbc:oracle:oci8:@database","username","passwo
rd");
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 a ServletException 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 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.
• 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 invalid driver
designator. Action: Correct the string and re-submit." Change the database connect string (of the
form host: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 :-)
Common Problems
Here are some common problems encountered with a web application which uses a database and
tips for how to solve them.
Intermittent dB Connection Failures
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.
To collect data on how long garbage collection is taking add the -verbose:gc argument to your
CATALINA_OPTS environment variable when starting Tomcat. When verbose gc is enabled your
$CATALINA_BASE/logs/catalina.out log file will include data for every garbage collection
including how long it took.
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.
Make sure that the db connection timeout is set to 10-15 seconds. For the DBCP you set this
using the parameter maxWait.