			Watchdog Compatibility Test Suite
			=================================


This subproject contains the source code for the Watchdog compatibility test
suite (CTS), which tests servlet containers for compliance with the Java
Servlet API Specification (version 2.2) and the JavaServer Pages Specification
(version 1.1).


Installing and Building Watchdog
================================

In order to successfully build the Watchdog CTS, 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 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 and install the Tools distribution (subproject
  "jakarta-tools") into a subdirectory named
  "$JAKARTA_HOME/jakarta-tools".  If you have downloaded the source
  distribution, you will need to build the executable version by
  executing the following commands:

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

* Optionally, you can download and install Tomcat to practice running
  Watchdog tests against (the instructions below illustrate how).
  To do this, download and install the Tomcat distribution (subproject
  "jakarta-tomcat") into a subdirectory named "$JAKARTA_HOME/jakarta-tomcat".
  If you have downloaded the source distribution, you will need to build the
  executable version by executing the following commands:

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

  This will result in a binary distribution version of Tomcat being
  built in directory "$JAKARTA_HOME/dist/tomcat", which can be used
  to practice executing the Watchdog tests, as described below.

* Download and install the Watchdog source distribution (subproject
  "jakarta-watchdog") into a subdirectory named
  "$JAKARTA_HOME/jakarta-watchdog".  To build the executable version
  of Watchdog, execute the following commands:

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

  This will result in a binary distribution version of Watchdog being
  built in directory "$JAKARTA_HOME/dist/watchdog", which can be used
  to execute the tests against your servlet container as described below.


Running the Watchdog CTS
========================

The Watchdog tests are executed by deploying two web applications (one for
servlet tests and one for JSP tests) into your servlet container, and then
executing an appropriate shell script.  The illustrations below assume that
you are running the tests against Tomcat -- make the appropriate changes in
procedures to test your own container.  The steps are as follows:

* Deploy the two web applications into your servlet container.  If you have
  downloaded and built the Tomcat source distribution, you would do this:

	cd $JAKARTA_HOME/dist/watchdog/webapps
	cp *.war ../../tomcat/webapps

* Start your servlet container.  If you have downloaded and built the Tomcat
  source distribution, you would do this:

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

* Execute the servlet test suite.  The default scripts assume you are running
  against a servlet container at http://localhost:8080 with the test suite
  deployed, but the server name and port can be added as arguments.

	cd $JAKARTA_HOME/dist/watchdog/bin
	./watchdog.sh servet [hostname] [port]	<-- Unix
	watchdog servlet [hostname] [port]	<-- Windows

* Execute the JSP test suite.  The default scripts assume you are running
  against a servlet container at http://localhost:8080 with the test suite
  deployed, but the server name and port can be added as arguments.

	cd $JAKARTA_HOME/dist/watchdog/bin
	./watchdog.sh jsp [hostname] [port]	<-- Unix
	watchdog jsp [hostname] [port]		<-- Windows

* If you modify the tests and wish to re-execute them, be sure to restart
  your servlet container and redeploy the tests (rerunning the tests without
  a restart will cause some tests to fail).  For Tomcat, you will need to
  delete the "expanded" versions of the two web applications in order for
  the new war files to be deployed, as follows:

	cd $JAKARTA_HOME/dist/tomcat/webapps
	rm -rf jsp-tests
	rm -rf servlet-tests


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

Before committing any changes to the Watchdog 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.


