			Catalina Servlet Container
			==========================


This subdirectory contains code for the Catalina container that will (when
complete) be proposed as a replacement for the org.apache.tomcat.core classes
(and their related classes) in Tomcat 3.x.


Installing and Building Catalina
================================

In order to successfully build Catalina, you will need to do the following.  In
the instructions below, $JAKARTA_HOME 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.  Set a "JAVA_HOME"
  environment variable to point at the directory where your JDK is installed,
  and add "$JAVA_HOME/bin" to your PATH.  Configure the CLASSPATH environment
  variable as well, if required.

* Download and install the Java API for XML Parsing implementation (current
  version number is 1.0) from <http://java.sun.com/xml>.  Make sure that the
  "jaxp.jar" and "parser.jar" files are on your class path.  (NOTE:  In the
  future it will be possible to use any JAXP-compliant parser).

* Download and install the Ant distribution (subproject "jakarta-ant") into
  a directory named "$JAKARTA_HOME/jakarta-ant".  If you have downloaded the
  source distribution, you will need to build the executable version by
  executing the following commands:

	cd $JAKARTA_HOME/jakarta-ant
	./bootstrap.sh		<-- Unix
	bootstrap		<-- Windows

  This should result in the creation of a file "ant.jar" in the "lib"
  subdirectory, which will be used when building Watchdog.

* Download and install the Regular Expressions distribution (subproject
  "jakarta-regexp") into a directory named
  "$JAKARTA_HOME/jakarta-regexp".  If you have downloaded the source
  distribution, you will need to build the library by executing the
  following commands:

	cd $JAKARTA_HOME/jakarta-regexp/build
	./build-regexp.sh	<-- Unix
	build-regexp		<-- Windows

* Download and install the Servletapi distribution (subproject
  "jakarta-servletapi") into a subdirectory named
  "$JAKARTA_HOME/jakarta-servletapi".  If you have downloaded the source
  distribution, you will need to build the executable version by
  executing the following commands:

	cd $JAKARTA_HOME/jakarta-servletapi
	./build.sh dist		<-- Unix
	build dist		<-- Windows

  This should result in the creation of a file "servlet.jar" in the "lib"
  subdirectory, which will be used when building Watchdog.

* Download the source distribution of Tomcat (subpackage "jakarta-tomcat"),
  or check it out via anonymous CVS, into a subdirectory named
  "$JAKARTA_HOME/jakarta-tomcat".  You will need to build the "unpacked"
  version of Tomcat to make shared classes available to Catalina:

	cd $JAKARTA_HOME/jakarta-tomcat
	./build.sh		<-- Unix
	build			<-- Windows

* Download the source distribution of Watchdog (subpackage "jakarta-watchdog"),
  or check it out via anonymous CVS, into a directory named
  "$JAKARTA_HOME/jakarta-watchdog".  You will need to build the "unpacked"
  version of Watchdog to make the test classes available to Catalina.

	cd $JAKARTA_HOME/jakarta-watchdog
	./build.sh		<-- Unix
	build			<-- Windows

* Now you can build the "unpacked" version of Catalina as follows:

	cd $JAKARTA_HOME/jakarta-tomcat/proposals/catalina
	./build.sh all		<-- Unix
	build all		<-- Windows


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

You can start and stop the unpacked version of Catalina as follows:

* If you are planning to run the Watchdog test suite against Catalina,
  you must install the corresponding web applications prior to startup:

	cd $JAKARTA_HOME/jakarta-tomcat/proposals/catalina
	./build.sh watchdog	<-- Unix
	build watchdog		<-- Windows

* To execute the "unpacked" version of Catalina:

	cd $JAKARTA_HOME/build/catalina
	./bin/catalina.sh start	<-- Unix
	bin\catalina start	<-- Windows

* To access the default context and examples (copied from Tomcat), access the
  following URL with your browser:

	http://localhost:8080

* To run the Watchdog tests against Catalina:

	cd $JAKARTA_HOME/build/watchdog/bin
	./watchdog.sh servlet	<-- Unix
	watchdog servlet	<-- Windows

  (JSP integration has not yet been tested)

* To shut down the "unpacked" version of Catalina:

	cd $JAKARTA_HOME/build/catalina
	./bin/catalina.sh stop	<-- Unix
	bin\catalina stop	<-- Windows

At present, there is no "distribution" build of Catalina, because it is not
yet ready to be tested by casual users.


Reporting Bugs
==============

If you encounter any bugs in Catalina, or wish to contribute a patch, or
wish to suggest any functionality improvements, please report them to our
bug tracking system, at:

	http://jakarta.apache.org/bugs

against product "Tomcat" and component "Catalina".



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.


