Links Getting Started Administrators Application Developers Catalina Developers Jasper Developers | JNDI Datasource Examples HOW-TOIntroduction |
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 posted to tomcat-user
for popular databases.
|
Jakarta DBCP Pooled Configurations |
For each of these configurations you will need the following Jakarta Commons projects
Note that currently, these all employ connection pooling
via the Jakarta-commons connection pool. Also, you should be aware that since these
notes are derived from the mysql configuration and/or feedback from 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.
- DBCP Nightly build > 20020523
- collections 2.0
- pool 1.0
Common Requirements |
Here are some common gotchas to consider
- Datasource related classes (drivers, pools etc) should be installed in
$CATALINA_HOME/common/lib
to enable the server to find your classes when it creates your Datasources
- Third Party drivers should be in jarfiles, not zipfiles as by default, Tomcat
only adds
$CATALINA_HOME/common/lib/*.jar to the classpath
|
mySQL using Jakarta Commons Connection Pool |
0. Software Manifest
Starting with the correct sotftware is manifestly important, so here's a list of
what we've found to work. Let us know of your success stories with other versions.
- Tomcat 5
- mySQL 4.0.1alpha
- mm.mysql 2.0.14 (JDBC Driver)
1. Installation
Ensure that you follow these instructions as variations can cause problems.
- Install mm.mysql driver, DBCP, collections and pool jarfiles into
$CATALINA_HOME/common/lib . You will experience problems if you place
these jarfiles in your webapp's WEB-INF/lib directory, in your
$JAVA_HOME/jre/lib/ext or anywhere else, so dont.
- 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>
|  |  |  |  |
- Now create a simple test.jsp for use later.
 |  |  |  |
<html>
<head>
<title>DB Test</title>
</head>
<body>
<%
foo.DBTest tst = new foo.DBTest();
tst.init();
%>
<h2>Results</h2>
Foo <%= tst.getFoo() %><br/>
Bar <%= tst.getBar() %>
</body>
</html>
|  |  |  |  |
- And create a Java class to actually use your new Datasource and connection pool. Note: this
code isn't anywhere near production ready - it's only supposed to be used as a simple test :-)
 |  |  |  |
package foo;
import javax.naming.*;
import javax.sql.*;
import java.sql.*;
public class DBTest {
String foo = "Not Connected";
int bar = -1;
public void init() {
try{
Context ctx = new InitialContext();
if(ctx == null )
throw new Exception("Boom - No Context");
DataSource ds =
(DataSource)ctx.lookup(
"java:comp/env/jdbc/TestDB");
if (ds != null) {
Connection conn = ds.getConnection();
if(conn != null) {
foo = "Got Connection "+conn.toString();
Statement stmt = conn.createStatement();
ResultSet rst =
stmt.executeQuery(
"select id, foo, bar from testdata");
if(rst.next()) {
foo=rst.getString(2);
bar=rst.getInt(3);
}
conn.close();
}
}
}catch(Exception e) {
e.printStackTrace();
}
}
public String getFoo() { return foo; }
public int getBar() { return bar;}
}
|  |  |  |  |
- Now create a
WEB-INF/web.xml for this test application
 |  |  |  |
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app PUBLIC
"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<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>
|  |  |  |  |
That completes the standard webapp aspects of the test application. Now to configure Tomcat.
- Add a declaration of 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. DONT ADD IT TO THE WARP CONNECTOR SECTION!!!
 |  |  |  |
<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>
<parameter>
<name>maxActive</name>
<value>100</value>
</parameter>
<parameter>
<name>maxIdle</name>
<value>30000</value>
</parameter>
<parameter>
<name>maxWait</name>
<value>100</value>
</parameter>
<parameter>
<name>username</name>
<value>javauser</value>
</parameter>
<parameter>
<name>password</name>
<value>javadude</value>
</parameter>
<parameter>
<name>driverClassName</name>
<value>org.gjt.mm.mysql.Driver</value>
</parameter>
<parameter>
<name>url</name>
<value>jdbc:mysql://localhost:3306/javatest</value>
</parameter>
</ResourceParams>
</Context>
|  |  |  |  |
- 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.
ToDo: Perhaps we could bundle a simple project and Ant buildfile to demonstrate?
|
|
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.
|
Tyrex Connection Pool |
Introduction |
Tomcat 5 provides transaction management and resource configuration support through the use of
Tyrex 1.0. This allows the user to obtain JTA/JCA resources
from the JNDI namespace, as well as the standard javax.transaction.UserTransaction .
|
Installing Required JARs |
In order for a web application to use Tyrex, the webapp and Tomcat need to have access to the
Tyrex jar, as well as the jars it requires. Here is a list of the required jars, and where to obtain them:
The following jars are included with Tyrex binary distribution, available at http://tyrex.exolab.org.
- tyrex-1.0.jar
- ots-jts_1.0.jar
- jta_1.0.1.jar
- xerces-J_1.4.0.jar
The following two jars are required as well:
All six of these jar files need to be placed on $TOMCAT_HOME/common/lib so that both Tomcat and your web application will see them.
|
|
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 :-)
|
|
|