The Apache Tomcat 5.5 Servlet/JSP Container - JNDI Datasource HOW-TO
The Apache Tomcat 5.5 Servlet/JSP Container
Links
Docs Home
FAQ
User Guide
1) Introduction
2) Setup
3) First webapp
4) Deployer
5) Manager
6) Realms and AAA
7) Security Manager
8) JNDI Resources
9) JDBC DataSources
10) Classloading
11) JSPs
12) SSL
13) SSI
14) CGI
15) Proxy Support
16) MBean Descriptor
17) Default Servlet
18) Clustering
19) Load Balancer
20) Connectors
21) Monitoring and Management
22) Logging
23) APR
24) Virtual Hosting
Reference
Release Notes
Apache Tomcat Configuration
JK 1.2 Documentation
Servlet API Javadocs
JSP API Javadocs
Apache Tomcat Development
Building
Changelog
Status
Developers
Functional Specs.
Apache Tomcat Javadocs
Apache Jasper Javadocs
Architecture
The Apache Tomcat 5.5 Servlet/JSP Container
JNDI Datasource HOW-TO
Table of Contents
Introduction
Database Connection Pool (DBCP) Configurations
Installation
Preventing dB connection pool leaks
MySQL DBCP Example
Oracle 8i, 9i & 10g
PostgreSQL
Non-DBCP Solutions
Oracle 8i with OCI client
Introduction
Putting it all together
Common Problems
Intermittent dB Connection Failures
Random Connection Closed Exceptions
Context versus GlobalNamingResources
JNDI Resource Naming and Realm Interaction
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 usage.
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.
Database Connection Pool (DBCP) Configurations
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.
See the
DBCP documentation
for a complete list of configuration parameters.
Installation
DBCP uses the Jakarta-Commons Database Connection Pool. It relies on
number of Jakarta-Commons components:
Jakarta-Commons DBCP
Jakarta-Commons Collections
Jakarta-Commons Pool
These libraries are located in a single JAR at
$CATALINA_HOME/common/lib/naming-factory-dbcp.jar
. However,
only the classes needed for connection pooling have been included, and the
packages have been renamed to avoid interfering with applications.
Preventing dB connection pool leaks
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.
There is one problem with connection pooling. A web application has
to explicitly 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.
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.
To configure a DBCP DataSource so that abandoned dB connections are
removed and recycled add the following attribute to the
Resource
configuration for your DBCP DataSource:
removeAbandoned="true"
When available db connections run low DBCP will recover and recycle
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"
The default timeout for removing abandoned connections is 300 seconds.
The
logAbandoned
attribute can be set to
true
if you want DBCP to log a stack trace of the code which abandoned the
dB connection resources.
logAbandoned="true"
The default is
false
MySQL DBCP Example
0. Introduction
Versions of
MySQL
and JDBC drivers that have been reported to work:
MySQL 3.23.47, MySQL 3.23.47 using InnoDB,, MySQL 3.23.58, MySQL 4.0.1alpha
Connector/J
3.0.11-stable (the official JDBC Driver)
mm.mysql
2.0.14 (an old 3rd party JDBC Driver)
Before you proceed, don't forget to copy the JDBC Driver's jar into
$CATALINA_HOME/common/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 user
must
have a password assigned. The driver
will 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 is
complete!
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 your
resource to your
Context
For example:
username="javauser" password="javadude" driverClassName="com.mysql.jdbc.Driver"
url="jdbc:mysql://localhost:3306/javatest"/>
3. web.xml configuration
Now create a
WEB-INF/web.xml
for this test application.
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
version="2.4">
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" %>
select id, foo, bar from testdata
Results
Foo ${row.foo}
Bar ${row.bar}
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
to view the fruits of
your hard work.
Oracle 8i, 9i & 10g
0. Introduction
Oracle requires minimal changes from the MySQL configuration except for the
usual gotchas :-)
Drivers for older Oracle versions may be distributed as *.zip files rather
than *.jar files. Tomcat will only use
*.jar
files installed in
$CATALINA_HOME/common/lib
. Therefore
classes111.zip
or
classes12.zip
will need to be renamed with a
.jar
extension. Since jarfiles are zipfiles, there is no need to unzip and jar these
files - a simple rename will suffice.
For Oracle 9i onwards you should use
oracle.jdbc.OracleDriver
rather than
oracle.jdbc.driver.OracleDriver
as Oracle have stated
that
oracle.jdbc.driver.OracleDriver
is deprecated and support
for 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 your
Datasource in your
Context
. Here we define a
Datasource 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 is
not the same as the tnsname). The schema used will be the default schema for the
user scott.
Use of the OCI driver should simply involve a changing thin to oci in the URL string.
url="jdbc:oracle:thin:@127.0.0.1:1521:mysid"
username="scott" password="tiger" maxActive="20" maxIdle="10"
maxWait="-1"/>
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.
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
Context initContext = new InitialContext();
Context envContext = (Context)initContext.lookup("java:/comp/env");
DataSource ds = (DataSource)envContext.lookup("jdbc/myoracle");
Connection conn = ds.getConnection();
//etc.
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.
url="jdbc:postgresql://127.0.0.1:5432/mydb"
username="myuser" password="mypasswd" maxActive="20" maxIdle="10" maxWait="-1"/>
2b. Application-specific resource configuration
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 your
Tomcat installation.
Create a resource definition for your
Context
The Context element should look something like the following.
url="jdbc:postgresql://127.0.0.1:5432/mydb"
username="myuser" password="mypasswd" maxActive="20" maxIdle="10"
maxWait="-1"/>
3. web.xml configuration
4. Accessing the datasource
When accessing the datasource programmatically, remember to prepend
java:/comp/env
to your JNDI lookup, as in the following snippet of
code. Note also that "jdbc/postgres" can be replaced with any value you prefer, provided
you 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!");
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.
Oracle 8i with OCI client
Introduction
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.
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
otn.oracle.com
After renaming
classes12.zip
file to
classes12.jar
for Tomcat, copy it into
$CATALINA_HOME/common/lib
You may also have to remove the
javax.sql.*
classes
from this file depending upon the version of Tomcat and JDK you are using.
Putting it all together
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
using
System.loadLibrary("ocijdbc8");
You should next create a simple test servlet or jsp that has these
critical lines
DriverManager.registerDriver(new
oracle.jdbc.driver.OracleDriver());
conn =
DriverManager.getConnection("jdbc:oracle:oci8:@database","username","password");
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.
$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
Random Connection Closed Exceptions
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:
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 db connection
obtained 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;
Context versus GlobalNamingResources
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
GlobalNamingResources
section of the server
configuration file. A resource placed in the GlobalNamingResources section will be shared
among the Contexts of the server.
JNDI Resource Naming and Realm Interaction
In order to get Realms to work, the realm must refer to the datasource as
defined in the
using
Copyright © 1999-2012, Apache Software Foundation