In the instructions below, substitute your UW Net ID wherever you see "uwnetid".

Last updated: 11 Jan 2008

Tomcat

Tomcat is an open-source project which provides the official reference implementation of the Java Server Pages (JSP) and Java Servlets technologies. In other words, Tomcat serves dynamic web content based on Java technology, and the way it does it is the way it should be done (for Java).

Tomcat is just one of many tools in the Apache Software Foundation. Other useful tools are:

• ant -- a Java-based software-build tool
• cactus -- a test framework for unit testing server-side code

Tomcat provides an environment for Java-based dynamic web content; in other words, a container for servlets. You create your JSP code or servlets, write some web pages in HTML to reference them, compile everything, deploy it to Tomcat (which encapsulates it in a container), and test it via a web browser.

For general servlet development information, see the Application Developer's Guide.

In a typical production environment for web serving, a web administrator would add new servlets to the proper location and configure Tomcat's files appropriately. In a lab environment such as ours, it is more convenient to have each person administer their own files.

Tomcat in a Development Environment

However, a standard Tomcat configuration is not well-suited for a development environment. Multiple users share the same Java virtual machine (JVM), which can lead to security exposures and interference between the shared users. Specifically, that interference can affect the performance and reliability of each web application in the shared JVM. If an error is made in one application, such as an infinite loop or excessive memory consumption, all other applications will be affected. In past quarters, this has led to Tomcat failing due to OutOfMemory errors and 99% CPU utilization, which barred students who had properly coded programs from doing their work until Tomcat was restarted by SET lab staff.

SET lab staff are now exploiting some advanced features of Tomcat to better suit our academic development environment. This involves copying and modifying files in your home directory and opening a port in the firewall. We only want to allow this for those students who need to use Tomcat, so we have established a means of requesting your own Tomcat development service.

Request Your Own Tomcat Development Service

A Tomcat Development Service is your own Tomcat service running exclusively for your development needs, as opposed to sharing the service with other developers and exposing your web application to the world (although it still is -- it just uses a non-standard port number). Once the bugs have been worked out of your development web application code, you could install it on the shared Tomcat service (uses port 8080), or, perhaps in the future, deploy it to another Tomcat server located elsewhere.

To request that you want to administer and use your own tomcat development service:

1. Login to the repository server
2. Enter:

     request_tomcat
     

3. Logoff

   Enter:

     exit
     

4. Login again

request_tomcat saves a special file that the logon process looks for. That file is called ~/.catalina_port. If it is an empty file (size is zero) and if there is no directory called ~/catalina, the logon process will:

• reserve three ports in the firewall for your use (a service port, debug port and a hidden shutdown port)
• store the service port number in ~/.catalina_port
• copy subdirectories and files into a new subdirectory called ~/catalina
• change information in ~/catalina specific to your UW Net ID and port

Under any other conditions, the logon process will do nothing towards creating a tomcat development environment... nor will it change an existing one.

All of this processing to get a tomcat development environment is done before you get a login session, so you don't see anything happen. You should notice the new ~/catalina subdirectory and also the changed ~/.catalina_port file, but there is little else that changed (except ~/.pw, to add a password for 'tomcatdev').

Administering the Tomcat Development Service

Once the tomcat development environment is created (it can be modified), one can start the Tomcat Development Service. The service needs to be running to accept web application installation requests from ant.

There are two ways to administer the service, and they depend on whether or not you are starting your own or a team account's service.

1. To start your own Tomcat Development Service:

     ~/catalina/startup
     

   Similarly, if you don't need to keep the tomcat development service operational all of the time (while the cssgate/repos server is up), you can and should shut it down:

     ~/catalina/shutdown
     

   This helps conserve resources on the server.

2. To start a team account's Tomcat Development Service:

   You only use a team account's resources -- you don't login as the team account. That means that you login as your own account, and navigate to the file space of the team account. For example, let's say your team account is called "_myteam". You would start up _myteam's web service (using its own ports but running under your login name) as follows:

     cd /home/INSTTECH/_myteam
     catalina/startup
     

   The startup script knows to start up the team account's tomcat development service instead of your own individual service by what directory you are in -- the "cd" command above navigated you to the team account's directory.

   You should see the team account's name in the output from the service startup. If you see your UW Net ID name instead, you'll know that you weren't in the right directory when you started -- shutdown your tomcat development service, and follow the example above.

   If you don't need to keep the team account's tomcat development service operational all of the time (while the cssgate/repos server is up), you can and should shut it down (e.g., using team account _myteam):

     cd /home/INSTTECH/_myteam
     catalina/shutdown
     

   This helps conserve resources on the server.

Note that your tomcat development service will remain operational while the server is up -- if it goes down for any reason, you will need to restart your service. You might also need to re-install your web applications (but check first -- they might be available).

Workflow for Creating JSP and Servlets

The instructions below reflect the mechanism SET Lab staff have used to allow faculty and students to manage their own development environment using built-in features of Tomcat. Since the workflow is essentially the same as when you use the shared services -- only the port number changes -- please refer to those instructions, except where noted below:

• Copy these files for easier build script creation:

    cp $BUILD_HOME/build.* .
    

  and edit the build.xml file to replace: <property file="${catalina.home}/conf/build.properties"/>

  with

  <property file="/home/INSTTECH/uwnetid/catalina/conf/build.properties"/>

  (after substituting "uwnetid" with your UW Net ID or the team account name).

  You should not need to change build.xml beyond this.

