Tomcat Setup and Configuration for CS320

This document describes a step-by-step procedure to install a Tomcat server with additional packages under Windows 2000/XP.

[Preparation]

Before installing Tomcat, make sure you already have J2SE 1.5 or above installed. If not, download J2SE 1.5.0 and install it first. In the rest of the document, I will assume that J2SE is installed under the directory d:\j2sdk.

[Download and Installation]

Download Tomcat 5.5.17 binary release from the Apache Project (just the "Core" package), and unzip the files to a local directory, e.g. d:\apache-tomcat-5.5.17.

Note that there are several Tomcat versions available for download. Version 5.5.17 is the current stable version that supports the latest Servlet and JSP specifications, and is the version that we are going to use in the class. Also note that for installation on Windows, you may choose to download either a ZIP file or an EXE file. If you want to setup Tomcat as a service on Windows 2000/XP, you should download the EXE file; otherwise you should download the ZIP file because installation from the ZIP file does not require administrator privilege.

[Environment Variables]

Set the JAVA_HOME environment variable to the directory where J2SE is installed, e.g d:\j2sdk. To check whether these environment variables are set properly, open a Command Prompt and do:

> echo %JAVA_HOME%

[Understand Tomcat Directory Structure]

Some key Tomcat directories, all relative to the directory where it is installed (and I'll later refer to this directory as %CATALINA_HOME%) are the following:

bin - Startup, shutdown, and other scripts. The .sh files are for Unix systems, and the .bat files are for Windows systems.
conf - Configuration files. The ones that need to be edited later are web.xml and tomcat-users.xml.
webapps - This is where the web applications go.
common - This is the directory where additional libraries can be installed. Libraries installed here are available to all web applications.

classes - for unpacked classes and resources.
lib - for packed classes and resources, a.k.a. JAR files.

[1st Test Run]

Start Tomcat server by running the startup.bat script. Open a browser window and go to URL http://localhost:8080, and the "Congratulation" page should appear.

Shutdown Tomcat server by running the shutdown.bat script.

[Edit Configuration Files]

Open web.xml and search for "invoker". Uncomment the <servlet> and <servlet-mapping> elements for the invoker servlet.

Open tomcat-users.xml, and add a manager user, e.g.

<user name="cysun" manager="abcd" roles="manager" />

The user names and passwords are arbitrary.

[Context]

Download context.xml to the %CATALINA_HOME%\conf\Catalina\localhost directory. Rename the file to the login name assigned to you on the CS server, e.g. cs320stu31.xml, and edit the file to replace "username" with the your actual login name on the CS server. Again, assume your login name is cs320stu31, your cs320stu31.xml should look like the following:

<Context
    path="/cs320stu31"
    docBase="cs320stu31"
    reloadable="true"
    useNaming="true">
</Context>

A context file describes the URL path, the file location, and the runtime environments for a web application. In particular,

path - The URL path used to access this web application. e.g. http://localhost:8080/cs320stu31/HelloJSP.jsp
docBase - The actual file location of the web application, which can be an absolute path, or a path relative to %CATALINA_HOME%\webapps.
reloadable - This attribute tells the server whether it should reload a new version of the webapp automatically. For a development setup, set this attributes to true, and for a production setup, set it to false for better performance and stability.
useNaming - This attribute tells the server whether the web application uses JNDI naming service. We may or may not use this feature in this course, depending on whether we have time to explore database connection pooling.

[Understand Web Application Directory Structure]

Like the Tomcat server itself, each web application has its own directory structure, rooted at docBase specified in the context file. Assume your docBase is set to cs320stu31 as described in the last section, you need to create the following subdirectories under %CATALINA_HOME%\webapps:

cs320stu31
cs320stu31\WEB-INF
cs320stu31\WEB-INF\classes
cs320stu31\WEB-INF\lib
cs320stu31\WEB-INF\files

[Additional Libraries]

Download the MySQL JDBC Driver, MySQL Connector/J 3.1 from www.mysql.com, and extract mysql-connector-java-3.1.13-bin.jar to %CATALINA_HOME%\common\lib.

Download JSP Standard Tag Library (JSTL) from the Apache Jarkata Project. There are many taglibs available, and the one you should get is jarkata-taglibs-standard-1.1.2.zip. Once you download the file, extract jstl.jar and standard.jar to %CATALINA_HOME%\common\lib.

[2nd Test Run]

Download HelloJSTL.jsp to your docBase directory, and use a browser to access it at http://localhost:8080/username/HelloJSTL.jsp, and you should see the message "Hello World in JSTL". Download HelloServlet.class to your docBase/WEB-INF/classes directory, access it with the URL http://localhost:8080/username/servlet/HelloServlet, and your should see a message "Servlet invoked!" and the display of current time.

[FAQ]

Q: How do I set the JAVA_HOME environment variable on Windows 2000/XP?

A: Right click on My Computer and select Properties -> Advanced -> Environment Variable. Check whether JAVA_HOME is already defined, and if not, click on New to add it to either User Variables or Systems Variables (create new System Variables will require administrator privilege). The variable name is JAVA_HOME, and the variable value is the path to the folder where your JDK is installed, e.g. d:\j2sdk. Note that you may need to restart the computer (or logout of your account then login again) to let the new environment variable take effect.

Q: I followed all the instructions but when I tried to access HelloJSTL.jsp, I got the error message org.apache.jasper.JasperException: The absolute uri: http://java.sun.com/jsp/jstl/core cannot be resolved in either web.xml or the jar files deployed with this application.

A: go to the common\lib folder under your tomcat folder and see whether standard.jar and jstl.jar are there. Sometimes WinZip will create a subfolder under common\lib (e.g. jarkata-taglibs-standard-1.1.2). If so, find the two jar files in that subfolder and move them to common\lib.

Q: I can access the JSP pages without any problem, however, when I tried to access the servlet through the url http://localhost:8080/username/HelloServlet, I got the HTTP Status 404 error.

A: To access the servlet, the url should be something like http://localhost:8080/username/servlet/HelloServlet. Note that there's an extra servlet/ between the servlet name and the docBase path. The reason for this is the configuration in web.xml under the /conf directory. Check out the <servlet-mapping> element of the "invoker" servlet and you'll see why.

THE END (or the beginning of a fun class)