JNDI Datasource HOW-TO
Table of Contents
Introduction
Database Connection Pool (DBCP) Configurations
Non DBCP Solutions
Oracle 8i with OCI client
Common Problems
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.
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 Javadocs BasicDataSource class for a complete list of configuration parameters.
Installation
DBCP uses the Jakarta-Commons Database Connection Pool. It relies on number of Jakarta-Commons componenets:
These jar files along with your the jar file for your JDBC driver should be installed in $CATALINA_HOME/common/lib.
- Jakarta-Commons DBCP 1.0
- Jakarta-Commons Collections 2.0
- Jakarta-Commons Pool 1.0
NOTE:Third Party drivers should be in jarfiles, not zipfiles. Tomcat only adds $CATALINA_HOME/common/lib/*.jar to the classpath.NOTE: Do not install these jarfiles in your /WEB-INF/lib, or $JAVA_HOME/jre/lib/ext, or anywhere else. You will experience problems if you install them anyplace other than $CATALINA_HOME/common/lib.
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 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.
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 paramater to the ResourceParams configuration for your DBCP DataSource Resource:
<parameter> <name>removeAbandoned</name> <value>true</value> </parameter>When available db connections run low DBCP will recover and recyle any abandoned dB connections it finds. The default is false. Use the removeAbandonedTimeout parameter to set the number of seconds a dB connection has been idle before it is considered abandoned.
<parameter> <name>removeAbandonedTimeout</name> <value>60</value> </parameter>The default timeout for removing abandoned connections is 300 seconds. The logAbandoned parameter can be set to true if you want DBCP to log a stack trace of the code which abandoned the dB connection resources.
<parameter> <name>logAbandoned</name> <value>true</value> </parameter>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);Next insert some test data into the testdata table.
2. server.xml configuration
Configure the JNDI DataSource in Tomcat by adding a declaration for your resource to $CATALINA_HOME/conf/server.xml.
Add this in between the </Context> tag of the examples context and the </Host> tag closing the localhost definition.
<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"/> <Resource name="jdbc/TestDB" auth="Container" type="javax.sql.DataSource"/> <ResourceParams name="jdbc/TestDB"> <parameter> <name>factory</name> <value>org.apache.commons.dbcp.BasicDataSourceFactory</value> </parameter> <!-- 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. --> <parameter> <name>maxActive</name> <value>100</value> </parameter> <!-- 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. --> <parameter> <name>maxIdle</name> <value>30</value> </parameter> <!-- 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. --> <parameter> <name>maxWait</name> <value>10000</value> </parameter> <!-- MySQL dB username and password for dB connections --> <parameter> <name>username</name> <value>javauser</value> </parameter> <parameter> <name>password</name> <value>javadude</value> </parameter> <!-- Class name for the old mm.mysql JDBC driver - uncomment this entry and comment next if you want to use this driver - we recommend using Connector/J though <parameter> <name>driverClassName</name> <value>org.gjt.mm.mysql.Driver</value> </parameter> --> <!-- Class name for the official MySQL Connector/J driver --> <parameter> <name>driverClassName</name> <value>com.mysql.jdbc.Driver</value> </parameter> <!-- 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. --> <parameter> <name>url</name> <value>jdbc:mysql://localhost:3306/javatest?autoReconnect=true</value> </parameter> </ResourceParams> </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"> <web-app> <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" %> <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>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.
Oracle 8i
0. Introduction
We would appreciate comments on this section as I'm not an Oracle DBA :-)
Oracle requires minimal changes from the MySQL configuration except for the usual gotchas :-) Firstly by default, 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. 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 javax.sql.* class heirarchy and rejar.
1. server.xml configuration
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)
Use of the OCI driver should simply involve a changing thin to oci in the URL string.
<Resource name="jdbc/myoracle" auth="Container" type="javax.sql.DataSource"/> <ResourceParams name="jdbc/myoracle"> <parameter> <name>factory</name> <value>org.apache.commons.dbcp.BasicDataSourceFactory</value> </parameter> <parameter> <name>driverClassName</name> <value>oracle.jdbc.driver.OracleDriver</value> </parameter> <parameter> <name>url</name> <value>jdbc:oracle:thin:myschema@127.0.0.1:1521:mysid</value> </parameter> <parameter> <name>username</name> <value>scott</value> </parameter> <parameter> <name>password</name> <value>tiger</value> </parameter> <parameter> <name>maxActive</name> <value>20</value> </parameter> <parameter> <name>maxIdle</name> <value>10</value> </parameter> <parameter> <name>maxWait</name> <value>-1</value> </parameter> </ResourceParams>
2. web.xml configuration
You should ensure that you respect the elemeent 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. Again, highlighting the differences. These notes are untested as yet and we would appreciate feedback.
1. server.xml configuration
<Resource name="jdbc/postgres" auth="Container" type="javax.sql.DataSource"/> <ResourceParams name="jdbc/postgres"> <parameter> <name>factory</name> <value>org.apache.commons.dbcp.BasicDataSourceFactory</value> </parameter> <parameter> <name>driverClassName</name> <value>org.postgresql.Driver</value> </parameter> <parameter> <name>url</name> <value>jdbc:postgresql://127.0.0.1:5432/mydb</value> </parameter> <parameter> <name>username</name> <value>myuser</value> </parameter> <parameter> <name>password</name> <value>mypasswd</value> </parameter> <parameter> <name>maxActive</name> <value>20</value> </parameter> <parameter> <name>maxIdle</name> <value>10</value> </parameter> <parameter> <name>maxWait</name> <value>-1</value> </parameter> </ResourceParams>
2. web.xml configuration
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.
- 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.
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 <GlobalNamingResources> or <Context> section, not a datasource as renamed using <ResourceLink>.