danmil 01/02/05 15:36:50
Modified: src/doc tomcat-ug.html
Log:
Cleaned up HTML, fixed typos.
Contributed by Chris Pepper <[EMAIL PROTECTED]>
Revision Changes Path
1.5 +597 -562 jakarta-tomcat/src/doc/tomcat-ug.html
Index: tomcat-ug.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat/src/doc/tomcat-ug.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- tomcat-ug.html 2000/08/25 22:13:09 1.4
+++ tomcat-ug.html 2001/02/05 23:36:49 1.5
@@ -1,253 +1,290 @@
-
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
- <head>
- <!-- $Id: tomcat-ug.html,v 1.4 2000/08/25 22:13:09 alex Exp $ -->
- <!-- Copyright 1999, Apache Software Foundation -->
+<head>
+ <!-- $Id: tomcat-ug.html,v 1.5 2001/02/05 23:36:49 danmil Exp $ -->
+ <!-- Copyright 1999,2001 Apache Software Foundation -->
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href="style.css">
<title>Tomcat User's Guide</title>
<!-- Changed by: Costin Manolache, 20-Mar-2000 -->
<!-- Changed by: Gal Shachor, 27-Mar-2000 -->
- </head>
- <body link="#0000ff" vlink="#800080">
- <!-- Banner element, all hail the Project! -->
- <table border="0" width="100%" cellspacing="0" cellpadding="0">
+</head>
+
+<body link="#0000ff" vlink="#800080">
+
+<!-- Banner element, all hail the Project! -->
+
+<table border="0" width="100%" cellspacing="0" cellpadding="0">
<tr>
- <td width="50%">
- <p align="left">
- <a href="http://jakarta.apache.org/index.html">
- <img src="images/banner.gif"
- width="350"
- height="100"
- alt="The Jakarta Project"
- border="0"></a>
- </td>
- <td width="50%">
- <p align="right"><img border="0" src="images/tomcat.gif" width="100"
height="71" alt="The mighty Tomcat - Meow!"></p>
- </td>
+ <td width="50%"><a
+ href="http://jakarta.apache.org/index.html"><img
+ src="images/banner.gif" width="350" height="100"
+ alt="The Jakarta Project" border="0"></a></td>
+ <td width="50%" align="right"><img border="0" src="images/tomcat.gif"
width="100" height="71" alt="The mighty Tomcat - Meow!"></td>
</tr>
- </table>
+</table>
- <H1>Tomcat User's Guide</H1>
- <p>This document is an introduction to the Tomcat servlet container.
- It should be enough for anyone to install, configure, and deploy
- Tomcat. As well, it answers many questions common to new users. We encourage
all users to add answers to questions into the
- <a href="http://jakarta.apache.org/faq/faqindex.html">
- Tomcat FAQ</a> and/or this document, if they don't already exist.
- If you have any comments or suggestions about this document don't
- hesitate to send them to the Tomcat
- <a href="http://jakarta.apache.org/getinvolved/mail.html">mailing lists</a>.
-
- <p>This document began life as <i>Tomcat: A Minimalistic User's
- Guide</i> by Gal Shachor, and has been revised by many others.
- It should be considered a <b>work in progress</b>. Since the
+
+<H1>Tomcat User's Guide</H1>
+
+<p>This document is an introduction to the Tomcat servlet
+ container. It should be enough for anyone to install,
+ configure, and deploy Tomcat. As well, it answers many
+ questions common to new users. We encourage all users to
+ add answers to questions into the <a
+ href="http://jakarta.apache.org/faq/faqindex.html">
+ Tomcat FAQ</a> and/or this document, if they don't
+ already exist. If you have any comments or suggestions
+ about this document don't hesitate to send them to the
+ Tomcat <a
+ href="http://jakarta.apache.org/getinvolved/mail.html">mailing
+ lists</a>.</p>
+
+ <p>This document began life as <cite>Tomcat: A Minimalistic User's
+ Guide</cite> by Gal Shachor, and has been revised by many others.
+ It should be considered a <strong>work in progress</strong>. 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/downloads/sourceindex.html">source
code</a>.</p>
-
<p>"???" means I'm not sure if this should go in, or
where it should go or be referred to as, if it does indeed
- belong. Other editorial comments are surrounded in [square brackets].
- </p>
+ belong. Other editorial comments are surrounded in [square brackets].</p>
- <p>
- Other important documents: <ul>
-<li><a href="http://jakarta.apache.org/faq/faqindex.html">Tomcat FAQ</a></li>
-<li> <A HREF="appdev/contents.html">Application Development manual</A> -
- an alternative to the User's Guide, somewhat out-of-date
-</li>
-<li>Other <a href="index.html">Tomcat Documentation</a> including HOWTOs for
various web servers</li>
+<p>Other important documents:</p>
+
+<ul>
+ <li><a href="http://jakarta.apache.org/faq/faqindex.html">Tomcat
+ FAQ</a></li>
+ <li><A HREF="appdev/contents.html">Application Development
+ manual</A> - an alternative to the User's Guide,
+ somewhat out-of-date</li>
+ <li>Other <a href="index.html">Tomcat Documentation</a>
+ including HOWTOs for various web servers</li>
</ul>
- </p>
- <h3>Table of Contents</h3>
+<h3>Table of Contents</h3>
-[This section needs to be revised to match current outline. Wouldn't
-it be nice if we used XSL to generate this file from an XML source?]
+<p>[This section needs to be revised to match current outline. Wouldn't
+it be nice if we used XSL to generate this file from an XML source?]</p>
+<ul>
+ <li><a href="#about_tomcat">About Tomcat</a>
<ul>
- <li><a href="#about_tomcat">About Tomcat</a><br>
- <a href="#what_is_tomcat">What is Tomcat?</a><br>
- <a href="#where_download">Where can I download
- Tomcat?</a><br>
- <a href="#just_jserv">Isn't Tomcat just JServ?</a><br>
- <a href="#what_servlets_jsps">What are
- servlets? What are JSPs?<br>
- </a> <a href="#contribute">How do/can I contribute?<br>
- </a> <a href="#where_help">How come X, Y, or Z isn't
- working? Help!<br>
- </a>
-
+ <li><a href="#what_is_tomcat">What is Tomcat?</a></li>
+ <li><a href="#where_download">Where can I download
+ Tomcat?</a></li>
+ <li><a href="#just_jserv">Isn't Tomcat just JServ?</a></li>
+ <li><a href="#what_servlets_jsps">What are
+ servlets? What are JSPs?</a></li>
+ <li><a href="#contribute">How do/can I contribute?</a></li>
+ <li><a href="#where_help">How come X, Y, or Z isn't
+ working? Help!</a>
+ </ul>
</li>
- <li><a href="#installing_tomcat">Installing Tomcat</a><br>
- <a href="#file_placement">File placement and
- environment setup<br>
- </a> <a href="#starting_and_stopping">Starting and
- stopping Tomcat<br>
- </a> <a href="#starting_another_dir">Starting
- multiple instances w/individual server.xml files<br>
- </a> <a href="#directory_structure">Tomcat directory
- structure<br>
- </a> <a href="#tomcat_scripts">Tomcat scripts</a><br>
-
+ <li><a href="#installing_tomcat">Installing Tomcat</a>
+ <ul>
+ <li><a href="#file_placement">File placement and
+ environment setup</a></li>
+ <li><a href="#starting_and_stopping">Starting and
+ stopping Tomcat</a>
+ <li><a href="#starting_another_dir">Starting
+ multiple instances w/individual server.xml files</a></li>
+ <li><a href="#directory_structure">Tomcat directory
+ structure</a></li>
+ <li><a href="#tomcat_scripts">Tomcat scripts</a><br>
+ </ul>
</li>
- <li><a href="#configuring_tomcat">Configuring Tomcat<br>
- </a> <a href="#container_types">Types of servlet
- containers</a><br>
- <a href="#server_xml">server.xml - Tomcat's main
configuration
- file<br>
- </a> <a href="#web_xml">web.xml - Default
- deployment descriptor<br>
- </a>
- Web application/context security and authorization<br>
- tomcat-users.xml<br>
- JDBC realms<br>
-
+ <li><a href="#configuring_tomcat">Configuring Tomcat</a>
+ <ul>
+ <li><a href="#container_types">Types of servlet
+ containers</a></li>
+ <li><a href="#server_xml">server.xml - Tomcat's main configuration
+ file</a></li>
+ <li><a href="#web_xml">web.xml - Default
+ deployment descriptor</a><br>
+ <li>Web application/context security and authorization</li>
+ <li>tomcat-users.xml</li>
+ <li>JDBC realms</li>
+ </ul>
</li>
- <li><a href="#webapps">Deploying Web Applications</a><br>
- <a href="#webapp">What is a Web Application?</a><br>
- <a href="#what_is_war">What is a WAR file?</a><br>
- <a href="#deploying_war">Deploying WAR files in
Tomcat</a><br>
+ <li><a href="#webapps">Deploying Web Applications</a></li>
+ <li><a href="#webapp">What is a Web Application?</a></li>
+ <li><a href="#what_is_war">What is a WAR file?</a></li>
+ <li><a href="#deploying_war">Deploying WAR files in Tomcat</a><br>
<br>
</li>
- <li><a href="#tutorials">Tomcat Tutorials</a> - ???<br>
- Deploying application<br>
- Creating your first web application ???<br>
- Creating and configuring your first servlet ???<br>
+ <li><a href="#tutorials">Tomcat Tutorials</a> - ???</li>
+ <li>Deploying application</li>
+ <li>Creating your first web application ???</li>
+ <li>Creating and configuring your first servlet ???<br>
<br>
- </a>
- </li>
- <li><a href="#real_world_tips">Real World Configuration Tips</a><br>
-<br>
-
</li>
+ <li><a href="#real_world_tips">Real World Configuration Tips</a></li>
<li><a href="#common_errors">Common Installation and Configuration
- Problems<br>
- </a> <a href="#error_bad_command">"Bad command or
- filename" when executing Tomcat scripts<br>
- </a> <a href="#error_8007">http://webserver:8007/
- gives an HTTP 500<br>
- </a> <a href="#error_ignore_directives">Apache
<Directory>
- and <Location> directives ignored<br>
- </a> <a href="#error_web_server">Web server won't
- start when Tomcat is running<br>
- </a>
-<br>
+ Problems</a>
+ <ul>
+ <li><a href="#error_bad_command">"Bad command or
+ filename" when executing Tomcat scripts</a>
+ <li><a href="#error_8007">http://webserver:8007/
+ gives an HTTP 500</a>
+ <li><a href="#error_ignore_directives">Apache <Directory>
+ and <Location> directives ignored</a>
+ <li><a href="#error_web_server">Web server won't
+ start when Tomcat is running</a>
+ </ul>
</li>
<li><a href="#credits">Credits</a></li>
- </ul>
+</ul>
- <hr size="5">
- <h3><a name="about_tomcat">About Tomcat</a></h3>
+<hr size="5">
- See also the official
- <a href="http://jakarta.apache.org/faq/faqindex.html">Tomcat FAQ</a>.
- <h4> <a name="what_is_tomcat">What is Tomcat?</a></h4>
- <blockquote>
- <p>Tomcat is the official reference implementation of the <a
href="http://java.sun.com/products/servlet/">Java
- Servlet 2.2</a> and <a href="http://java.sun.com/products/jsp/">JavaServer
- Pages 1.1</a> technologies. Developed under the Apache license in an
- open and participatory environment, it is intended to be a collaboration
- of the best-of-breed developers from around the world.
+<h3><a name="about_tomcat">About Tomcat: Q&A</a></h3>
- </blockquote>
- <h4> <a name="where_download">Where can I download
Tomcat?</a></h4>
- <blockquote>
- <p>At the <a href="http://jakarta.apache.org/downloads/binindex.html">Jakarta
- download page</a>!
- </blockquote>
- <h4> <a name="just_jserv">Isn't Tomcat just JServ?</a></h4>
- <blockquote>
- <p>
- This is a common misunderstanding. <a
href="http://java.apache.org/jserv">JServ</a> is a Servlet API
- 2.0-compliant container that was created to be used with Apache.
- Tomcat is a complete re-write and is a Servlet API 2.2 and JSP
- 1.1-compliant container. Tomcat uses some of the code written for
- JServ, especially JServ's Apache server adapter, but this is where the
- similarities end.
- </p>
- </blockquote>
- <h4> <a name="what_servlets_jsps">What are servlets?
- What are JSPs?</a></h4>
- <blockquote>
- <p>In a nutshell, servlets are memory-resident Java programs, running
- inside a servlet container (e.g. Tomcat!). Because they're
- memory-resident, they can quickly respond to requests, as they do not
- incur the overhead of process creation and subsequent cleanup, unlike
- CGI-based scripting, e.g. perl, etc.<p>From <a
href="http://java.sun.com/products/servlet/">Sun's
- servlet site</a>:
- <blockquote>
- <p>"The <b>Java<sup><font size="-2">TM</font></sup> Servlet API</b>
- provides web developers with a simple, consistent mechanism for
- extending the functionality of a web server and for accessing existing
- business systems. A servlet can almost be thought of as an applet that
- runs on the server side -- without a face."
- </blockquote>
- <p>...and about JSPs (JavaServer Pages), again from <a
href="http://java.sun.com/products/servlet/">Sun's
+<p>See also the official <a
+ href="http://jakarta.apache.org/faq/faqindex.html">Tomcat FAQ</a>.</p>
+
+<dl>
+ <dt><strong><a name="what_is_tomcat">What is Tomcat?</a></strong></dt>
+ <dd>Tomcat is the official reference implementation of the <a
+ href="http://java.sun.com/products/servlet/">Java
+ Servlet 2.2</a> and <a
+ href="http://java.sun.com/products/jsp/">JavaServer
+ Pages 1.1</a> technologies. Developed under the Apache
+ license in an open and participatory environment, it is
+ intended to be a collaboration of the best-of-breed
+ developers from around the world.</dd>
+
+ <dt><strong><a name="where_download">Where can I download
+ Tomcat?</a></strong></dt>
+ <dd>At the <a
+ href="http://jakarta.apache.org/downloads/binindex.html">Jakarta
+ download page</a>!</dd>
+
+ <dt><strong><a name="just_jserv">Isn't Tomcat just
+ JServ?</a></strong></dt>
+ <dd>This is a common misunderstanding. <a
+ href="http://java.apache.org/jserv">JServ</a> is a
+ Servlet API 2.0-compliant container that was created to
+ be used with Apache. Tomcat is a complete re-write and
+ is a Servlet API 2.2 and JSP 1.1-compliant container.
+ Tomcat uses some of the code written for JServ,
+ especially JServ's Apache server adapter, but this is
+ where the similarities end.</dd>
+ <dt><strong><a name="what_servlets_jsps">What are servlets? What
+ are JSPs?</a></strong></dt>
+ <dd>In a nutshell, servlets are memory-resident Java programs,
+ running inside a servlet container (<em>e.g.,</em>
+ Tomcat!). Because they're memory-resident, they can
+ quickly respond to requests, as they do not incur the
+ overhead of process creation and subsequent cleanup,
+ unlike CGI-based scripting, e.g. perl, etc.
+
+ <p>From <a href="http://java.sun.com/products/servlet/">Sun's
servlet site</a>:
- <blockquote>
- <p>"JSP technology is an extension of the servlet technology
- created to support authoring of HTML and XML pages. It makes it easier
- to combine fixed or static template data with dynamic content."
- </blockquote>
- <p>JSP is comparable to other technologies such as PHP and ASP, which
- combine
- programming/scripting with a markup language like HTML. The key
- difference being the programming language of choice. For example,
- PHP uses a C/C++/Java hybrid, ASP uses VBScript, and JSP utilizes the
- full power of the Java programming language. There have been many
- comparisons of these technologies, and each has its place in the astute
- developer's toolbox.<p>All of the above information is available at <a
href="http://java.sun.com/">Sun's
- Java website</a>, which is a starting place for all the ins and outs of JSPs,
- servlets, etc. <b>Your time spent with these technologies will be much
- more rewarding if you first read through the <a
href="http://java.sun.com/products/jsp/download.html">JavaServer
- Pages</a> and <a
href="http://java.sun.com/products/servlet/download.html">servlet</a>
- specifications!</b>
- </blockquote>
- <h4> <a name="contribute">How do/can I contribute?</a></h4>
- <blockquote>
- <p>Please do! See the Jakarta project contribution page, right <a
href="http://jakarta.apache.org/getinvolved/getinvolvedindex.html">here</a>.
- You'll probably want to <a
href="mailto:[EMAIL PROTECTED]">subscribe</a>
- to the <b> tomcat-dev</b> mailing list.</p>
- </blockquote>
- <h4> <a name="where_help">How come X, Y, or Z isn't
- working? Help!</a></h4>
- <blockquote>
- While we hope to cater to many common issues, we have undoubtedly missed
- some. For more help, try (in this order):
- <ol>
- <li>Your log files, in the <a href="#logs_dir_defn">logs</a> subdirectory
- of your Tomcat installation. These are an untapped
- resource!</li>
- <li>The <a href="#common_errors">Common problems</a> section of this
- document.</li>
- <li>Have a look through the <a
href="http://jakarta.apache.org/faq/faqindex.html"> Tomcat
- FAQ</a>. Most installation and configuration questions can be found
here.</li>
- <li>Search the Tomcat <a
href="http://mikal.org/interests/java/tomcat/index.html">user</a>
- and <a href="http://www.metronet.com/~wjm/tomcat/">developer</a> list
- archives. </li>
- <li>Post a question to the <b> tomcat-user</b> <a
href="http://jakarta.apache.org/getinvolved/mail.html">
- mailing list</a>, which you must first <a
href="mailto:[EMAIL PROTECTED]">subscribe</a>
- to if you'd like to see any replies!
- </ol>
- </blockquote>
- <hr size="5">
- <h3><a name="installing_tomcat">Installing Tomcat</a></h3>
- <h4> <a name="file_placement">File placement and
- environment setup</a></h4>
- <blockquote>
+
+ <blockquote>"The <strong>Java<sup><font
+ size="-2">TM</font></sup> Servlet API</strong>
+ provides web developers with a simple,
+ consistent mechanism for extending the
+ functionality of a web server and for accessing
+ existing business systems. A servlet can almost
+ be thought of as an applet that runs on the
+ server side -- without a face."</blockquote>
+
+ <p>...and about JSPs (JavaServer Pages), again from <a
+ href="http://java.sun.com/products/servlet/">Sun's
+ servlet site</a>:</p>
+
+ <blockquote>"JSP technology is an extension of the
+ servlet technology created to support authoring
+ of HTML and XML pages. It makes it easier to
+ combine fixed or static template data with
+ dynamic content."</blockquote>
+
+ <p>JSP is comparable to other technologies such as PHP
+ and ASP, which combine programming/scripting
+ with a markup language like HTML. The key
+ difference being the programming language of
+ choice. For example, PHP uses a C/C++/Java
+ hybrid, ASP uses VBScript, and JSP utilizes the
+ full power of the Java programming language.
+ There have been many comparisons of these
+ technologies, and each has its place in the
+ astute developer's toolbox.</p>
+
+ <p>All of the above information is available at <a
+ href="http://java.sun.com/">Sun's Java
+ website</a>, which is a starting place for all
+ the ins and outs of JSPs, servlets, etc.
+ <strong>Your time spent with these technologies
+ will be much more rewarding if you first read
+ through the <a
+
href="http://java.sun.com/products/jsp/download.html">JavaServer
+ Pages</a> and <a
+
href="http://java.sun.com/products/servlet/download.html">servlet</a>
+ specifications!</strong></p>
+ </dd>
+
+ <dt><strong><a name="contribute">How do/can I contribute?</a></strong></dt>
+ <dd>Please do! See the Jakarta project contribution page, right
+ <a
+
href="http://jakarta.apache.org/getinvolved/getinvolvedindex.html">here</a>.
+ You'll probably want to <a
+ href="mailto:[EMAIL PROTECTED]">subscribe</a>
+ to the <strong>tomcat-dev</strong> mailing list.</dd>
+
+ <dt><strong><a name="where_help">How come X, Y, or Z isn't
+ working? Help!</a></strong></dt>
+ <dd>While we hope to cater to many common issues, we have
+ undoubtedly missed some. For more help, try (in this
+ order):
+
+<ol>
+ <li>Your log files, in the <a href="#logs_dir_defn">logs</a>
+ subdirectory of your Tomcat installation. These are an
+ untapped resource!</li>
+ <li>The <a href="#common_errors">Common problems</a> section of
+ this document.</li>
+ <li>Have a look through the <a
+ href="http://jakarta.apache.org/faq/faqindex.html">
+ Tomcat FAQ</a>. Most installation and configuration
+ questions can be found here.</li>
+ <li>Search the Tomcat <a
+ href="http://mikal.org/interests/java/tomcat/index.html">user</a>
+ and <a
+ href="http://www.metronet.com/~wjm/tomcat/">developer</a>
+ list archives.</li>
+ <li>Post a question to the <strong> tomcat-user</strong> <a
+ href="http://jakarta.apache.org/getinvolved/mail.html">
+ mailing list</a>, which you must first <a
+ href="mailto:[EMAIL PROTECTED]">subscribe</a>
+ to if you'd like to see any replies!</li>
+</ol>
+
+ </dd>
+</dl>
+
+<hr size="5">
+
+
+<h3><a name="installing_tomcat">Installing Tomcat</a></h3>
+
+
+<h4><a name="file_placement">File placement and environment setup</a></h4>
+
+<blockquote>
<ul>
<li><a href="http://jakarta.apache.org/downloads/binindex.html">Download</a>
the
appropriate jakarta-tomcat [.zip | .gz | .Z] file.
<li>Unzip the file into some directory (say /usr/local or C:\). This
- should create a new subdirectory named "tomcat". [Does it still create
"jakarta-tomcat" instead? If so, just rename it "tomcat".] </li>
+ should create a new subdirectory named "tomcat". [Does it still create
"jakarta-tomcat" instead? If so, just rename it "tomcat".]</li>
<li>Change directory to "tomcat" and set a new environment
variable (<a name="tomcat_home_env">TOMCAT_HOME</a>) to point to the root
directory of your
@@ -288,25 +325,19 @@
</li>
</ol>
</li>
-
</ul>
- <p> That's it! You can now <a href="#starting_and_stopping"> execute Tomcat</a>
and it will run as a
- <a href="#type_1">
- stand-alone</a> servlet container.
- </p>
+<p>That's it! You can now <a href="#starting_and_stopping">
+ execute Tomcat</a> and it will run as a <a
+ href="#type_1"> stand-alone</a> servlet container.</p>
- <p>
- Once you're sure they work, these environment variables should probably be
set in a
+ <p>Once you're sure they work, these environment variables should probably be
set in a
config file: C:/AUTOEXEC.BAT for Windows, ~/bash_profile
- or ~/[what is it for tcsh?]
- </p>
+ or ~/[what is it for tcsh?]</p>
- </blockquote>
+</blockquote>
- <h4> <a name="starting_and_stopping">Starting and
- stopping Tomcat</a>
- </h4>
+<h4><a name="starting_and_stopping">Starting and stopping Tomcat</a></h4>
<blockquote>
<p>You start and stop Tomcat using the scripts in
@@ -316,31 +347,30 @@
<p>On UNIX: bin/startup.sh</p>
<p>On Win32: bin\startup</p>
</blockquote>
- <p>To stop Tomcat execute: </p>
+ <p>To stop Tomcat execute:</p>
<blockquote style="margin-right: 0px">
- <p>On UNIX: bin/shutdown.sh </p>
+ <p>On UNIX: bin/shutdown.sh</p>
<p>On Win32: bin\shutdown</p>
</blockquote>
</blockquote>
- <h4> <a name="starting_another_dir">Starting multiple
- instances with individual server.xml files</a>
- </h4>
+<h4><a name="starting_another_dir">Starting multiple instances with
+ individual server.xml files</a></h4>
<blockquote>
<p>This might not make a whole lot of sense until you read the next section
explaining Tomcat's <a href="#directory_structure">directory structure</a>,
as well as <a href="#configuring_tomcat">Configuring Tomcat</a>. You
- may want to come back here afterwards. </p>
+ may want to come back here afterwards.</p>
<p>By default, Tomcat will use TOMCAT_HOME/conf/server.xml for
configuration, which by default, uses TOMCAT_HOME as its base for the contexts.
You can change this by using the "-f /path/to/server.xml" option, with a
different server configuration file and setting the home attribute of
the <a href="#context_manager_element">ContextManager</a> element. You need
to set up the required files inside the
- home: </p>
+ home:</p>
<ul>
<li>webapps/ - all war files will
be expanded and all subdirectories added as contexts.</li>
@@ -357,24 +387,23 @@
</blockquote>
- <h4> <a name="directory_structure">The Tomcat directory
- structure</a>
- </h4>
+<h4><a name="directory_structure">The Tomcat directory structure</a></h4>
<blockquote>
<p>Assuming you extracted the Tomcat binary distribution
you should have the following directory structure under <a
href="#tomcat_home_env">TOMCAT_HOME</a>:</p>
- <table border width="75%" valign="MIDDLE">
+
+<table border=1 width="75%" valign="MIDDLE">
<tr>
- <th bgcolor="#c0c0c0" WIDTH="15%"> Directory</th>
- <th bgcolor="#c0c0c0" WIDTH="85%"> Contents</th>
+ <th bgcolor="#c0c0c0" WIDTH="15%">Directory</th>
+ <th bgcolor="#c0c0c0" WIDTH="85%">Contents</th>
</tr>
<tr>
- <td WIDTH="15%" align="center"> bin </td>
+ <td WIDTH="15%" align="center">bin</td>
<td WIDTH="85%"> Startup/shutdown scripts and other useful files.</td>
</tr>
<tr>
- <td WIDTH="15%" align="center"> conf </td>
+ <td WIDTH="15%" align="center">conf</td>
<td WIDTH="85%"> Configuration files including <a
href="#server_xml">server.xml</a> (Tomcat's main configuration file) and
<a href="#web_xml">
web.xml</a> (default values for the various web applications deployed in
@@ -382,38 +411,38 @@
</td>
</tr>
<tr>
- <td WIDTH="15%" align="center"> doc </td>
+ <td WIDTH="15%" align="center">doc</td>
<td WIDTH="85%">Miscellaneous documents regarding Tomcat.</td>
</tr>
<tr>
- <td WIDTH="15%" align="center"> lib </td>
+ <td WIDTH="15%" align="center">lib</td>
<td WIDTH="85%"> Various jar files that are used by Tomcat.
Any file in this directory is appended to Tomcat's classpath.
</td>
</tr>
<tr>
- <td WIDTH="15%" align="center"> <a name="logs_dir_defn"> logs</a> </td>
+ <td WIDTH="15%" align="center"><a name="logs_dir_defn">logs</a></td>
<td WIDTH="85%"> This is where Tomcat places its log files by default.</td>
</tr>
<tr>
- <td WIDTH="15%" align="center"> src </td>
+ <td WIDTH="15%" align="center">src</td>
<td WIDTH="85%"> The servlet API source files. Don't get excited,
though; these are only the empty interfaces and abstract
classes that should be implemented by any servlet
container.</td>
</tr>
<tr>
- <td WIDTH="15%" align="center"> webapps </td>
+ <td WIDTH="15%" align="center">webapps</td>
<td WIDTH="85%"> Sample web applications. Any .war files placed
- here will be automatically expanded. See <a
href="#deploying_war">Deploying WAR files</a>. </td>
+ here will be automatically expanded. See <a
href="#deploying_war">Deploying WAR files</a>.</td>
</tr>
- </table>
+</table>
<p>Additionally you can, or Tomcat will, create the following
directories:</p>
<table border="1" width="75%" VALIGN="MIDDLE">
<tr>
- <td width="15%" align="center"> <a name="work_dir_defn"> work</a> </td>
+ <td width="15%" align="center"> <a name="work_dir_defn"> work</a></td>
<td width="85%"> Where Tomcat
places intermediate files (such as compiled JSP files) during
its work. If you delete this directory while Tomcat is running
@@ -421,17 +450,16 @@
</td>
</tr>
<tr>
- <td width="15%" align="center"> classes </td>
+ <td width="15%" align="center">classes</td>
<td width="85%"> Any class that you add to this directory will
find its place in Tomcat's classpath.
</td>
</tr>
- </table>
+</table>
- </blockquote>
+</blockquote>
- <h4> <a name="tomcat_scripts">Tomcat scripts</a></h4>
- <blockquote>
+ <h4><a name="tomcat_scripts">Tomcat scripts</a></h4>
<p>This section is not required reading, as the default functionality
provided by the aforementioned startup and shutdown scripts is sufficient
for most users to get started. If everything is working so far, skip ahead to
<a href="#configuring_tomcat">Configuring
@@ -445,15 +473,15 @@
tedious. Instead, the Tomcat development team provides a few scripts
to ease starting and stopping Tomcat.</p>
- <p><b>Note: The scripts are only a convenient way to start/stop. You can modify
them to customize the
- CLASSPATH, environment
+<p><strong>Note: The scripts are only a convenient way to start/stop.
+ You can modify them to customize the CLASSPATH, environment
variables such as PATH and LD_LIBRARY_PATH, etc., so long as a
- correct command line is generated for Tomcat.</b>
- </p>
+ correct command line is generated for Tomcat.</strong></p>
- <p> The following table presents the scripts that are
+ <p>The following table presents the scripts that are
most important for the common user:</p>
- <table border width="75%" valign="MIDDLE">
+
+<table border=1 width="75%" valign="MIDDLE">
<tr>
<th bgcolor="#c0c0c0" width="15%"> Script name </th>
<th bgcolor="#c0c0c0" width="85%"> Description </th>
@@ -472,18 +500,16 @@
<td width="15%" align="center"> shutdown </td>
<td width="85%"> Stops tomcat (shutting it down). Shortcut for "tomcat
stop" </td>
</tr>
- </table>
+</table>
<p>The script which has the most significance for users is tomcat
(tomcat.sh/tomcat.bat). The other Tomcat related scripts serve as a
simplified single-task oriented entry point to the tomcat script (set
different command line parameters etc.).</p>
- </blockquote>
- <h4> <a name="tomcat_scripts_closer">Tomcat scripts: a
closer look</a></h4>
- <blockquote>
- <p>
- A closer look at tomcat.sh/tomcat.bat yields that it performs the
+<h4><a name="tomcat_scripts_closer">Tomcat scripts: a closer look</a></h4>
+
+ <p>A closer look at tomcat.sh/tomcat.bat yields that it performs the
following actions:</p>
<p>These behaviors, especially CLASSPATH setting, have changed
@@ -491,7 +517,7 @@
details on what variables are set and what class files are
loaded. [??? - delete entire section pending reexamination?]</p>
- <table border =1 width="75%" valign="MIDDLE">
+<table border =1 width="75%" valign="MIDDLE">
<tr>
<th bgcolor="#c0c0c0" width="15%"> Operating System </th>
<th bgcolor="#c0c0c0" width="85%"> Actions </th>
@@ -523,14 +549,15 @@
org.apache.tomcat.startup.Tomcat, such as:
<ol>
- <li>The operation to perform start/stop/run/etc.
-
- <li>A path to the server.xml used by this Tomcat process. </li>
+ <li>The operation to perform start/stop/run/etc.</li>
+ <li>A path to the server.xml used by this Tomcat process.</li>
</ol>
+
<p>For example if server.xml is located in /etc/server_1.xml and
the user wants to start apache in the background they should
- provide the following command line:
- <div>bin/tomcat.sh start -f /etc/server_1.xml</div></p>
+ provide the following command line:</p>
+
+ <div>bin/tomcat.sh start -f /etc/server_1.xml</div>
</li>
</ul>
</td>
@@ -567,59 +594,60 @@
</li></ul>
</td>
</tr>
- </table>
+</table>
<p>As you can see, the Win32 version of tomcat.bat pales in comparison to the
Unix
one. Especially it does not guess the values of TOMCAT_HOME and
JAVA_HOME and it also doesn't take add all of the .jar files into the
classpath.</p>
- </blockquote>
+<hr size="5">
+
- <hr size="5">
- <h3><a name="container_types">Servlet Container Types</a></h3>
+<h3><a name="container_types">Servlet Container Types</a></h3>
- Tomcat, like any servlet container, is meant to run behind a web
+<p>Tomcat, like any servlet container, is meant to run behind a web
server. The web server takes care of receiving HTTP requests from
client browsers; the servlet container takes care of serving
- Servlets and JSPs for those URLs that request them.
- <p>
- In Tomcat's case, there are three different modes of execution
- Tomcat supports.
-
- <ol>
- <li><strong><u><a name="type_1">Stand-alone servlet
containers</a></u></strong><br>
- These are an integral part of the web server. This
- is the case when using a Java-based web server, for example the
- servlet container that is part of the JavaWebServer. Stand-alone
- is the default mode used by Tomcat. Most web servers, however, are not
Java-based, which leads us to
- the next two container types.<br>
- </li>
+ Servlets and JSPs for those URLs that request them.</p>
+<p>In Tomcat's case, there are three different modes of execution
+ Tomcat supports.</p>
+
+<dl>
+ <dt><strong><a name="type_1">Stand-alone servlet containers</a></strong>
+ <dd>These are an integral part of the web server. This is the
+ case when using a Java-based web server, for example the
+ servlet container that is part of the JavaWebServer.
+ Stand-alone is the default mode used by Tomcat. Most web
+ servers, however, are not Java-based, which leads us to
+ the next two container types.</dd>
- <li><strong><u>In-process servlet containers</u></strong><br>
- The servlet container is a combination of a web server plugin and a
- Java container implementation. The web server plugin opens a JVM
- inside the web server's address space and lets the servlet container
- run in it. If a certain request should execute a servlet, the plugin
- takes control over the request and passes it (using <a
href="http://java.sun.com/products/jdk/1.2/docs/guide/jni/index.html">JNI</a>) to the
- servlet
- container. An in-process container is suitable for multi-threaded
- single-process servers and provides good performance but is limited
- in scalability.<br>
- </li>
+ <dt><strong>In-process servlet containers</strong>
+ <dd>The servlet container is a combination of a web server
+ plugin and a Java container implementation. The web
+ server plugin opens a JVM inside the web server's
+ address space and lets the servlet container run in it.
+ If a certain request should execute a servlet, the
+ plugin takes control over the request and passes it
+ (using <a
+
href="http://java.sun.com/products/jdk/1.2/docs/guide/jni/index.html">JNI</a>)
+ to the servlet container. An in-process container is
+ suitable for multi-threaded single-process servers and
+ provides good performance but is limited in
+ scalability.</dd>
- <li><strong><u>Out-of-process servlet containers</u></strong><br>
- The servlet container is a combination of a
- web server plugin and a Java container implementation that runs
- in a JVM outside the web server. The web server plugin and the
- Java container JVM communicate using some IPC mechanism (usually
- TCP/IP sockets).
- If a certain request should execute a servlet the plugin takes
- control over the request and passes it (using IPC) to the servlet container.
- The response time of an out-of-process engine is not as good as
- in the in-process one but the out-of-process engine performs
- better in many measurable ways (scalability, stability, etc.).
- </li>
- </ol>
+ <dt><strong>Out-of-process servlet containers</strong>
+ <dd>The servlet container is a combination of a web server
+ plugin and a Java container implementation that runs in
+ a JVM outside the web server. The web server plugin and
+ the Java container JVM communicate using some IPC
+ mechanism (usually TCP/IP sockets). If a certain request
+ should execute a servlet the plugin takes control over
+ the request and passes it (using IPC) to the servlet
+ container. The response time of an out-of-process engine
+ is not as good as in the in-process one but the
+ out-of-process engine performs better in many measurable
+ ways (scalability, stability, etc.).</dd>
+</dl>
<p>Tomcat can be used as either a stand-alone container
(mainly for development and debugging) or as an add-on to an
@@ -634,18 +662,20 @@
integration with your web server when you do so in the future - "Is
Tomcat or my web server at fault for the error I'm seeing?"</p>
+<hr size="5">
+
- <hr size="5">
- <h3><a name="configuring_tomcat">Configuring Tomcat</a></h3>
+<h3><a name="configuring_tomcat">Configuring Tomcat</a></h3>
<p> Tomcat's configuration is based on two files:
<ol>
<li> <a href="#server_xml"> server.xml</a> - Tomcat's global configuration
file. </li>
<li> <a href="#web_xml"> web.xml</a> - Default deployment descriptor. </li>
</ol>
- <h4> <a name="server_xml">server.xml - Tomcat's main
configuration
+<h4><a name="server_xml">server.xml - Tomcat's main configuration
file</a></h4>
- <blockquote>
+
+<blockquote>
<p>
The elements in server.xml (found in the conf subdirectory of
TOMCAT_HOME) are described below. Following along with the
@@ -655,7 +685,7 @@
how-to.</p>
<table border="0" width="90%">
<tr>
- <td width="10%" valign="top"><b><Server></b></td>
+ <td width="10%" valign="top"><strong><Server></strong></td>
<td width="90%" valign="top">The topmost element. <Server>
defines a single Tomcat server. Generally you should not bother with
it.<br>
@@ -666,56 +696,56 @@
<td width="90%" valign="top">
<table border="0" width="100%">
<tr>
- <td width="15%" valign="top"><b><xmlmapper:debug>
- </b></td>
+ <td width="15%" valign="top"><strong><xmlmapper:debug>
+ </strong></td>
<td width="85%">You'll most likely never have to touch this, unless
you're
worried about how Tomcat is registering the contents of this
server.xml file. Even if you are concerned, the startup output
found in Tomcat's main log
file will usually be sufficient for this purpose.
<p>Attributes:</p>
<ul>
- <li> <b>level</b>. A value of "0"
+ <li> <strong>level</strong>. A value of "0"
means "no output". "9" meaning
"most everything".</li>
</ul>
</td>
</tr>
<tr>
- <td width="15%" valign="top"><b><Logger></b></td>
+ <td width="15%" valign="top"><strong><Logger></strong></td>
<td width="85%">
This element defines a Logger object, equivalent to a log file. Currently there
are loggers for the servlets (where the
ServletContext.log() goes),
JSP files and the tomcat runtime.
<p>Attributes:</p>
<ul>
- <li><b>name. </b> Identifies
+ <li><strong>name. </strong> Identifies
the logger. One of "tc_log", "servlet_log",
or "JASPER_LOG".</li>
- <li><b>path. </b>Output file, relative to
+ <li><strong>path. </strong>Output file, relative to
TOMCAT_HOME. If you omit a "path" value, then stderr &
stdout are used.</li>
- <li><b>verbosityLevel.</b> In order of increasing verbosity;
one of "FATAL", "ERROR",
+ <li><strong>verbosityLevel.</strong> In order of increasing
verbosity; one of "FATAL", "ERROR",
"WARNING", "INFORMATION", or
"DEBUG".</li>
</ul>
</td>
</tr>
<tr>
- <td width="15%" valign="top"><b><a
name="context_manager_element"><ContextManager></a></b></td>
+ <td width="15%" valign="top"><strong><a
name="context_manager_element"><ContextManager></a></strong></td>
<td width="85%">
A ContextManager specifies the configuration and structure for a set of
ContextInterceptors, RequestInterceptors, Contexts and their
Connectors.
<p>
Attributes:</p>
<ul>
- <li><b>debug.</b> A value of "0"
+ <li><strong>debug.</strong> A value of "0"
means "no output". "9" meaning
"most everything".</li>
- <li><b>home.</b> The base location for the
+ <li><strong>home.</strong> The base location for the
webapps, conf, and logs directories, as well as all defined contexts.
It is used to start Tomcat from a directory other than
TOMCAT_HOME. The default value for this attribute is
TOMCAT_HOME.</li>
- <li><b>workDir.</b> The name of the <a href="#work_dir_defn">
working
+ <li><strong>workDir.</strong> The name of the <a
href="#work_dir_defn"> working
directory</a>, relative to the above home attribute.</li>
</ul>
</td>
@@ -725,8 +755,8 @@
<td width="85%">
<table border="0" width="100%">
<tr>
- <td width="15%" valign="top"><b><ContextInterceptor><br>
- <RequestInterceptor></b></td>
+ <td width="15%"
valign="top"><strong><ContextInterceptor><br>
+ <RequestInterceptor></strong></td>
<td width="85%"> These interceptors listen for certain events
that happen in
the ContextManager. For example, the ContextInterceptor listens for
startup and shutdown events of Tomcat, and the RequestInterceptor
@@ -738,8 +768,8 @@
</td>
</tr>
<tr>
- <td width="15%" valign="top"><b><Connector>
- </b></td>
+ <td width="15%" valign="top"><strong><Connector>
+ </strong></td>
<td width="85%">The Connector represents a connection to the
user, either
through a web server or directly to the user's browser (in a <a
href="#type_1">
stand-alone</a> configuration).
@@ -748,7 +778,7 @@
from the sockets connecting to the various clients.
<p>Attributes:</p>
<ul>
- <li><b>className.</b> Which Connector to use.</li>
+ <li><strong>className.</strong> Which Connector to
use.</li>
</ul>
We will describe how to use this Connector configuration later in the
document.<br>
</td>
@@ -758,15 +788,15 @@
<td width="85%">
<table border="0" width="100%">
<tr>
- <td width="15%"
valign="top"><b><Parameter></b></td>
+ <td width="15%"
valign="top"><strong><Parameter></strong></td>
<td width="85%">Connector initialization
parameters. You may have as many of these
elements as required under each Connector.
<p>Attributes:</p>
<ul>
- <li><b>name.</b> So far, one of
+ <li><strong>name.</strong> So far, one of
"handler", "port",
"socketFactory".</li>
- <li><b>value.</b> The appropriate value.</li>
+ <li><strong>value.</strong> The appropriate
value.</li>
</ul>
</td>
</tr>
@@ -774,24 +804,24 @@
</td>
</tr>
<tr>
- <td width="15%" valign="top"><b><Context>
- </b> </td>
+ <td width="15%" valign="top"><strong><Context>
+ </strong> </td>
<td width="85%"> Each Context represents a path in the Tomcat
hierarchy where you
place a web application.
<p>
Attributes:</p>
<ul>
- <li><b>path. </b>The <i>context path</i> for a
+ <li><strong>path.</strong>The <em>context path</em> for a
particular web application, which
is the prefix of a request URI that tells Tomcat which Context
should be used to process this request. This attribute is
required,
and must start with a slash ('/') character.</li>
- <li><b>docBase.</b> The root of your web
+ <li><strong>docBase.</strong> The root of your web
application. This can be a full path or relative to the <a
href="#context_manager_element">
ContextManager's</a> home. This is Tomcat's version of
Apache's "DocumentRoot" directive.</li>
- <li><b>reloadable.</b> When developing a servlet it is
very
+ <li><strong>reloadable.</strong> When developing a
servlet it is very
convenient to have Tomcat automatically reload it, allowing you
to fix bugs and have Tomcat test the new code without the need to
restart the container. To turn on servlet reloading set
the
reloadable flag to true. Detecting changes however is time
@@ -800,22 +830,22 @@
class-reloading trigger casts errors. To avoid these problems
you can set the reloadable flag to false; this will disable
the
autoreload feature.</li>
- <li><b>trusted.</b> Trusted allows you to access tomcat
internal objects with FacadeManager.</li>
- <li><b>debug.</b> A value of "0"
+ <li><strong>trusted.</strong> Trusted allows you to
access tomcat internal objects with FacadeManager.</li>
+ <li><strong>debug.</strong> A value of "0"
means "no output". "9" meaning
"most everything".</li>
</ul>
</td>
</tr>
<tr>
- <td width="15%" valign="top"><b><Host>
- </b></td>
+ <td width="15%" valign="top"><strong><Host>
+ </strong></td>
<td width="85%">Contains <Context> elements. The
<Host>
element is used to configure per-virtual host Contexts.
<p>
Attributes:</p>
<ul>
- <li><b>name</b>: The fully-qualified hostname
+ <li><strong>name</strong>: The fully-qualified hostname
or IP address of the virtual host.</li>
</ul>
</td>
@@ -824,27 +854,30 @@
</td>
</tr>
<tr>
- <td width="15%" valign="top"><b></ContextManager></b></td>
+ <td width="15%"
valign="top"><strong></ContextManager></strong></td>
<td width="85%"></td>
</tr>
</table>
</td>
</tr>
<tr>
- <td width="10%" valign="top"><b></Server></b></td>
+ <td width="10%" valign="top"><strong></Server></strong></td>
<td width="90%" valign="top"></td>
</tr>
</table>
</blockquote>
- <h4> <a name="web_xml">web.xml - Default deployment
descriptor</a></h4>
+
+
+<h4><a name="web_xml">web.xml - Default deployment descriptor</a></h4>
+
<blockquote>
<p>
A detailed description of web.xml and the web application structure
(including directory structure and configuration) is available in
chapters 9, 10 and 13 of the <a
href="http://java.sun.com/products/servlet/download.html">Servlet API Spec</a>
and we are not going to write about it. <a
href="../appdev/index.html">Developing Applications with Tomcat</a>
- covers web application and deployment with Tomcat. <b>It is required reading
if you're not going to
- take the time to read through the <a
href="http://java.sun.com/products/servlet/download.html">Servlet API Spec</a>!</b>
</p>
+ covers web application and deployment with Tomcat. <strong>It is required
reading if you're not going to
+ take the time to read through the <a
href="http://java.sun.com/products/servlet/download.html">Servlet API
Spec</a>!</strong> </p>
<p>
There is a small Tomcat "feature" that is related
to web.xml. Tomcat lets the user define default web.xml values for all
@@ -852,69 +885,64 @@
TOMCAT_HOME. When
constructing a new Context, Tomcat uses the default web.xml file as the
base configuration, and then applies the application specific web.xml (the
- application's WEB-INF/web.xml file) settings.
+ application's WEB-INF/web.xml file) settings.</p>
-This means that in Tomcat, you can get away with an empty
+<p>This means that in Tomcat, you can get away with an empty
web.xml file, containing only the element
+
<tt><big><web-app/></big></tt>, or (more realistically)
containing only the elements (e.g. mappings and mime-types) you need. However,
this will limit your
webapp's portability, so it is recommended to use a full web.xml
-file. You may instead want to copy TOMCAT_HOME/conf/web.xml and modify it.
+file. You may instead want to copy TOMCAT_HOME/conf/web.xml and modify it.</p>
- </p>
+ <p>We cover certain aspects of web.xml in subsequent sections, where it
+ pertains to application deployment and interaction with Tomcat.</p>
- <p>
- We cover certain aspects of web.xml in subsequent sections, where it
- pertains to application deployment and interaction with Tomcat.
- </p>
-
</blockquote>
+
+<hr size="5">
- <hr size="5">
- <a name="webapps">
- <h3>Deploying Web Applications</h3>
- <a name="webapp">
- <h4>What is a Web Application?</h4>
+<h3><a name="webapps">Deploying Web Applications</a></h3>
-[??? - move this section up above the Configuring Tomcat section? It's
+<h4>What is a Web Application?</h4>
+
+<p>[??? - move this section up above the Configuring Tomcat section? It's
not clear whether we should teach about webapps before or after we
-introduce server.xml et al.]
-<p>
-A Web Application (or "webapp") is a concept that was introduced in
+introduce server.xml et al.]</p>
+
+<p>A Web Application (or "webapp") is a concept that was introduced in
the <a href="http://java.sun.com/products/servlet/2.2/">Servlet
Specification</a> version 2.2. [2.1?] You should definitely read the
-spec for the full story. From the spec (chapter 9):
-<blockquote>
-<p>
-A web application is a collection of servlets, html pages, classes, and other
resources that can be
+spec for the full story. From the spec (chapter 9):</p>
+
+<!--[[blockquote]] not sure what the range of this quite is supposed to be-->
+<p>A web application is a collection of servlets, html pages, classes, and other
resources that can be
bundled and run on multiple containers from multiple vendors. A web application is
rooted at a
specific path within a web server. For example, a catalog application could be
located at http://
www.mycorp.com/catalog. All requests that start with this prefix will be routed to
the
-ServletContext which represents the catalog application.
-</p>
-<p>
-A servlet container can also establish rules for automatic generation of web
applications. For
+ServletContext which represents the catalog application.</p>
+
+<p>A servlet container can also establish rules for automatic generation of web
applications. For
example a ~user/ mapping could be used to map to a web application based at
/home/user/
-public_html/.
-</p>
+public_html/.</p>
+
<p>[...]</p>
-<p>
-A web application exists as a structured hierarchy of directories. The
+
+<p>A web application exists as a structured hierarchy of directories. The
root of this hierarchy serves as a document root for serving files
that are part of this context. For example, for a web application
located at /catalog in a web server, the index.html file located at
the base of the web application hierarchy can be served to satisfy a
-request to /catalog/index.html.
-</p>
-<p>
-A special directory exists within the application hierarchy named "WEB-INF". This
directory
+request to /catalog/index.html.</p>
+
+<p>A special directory exists within the application hierarchy named "WEB-INF".
This directory
contains all things related to the application that aren't in the document root of
the application. It is
important to note that the WEB-INF node is not part of the public document tree of
the application.
-No file contained in the WEB-INF directory may be served directly to a client.
-</p>
-<p>
-The contents of the WEB-INF directory are:
+No file contained in the WEB-INF directory may be served directly to a client.</p>
+
+<p>The contents of the WEB-INF directory are:</p>
+
<ul>
<li> /WEB-INF/web.xml deployment descriptor </li>
<li> /WEB-INF/classes/* directory for servlet and utility classes. The classes in
this directory
@@ -923,11 +951,13 @@
utility classes useful to the web application. All such archive files are used by
the web
application class loader to load classes from. </li>
</ul>
-</p>
+
<h3>Sample Web Application Directory Structure</h3>
-<p>
-Illustrated here is a listing of all the files in a sample web application:
-<blockquote><pre><big>/index.html
+
+<p>Illustrated here is a listing of all the files in a sample web application:</p>
+
+<blockquote>
+<pre>/index.html
/howto.jsp
/feedback.jsp
/images/banner.gif
@@ -936,106 +966,101 @@
/WEB-INF/lib/jspbean.jar
/WEB-INF/classes/com/mycorp/servlets/MyServlet.class
/WEB-INF/classes/com/mycorp/util/MyUtils.class
-</big></pre>
+</pre>
</blockquote>
-</blockquote>
-</p>
-<p>
-You can deploy a WAR file that is present on the local filesystem by
+<p>You can deploy a WAR file that is present on the local filesystem by
adding a <Context> tag to TOMCAT_HOME/conf/server.xml. For
-example:
-<blockquote><pre><big><Context path="/mywebapp"
+example:</p>
+
+<blockquote>
+<pre><Context path="/mywebapp"
docBase="/home/alex/webapps/mywebapp"
reloadable="true" >
</Context>
-</big></pre></blockquote>
-</p>
+</pre>
+</blockquote>
+
-<a name="what_is_war">
- <h4>What is a WAR file?</h4>
+<h4><a name="what_is_war">What is a WAR file?</a></h4>
-<p><i>"WAR. Huh! What is it good for?" - Edwin Starr</i></p>
+<p><em>"WAR. Huh! What is it good for?" - Edwin Starr</em></p>
-<p>
-A WAR (or "web archive") file is simply a packaged webapp directory.
+<p>A WAR (or "web archive") file is simply a packaged webapp directory.
It is created using the standard Java <tt><big>jar</big></tt> tool.
-For example:
-<blockquote><pre><big>cd /home/alex/webapps/mywebapp
-jar cf mywebapp.war * </big></pre></blockquote>
-</p>
+For example:</p>
+
+<blockquote><pre>cd /home/alex/webapps/mywebapp
+jar cf mywebapp.war *</pre></blockquote>
- <a name="deploying_war">
- <h4>Deploying WAR files in Tomcat</h4>
+<h4><a name="deploying_war">Deploying WAR files in Tomcat</a></h4>
<blockquote>
-<p>
-Currently (as of version 3.2) the procedure for deploying a new WAR file is:
+<p>Currently (as of version 3.2) the procedure for deploying a new WAR file is:</p>
+
<ol>
-<li><b>Stop Tomcat</b>.
-</li>
-<li><b>Delete existing deployment.</b>
-If you have previously deployed "foo.war" in TOMCAT_HOME/webapps, then it
has been unpacked into webapps/foo/... You must delete this directory and all its
contents. On Unix, this can be done with <pre><big>rm -r
$TOMCAT_HOME/webapps/foo</big></pre>
-</li>
-<li><b>Copy WAR file to TOMCAT_HOME/webapps/</b>.
-</li>
-<li><b>Start Tomcat</b>.
-</li>
+ <li><strong>Stop Tomcat.</strong></li>
+ <li><p><strong>Delete existing deployment.</strong> If you have
+ previously deployed "foo.war" in
+ TOMCAT_HOME/webapps, then it has been unpacked into
+ webapps/foo/... You must delete this directory and all
+ its contents. On Unix, this can be done with:</p>
+
+ <pre>rm -r $TOMCAT_HOME/webapps/foo</pre>
+ </li>
+ <li><strong>Copy WAR file to TOMCAT_HOME/webapps/.</strong></li>
+ <li><strong>Start Tomcat.</strong></li>
</ol>
-</p>
-<p>
-This process may become easier in the future. A "deploy tool" is on the
Tomcat "to-do" list.
-</p>
+<p>This process may become easier in the future. A "deploy tool" is on
the Tomcat "to-do" list.</p>
-<p>
-Note that if you deploy a WAR file in this manner, you do not need to
+<p>Note that if you deploy a WAR file in this manner, you do not need to
make any changes to <tt><big>server.xml</big></tt> -- it will
automatically be recognized and activated when the server starts.
However, if you wish to specify non-default options for this webapp,
you may do so by adding an element like <tt><big><Context
-docBase="webapps/foo" ...</big></tt> to server.xml.
-</p>
+docBase="webapps/foo" ...</big></tt> to server.xml.</p>
-<p>
-See also <a href="http://www.jguru.com/jguru/faq/view.jsp?EID=123229">How do I
-deploy a WAR file in Tomcat?</a> in the jGuru FAQ.
-</p>
+<p>See also <a href="http://www.jguru.com/jguru/faq/view.jsp?EID=123229">How
+do I deploy a WAR file in Tomcat?</a> in the jGuru FAQ.</p>
</blockquote>
-
- <hr size="5">
- <a name="tutorials">
- <h3>Tomcat Tutorials</h3>
- <p>These tutorials will be run with the assumption that Tomcat is operating
- as a stand-alone container. Like we said before, it can be helpful to
- understand Tomcat's functionality, irrespective of the particular web server
- you're using. Trying to get more than one thing working at once
- usually leads to more problems than its worth. Integration will be
- covered later in subsequent sections.</p>
+<hr size="5">
- [Note: add some tutorials here :-) ]
+<h3><a name="tutorials">Tomcat Tutorials</a></h3>
+<p>These tutorials will be run with the assumption that Tomcat
+ is operating as a stand-alone container. Like we said
+ before, it can be helpful to understand Tomcat's
+ functionality, irrespective of the particular web server
+ you're using. Trying to get more than one thing working
+ at once usually leads to more problems than its worth.
+ Integration will be covered later in subsequent
+ sections.</p>
+
+[Note: add some tutorials here :-) ]
+
+
+<h2>Real World Configuration Tips</h2>
+
+<p>By default the Tomcat distribution comes with a naive
+ configuration whose main goal is to promote first time
+ user experience and an "out of the box" operation...
+ This configuration however is not the best way to deploy
+ Tomcat on real sites. For example, real sites may
+ require some performance tuning and site-specific
+ settings (additional path elements for example). This
+ section will try to get you started by directing you to
+ the first steps that should be taken before publishing a
+ Tomcat based site.</p>
+
+<h3>Modify and Customize the Batch Files</h3>
+<p>As stated in the previous sections, the startup scripts are
+ here for your convenience. Yet, sometimes the scripts
+ that are needed for deployment should be modified:</p>
- <h2> Real World Configuration Tips </h2>
- <p>
- By default the Tomcat distribution comes with a naive configuration
- whose main goal is to promote first time user experience and an "out
- of the box" operation... This configuration however is not the best
- way to deploy Tomcat on real sites. For example, real sites may
- require some performance tuning and site-specific settings
- (additional path elements for example). This section will try to get
- you started by directing you to the first steps that should be taken
- before publishing a Tomcat based site.
- </p>
-
- <h3> Modify and Customize the Batch Files </h3>
- <p>
- As stated in the previous sections, the startup scripts are here for
- your convenient. Yet, sometimes the scripts that are needed for
- deployment should be modified:
- <ul>
+<ul>
<li> To set resource limits such as maximum number of
descriptors. </li>
<li> To add new CLASSPATH entries (for example, JDBC drivers). </li>
@@ -1047,24 +1072,30 @@
<li> To switch user from root to some other user using the "su"
UNIX command. </li>
<li> Your pet reason. </li>
- </ul>
+</ul>
- Some of these changes can be done without explicit changes to
- the basic scripts; for example, the tomcat script can use an
- environment variable named <tt>TOMCAT_OPTS</tt> to set extra command
- line parameters to the JVM (such as memory setting etc.).
- On <em>UNIX</em> you can also create a file named <tt>".tomcatrc"</tt> in
- your home directory and Tomcat will take environment information such
- as PATH, JAVA_HOME, TOMCAT_HOME and CLASSPATH from this file. On NT
- however (and also on UNIX when the modifications are for something
- such as the JVM command line) you are forced to rewrite some of the
- startup script... <div><b> Do not hesitate, just do it.</b> </div>
+<p>Some of these changes can be done without explicit changes to
+ the basic scripts; for example, the tomcat script can
+ use an environment variable named <tt>TOMCAT_OPTS</tt>
+ to set extra command line parameters to the JVM (such as
+ memory setting etc.). On <em>UNIX</em> you can also
+ create a file named <tt>".tomcatrc"</tt> in your home
+ directory and Tomcat will take environment information
+ such as PATH, JAVA_HOME, TOMCAT_HOME and CLASSPATH from
+ this file. On NT however (and also on UNIX when the
+ modifications are for something such as the JVM command
+ line) you are forced to rewrite some of the startup
+ script...</p>
+
+<div><strong>Do not hesitate, just do it.</strong></div>
+
+<h3>Modify the Default JVM Settings</h3>
+
+<p>The default JVM settings in the tomcat script are very
+ naïve; everything is left for defaults. There are a
+ few things that you should consider to improve your
+ Tomcat performance:</p>
- <h3> Modify the Default JVM Settings </h3>
- <p>
- The default JVM settings in the tomcat script are very naïve;
- everything is left for defaults. There are a few things that you
- should consider to improve your Tomcat performance:
<ol>
<li> Modify your JVM memory configuration. Normally the JVM
allocates an initial size for the Java heap and that's it, if
@@ -1093,24 +1124,20 @@
and make a calculated decision.
</li>
</ol>
+
- <h3> Modify your Connectors </h3>
+<h3>Modify your Connectors</h3>
+
<p>
The Connectors, as configured in Tomcat's default server.xml
contains two Connectors configured as in the next server.xml
- fragment:
+ fragment:</p>
- <p>
- <table border="1"
- cellspacing="0"
- cellpadding="0"
- valign="middle">
- <caption valign="bottom" width="100%">
- <em> The two default Connectors in server.xml </em>
- </caption>
+<table border="1" cellspacing="0" cellpadding="0" valign="middle">
+ <caption><em>The two default Connectors in server.xml</em></caption>
<tr>
<td bgcolor="#c0c0c0">
- <pre>
+<pre>
<!-- (1) HTTP Connector for stand-alone operation -->
<Connector
className="org.apache.tomcat.service.SimpleTcpConnector">
<Parameter
@@ -1130,12 +1157,12 @@
name="port"
value="8007"/>
</Connector>
- </pre>
+</pre>
</td>
</tr>
- </table>
+</table>
- <ol>
+<ol>
<li> Is a Connector that listens on port 8080 for incoming HTTP
requests. This connector is needed for stand-alone
operation.
@@ -1144,77 +1171,78 @@
integration (out-of-process servlet integration).
</ol>
- It is clear that a sane Tomcat deployment will use either an
+<p>It is clear that a sane Tomcat deployment will use either an
out-of-process servlet integration or a stand-alone operation,
- removing the unnecessary Connector is important.
- <h3> Use a Thread Pool in your Connectors </h3>
+ removing the unnecessary Connector is important.</p>
+
+
+<h3>Use a Thread Pool in your Connectors</h3>
+
<p>
Tomcat is a multi-threaded servlet container this means that each
request needs to be executed by some thread. By default when a
request arrives Tomcat creates a new thread, starts it and has it
serve the request. This behavior is problematic for loaded sites
- because:
- <ul>
+ because:</p>
+
+<ul>
<li>Starting and stopping a thread for every request puts a
- needless burden on the operating system and the JVM. </li>
+ needless burden on the operating system and the JVM.</li>
<li>It is hard to limit the resource consumption. If 300
requests arrive concurrently Tomcat will open 300
threads to serve them and allocate all the resources needed
to serve all the 300 requests at the same time. This causes
Tomcat to allocate much more resources (CPU, Memory,
Descriptors...) than it should and it can lead to low
- performance and even crashes if resources are exhausted. </li>
- </ul>
- The solution for these problems is to use a <b>thread pool</b>.
+ performance and even crashes if resources are exhausted.</li>
+</ul>
+
+<p>The solution for these problems is to use a <strong>thread pool</strong>.
Servlet containers that are using a thread pool relieve themselves
from directly managing their threads. Instead of allocating new
threads; whenever they need a thread they ask for it from the pool,
and when they are done, the thread is returned to the pool. The
thread pool can now be used to implement sophisticated thread
- management techniques, such as:
- <ol>
- <li> Keeping threads "open" and reusing them over and over
+ management techniques, such as:</p>
+
+<ol>
+ <li>Keeping threads "open" and reusing them over and over
again. This saves the trouble associated with creating and
destroying threads continuously.
- <ul> <li>
- Usually the administrator can instruct the pool not to keep
- too many idle threads, freeing them if needed.
- </li> </ul>
+ <ul>
+ <li>Usually the administrator can instruct the pool not to keep too
many idle threads, freeing them if needed.</li>
+ </ul>
</li>
- <li> Setting an upper bound on the number of threads used
+
+ <li>Setting an upper bound on the number of threads used
concurrently. This prevents the resources allocation
problem associated with unlimited thread allocation.
- <ul> <li>
- If the container maxed out to the threads upper limit, and a new
+ <ul>
+ <li>If the container maxed out to the threads upper limit, and a new
request arrives, the new request will have to wait for
some other (previous) request to finish and free the thread
- used to service it.
- </li> </ul>
+ used to service it.</li>
+ </ul>
</li>
- </ol>
- You can refine the techniques described above in various ways, but
+</ol>
+
+<p>You can refine the techniques described above in various ways, but
these are only refinements. The main contribution of thread pools is
thread-reuse and having a concurrency upper bound that limits
- resource usage.
+ resource usage.</p>
<p>
Using a thread pool in Tomcat is a simple move; all you need to do
is to use a <tt>PoolTcpConnector</tt> in your <Connector>
configuration. For example the following server.xml fragment defines
- ajpv12, pooled Connector:
+ ajpv12, pooled Connector:</p>
- <p>
- <table border="1"
- cellspacing="0"
- cellpadding="0"
- valign="middle">
- <caption valign="bottom" width="100%">
- <em> Pooled ajpv12 Connector </em>
- </caption>
+<table border="1" cellspacing="0" cellpadding="0" valign="middle">
+ <caption><em>Pooled ajpv12 Connector</em></caption>
<tr>
<td bgcolor="#c0c0c0">
- <pre>
- <!-- A pooled AJPV12 Connector for out-of-process operation -->
+
+<pre><!-- A pooled AJPV12 Connector for out-of-process operation -->
<Connector
className="org.apache.tomcat.service.PoolTcpConnector">
<Parameter
name="handler"
@@ -1223,13 +1251,14 @@
name="port"
value="8007"/>
</Connector>
- </pre>
+</pre>
</td>
</tr>
- </table>
+</table>
+
+<p>This fragment is very simple and the (default) pool behaviour
+ instructed by it is:</p>
- This fragment is very simple and the (default) pool behaviour
- instructed by it is:
<ul>
<li> Upper bound for concurrency of 50 threads. </li>
<li> When the pool has more then 25 threads standing idle it
@@ -1244,16 +1273,12 @@
limit). Configuring the pool can be done through the <Connector>
element in server.xml as demonstrated in the next fragment:
<p>
- <table border="1"
- cellspacing="0"
- cellpadding="0"
- valign="middle">
- <caption valign="bottom" width="100%">
- <em> Configuring the Thread Pool </em>
- </caption>
+
+<table border="1" cellspacing="0" cellpadding="0" valign="middle">
+ <caption><em>Configuring the Thread Pool</em></caption>
<tr>
<td bgcolor="#c0c0c0">
- <pre>
+<pre>
<!-- A pooled AJPV12 Connector for out-of-process operation -->
<Connector
className="org.apache.tomcat.service.PoolTcpConnector">
<Parameter
@@ -1272,12 +1297,14 @@
name="min_spare_threads"
value="5" />
</Connector>
- </pre>
+</pre>
</td>
</tr>
- </table>
- As can be seen the pool has 3 configuration parameters:
- <ul>
+</table>
+
+<p>As can be seen the pool has 3 configuration parameters:</p>
+
+<ul>
<li> max_threads - defines the upper bound to the for the
concurrency, the pool will not create more then this
number
of threads. </li>
@@ -1294,7 +1321,9 @@
You should use the above parameters to adjust the pool behavior to
your needs.
- <h3> Disable Servlet Auto-Reloading </h3>
+
+<h3>Disable Servlet Auto-Reloading</h3>
+
<p>
Servlet auto-reloading is really useful for development time.
However it is very expensive (in performance degradation terms) and
@@ -1306,8 +1335,9 @@
So, unless you have a real need for class reloading during your
deployment you should turn off the reloadable flag in your contexts.
</p>
+
+<h3>Start Tomcat from /etc/inittab</h3>
- <h3> Start Tomcat from /etc/inittab </h3>
<p>
Unfortunately the adapters developed for Apache (or for any of the
other servers) cannot start Tomcat yet. On UNIX however, you can
@@ -1315,33 +1345,38 @@
startup. FIXME:
</p>
-<a name="credits">
- <h2>Credits</h2>
+
+<h2><a name="credits">Credits</a></h2>
+
<p>Tomcat was originally written by Sun Microsystems, and has been improved (we
hope) by a <a href="http://jakarta.apache.org/credits/whoweare.html">cast of
thousands</a>.</p>
- <p>
- This document was created by:
- <ul>
- <a href="mailto:[EMAIL PROTECTED]"> Gal Shachor</a>
- </ul>
- With help from (in alphabetical order):
- <ul>
- Jonathan Bnayahu<br>
- Alex Chaffee<br>
- Fiona Czuczman<br>
- Costin Manolache<br>
- Rob Slifka<br>
- </ul>
+
+<p>This document was created by:</p>
+
+<ul>
+ <li><a href="mailto:[EMAIL PROTECTED]">Gal Shachor</a>
+</ul>
+
+<p>With help from (in alphabetical order):</p>
+
+<ul>
+ <li>Jonathan Bnayahu
+ <li>Alex Chaffee
+ <li>Fiona Czuczman
+ <li>Costin Manolache
+ <li>Rob Slifka
+</ul>
- <table width="100%" border="0" cellpadding="10" cellspacing="0">
+<table width="100%" border="0" cellpadding="10" cellspacing="0">
<tr>
<td>
<p class="fineprint">
- Copyright ©1999 The Apache Software Foundation<br>
+ Copyright ©1999,2001 The Apache Software Foundation<br>
<a href="http://jakarta.apache.org/legal.html">Legal Stuff They Make Us
Say</a><br>
- <a href="http://jakarta.apache.org/contact.html">Contact
Information</a> </p>
+ <a href="http://jakarta.apache.org/contact.html">Contact Information</a>
+ </p>
</td>
</tr>
- </table>
+</table>
- </body>
+</body>
</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
