offering additional documentation

[Daniel Kehoe <ke...@fortuity.com>]

There has been no traffic on the list docs@jakarta.apache.org so 
maybe tomcat-dev is the right place for this. I put together 
instructions to supplement the (sketchy) README and TomCatFAQ.txt 
files. These instructions are long on detail and intended to be 
complete enough to help very inexperienced users get started. It's 
been a long time since I wrote techdocs so I hope they are helpful to 
others! Perhaps someone would like to include them in the 
distribution or edit the README to include more detail. Let me know 
how I can help.

Daniel
kehoe@fortuity.com


instructions.txt,v 1.1 2000/02/24 18:40 kehoe

1. Instructions For Installing and Configuring the Tomcat Web Server

Tomcat is the reference implementation of the Java servlet API 2.2 
and JSP 1.1.  Tomcat provides its own web server (it can also be used 
in conjunction with the Apache  web server).  These instructions were 
written for Tomcat version 3.1M1.

You can download Tomcat from
http://jakarta.apache.org/

Unarchiving Tomcat is all that is needed to install Tomcat in its 
default configuration if you have downloaded one of the binary 
distributions. To unarchive, use gnutar (for jakarta-tomcat.tar.gz), 
or uncompress and tar (for jakarta-tomcat.tar.Z), or a Windows unzip 
utility (for jakarta-tomcat.zip).

For these instructions, we assume Tomcat is unarchived on a Unix host 
in the directory
/usr/local/tomcat

To start Tomcat, go to /usr/local/tomcat and enter
startup.sh
To stop Tomcat, go to /usr/local/tomcat and enter
shutdown.sh
You can combine Unix shell commands to restart TomCat when it is running.
Go to /usr/local/tomcat and enter
./tomcat.sh stop;./tomcat.sh start

If you get the error
"warning: The following class is required by Tomcat but was not 
found: sun.tools.javac.Main"
it means that Tomcat could not find your jdk (JDK, Java Development 
Kit, or JRE, Java Runtime Environment) installation directory. You 
must have a jdk installed, typically in the directory
/usr/local/jdk/
Obtain the JDK from
http://java.sun.com/

You must modify the Tomcat startup script tomcat.sh to include a path to the
jdk. Add the line
JAVA_HOME=/usr/local/jdk
at the top of the file.

If Tomcat is properly installed, you can use a web browser to access
http://www.yourserver.com:8080/

By default, Tomcat is accessible on port 8080 (so it doesn't 
interfere with any previously installed web servers). Web browsers 
connect to port 80 by default, so you should change the Tomcat 
configuration file
/usr/local/tomcat/server.xml
substituting
<Server adminPort="-1" workDir="work">
     <ContextManager port="8080" hostName="" inet="">
with
<Server adminPort="8080" workDir="work">
     <ContextManager port="80" hostName="" inet="">
and restarting Tomcat. If you are not starting Tomcat as the system 
superuser (root), you will get an error "java.net.BindException: 
Permission denied" because access to port 80 is denied to anyone but 
root. With Tomcat set to use port 80, you must be the superuser to 
start and stop Tomcat.

With Tomcat listening on port 80, you should be able to use a web 
browser to access Tomcat test pages at
http://www.yourserver.com/examples/

You can create your own test page by adding a "test.jsp" page to the directory
/usr/local/tomcat/examples/jsp/dates
(or a similar directory) and trying
http://www.yourserver.com/examples/jsp/dates/test.jsp
Note that files are created in
/usr/local/tomcat/work/localhost_80%2Fexamples
These files are the servlets (".java" and ".class" files) that are 
created by Tomcat to deliver the JSP page you created. When you make 
a change to the "test.jsp" page and make a new request for the page, 
these files will automatically be recreated and you will see your 
changes.

You can try using a Java bean (for example, "UserBean") by including 
in your "test.jsp" page
(in the /usr/local/tomcat/examples/jsp/dates directory):
<jsp:useBean id='userBean' scope='page' class='dates.UserBean'
	type="dates.UserBean" />
