Tomcat Servlet Container
			========================


This subproject contains the source code for the Tomcat servlet container (and
JSP engine) that conforms to the Java Servlet API Specification (version 2.2)
and the JavaServer Pages Specificaton (version 1.1).


Installing and Building Tomcat
==============================

In order to successfully build Tomcat, you will need to do the following.
In the instructions below, $JAKARTA_HOME (subsitute %JAKARTA_HOME% for
Windows systems) is assumed to be the directory into which you are installing
all of the required distributions.

* Download and install a version 1.1 or later Java Development Kit
  implementation for your operating system platform.  JDK 1.2.2 or later
  is recommended.  Set a "JAVA_HOME" environment variable to point at the
  directory where your JDK is installed, and add "$JAVA_HOME/bin"
  ("%JAVA_HOME%\bin" for Windows) to your PATH.  Configure the CLASSPATH
  environment variable as well, if required.

* Download the latest Ant binary distribution (currently version 1.6.1) from
  <http://ant.apache.org/bindownload.cgi> and install it in the
  $JAKARTA_HOME directory.  Set an "ANT_HOME" environment variable
  to point to $JAKARTA_HOME/jakarta-ant-<version> where <version> matches
  the version of Ant downloaded ($JAKARTA_HOME/jakarta-ant-1.6.1 for
  Ant v1.6.1).  If you are using Windows 9x, you should set ANT_HOME using
  the DOS 8.3 name.  In this case, you may find it convenient to rename
  the directory to a name that is within the DOS 8.3 format, such as "ant-161".
  Also, add "$ANT_HOME/bin" (%ANT_HOME%/bin for Windows) to your PATH.

* Download the latest RegExp binary distribution (currently version 1.3.1) from
  <http://jakarta.apache.org/site/binindex.cgi> and install it in the
  $JAKARTA_HOME directory.  

* Download the latest commons-modeler binary distribution 
  (currently version 1.1.1) from <http://jakarta.apache.org/site/binindex.cgi>
  and install it in the $JAKARTA_HOME directory.  

* If you want to include SSL support, download the Java Secure Sockets
  Extension (JSSE) implementation (current version number is 1.0.2) from
  <http://java.sun.com/products/jsse/> and install it into $JAKARTA_HOME.  
  This step is not necessary if you are using a 1.4.x JVM.

