You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by re...@apache.org on 2002/07/03 19:42:55 UTC
cvs commit: jakarta-tomcat-4.0/webapps/tomcat-docs jndi-datasource-examples-howto.xml project.xml
remm 2002/07/03 10:42:54
Modified: webapps/tomcat-docs project.xml
Added: webapps/tomcat-docs jndi-datasource-examples-howto.xml
Log:
- Add some example configurations for the datasources. Much sought
after information :)
- Thanks to Leslie Hughes <leslie.hughes at rubus.com>
and David Haraburda <david-tomcat at haraburda.com>
Revision Changes Path
1.14 +2 -0 jakarta-tomcat-4.0/webapps/tomcat-docs/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/project.xml,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- project.xml 9 Sep 2001 22:43:48 -0000 1.13
+++ project.xml 3 Jul 2002 17:42:53 -0000 1.14
@@ -26,6 +26,8 @@
<item name="Config. Reference" href="config/index.html"/>
<item name="Class Loader HOW-TO" href="class-loader-howto.html"/>
<item name="JNDI Resources HOW-TO" href="jndi-resources-howto.html"/>
+ <item name="JNDI DataSource Examples"
+ href="jndi-datasource-examples-howto.html"/>
<item name="Manager App HOW-TO" href="manager-howto.html"/>
<item name="Proxy Support HOW-TO" href="proxy-howto.html"/>
<item name="Realm HOW-TO" href="realm-howto.html"/>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/jndi-datasource-examples-howto.xml
Index: jndi-datasource-examples-howto.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
<properties>
<author email="leslie.hughes@rubus.com">Les Hughes</author>
<author email="david-tomcat@haraburda.com">David Haraburda</author>
<title>JNDI Datasource Examples HOW-TO</title>
</properties>
<body>
<section name="Introduction">
<p>JNDI Datasource configuration is covered extensively in the JNDI-Resources-HOWTO
however, feedback from <code>tomcat-user</code> has shown that specifics for individual
configurations can be rather tricky.</p>
<p>Here then are some example configurations that have posted to tomcat-user
for popular databases.</p>
</section>
<section name="Jakarta DBCP Pooled Configurations">
<p>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 <code>tomcat-user</code>.
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.</p>
<ul>
<li>DBCP Nightly build > 20020523</li>
<li>collections 2.0</li>
<li>pool 1.0</li>
</ul>
<subsection name="Common Requirements">
<p>Here are some common gotchas to consider</p>
<ul>
<li>Datasource related classes (drivers, pools etc) should be installed in <code>$CATALINA_HOME/common/lib</code>
to enable the server to find your classes when it creates your Datasources</li>
<li>Third Party drivers should be in jarfiles, not zipfiles as by default, Tomcat
only adds <code>$CATALINA_HOME/common/lib/*.jar</code> to the classpath</li>
</ul>
</subsection>
<subsection name="mySQL using Jakarta Commons Connection Pool">
<h3>0. Software Manifest</h3>
<p>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.</p>
<ul>
<li>Tomcat 4.0.3</li>
<li>mySQL 4.0.1alpha</li>
<li>mm.mysql 2.0.14 (JDBC Driver)</li>
</ul>
<h3>1. Installation</h3>
<p>Ensure that you follow these instructions as variations can cause problems.</p>
<ul>
<li>Install mm.mysql driver, DBCP, collections and pool jarfiles into
<code>$CATALINA_HOME/common/lib</code>. You will experience problems if you place
these jarfiles in your webapp's <code>WEB-INF/lib</code> directory, in your
<code>$JAVA_HOME/jre/lib/ext</code> or anywhere else, so dont.</li>
<li>Create a new test user, a new database and a single test table.
Your mySQL user <b>must</b> have a password assigned. The driver
will fail if you try to connect with an empty password.</li></ul>
<source>
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);
</source>
<p>Note: the above user should be removed once testing is complete!</p>
<ul><li>Next insert some test data into the testdata table</li></ul>
<source>
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>
</source>
<ul><li>Now create a simple test.jsp for use later.</li></ul>
<source>
<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>
</source>
<ul><li>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 :-)</li></ul>
<source>
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;}
}
</source>
<ul><li>Now create a <code>WEB-INF/web.xml</code> for this test application</li></ul>
<source>
<?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>
</source>
<p>That completes the standard webapp aspects of the test application. Now to configure Tomcat.</p>
<ul><li>Add a declaration of your resource to <code>$CATALINA_HOME/conf/server.xml</code>
Add this in between the <code></Context></code> tag of the examples context and the
<code></Host></code> tag closing the localhost definition. DONT ADD IT TO THE WARP CONNECTOR SECTION!!!
</li></ul>
<source>
<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>
</source>
<ul><li>Finally deploy your web app into <code>$CATALINA_HOME/webapps</code> either as a warfile called
<code>DBTest.war</code> or into a sub-directory called <code>DBTest</code></li>
<li>Once deployed, point a browser at <code>http://localhost:8080/DBTest/test.jsp</code> to view the fruits of your hard work.</li></ul>
<p><i>ToDo: Perhaps we could bundle a simple project and Ant buildfile to demonstrate?</i></p>
</subsection>
<subsection name="Oracle 8i using Jakarta Commons Connection Pool">
<h3>0. Introduction</h3>
<p><i>We would appreciate comments on this section as I'm not an Oracle DBA :-)</i></p>
<p>Oracle requires minimal changes from the mySQL configuration except for the usual gotchas :-) Firstly
by default, Tomcat will only use <code>*.jar</code> files installed in <code>$CATALINA_HOME/common/lib</code>
therefore <code>classes111.zip</code> or <code>classes12.zip</code> will need to be renamed with a <code>.jar</code>
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 <code>javax.sql.*</code> class heirarchy and rejar.</p>
<h3>1. server.xml configuration</h3>
<p>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)</p>
<p>Use of the OCI driver should simply involve a changing thin to oci in the URL string.</p>
<source>
<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>
</source>
<h3>2. web.xml configuration</h3>
<p>You should ensure that you respect the elemeent ordering defined by the DTD when you
create you applications web.xml file.</p>
<source>
<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>
</source>
<h3>3. Code example</h3>
<p>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</p>
<source>
Context initContext = new InitialContext();
Context envContext = (Context)initContext.lookup("java:/comp/env");
DataSource ds = (DataSource)envContext.lookup("jdbc/myoracle");
Connection conn = ds.getConnection();
//etc.
</source>
</subsection>
<subsection name="PostgreSQL using Jakarta Commons Connection Pool">
<h3>0. Introduction</h3>
<p>PostgreSQL is configured in a similar manner to Oracle. Again, highlighting the differences.
These notes are untested as yet and we would appreciate feedback.</p>
<h3>1. server.xml configuration</h3>
<source>
<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>
</source>
<h3>2. web.xml configuration</h3>
<source>
<resource-ref>
<description>postgreSQL Datasource example</description>
<res-ref-name>jdbc/mydb</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
</source>
</subsection>
</section>
<section name="Non DBCP Solutions">
<p>
These solutions either utilise a single connection to the database (not recommended for anything other
than testing!) or some other pooling technology.
</p>
</section>
<section name="Tyrex Connection Pool and Castor ORM with mysql">
<subsection name="Introduction">
<p>
Tomcat 4.1 provides transaction management and resource configuration support through the use of
<a href="http://tyrex.exolab.org/">Tyrex</a> 1.0. This allows the user to obtain JTA/JCA resources
from the JNDI namespace, as well as the standard <code>javax.transaction.UserTransaction</code>.
</p>
</subsection>
<subsection name="Installing Required JARs">
<p>
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:
</p>
<p>
The following jars are included with Tyrex binary distribution, available at http://tyrex.exolab.org.
<ul>
<li>tyrex-1.0.jar</li>
<li>ots-jts_1.0.jar</li>
<li>jta_1.0.1.jar</li>
<li>xerces-J_1.4.0.jar</li>
</ul>
The following two jars are required as well:
<ul>
<li>Castor XML jar (<a href="http://castor.exolab.org/">http://castor.exolab.org/</a>, version 0.92 or higher is reccommended)</li>
<li>Log4J (<a href="http://jakarta.apache.org/log4j/">http://jakarta.apache.org/log4j/</a>, version 1.0.4 or higher is reccommended)</li>
</ul>
</p>
<p>
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.
</p>
</subsection>
<subsection name="Configuring Tyrex">
<p>
The Tyrex documentation (http://tyrex.exolab.org) provides complete details on how to properly configure Tyrex. As an example, we will use the following Tyrex configuration, specified in Tyrex's domain configuration XML file:
</p>
<source>
<domain>
<name>myDomain</name>
<resources>
<dataSource>
<name>myDatasource</name>
<jar>/home/david/mm.mysql-2.0.14-bin.jar</jar>
<class>org.gjt.mm.mysql.jdbc2.optional.MysqlXaDataSource</class>
<config>
<user>david</user>
<password>secret</password>
<serverName>localhost</serverName>
<port>3306</port>
<database>daviddb</database>
</config>
</dataSource>
</resources>
</domain>
</source>
<p>
A few things to note:
<ul>
<li>You need to specify the full pathname of the JAR file (for relative paths, Tyrex looks in the current working directory, this usually isn't what you want). You can also specify a URL.</li>
<li>Any elements nested inside the <config></config> elements are passed as parameters to the datasource class, using standard setter methods.</li>
<li>More configuration options are available, as well as a better description of how to setup Tyrex, at <a href="http://tyrex.exolab.org/configuration.html">http://tyrex.exolab.org/configuration.html</a></li>
</ul>
</p>
<p>
This XML config file needs to be placed where Tomcat's classloader can find it using getResource(). This means that the WEB-INF/classes directory under your webapp is a very good choice.
</p>
</subsection>
<subsection name="Configuring Tomcat">
<p>
Now that your Tyrex XML config file is in place and ready, you must enlist the Tyrex resources in the JNDI namespace. This is done through Tomcat's server.xml file.
Two important parameters must be specified: the name of the domain config file (<code>tyrexDomainConfig</code>), and the name of the Tyrex domain that is to be used (<code>tyrexDomainName</code>).
These need to be setup as Environment parameters, like so:
</p>
<source>
<Environment name="tyrexDomainConfig" type="java.lang.String" value="domain-config.xml"/>
<Environment name="tyrexDomainName" type="java.lang.String" value="myDomain"/>
</source>
<p>
Now, you must configure the resource (under the <Context> element of your webapp):
</p>
<source>
<Resource name="my-datasource" auth="Container" type="tyrex.resource.Resource"/>
<ResourceParams name="my-datasource">
<parameter>
<name>name</name>
<value>myDataSource</name>
</parameter>
</ResourceParams>
</source>
<p>
A couple of things to point out:
<ul>
<li>The type of resource should always be <code>tyrex.resource.Resource</code>, regardless of how you have Tyrex configured.</li>
<li>Only one ResourceParam parameter is needed, <code>name</code> -- the value should be set to the name of resource specified in the Tyrex config file.</li>
<li>Note the difference between a Tomcat/JNDI resource and a Tyrex resource (it can be confusing at first glance!)</li>
</ul>
</p>
</subsection>
<subsection name="Coding Your Application">
<p>
Making use of your Tyrex resource should now be relatively simple. To obtain your datasource, simply use JNDI:
</p>
<source>
InitialContext initCtx = new InitialContext();
DataSource ds = (DataSource) initCtx.lookup("java:comp/env/my-datasource");
Connection conn = ds.getConnection();
..and so on.
</source>
<p>
Tyrex also provides a <code>javax.transaction.UserTransaction</code>,
obtainable through JNDI at the standard location (<code>java:comp/UserTransaction</code>).
</p>
</subsection>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: cvs commit: jakarta-tomcat-4.0/webapps/tomcat-docs
jndi-datasource-examples-howto.xml project.xml
Posted by David Haraburda <da...@haraburda.com>.
The subtitle for the Tyrex stuff is incorrect, it reads:
"Tyrex Connection Pool and Castor ORM with mysql"
Tyrex has nothing to do with Castor (especially my example!), and
the stuff I wrote was not meant to serve as an example on how to use
it with mysql (I only used the JAR file name as an example -- the config
was not tested). And of course, Tyrex is more than a connection pool.
I would suggest that it be changed to something like:
"Tyrex Resource Management"
Tyrex is kind of different from the rest of the examples, and its purpose is different,
so I'd think it may want to be kept split into a different doc -- but I'm not picky, it's
just a suggestion (although the title needs to change for sure). :-)
David
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>