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/11/16 15:59:08 UTC
cvs commit: jakarta-tomcat-catalina/webapps/docs/config jk2.xml project.xml connectors.xml http11.xml jk.xml webapp.xml
remm 2002/11/16 06:59:07
Modified: webapps/docs build.xml jndi-datasource-examples-howto.xml
project.xml
webapps/docs/config jk2.xml project.xml
Added: webapps/docs cgi-howto.xml jasper-howto.xml ssi-howto.xml
Removed: webapps/docs/config connectors.xml http11.xml jk.xml
webapp.xml
Log:
- Documentation spring cleaning (massive port from TC 4.1).
- Remove docs for non Coyote based connectors (which wouldn't work).
Revision Changes Path
1.2 +8 -0 jakarta-tomcat-catalina/webapps/docs/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/build.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- build.xml 18 Jul 2002 16:48:28 -0000 1.1
+++ build.xml 16 Nov 2002 14:59:07 -0000 1.2
@@ -65,6 +65,14 @@
<fileset dir="WEB-INF"/>
</copy>
+ <!-- Build Coyote JK2 documentation -->
+ <mkdir dir="${webapps.build}/${webapp.name}/jk2"/>
+ <ant dir="${jtc.home}/jk" target="docs"/>
+
+ <copy todir="${webapps.build}/${webapp.name}/jk2">
+ <fileset dir="${jtc.home}/jk/build/docs"/>
+ </copy>
+
</target>
1.4 +380 -151 jakarta-tomcat-catalina/webapps/docs/jndi-datasource-examples-howto.xml
Index: jndi-datasource-examples-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/jndi-datasource-examples-howto.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- jndi-datasource-examples-howto.xml 24 Sep 2002 12:13:16 -0000 1.3
+++ jndi-datasource-examples-howto.xml 16 Nov 2002 14:59:07 -0000 1.4
@@ -9,66 +9,162 @@
<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>
+ <author>Glenn Nielsen</author>
+ <title>JNDI Datasource HOW-TO</title>
</properties>
<body>
+<section name="Table of Contents">
+<p>
+<a href="#Introduction">Introduction</a><br />
+<a href="#Database Connection Pool (DBCP) Configurations">
+Database Connection Pool (DBCP) Configurations</a><br />
+<a href="#Tyrex Connection Pool">Tyrex Connection Pool</a><br />
+<a href="#Non DBCP Solutions">Non DBCP Solutions</a><br />
+<a href="#Oracle 8i with OCI client">Oracle 8i with OCI client</a><br />
+<a href="#Common Problems">Common Problems</a><br />
+</p>
+</section>
<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>
+<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 been posted to
+tomcat-user for popular databases and some general tips for db useage.</p>
+
+<p>You should be aware that since these notes are derived from configuration
+and/or feedback posted to <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>
+
</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>
+
+<section name="Database Connection Pool (DBCP) Configurations">
+
+<p>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.
+</p>
+
+<p>See the <a href="http://jakarta.apache.org/commons/dbcp/api/index.html">
+DBCP Javadocs</a> BasicDataSource class for a complete list
+of configuration parameters.
+</p>
+
+<subsection name="Installation">
+<p>DBCP uses the Jakarta-Commons Database Connection Pool. It relies on
+number of Jakarta-Commons componenets:
<ul>
-<li>DBCP Nightly build > 20020523</li>
-<li>collections 2.0</li>
-<li>pool 1.0</li>
+<li>Jakarta-Commons DBCP 1.0</li>
+<li>Jakarta-Commons Collections 2.0</li>
+<li>Jakarta-Commons Pool 1.0</li>
</ul>
-<subsection name="Common Requirements">
-<p>Here are some common gotchas to consider</p>
+These jar files along with your the jar file for your JDBC driver should
+be installed in <code>$CATALINA_HOME/common/lib</code>.
+<blockquote>
+<strong>NOTE:</strong>Third Party drivers should be in jarfiles, not zipfiles.
+Tomcat only adds <code>$CATALINA_HOME/common/lib/*.jar</code> to the classpath.
+</blockquote>
+<blockquote>
+<strong>NOTE:</strong>
+Do not install these jarfiles in your <code>/WEB-INF/lib</code>, or
+<code>$JAVA_HOME/jre/lib/ext</code>, or anywhere else. You will
+experience problems if you install them anyplace other than
+<code>$CATALINA_HOME/common/lib</code>.
+</blockquote>
+</p>
+
+</subsection>
+
+<subsection name="Preventing dB connection pool leaks">
+
+<p>
+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.
+</p>
+
+<p>
+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.</p>
+
+<p>
+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.</p>
+
+<p>
+To configure a DBCP DataSource so that abandoned dB connections are
+removed and recycled add the following <code>paramater</code> to the
+<code>ResourceParams</code> configuration for your DBCP DataSource
+<code>Resource</code>:
+<source>
+ <parameter>
+ <name>removeAbandoned</name>
+ <value>true</value>
+ </parameter>
+</source>
+When available db connections run low DBCP will recover and recyle
+any abandoned dB connections it finds. The default is <code>false</code>.
+</p>
+
+<p>
+Use the <code>removeAbandonedTimeout</code> parameter to set the number
+of seconds a dB connection has been idle before it is considered abandoned.
+<source>
+ <parameter>
+ <name>removeAbandonedTimeout</name>
+ <value>60</value>
+ </parameter>
+</source>
+The default timeout for removing abandoned connections is 300 seconds.
+</p>
+
+<p>
+The <code>logAbandoned</code> parameter can be set to <code>true</code>
+if you want DBCP to log a stack trace of the code which abandoned the
+dB connection resources.
+<source>
+ <parameter>
+ <name>logAbandoned</name>
+ <value>true</value>
+ </parameter>
+</source>
+The default is <code>false</code>.
+</p>
+
+</subsection>
+
+<subsection name="MySQL DBCP Example">
+
+<h3>0. Introduction</h3>
+<p>Versions of MySQL and the mm.mysql JDBC driver when have been
+reported to work:
<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>
+<li>MySQL 3.23.47, MySQL 3.23.47 using InnoDB, MySQL 4.0.1alpha</li>
+<li>mm.mysql 2.0.14 (JDBC Driver)</li>
</ul>
-</subsection>
+Please let us know if you have tested the new MySQL mm.mysql 3.0 driver.
+</p>
+<h3>1. MySQL configuration</h3>
+<p>
+Ensure that you follow these instructions as variations can cause problems.
+</p>
-<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 5</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>
+<p>Create a new test user, a new database and a single test table.
+Your MySQL user <strong>must</strong> have a password assigned. The driver
+will fail if you try to connect with an empty password.
+<source>
mysql> GRANT ALL PRIVILEGES ON *.* TO javauser@localhost
-> IDENTIFIED BY 'javadude' WITH GRANT OPTION;
mysql> create database javatest;
@@ -77,10 +173,15 @@
-> 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>
+</source>
+<blockquote>
+<strong>Note:</strong> the above user should be removed once testing is
+complete!
+</blockquote>
+</p>
+
+<p>Next insert some test data into the testdata table.
+<source>
mysql> insert into testdata values(null, 'hello', 12345);
Query OK, 1 row affected (0.00 sec)
@@ -94,8 +195,109 @@
mysql>
</source>
- <ul><li>Now create a simple test.jsp for use later.</li></ul>
- <source>
+</p>
+
+<h3>2. server.xml configuration</h3>
+<p>Configure the JNDI DataSource in Tomcat by adding a declaration for your
+resource to <code>$CATALINA_HOME/conf/server.xml</code>.</p>
+<p>Add this in between the <code></Context></code> tag of the examples
+context and the <code></Host></code> tag closing the localhost definition.<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>
+
+ <!-- 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 0 for no limit.
+ -->
+ <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 mm.mysql JDBC driver -->
+ <parameter>
+ <name>driverClassName</name>
+ <value>org.gjt.mm.mysql.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>
+</source>
+</p>
+
+<h3>3. web.xml configuration</h3>
+
+<p>Now create a <code>WEB-INF/web.xml</code> for this test application.
+<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>
+
+<h3>4. Test code</h3>
+<p>Now create a simple test.jsp for use later.
+<source>
<html>
<head>
<title>DB Test</title>
@@ -114,9 +316,12 @@
</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>
+</p>
+
+<p>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 :-)
+<source>
package foo;
import javax.naming.*;
@@ -163,101 +368,32 @@
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>
+</p>
-<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>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></p>
+<p>Once deployed, point a browser at
+<code>http://localhost:8080/DBTest/test.jsp</code> to view the fruits of
+your hard work.</p>
-<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">
+<subsection name="Oracle 8i">
<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
+<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 5 when used with JDK 1.4 will not load classes12.zip unless
+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>
+<p>Use of the OCI driver should simply involve a changing thin to oci in the URL string.
<source>
<Resource name="jdbc/myoracle" auth="Container"
type="javax.sql.DataSource"/>
@@ -297,6 +433,8 @@
</parameter>
</ResourceParams>
</source>
+</p>
+
<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>
@@ -321,7 +459,7 @@
</subsection>
-<subsection name="PostgreSQL using Jakarta Commons Connection Pool">
+<subsection name="PostgreSQL">
<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>
@@ -377,18 +515,8 @@
</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">
+
<subsection name="Introduction">
<p>
@@ -516,10 +644,14 @@
</p>
</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="Oracle 8i with OCI client">
<subsection name="Introduction">
@@ -545,7 +677,8 @@
using <code>System.loadLibrary("ocijdbc8");</code>
</p>
<p>
-You should next create a simple test servlet or jsp that has these <b>critical lines</b>:
+You should next create a simple test servlet or jsp that has these
+<strong>critical lines</strong>:
</p>
<source>
DriverManager.registerDriver(new
@@ -588,6 +721,102 @@
</subsection>
</section>
+<section name="Common Problems">
+<p>Here are some common problems encountered with a web application which
+uses a database and tips for how to solve them.</p>
+
+<subsection name="Intermittent dB Connection Failures">
+<p>
+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.
+</p>
+
+<p>To collect data on how long garbage collection is taking add the
+<code>-verbose:gc</code> argument to your <code>CATALINA_OPTS</code>
+environment variable when starting Tomcat. When verbose gc is enabled
+your <code>$CATALINA_BASE/logs/catalina.out</code> log file will include
+data for every garbage collection including how long it took.</p>
+
+<p>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.</p>
+
+<p>Make sure that the db connection timeout is set to 10-15 seconds.
+For the DBCP you set this using the parameter <code>maxWait</code>.</p>
+
+</subsection>
+
+<subsection name="Random Connection Closed Exceptions">
+<p>
+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:
+<pre>
+ 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.
+</pre>
+Here is an example of properly written code to use a db connection
+obtained from a connection pool:
+<pre>
+ 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;
+ }
+ }
+</pre>
+</p>
+
+</subsection>
+
+</section>
+
</body>
</document>
-
1.5 +10 -3 jakarta-tomcat-catalina/webapps/docs/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/project.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- project.xml 18 Oct 2002 20:47:02 -0000 1.4
+++ project.xml 16 Nov 2002 14:59:07 -0000 1.5
@@ -22,16 +22,23 @@
<item name="Building from Source" href="BUILDING.txt"/>
</menu>
+ <menu name="Configuration">
+ <item name="Reference" href="config/index.html"/>
+ </menu>
+
<menu name="Administrators">
- <item name="Config. Reference" href="config/index.html"/>
+ <item name="CGI HOW-TO" href="cgi-howto.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"
+ <item name="JK Documentation" href="jk2/index.html"/>
+ <item name="JNDI DataSource HOW-TO"
href="jndi-datasource-examples-howto.html"/>
+ <item name="JNDI Resources HOW-TO" href="jndi-resources-howto.html"/>
+ <item name="JSP Engine Config HOW-TO" href="jasper-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"/>
<item name="Security Mgr. HOW-TO" href="security-manager-howto.html"/>
+ <item name="SSI Config HOW-TO" href="ssi-howto.html"/>
<item name="SSL Config HOW-TO" href="ssl-howto.html"/>
</menu>
1.1 jakarta-tomcat-catalina/webapps/docs/cgi-howto.xml
Index: cgi-howto.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
<properties>
<author email="glenn@apache.org">Glenn L. Nielsen</author>
<title>CGI How To</title>
</properties>
<body>
<section name="Introduction">
<p>The CGI (Common Gateway Interface) defines a way for a web server to
interact with external content-generating programs, which are often
referred to as CGI programs or CGI scripts.
</p>
<p>Within Tomcat CGI support can be added when using Tomcat as your
HTTP server and you require CGI support. Typically this is done
during development when you don't want to run a web server like Apache.</p>
<p>CGI support is implemented using the servlet class
<code>org.apache.catalina.servlets.CGIServlet</code>. Traditionally,
this servlet is mapped to the URL pattern "/cgi-bin/*".</p>
<p>By default CGI support is disabled in Tomcat.</p>
</section>
<section name="Installation">
<p><strong>CAUTION</strong> - CGI scripts are used to execute programs
external to the Tomcat JVM. If you are using the Java SecurityManager this
will bypass your security policy configuration in <code>catalina.policy.</code></p>
<p>Rename <code>$CATALINA_BASE/server/lib/servlets-cgi.renametojar</code>
to <code>$CATALINA_BASE/server/lib/servlets-cgi.jar</code>.</p>
<p>Remove the XML comments from around the CGI servlet and servlet-mapping
configuration in <code>$CATALINA_BASE/conf/web.xml</code>.</p>
</section>
<section name="Configuration">
<p>There are several servlet init parameters which can be used to
configure the behaviour of the CGI servlet.
<ul>
<li><strong>cgiPathPrefix</strong> - The CGI search path will start at
the web application root directory + File.separator + this prefix.
The default cgiPathPrefix is <code>/WEB-INF/cgi</code></li>
<li><strong>clientInputTimeout</strong> - The time (in milliseconds) to
wait for input from the browser before assuming that there is none.
Default is <code>100</code> seconds.</li>
<li><strong>debug</strong> - Debugging detail level for messages logged
by this servlet. Default 0.</li>
</ul>
</p>
</section>
</body>
</document>
1.1 jakarta-tomcat-catalina/webapps/docs/jasper-howto.xml
Index: jasper-howto.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
<properties>
<author email="glenn@apache.org">Glenn L. Nielsen</author>
<title>Jasper 2 JSP Engine How To</title>
</properties>
<body>
<section name="Table of Contents">
<p>
<a href="#Introduction">Introduction</a><br />
<a href="#Upgrading">Upgrading</a><br />
<a href="#Configuration">Configuration</a><br />
<a href="#Production Configuration">Production Configuration</a><br />
<a href="#Using Jikes">Using Jikes</a><br />
</p>
</section>
<section name="Introduction">
<p>Starting with Tomcat 4.1, Tomcat uses the Jasper 2 JSP Engine to implement
the <a href="http://java.sun.com/products/jsp/">JavaServer Pages 1.2</a>
specification.</p>
<p>Jasper 2 has been redesigned to significantly improve performance over
the orignal Jasper. In addition to general code improvements the following
changes were made:
<ul>
<li><strong>JSP Custom Tag Pooling</strong> - The java objects instantiated
for JSP Custom Tags can now be pooled and reused. This significantly boosts
the performance of JSP pages which use custom tags.</li>
<li><strong>Background JSP compilation</strong> - If you make a change to
a JSP page which had already been compiled Jasper 2 can recompile that
page in the background. The previously compiled JSP page will still be
available to serve requests. Once the new page has been compiled
successfully it will replace the old page. This helps improve availablity
of your JSP pages on a production server.</li>
<li><strong>Recompile JSP when included page changes</strong> - Jasper 2
can now detect when a page included at compile time from a JSP has changed
and then recompile the parent JSP.</li>
<li><strong>Ant used to compile JSP pages</strong> - The
<a href="http://jakarta.apache.org/ant/">Ant Build Tool</a> is now
used to perform JSP java source code compilation.</li>
</ul>
</p>
<p>Jasper is implemented using the servlet class
<code>org.apache.jasper.servlet.JspServlet</code>.</p>
</section>
<section name="Upgrading">
<p>Upgrading to Tomcat 4.1 and Jasper 2 from an earlier version of
Tomcat and/or Jasper.</p>
<p>Jasper 2 generates different java source code from Jasper 1. You
must remove all previous class files generated for your JSP pages
from your <code>work</code> directory.</p>
<p>Jasper 2 implements JSP Custom Tag Pooling. This can cause
JSP custom tags which are not compliant with the JSP specification to fail
or behave inconsistently. When upgrading from a version of Tomcat earlier
than 4.1 you should test to make sure your JSP pages which use custom tags
are working correctly.</p>
</section>
<section name="Configuration">
<p>By default Jasper is configured for use when doing web application
development. See the section <a href="#Production Configuration">
Production Configuration</a> for information on configuring Jasper
for use on a production Tomcat server.</p>
<p>The servlet which implements Jasper is configured using init parameters
in your global <code>$CATALINA_BASE/conf/web.xml</code>.
<ul>
<li><strong>checkInterval</strong> - If development is false and reloading is
true, background compiles are enabled. checkInterval is the time in seconds
between checks to see if a JSP page needs to be recompiled. Default
<code>300</code> seconds.</li>
<li><strong>compiler</strong> - Which compiler Ant should use to compile JSP
pages. See the Ant documenation for more information. Default
<code>javac</code>.</li>
<li><strong>classdebuginfo</strong> - Should the class file be compiled with
debugging information? <code>true</code> or <code>false</code>, default
<code>true</code>.
</li>
<li><strong>classpath</strong> - What class path should I use while compiling
generated servlets? By default the classpath is created dynamically based on
the current web application.</li>
<li><strong>development</strong> - Is Jasper used in development mode (will
check for JSP modification on every access)? <code>true</code> or
<code>false</code>, default <code>true</code>.</li>
<li><strong>enablePooling</strong> - Determines whether tag handler pooling is
enabled. <code>true</code> or <code>false</code>, default <code>true</code>.
</li>
<li><strong>ieClassId</strong> - The class-id value to be sent to Internet
Explorer when using <jsp:plugin> tags. Default
<code>clsid:8AD9C840-044E-11D1-B3E9-00805F499D93</code>.</li>
<li><strong>javaEncoding</strong> - Java file encoding to use for generating
java source files. Default <code>UTF8</code>.</li>
<li><strong>keepgenerated</strong> - Should we keep the generated Java source
code for each page instead of deleting it? <code>true</code> or
<code>false</code>, default <code>true</code>.</li>
<li><strong>largefile</strong> - Should we store the static content of JSP
pages in external data files, to reduce the size of the generated servlets?
<code>true</code> or <code>false</code>, default <code>false</code>.</li>
<li><strong>logVerbosityLevel</strong> - The level of detailed messages to be
produced by this servlet. Increasing levels cause the generation of more
messages. Valid values are <code>FATAL, ERROR, WARNING, INFORMATION,</code>
and <code>DEBUG</code>. Default <code>WARNING</code>.</li>
<li><strong>mappedfile</strong> - Should we generate static content with one
print statement per input line, to ease debugging?
<code>true</code> or <code>false</code>, default <code>false</code>.</li>
<li><strong>reloading</strong> - Should Jasper check for modified JSPs?
<code>true</code> or <code>false</code>, default <code>true</code>.</li>
<li><strong>scratchdir</strong> - What scratch directory should we use when
compiling JSP pages? Default is the work directory for the current web
application.</li>
</ul>
</p>
</section>
<section name="Production Configuration">
<p>When using Jasper 2 in a production Tomcat server you should consider
making the following changes from the default configuration.
<ul>
<li><strong>development</strong> - To enable background compilation of JSP
pages set this to <code>false</code>.</li>
<li><strong>compiler</strong> - The internal JVM javac compiler used by Ant
has a known memory leak. If you anticipate that JSP pages will get recompiled
frequently consider using an external compiler such as <code>jikes</code>.</li>
</ul>
</p>
</section>
<section name="Using Jikes">
<p>If you wish to use
<a href="http://oss.software.ibm.com/developerworks/opensource/jikes/">
Jikes</a> to compile JSP pages:
<ul>
<li>Download and install jikes. jikes must support the -encoding option.
Execute <code>jikes -help</code> to verify that it was built with support
for <code>-encoding</code>.</li>
<li>Set the init parameter <code>compiler</code> to <code>jikes</code>.</li>
<li>Define the property <code>-Dbuild.compiler.emacs=true</code> when starting
Tomcat by adding it to your <code>CATALINA_OPTS</code> environment variable.
This changes how jikes outputs error messages so that it is compatible with
Jasper.</li>
<li>If you get an error reporting that jikes can't use UTF8 encoding, try
setting the init parameter <code>javaEncoding</code> to
<code>ISO-8859-1</code>.</li>
</ul>
</p>
</section>
</body>
</document>
1.1 jakarta-tomcat-catalina/webapps/docs/ssi-howto.xml
Index: ssi-howto.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document>
&project;
<properties>
<author email="glenn@apache.org">Glenn L. Nielsen</author>
<title>SSI How To</title>
</properties>
<body>
<section name="Introduction">
<p>SSI (Server Side Includes) are directives that are placed in HTML pages,
and evaluated on the server while the pages are being served. They let you
add dynamically generated content to an existing HTML page, without having
to serve the entire page via a CGI program, or other dynamic technology.
</p>
<p>Within Tomcat SSI support can be added when using Tomcat as your
HTTP server and you require SSI support. Typically this is done
during development when you don't want to run a web server like Apache.</p>
<p>Tomcat SSI support implements the same SSI directives as Apache. See the
<a href="http://httpd.apache.org/docs/howto/ssi.html#basicssidirectives">
Apache Introduction to SSI</a> for information on using SSI directives.</p>
<p>SSI support is implemented using the servlet class
<code>org.apache.catalina.ssi.SSIServlet</code>. Traditionally, this servlet
is mapped to the URL pattern "*.shtml".</p>
<p>By default SSI support is disabled in Tomcat.</p>
</section>
<section name="Installation">
<p><strong>CAUTION</strong> - SSI directives can be used to execute programs
external to the Tomcat JVM. If you are using the Java SecurityManager this
will bypass your security policy configuration in <code>catalina.policy.</code>
</p>
<p>Rename <code>$CATALINA_BASE/server/lib/servlets-ssi.renametojar</code>
to <code>$CATALINA_BASE/server/lib/servlets-ssi.jar</code>.</p>
<p>Remove the XML comments from around the SSI servlet and servlet-mapping
configuration in <code>$CATALINA_BASE/conf/web.xml</code>.</p>
</section>
<section name="Configuration">
<p>There are several servlet init parameters which can be used to
configure the behaviour of the SSI servlet.
<ul>
<li><strong>buffered</strong> - Should output from this servlet be buffered?
(0=false, 1=true) Default 0 (false).</li>
<li><strong>debug</strong> - Debugging detail level for messages logged
by this servlet. Default 0.</li>
<li><strong>expires</strong> - The number of seconds before a page with SSI
directives will expire. Default behaviour is for all SSI directives to be
evaluated for every request.</li>
<li><strong>isVirtualWebappRelative</strong> - Should "virtual" SSI directive
paths be interpreted as relative to the context root, instead of the server
root? (0=false, 1=true) Default 0 (false).</li>
</ul>
</p>
</section>
</body>
</document>
1.3 +3 -451 jakarta-tomcat-catalina/webapps/docs/config/jk2.xml
Index: jk2.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/config/jk2.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- jk2.xml 30 Jul 2002 03:58:28 -0000 1.2
+++ jk2.xml 16 Nov 2002 14:59:07 -0000 1.3
@@ -93,8 +93,7 @@
<strong>org.apache.coyote.tomcat4.CoyoteConnector</strong>, but you
must specify the protocolHandlerClassName attribute (see below).</p>
- <p><strong>This implementation supports the AJP 1.3 and 1.4
- protocols.</strong></p>
+ <p><strong>This implementation supports the AJP 1.3 protocol.</strong></p>
<p>It supports the following additional attributes (in addition to the
common attributes listed above):</p>
@@ -128,13 +127,6 @@
<code>maxProcessors</code>. The default value is 5.</p>
</attribute>
- <attribute name="port" required="true">
- <p>The TCP port number on which this <strong>Connector</strong>
- will create a server socket and await incoming connections. Your
- operating system will allow only one server application to listen
- to a particular port number on a particular IP address.</p>
- </attribute>
-
<attribute name="protocolHandlerClassName" required="false">
<p>This attribute value must be
<code>org.apache.jk.server.JkCoyoteHandler</code> to use the JK 2
@@ -157,448 +149,8 @@
<section name="Configuration HOWTOs">
- <subsection name="Apache">
-
- <subsection name="Introduction">
-
- <p>This section explains how to connect Tomcat 5 to the popular
- open source web server, Apache. It was originally part of
- <i>Tomcat: A Minimalistic User's Guide</i> by Gal Shachor, but
- has been split off for organizational reasons. It should be
- considered a <b>work in progress</b>. Since the Tomcat source
- tree is constantly changing, the information herein may be out
- of date. The only definitive reference at this point is the <a
- href="http://jakarta.apache.org/site/sourceindex.html">source
- code</a>.</p>
-
- </subsection>
-
- <subsection name="Installation">
-
- <subsection name="Needed Components">
-
- <p>In a nutshell a web server is waiting for client HTTP requests.
- When these requests arrive the server does whatever is needed to
- serve the requests by providing the necessary content. Adding a
- servlet container may somewhat change this behavior. Now the web
- server needs also to perform the following:</p>
-
- <ul>
- <li>Load the servlet container adapter library
- and initialize it (prior to serving requests). </li>
- <li>When a request arrives, it needs to check and see if a certain
- request belongs to a servlet, if so it needs to let the adapter
- take the request and handle it.</li>
- </ul>
-
- <p>The adapter on the other hand needs to know what requests it is
- going to serve, usually based on some pattern in the request URL,
- and to where to direct these requests.</p>
-
- <p>Things are even more complex when the user wants to set
- a configuration that uses virtual hosts, or when they want multiple
- developers to work on the same web server but on different servlet
- container JVMs. We will cover these two cases
- in the advanced sections.</p>
-
- </subsection>
-
- <subsection name="mod_jk Terminology">
-
- <p>The following terms are used in this section:</p>
-
- <ul>
- <li><strong>Worker process</strong> - A worker is a Tomcat
- instance that is running to serve servlet requests coming
- from the web server. In most cases there is only a single worker
- (the one and only Tomcat process) but sometimes you will run
- multiple workers to achieve load balancing or site partitioning.
- Each worker is identified to the web server by the host were
- it is located, the port where it listens and the communication
- protocol used to exchange messages.</li>
- <li><strong>In-Process Worker</strong> - This is a special
- worker. Instead of working with a Tomcat process residing on
- another process, the web server opens a JVM and executes
- Tomcat inside the web server process address space.
- Our discussion in this document is not going to get into this
- special worker. Note: Tomcat 5 can't be run as this type of
- worker at the moment.</li>
- <li><strong>Web Server Plug-in/Tomcat Redirector</strong> -
- For Tomcat to cooperate with any web server it needs an "agent"
- to reside in the web server and send him servlet requests.
- This is the web server plug-in, and in our case the web server
- plug-in is mod_jk. The redirector usually comes in the shape of
- a DLL or shared object module that you plug into
- the web server.</li>
- <li><strong>Plug-in Configuration</strong> - We need to
- configure the web server plug-in so that it knows where
- the different Tomcat workers are and to which of them
- it should forward requests. This information, accompanied with
- some internal parameter, such as the log level, comprises
- the plug-in configuration.</li>
- <li><strong>Web Server Configuration</strong> - Each web server
- has some configuration that defines its behavior, e.g. on which
- port to listen, what files to serve, what web server plug-ins
- to load, etc. You will need to modify your web server
- configuration to instruct it to load the Tomcat
- redirector mod_jk.</li>
- </ul>
-
- </subsection>
-
- <subsection name="Getting mod_jk">
-
- <p>The mod_jk source now resides in the jakarta-tomcat-connectors
- subproject. Please refer to it for build instructions.</p>
-
- <p>Binaries for mod_jk are available for several platforms in the
- same area as the Tomcat Binary Release. The binaries are located
- in subdirectories by platform. For some platforms, such as Windows,
- this is the typical way of obtaining mod_jk since most Windows
- systems do not have C compilers. For others, the binary
- distribution of mod_jk offers simpler installation.</p>
-
- <p><strong>Note: Note: The version of mod_jk is not dependent on
- the version of Tomcat. The Tomcat 3.3 distribution of mod_jk will
- function correctly with Tomcat 5, 4.x, and other 3.x versions of
- Tomcat, such as Tomcat 3.2.1.</strong></p>
-
- </subsection>
-
- <subsection name="Configuring Apache">
-
- <p>If you've previously configured Apache to use mod_jserv, remove
- any ApJServMount directives from your httpd.conf. If you're
- including tomcat-apache.conf or tomcat.conf, you'll want to remove
- them as well - they are specific to mod_jserv.
- The mod_jserv configuration directives are not compatible
- with mod_jk!</p>
-
- <p>Unlike Tomcat 4.x, Tomcat 5 doesn't automatically generate the
- necessary <code>$CATALINA_HOME/conf/mod_jk.conf</code>,
- and it will have to be created manually. Note that Tomcat
- and Apache must be restarted after adding a new context.</p>
-
- <p>The basic configuration is as follows:</p>
-
- <ul>
- <li>You will need to instruct Apache to load Tomcat. This can be
- done with Apache's LoadModule and AddModule configuration
- directives.</li>
- <li>You must inform mod_jk the location of your
- workers.properties file. Use mod_jk's JkWorkersFile
- configuration directive.</li>
- <li>You should specify a location where mod_jk is going to place
- its log file and a log level to be used. Use the JkLogFile and
- JkLogLevel configuration directives. Possible log levels are
- debug, info, error and emerg. If the JkLogLevel is not specified,
- no log is generated.</li>
- <li>The directive JkLogStampFormat will configure the date/time
- format found on mod_jk logfile. Using strftime() format string
- it's set by default to "[%a %b %d %H:%M:%S %Y] "</li>
- <li>Use mod_jk's JkMount directive to assign specific URLs to
- Tomcat. In general the structure of a JkMount directive is:
- <code>JkMount URL_PREFIX WORKER_NAME</code>. You can use the
- JkMount directive at the top level or inside <VirtualHost>
- sections of your httpd.conf file.</li>
- </ul>
-
- </subsection>
-
- <subsection name="Configuring Tomcat">
-
- <p>Tomcat 5 won't automatically generate the Apache configuration
- file at the moment.</p>
-
- <p>After enabling the AJP 1.3 connector, you need to define workers,
- using a <code>$CATALINA_HOME/conf/workers.properties</code> file.
- In most cases, using the example workers.properties given below
- should work fine, after changing the path values to reflect how your
- environment is set up.</p>
-
- </subsection>
-
- <subsection name="Example Configuration Files">
-
- <p>Excerpt from workers.properties showing the Ajp13 worker:</p>
-
-<source>
-# Setup for Solaris system
-#
-workers.tomcat_home=/usr/local/jakarta-tomcat
-workers.java_home=/usr/java
-ps=/
-worker.list=ajp12, ajp13
-
-# Definition for Ajp13 worker
-#
-worker.ajp13.port=8009
-worker.ajp13.host=localhost
-worker.ajp13.type=ajp13
-</source>
-
- <p>Excerpt from Apaches httpd.conf showing JK directives:</p>
-
-<source>
-# Load mod_jk
-#
-LoadModule jk_module libexec/mod_jk.so
-AddModule mod_jk.c
-
-# Configure mod_jk
-#
-JkWorkersFile /usr/local/jakarta-tomcat/conf/jk/workers.properties
-JkLogFile /usr/local/apache/logs/mod_jk.log
-JkLogLevel info
-
-# First Virtual Host.
-#
-<VirtualHost 10.0.0.1:80>
-DocumentRoot /web/host1
-ServerName host1.apache.org
-JkMount /*.jsp ajp13
-JkMount /servlet/* ajp13
-</VirtualHost>
-
-# Second Virtual Host. Also accessible via HTTPS
-#
-<VirtualHost 10.0.0.2:80>
-DocumentRoot /web/host2
-ServerName host2.apache.org
-JkMount /*.jsp ajp13
-JkMount /servlet/* ajp13
-</VirtualHost>
-
-<VirtualHost 10.0.0.2:443>
-DocumentRoot /web/host2
-ServerName host2.apache.org
-SSLEngine On
-JkMount /*.jsp ajp13
-JkMount /servlet/* ajp13
-</VirtualHost>
-</source>
-
- </subsection>
-
- </subsection>
-
- </subsection>
-
- <subsection name="IIS 4.x and 5.x">
-
- <subsection name="Introduction">
-
- <p>This section explains how to set up IIS 4.0 or newer to cooperate
- with Tomcat 5. Normally IIS cannot execute Servlets and Java Server
- Pages (JSPs), configuring IIS to use Tomcat redirector plugin
- will allow IIS to redirect Servlet and JSP requests to Tomcat.</p>
-
- <p>The Tomcat redirector for IIS is composed of four entities:
- <ul>
- <li>isapi_redirect.dll - The IIS server plugin, either obtain a
- pre-built DLL or build it yourself (see the build section).</li>
- <li>worker.properties - A file that describes the host(s) and
- port (s) used by the workers (Tomcat processes).</li>
- <li>uriworkermap.properties - A file that maps URL-Path patterns
- to workers.</li>
- <li>iis_redirect.reg - A file that creates registry entries
- in the Windows registry.</li>
- </ul>
- </p>
-
- </subsection>
-
- <subsection name="Installation">
-
- <p>Make sure the Tomcat AJP connector is properly declared in the
- Catalina configuration file.</p>
-
- <p>Download isapi_redirect.dll for Tomcat 3.3 release or use the
- following
- <a href="http://jakarta.apache.org/builds/jakarta-tomcat/release/v3.3/bin/win32/i386/">link</a>.
- </p>
-
- <p>Note: See below for examples of the configuration files. Those
- configuration files assume Tomcat is installed in the
- <code>c:\jakarta-tomcat-4.0.1</code> directory.</p>
-
- <p>The next step is to create worker.properties to help
- isapi_redirect.dll to identify where to find Tomcat and its
- configuration.</p>
-
- <p>Next, the ISAPI filter for Tomcat must be configured to redirect
- requests for specific webapps to Tomcat.</p>
-
- <p>Then the <code>uriworkermap.properties</code> file must be created
- in <code>%CATALINA_HOME%\conf</code> directory.</p>
-
- </subsection>
-
- <subsection name="Configuring IIS">
-
- <p>
- <ul>
- <li>Launch Internet Service Manager</li>
- <li>Stop the Web Site if it is running</li>
- <li>Create a virtual directory, by clicking on the default
- web site
- <ul>
- <li>Type the alias to say jakarta, press Next</li>
- <li>Set the directory to <code>%CATALINA_HOME%\bin</code>
- where you installed isapi_redirect.dll, press next</li>
- <li>Provide only read and execute privileges for
- security purposes</li>
- </ul>
- </li>
- <li>Add a filter to the default web site, using the
- IIS Management Console, right click on the properties and
- go to ISAPI filters tab. Press Add button,
- add isapi_redirect.dll as a filter the name of the filter
- should reflect its task (for example, "Jakarta Redirector").
- The Executable field should point to the place where we installed
- isapi_redirect.dll, in our case
- <code>%CATALINA_HOME%\bin\isapi_redirect.dll</code></li>
- <li>Copy and paste the registry entries found below into a file
- iis_redirect.reg. Remember to correct the
- directories where Tomcat is installed in this file.
- Run the iis_redirect.reg file found at the end of this document.
- This will create entries in the registry which
- the isapi_redirect.dll looks for to determine the configuration
- and location of Tomcat.</li>
- <li>Startup IIS.</li>
- <li>Go to the Properties of the web site and select the ISAPI
- filters tab to make sure that the ISAPI filter got registered
- correctly. It should have a Green arrow alongside it.
- Note: it is recommended to restart computer for the ISAPI filter
- to load.</li>
- </ul>
- </p>
-
- </subsection>
-
- <subsection name="Sample worker.properties file">
-
- <p>
-<source>
-# ************ Begin worker.properties **************
-worker.ajp13.type=ajp13
-
-#
-# Specifies the load balance factor when used with
-# a load balancing worker.
-# Note:
-# ----> lbfactor must be > 0
-# ----> Low lbfactor means less work done by the worker.
-worker.ajp13.lbfactor=1
-
-#
-# Specify the size of the open connection cache.
-#worker.ajp13.cachesize
-
-#
-#------ DEFAULT LOAD BALANCER WORKER DEFINITION ----------------------
-#---------------------------------------------------------------------
-#
-
-#
-# The loadbalancer (type lb) worker perform weighted round-robin
-# load balancing with sticky sessions.
-# Note:
-# ----> If a worker dies, the load balancer will check its state
-# once in a while. Until then all work is redirected to peer
-# worker.
-worker.loadbalancer.type=lb
-worker.loadbalancer.balanced_workers=ajp13
-
-#
-# worker.tomcat_home should point to the location where you
-# installed tomcat. This is where you have your conf, webapps and lib
-# directories.
-#
-worker.tomcat_home=C:\jakarta-tomcat-4.0.1
-
-#
-# worker.java_home should point to your Java installation. Normally
-# you should have a bin and lib directories beneath it.
-#
-worker.java_home=C:\jdk1.3.1
-
-#
-# You should configure your environment slash... ps=\ on NT and / on UNIX
-# and maybe something different elsewhere.
-#
-ps=\
-
-#
-#------ ADVANCED MODE ------------------------------------------------
-#---------------------------------------------------------------------
-#
-
-#
-#------ DEFAULT worker list ------------------------------------------
-#---------------------------------------------------------------------
-#
-# The worker that your plugins should create and work with
-worker.list=ajp13
-
-#
-#------ DEFAULT ajp13 WORKER DEFINITION ------------------------------
-#---------------------------------------------------------------------
-#
-
-#
-# Defining a worker named ajp13 and of type ajp13
-# Note that the name and the type do not have to match.
-#
-worker.ajp13.port=8009
-worker.ajp13.host=localhost
-
-# ************ End worker.properties **************
-</source>
- </p>
-
- </subsection>
-
- <subsection name="Sample uriworkermap.properties">
-
- <p>
-<source>
-# *********** Begin uriworkermap.properties ***
-#
-# Simple worker configuration file
-#
-
-# Mount the Servlet context to the ajp13 worker
-/servlet/*=ajp13
-
-# Mount the examples context to the ajp13 worker
-/examples/*=ajp13
-
-# Advanced mount of the examples context
-# /examples/servlet/*=ajp13
-# ************* End uriworkermap.properties ****
-</source>
- </p>
-
- </subsection>
-
- <subsection name="iis_redirect.reg">
-
- <p>
-<source>
-REGEDIT4
-[HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0]
-"extension_uri"="/jakarta/isapi_redirect.dll"
-"log_file"="C:\\jakarta-tomcat-4.0.1\\logs\\iis_redirect.log"
-"log_level"="emerg"
-"worker_file"="C:\\jakarta-tomcat-4.0.1\\conf\\worker.properties"
-"worker_mount_file"="C:\\jakarta-tomcat-4.0.1\\conf\\uriworkermap.properties"
-</source>
- </p>
-
- </subsection>
-
- </subsection>
+ <p>Please refer to the <a href="../jk2/index.html">Coyote JK 2 documentation</a>
+ for HOWTOs and complete configuration information.</p>
</section>
1.2 +2 -6 jakarta-tomcat-catalina/webapps/docs/config/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/config/project.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- project.xml 18 Jul 2002 16:48:38 -0000 1.1
+++ project.xml 16 Nov 2002 14:59:07 -0000 1.2
@@ -22,12 +22,8 @@
</menu>
<menu name="Connectors">
- <item name="JTC Connectors" href="connectors.html"/>
- <item name="Coyote HTTP/1.1" href="coyote.html"/>
- <item name="Coyote JK 2" href="jk2.html"/>
- <item name="HTTP/1.1" href="http11.html"/>
- <item name="JK" href="jk.html"/>
- <item name="Webapp" href="webapp.html"/>
+ <item name="HTTP/1.1" href="coyote.html"/>
+ <item name="JK" href="jk2.html"/>
</menu>
<menu name="Containers">
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>