* Obtain the following source distribution(s) either from anonymous CVS (see
  <http://jakarta.apache.org/site/cvsindex.html> for details) or by
  downloading the appropriate source archives from the Jakarta site
  (see <http://jakarta.apache.org/site/sourceindex.html>):

  jakarta-tomcat

  If you download source archive(s), you will need to expand them and rename
  the resulting directories to match the following build directory structure.
  JSSE is shown below as well.

  <$JAKARTA_HOME>
      jakarta-tomcat
      jsse1.0.2  optional
      
* You can now build an "unpacked" version of Tomcat (builds quicker because
  no time is spent JARing up results) by executing the following commands:

	cd $JAKARTA_HOME/jakarta-tomcat
        ant

  This version can be executed as follows:

	cd $JAKARTA_HOME/jakarta-tomcat/build/tomcat
	./bin/startup		<-- Unix
	bin\startup		<-- Windows

  and it can be shut down as follows:

	cd $JAKARTA_HOME/jakarta-tomcat/build/tomcat
	./bin/shutdown		<-- Unix
	bin\shutdown		<-- Windows

* You can also build a binary distribution version of Tomcat as follows:

	cd $JAKARTA_HOME/jakarta-tomcat
        ant dist

  This will create a binary distribution in
  "$JAKARTA_HOME/jakarta-tomcat/dist/tomcat" that is equivalent
  (in file arrangement) to the binary distribution releases of Tomcat 3.3
  that can be downloaded from the Jakarta web site at
  <http://jakarta.apache.org/site/binindex.html>.

* You can delete the generated files in the "build/tomcat" and "dist/tomcat"
  directories by executing the following:

	cd $JAKARTA_HOME/jakarta-tomcat
        ant clean


Running the Build
=================

You can run the "unpacked" version of Tomcat as follows:

* To start Tomcat, execute the following commands:

	cd $JAKARTA_HOME/jakarta-tomcat/build/tomcat
	./bin/startup		<-- Unix
	bin\startup		<-- Windows

* You can now access the default web pages from a web browser at URL:

	http://localhost:8080

* To stop Tomcat, execute the following commands:

	cd $JAKARTA_HOME/jakarta-tomcat/build/tomcat
	./bin/shutdown		<-- Unix
	bin\shutdown		<-- Windows

You can run the "distribution" version of Tomcat as follows:

* To start Tomcat, execute the following commands:

	cd $JAKARTA_HOME/jakarta-tomcat/dist/tomcat
	./bin/startup		<-- Unix
	bin\startup		<-- Windows

* You can now access the default web pages from a web browser at URL:

	http://localhost:8080

* To stop Tomcat, execute the following commands:

	cd $JAKARTA_HOME/jakarta-tomcat/dist/tomcat
	./bin/shutdown		<-- Unix
	bin\shutdown		<-- Windows

Alternatively, you can run Tomcat without changing your current working
directory, by setting the TOMCAT_HOME environment variable to point at the
Tomcat files you have built (for example, at directory
"$JAKARTA_HOME/jakarta-tomcat/build/tomcat" or
"$JAKARTA_HOME/jakarta-tomcat/dist/tomcat").  Now, you can start Tomcat
as follows:

	$TOMCAT_HOME/bin/startup	<-- Unix
	%TOMCAT_HOME%\bin\startup	<-- Windows

and shut it down likewise:

	$TOMCAT_HOME/bin/shutdown	<-- Unix
	%TOMCAT_HOME%\bin\shutdown	<-- Windows

Tomcat may be run with any XML parser that is compliant with the Java API for
XML Parsing specification.  Parsers known to successfully run Tomcat include:

  * The JAXP reference implementation (version 1.0 or later), which can be
    downloaded from <http://java.sun.com/xml/download.html>.  JAXP version 1.1
    is included in the Tomcat binary distribution.

  * The Xerces parser (version 1.1.2 or later), which can be downloaded
    from <http://xml.apache.org>.  Make sure that the "xerces.jar" replaces
    jaxp.jar and crimson.jar in Tomcat's lib/container directory.


Testing the Build
=================

Tomcat includes a "test" web application with some quick tests to exercise
the various parts of the Tomcat container.  This test is not built by
default.  To add the "test" web application to your "unpackaged" build,
execute:

	cd $JAKARTA_HOME/jakarta-tomcat
	ant sanity-test

To add the "test" web application to the distribution build, execute:

	cd $JAKARTA_HOME/jakarta-tomcat
	ant test.war

Before you can run the test, you must set the Admin web application to
"trusted". This can be accomplished by executing the following:

	cd $JAKARTA_HOME/jakarta-tomcat/build/tomcat	<-- Unix
	./bin/tomcat enableAdmin

	cd %JAKARTA_HOME%\jakarta-tomcat\build\tomcat	<-- Windows
	bin\tomcat enableAdmin

Next, start Tomcat with: 

	./bin/startup		<-- Unix
	bin\startup		<-- Windows

To run the test, invoke the following URL in your browser:

	http://localhost:8080/admin/test/test.jsp

and then click "Submit Query".  The build targets for the Ant based test
script are then listed and the tests executed.  After the tests are
completed, the results will appear with "FAILED Tests" listed first,
followed the "PASSED Tests". This same procedure will also work with the
binary distribution which is created in
"$JAKARTA_HOME/jakarta-tomcat/dist/tomcat".

If you use Jikes as the JSP page Java compiler, you will need version
1.14-1 or later to run the tests without error.  Some tests will fail
due to Java compilation errors if an earlier Jikes compiler is used.
See <http://oss.software.ibm.com/developerworks/opensource/jikes/> for
the latest version.

For security reasons, after you are done with the test, you should either
restore the Admin web application to the default "untrusted" state, or change
the password for the "admin" user. To restore the Admin web application to
the default "untrusted" state, change trusted="true" to trusted="false" in
the "apps-admin.xml" file found in Tomcat's "conf" directory. If you want to
leave the Admin web application as "trusted, you should change the password
for the "admin" user in the "admin-users.xml" file located in Tomcat's
"conf/users" directory.

You can also use the Watchdog compatibility test suite, also available at
<http://jakarta.apache.org>, to test Tomcat's compliance to the servlet and
JSP specifications.



Before Committing Changes
=========================

Before committing any changes to the Tomcat CVS repository, you MUST do a
"build clean" followed by a "build dist" to ensure that the build process runs
cleanly, and you must ensure that the tests run correctly.