Place the bean (a file named UserBean.java) in
/usr/local/tomcat/examples/WEB-INF/classes/dates/
and compile it (using javac). Be sure the bean contains the statement 
"package dates;". Note that no classpath information has to be added 
to the Tomcat configuration files or startup script. Tomcat looks for 
the "WEB-INF" subdirectory in the "examples" directory and 
automatically looks for any class files in the "WEB-INF/classes" 
heirarchy. Note that recompiling the bean with changes will not 
result in any changes until the Tomcat server is restarted. 
Restarting the Tomcat server will clear the servlets cached in
/usr/local/tomcat/work/localhost_80%2Fexamples

Tomcat considers a web application to be a collection of resources 
such as jsp pages, servlets, html files, images, etc. which are 
mapped to a specific "URI" prefix. For example, all the resources 
related to a myApp application are assembled into a "myApp" directory 
and correspondingly all the requests that start with "/myApp"  are 
mapped to this application.

For example, all files used by a myApp application might be stored in the
directory
/home/docroot/myApp

To run a myApp application, the Tomcat configuration file
/usr/local/tomcat/server.xml
must contain an entry like this:

         <Context path="/myApp" docBase="/home/docroot/myApp"
             defaultSessionTimeOut="30" isWARExpanded="true"
             isWARValidated="false" isInvokerEnabled="true"
             isWorkDirPersistent="false"/>

New JSP pages simply may be added to the "/home/docroot/myApp" directory.

There might be two subdirectories:
images/
for graphics used by the JSP pages and
WEB-INF/
which contains Java beans, Java servlets, and accessory classes in 
the subdirectory
classes/
and
lib/
which can contain jar files (archived Java classes) for deployment. 
You might add servlets and Java beans to the "classes" directory 
during development and later package them in a jar file in the "lib" 
directory for deployment.


2. Instructions for Developing Web Applications With the Tomcat Web Server

These instructions assume you are using a text editor to write Java 
beans, JSP pages, and servlets and using ftp to move them to the 
www.yourserver.com server. You can use telnet or ssh to connect to 
the remote server and compile the beans or servlets using the Unix 
shell.

During development, new Java beans should be added to the directory
/home/docroot/myApp/WEB-INF/classes/com/yourCompany/myApp
(the server has to be restarted for changes to the beans to be recognized).

When new Java beans or servlets are added to the directory
/home/docroot/myApp/WEB-INF/classes/com/yourCompany/myApp
the .java files must be compiled using the javac compiler. On 
www.yourserver.com, the javac compiler might be located at 
/usr/local/jdk/bin/javac. If the PATH variable for your Unix shell is 
set to include
/usr/local/jdk/bin/
you can run the compiler with
javac MyBean.java

If your classpath environment variable is not set properly for your 
Unix shell, you may get a compile error such as:
"Package javax.servlet not found in import"
if you are importing the javax.servlet package into your bean.

The javax.servlet package is contained in the Tomcat distribution:
/usr/local/tomcat/lib/servlet.jar
so you will need to have a line in your shell configuration file that 
sets the classpath environment variable. For a .bashrc file, the 
syntax is:
export CLASSPATH='/usr/local/tomcat/lib/servlet.jar'
allowing the javac compiler to find the class libraries it needs.
If you will be using beans or accessory classes of your own, you may 
need to specify the location of these files as well:
export 
CLASSPATH='/usr/local/tomcat/lib/servlet.jar:/home/docroot/myApp/WEB-I 
NF/classes/'

These instructions were prepared by Daniel Kehoe <ke...@fortuity.com> 
for Tomcat version 3.1M1. For assistance, see the Tomcat FAQ at
http://jakarta.apache.org/faq/faqindex.html
or the archives of the Tomcat developers mailing list at
http://www.metronet.com/~wjm/tomcat/