• Test by using the application name (e.g., /tcss460_johndoe_myproj) as part of the URI:

  Here is where you need to know your own unique Tomcat Development Service port number; enter:

    cat ~/.catalina_port
    

  Team accounts get the service port number from the team account space. For example, a member of the team _myteam would display the team's port information as follows:

    cat /home/INSTTECH/_myteam/.catalina_port
    

  The first number is the regular service port number. For example, it may be "8092". Then you would reference your application as:

  http://cssgate.insttech.washington.edu:8092/tcss460_johndoe_myproj

  The second number is the debug port number. For example, it might be "8093". See the information on remote debugging.

Troubleshooting Tips

Here are some common problems and their possible resolutions. Thanks to Prof. Sam Chung and the Autumn 2004 TCSS460 and Spring 2005 TCSS460 classes for helping to illuminate the problems.

In the following descriptions, for team accounts, use the team account's home directory path instead of the tilde ("~", which represents your login's home directory); e.g., for team account "_myteam", it's /home/INSTTECH/_myteam.

1. No port number in ~/.catalina_port
   • You may have forgotten to logoff then logon again. Try that.
   • If you have a ~/catalina directory, then this may be a bug in the request_tomcat mechanism. To resolve this, please send email to csslab@u.washington.edu
2. ant install problems
   1. malformedURL exception

      This generally means that ant cannot find the URL to the manager application that allows installation and removal of applications to your development service.

      Most of the time, this indicates that something is wrong in the build.xml file, which needs to be modified -- see the documentation above for changing the

          <property file...
          

      line. Make sure there is no "$" in the modified line.

      If you follow the path to that property file, you will see a build.properties file which should contain the manager.url and other property/value pairs. If you don't, please send email to csslab@u.washington.edu

   2. no response when installing -- prompt doesn't return

      It is likely that you forgot to start tomcat, so it is waiting for something to service the request you are sending. Using Ctrl-C, cancel the install, run ~/catalina/startup, and re-enter ant install.

   3. HTML code appears after the install: response

      Something is corrupted in your ~/catalina directory; please send email to csslab@u.washington.edu

3. problems when trying to run the servlet
   1. web page not found

      Either your port is blocked by the firewall (send email to csslab@u.washington.edu), you entered the wrong port number, or you forgot to start your service via ~/catalina/startup.

   2. application was installed/deployed, but cannot start it

      Please note that a lot of things need to be done exactly right in order for and and tomcat to work. Especially important to review are:

      • directory and file permissions
      • names of directories and files are case-sensitive, and must be created exactly as specified in this and other documentation
      • the application's build.properties file's app.path needs to include the path to your application, after the /coursename_uwnetid specification.

        For example, if your uwnetid was "jdoe" and your application is in directory ~/tcss460/my_first_app, the app.path should be:

                  app.path=/tcss460/jdoe_tcss460_my_first_app
                  

      • your URL for typos

        If you can cut-and-paste application path and directory information, you can avoid many problems due to typos. To see your current directory in Unix, enter pwd to print your "working directory".

4. shutdown error: java.net.ConnectException: Connection refused

   It is likely that the service was never started, or it failed to start all the way when you thought it succeeded.

   • To check to see if it is running:

         ps aux | grep tomcat | grep uwnetid
         

     Don't forget to substitute your login name for "uwnetid".

   • If it isn't running, look at the log to see why it failed:

         less ~/catalina/logs/catalina.out
         

     You may want to read about the less command before using it. Some helpful subcommands are: space bar (scroll forward one page), b (scroll backward one page), ESC > (scroll to bottom of file), q (quit).

     Generally, you are looking for "SEVERE" errors, which usually have a Java stack trace associated with them. Look carefully at the trace, and try to find the file that caused the problem. Often, it is an XML file which has some syntax error in it.

Benefits of the Tomcat Development Service

In addition to preventing others from interfering with your work and vice versa, this environment makes it much easier to debug problems with tomcat. Everything you need to know about your application is stored somewhere in your ~/catalina directory. For team accounts, use the team account's home directory path instead of the tilde ("~", which represents your login's home directory); e.g., for team account "_myteam", it's /home/INSTTECH/_myteam.

The most useful locations are (substitute either your UW Net ID or the team account name for "uwnetid" in the file names below):

• ~/catalina/logs

  Here you will find:

  • catalina.out, which records what happens when the service is started and shuts down
  • uwnetid_access.log, which records access activity for web pages
  • uwnetid_manager.log, which records what happens when you install and remove applications
• ~/catalina/work/Catalina/uwnetid.dom

  This is the working directory for tomcat. You will recognize a directory formed from your build.properties application path; inside the directory is information on the compilation of your servlets and server pages. This can be very valuable when debugging a problem when all you have is a stack trace and a line number, but no way of mapping that back to your source code.

• ~/catalina/conf

  where configuration information about the server, the users authorized for your server, and the applications themselves (in a subdirectory called Catalina/uwnetid.dom) can be found. In addition, security policies can be set here, but require tomcat to be started specially to respect them (add -security as a parameter to the ~/catalina/startup script).

Change Log