CSc31800 Internet Programming -

Spring 2004, CCNY-CUNY, Jinzhong Niu

Activating Tomcat 5.0 and Servlet Applications

1. Activating Tomcat 5.0

If you use csh, edit your login initialization file ".login" to append the following lines. Use cut-and-paste to avoid inexplicable errors caused by typos!

setenv JAVA_HOME /usr/local/apps/j2se.v9
setenv PATH `echo ${JAVA_HOME}/bin`:`echo /usr/local/apps/bin`:`echo $PATH`

These lines instruct your shell (terminal window) to use-32 bit Java 1.2, instead of Lab's default 64-bit configuration incompatible to the tomcat. Type "source .login" to activate the change. You do not need to type this command again. Every login'ed session to your account after the edit will automatically activate the above definition.

If you use bash, edit your login initialization file ".bashrc" instead to append the following lines and type "source .bashrc" to activate the change.

export JAVA_HOME=/usr/local/apps/j2se.v9
export PATH=`echo ${JAVA_HOME}/bin`:`echo /usr/local/apps/bin`:`echo $PATH`

Download and expand a tomcat compressed tape archived file, "jakarta-tomcat-5.0.18.tar.gz", a widely tested and most recent public release. Suppose your account is opqr1234 and "jakarta-tomcat-5.0.18.tar.gz" is saved in your home directory. CCNY's space quota of your account most probably prohibits you from expanding all the tomcat modules into your directory. So, create a directory in the /tmp space and expand the tomcat modules in that place. The /tmp space will be erased when the machine is powered off and on (i.e., rebooted), which rarely occurs. Erasing the contents is your responsibility. Follow the next commands:

$ cd /tmp
$ mkdir opqr1234
$ chmod og-rx opqr1234
$ cd opqr1234
$ tar --ungzip -xf ~opqr1234/jakarta-tomcat-5.0.18.tar.gz

The /tmp space is a machine specific area, not across the machines. The command "chmod og-rx opqr1234" is to prohibit others from looking into your work in the /tmp/opqr1234 directory. You need to login the same host to reuse the expanded tomcat modules. Type "hostname" to know of it. You should remember the hostname of the workstation you expanded. You do not need to physically sit in front of the machine; you can access it with "telnet" or "ssh", even from outside.

Activation of tomcat is simply getting into its bin directory and execute a startup shell script found there:

$ cd jakarta-tomcat-5.0.18/bin
$ startup.sh

The startup process prints out several lines indicating tomcat environment variables, which does not mean that the startup is successful. Any trouble, particularly related to servlet deployment, should be found at the log files found under "logs" directory.

You should be able to see the tomcat welcome page using Web browser by accessing http://[hostname]:8080, where the "[hostname]" is the machine you're using. Don't forget shutting down the tomcat if you finish testing. Deactivation is done by typing out

$ shutdown.sh

Without shutdown, tomcat will keep running after your logoff, and machine's port 8080 will be occupied.

Note that the tomcat port (default 8080) cannot be accessed outside CS firewall. Come to school to test your servlet that is migrated from your home computer.

2. Servlet Activation

Read carefully this part -- many problems are caused by careless mistakes and/or misunderstanding from not reading the next explanation carefully.

In a web container (i.e., the runtime environment realizing servlet and JSP), each web application is associated with a context, and all resources in a web application exist relative to that context. The context is physically a subdirectory under the document root of a web server, and appears in part of the URL.

Thus, if you would like to develop a servlet under a context named as say "mycontext," then create a mycontext subdirectory under the tomcat's webapps directory (i.e., webapps/mycontext). The webapps directory is to hold all the defined context, and no other place will work to activate servlet/JSP. All the servlets developed under the mycontext can be accessed via Web browser with a specific URL "http://[hostname].engr.ccny.cuny.edu:8080/mycontext".

A servlet has an alias name, a servlet name, that needs to be mapped to a physical Java class upon its use. If you would like to develop a servlet, say "myservlet1," then you have to also build a Java class, say "mydriver1.class," and the mapping from alias name to concrete Java class must be established in a "web.xml" file as detailed below. The use of the servlet alias name allows to refer to servlets more easily and replace the implementation class for servlet without modifying the reference to the servlet within the application.

The mycontext directory usually needs to contain an index.html file. This is the default entry for Web browser to invoke your web application. The index.html usually has a html form element, such as "<form action=servlet/myservlet1 method=post>", in which myservlet1 is the servlet alias name to be mapped to the concrete mydriver1.class Java class and activated as a servlet.
Under the mycontext directory, create a WEB-INF directory (i.e., mycontext/WEB-INF). Note that "WEB-INF" must be uppercases and spelled as it is. Then, under WEB-INF, create a classes directory (i.e., mycontext/WEB-INF/classes) and web.xml file. Copy the provided web.xml file into your place, and change its contents as instructed if you choose different servlet name and Java class name. Servlet never becomes accessible otherwise.
The web.xml file plays a central role in deploying an alias named servlet and activating a corresponding Java class by defining a pattern in the URL to forward the request to the activated servlet. Thus, there are two levels of abstraction, resulting the source of confusion and problem. For instance, in "<form action=servlet/myservlet1 method=post>", the pattern to invoke the servlet in the request URL ("servlet/myservlet1") in fact can be anything other than this, like "call-servlet/my-developed-servlet1" instead, but the transformation to point to the alias "myservlet1" must be properly defined in web.xml. Otherwise, 404/500 error occurs.
All the Java programs will be implemented under the classes directory. The servlet myservlet1 should be runnable as mydriver1.class, compiled from mydriver1.java. A sample Makefile is provided for you. Notice as indicated in this file that the first line must be changed to point a servlet API jar file located in the expanded tomcat module library.
Type "chmod +x Makefile" and type "make" will compile all the java source code. You will see how the make command will facilitate Java compilation tasks.
In summary, the whole structure looks like

You can add any number of servlets into an established context. For instance, you can add myservlet2 that will be mapped to mydriver2.class, etc. The URL pattern matching must be added as well.

Reproduce a simple "hello world" servlet example (provided by tomcat project) into the "mycontext" subdirectory as a practice before installing full-fledged servlet, so that you will be able to make sure that all of your customization works.
You have to stop and restart tomcat to activate a revised servlet. This means that if you recompile the Java servlet module, you have to restart the tomcat in order to activate newly created module. Old module will continue to be used otherwise. There is an "auto-reload" option that lets the tomcat reflect the new module without reactivating the entire tomcat, which can be set in the configuration file. Setting the reload option will accelerate your servlet development.
All the errors related to servlet initialization and execution are found in a logs directory. The log files are cumulative, and once tomcat is successfully terminated you can delete all the file there to let the system accumulate new logs.