More Servlets & JSP
Core Servlets & JSP
| Configuring & Using Apache Tomcat 4 |
|---|
| Contents |
|---|
| Introduction |
|---|
More Servlets & JSP |
|---|
Core Servlets & JSP |
Integrating Tomcat with a regular Web server is valuable for a deployment scenario, but my goal here is to show how to use Tomcat as a development server on your desktop. Regardless of what deployment server you use, you'll want a standalone server on your desktop to use for development. (Note: Tomcat is sometimes referred to as Jakarta Tomcat since the Apache Java effort is known as "The Jakarta Project").
The examples here assume you are using Windows, but they can be easily adapted for Solaris, Linux, and other versions of Unix. I've gotten many reports of successful use on MacOS X, but don't know the setup details. Except when I refer to specific Windows paths (e.g., C:\blah\blah), I use URL-style forward slashes for path separators (e.g., install_dir/webapps/ROOT). Adapt as necessary.
The information here is adapted from More Servlets and JavaServer
Pages from Sun Microsystems Press. For the book table of contents, index,
source code, etc., please see http://www.moreservlets.com/. For
information on servlet and JSP training courses (either at public venues or
on-site at your company), please see http://courses.coreservlets.com/. To
report errors or omissions in this writeup or to inquire about an on-site
servlet and JSP training course, please contact Marty at hall@coreservlets.com.
| Executive Summary |
|---|
| JSP & Servlet Training Courses:
Programming with Servlet and JSP Technology. Intermediate-level course aimed at developers with knowledge of basic Java but little experience with servlets and JSP. Includes coverage of cookies, session tracking, use of beans in JSP, the MVC architecture, JDBC, custom tag libraries, SCWCD certification review, and more. June 17-20, 2003, Rockville, Maryland (near DC). Advanced JSP and Servlet Programming. Advanced course aimed at developers with moderate to significant previous experience with servlets and JSP. Includes coverage of filters, listeners, Apache Struts, JSTL, and advanced custom tag libraries. On-site Training Taught at your organization. Topics customizable. |
I give extremely detailed instructions in the following sections. If you're pretty experienced and just want a short summary, this section will probably be enough for you.
PATH set so that both "java -version" and
"javac -help" give a result.
<Context path="" docBase="ROOT" debug="0"/>.
Not necessary in Tomcat 4.0.3 and earlier.
servlet-mapping element that maps the invoker
servlet to /servlet/*. Not necessary prior to Tomcat 4.1.12.
port attribute of the Connector element from 8080
to 80.
DefaultContext subelement to the main Service
element and supply true for the reloadable
attribute.
JAVA_HOME variable. Set it to refer to the base JDK
directory, not the bin subdirectory.
CATALINA_HOME variable. Optionally, set
CATALINA_HOME to refer to the top-level Tomcat installation
directory. CLASSPATH. Include the current directory ("."),
install_dir/common/lib/servlet.jar, and the main development
directory.
CLASSPATH includes the top level of your development directory.
-d option of javac. Use -d to
tell Java where the deployment directory is.
ant or a similar tool. Use the Apache
make-like tool to automate copying of files.
| Install the JDK |
|---|
Your first step is to download and install Java. The servlet 2.3
specification requires Java 2; I suggest JDK 1.3 or later. See the following
sites for download and installation information. Once you've installed Java,
confirm that everything including your PATH is configured properly
by opening a DOS window and typing "java -version" and
"javac -help". You should see a real result both times, not an
error message about an unknown command. Or, if you use an IDE, compile and run a
simple program to confirm that the IDE knows where you installed Java.
| Configure Tomcat |
|---|
JSP & Servlet Training Courses
|
JAVA_HOME variable.
CATALINA_HOME variable. Note: from this point forward, I'll refer to that location as install_dir.
<Context path="" docBase="ROOT" debug="0"/>If you are using Tomcat 4.1.12, you can download Marty's server.xml file with this change already made. Only use this file in Tomcat 4.1.12; other entries (not discussed here) vary slightly in different Tomcat versions.
To enable the invoker servlet, uncomment the following
servlet-mapping element in install_dir/conf/web.xml
(not .../server.xml, and do not confuse this Apache
Tomcat-specific web.xml file with the standard one that goes in the
WEB-INF directory of each Web application):
<servlet-mapping>
<servlet-name>invoker</servlet-name>
<url-pattern>/servlet/*</url-pattern>
</servlet-mapping>
To change the port, edit install_dir/conf/server.xml and change the
port attribute of the Connector element from 8080 to
80, yielding the result below. (Note that the exact class name of the Connector
varies in different Tomcat versions. It was called HttpConnector in earlier
versions of Tomcat 4.)
<Connector
className="org.apache.coyote.tomcat4.CoyoteConnector"
port="80" ...
... />
If you are using Tomcat 4.1.12, you can download Marty's server.xml file
with this change already made. Only use this file in Tomcat 4.1.12;
other entries (not discussed here) vary slightly in different Tomcat versions.
To turn on servlet reloading, edit install_dir/conf/server.xml and add
a DefaultContext subelement to the main Service
element and supply true for the reloadable attribute.
The easiest way to do this is to find the following comment:
<!-- Define properties for each web application. This is only needed
if you want to set non-default properties, or have web application
document roots in places other than the virtual host's appBase
directory. -->
and insert the following line just below it: <DefaultContext reloadable="true"/>Be sure to make a backup copy of server.xml before making the above change. If you are using Tomcat 4.1.12, you can download Marty's server.xml file with this change already made. Only use this file in Tomcat 4.1.12; other entries (not discussed here) vary slightly in different Tomcat versions.
JAVA_HOME VariableNext, you must set the JAVA_HOME environment variable to tell
Tomcat where to find Java. Failing to properly set this variable prevents Tomcat
from handling JSP pages. This variable should list the base JDK installation
directory, not the bin subdirectory. For example, if you are on Windows
98/Me and installed the JDK in j2sdk1.4.0_02 on your C drive, you
might put the following line in your C:\autoexec.bat file.
set JAVA_HOME=C:\j2sdk1.4.0_02On Windows NT/2000/XP, you could also go to the Start menu and select Settings, then Control Panel, then System, then Environment. Then, you could enter the
JAVA_HOME value. But, you can use C:\autoexec.bat
on those versions of Windows also, if you prefer.
Rather than setting the JAVA_HOME environment variable globally
in the operating system, some developers prefer to edit the startup script to
set it there. If you prefer this strategy, edit
install_dir/bin/catalina.bat and insert the following after the first set
of comments:
if not "%JAVA_HOME%" == "" goto gotJavaHome set JAVA_HOME=C:\j2sdk1.4.0_02 :gotJavaHomeBe sure to make a backup copy of catalina.bat before making the changes.
CATALINA_HOME Variable
(Optional)CATALINA_HOME
environment variable to refer to the top-level directory of the Apache Tomcat
installation (e.g., C:\jakarta-tomcat-4.1.12-LE-jdk14). This variable
identifies the Tomcat installation directory to the server. However, if you are
careful to avoid copying the server startup scripts and you use only shortcuts
(called "symbolic links" on Unix/Linux) instead, you are not required to
set this variable.
| Test the Server |
|---|
JSP & Servlet Training Courses
|
To halt the server, double click on install_dir/bin/shutdown.bat. I recommend that you make shortcuts to (not copies of) the startup and shutdown scripts and place those shortcuts on the desktop or in your main development directory. If you use an IDE, you'll have to tell it where these scripts are.
Eventually, you will almost certainly want to create and use your own Web applications (see Chapter 4 of More Servlets and JavaServer Pages), but for initial testing I recommend that you use the default Web application. Although Web applications follow a common directory structure, the exact location of the default Web application is server specific. With Tomcat 4 and the default Web application, you put HTML and JSP pages in install_dir/webapps/ROOT or install_dir/webapps/ROOT/SomePath and access them with http://localhost/filename or http://localhost/SomePath/filename. Note that Tomcat creates install_dir/webapps/ROOT when the server is first run. So, you must start the server as described above before trying to access the directory.
For your first tests, I suggest you simply take Hello.html and Hello.jsp and drop them into the appropriate locations. Right click on the links to download these two files to your system. The code for these files, as well as all the code from the book, is available online at http://www.moreservlets.com/. That Web site also contains book updates, additions, information on servlet and JSP short courses, and the full text of Core Servlets and JavaServer Pages (in PDF).
If you put the files in the top-level directory of the default Web application (i.e., in install_dir/webapps/ROOT), access them with the URLs http://localhost/Hello.html and http://localhost/Hello.jsp, respectively. If you put them in a subdirectory of install_dir/webapps/ROOT, use the URLs http://localhost/directoryName/Hello.html and http://localhost/directoryName/Hello.jsp, respectively.
If neither the HTML file nor the JSP file works (e.g., you get File Not
Found--404--errors), you likely are using the wrong directory for the files. If
the HTML file works but the JSP file fails, you probably have incorrectly
specified the base JDK directory (e.g., with the JAVA_HOME
variable).
| Set Up Your Development Environment |
|---|
The server startup script automatically sets the server's
CLASSPATH to include the standard servlet and JSP classes and the
WEB-INF/classes directory (containing compiled servlets) of each Web
application. But you need similar settings, or you will be unable to
compile servlets in the first place. Configuring your server for servlet
development involves the following four steps:
CLASSPATH
Eventually, you will organize this development directory into different Web applications (each with a common structure--see More Servlets and JavaServer Pages Chapter 4). For initial testing of your environment, however, you can just put servlets either directly in the development directory (for packageless servlets) or in a subdirectory that matches the servlet package name. Many developers simply put all their code in the server's deployment directory (within install_dir/webapps). I strongly discourage this practice and instead recommend one of the approaches described in the deployment section. Although developing in the deployment directory seems simpler at the beginning since it requires no copying of files, it significantly complicates matters in the long run. Mixing locations makes it hard to separate an operational version from a version you are testing, makes it difficult to test on multiple servers, and makes organization much more complicated. Besides, your desktop is almost certainly not the final deployment server, so you'll eventually have to develop a good system for deploying anyhow.
For example, one way to make these shortcuts is to go to
install_dir/bin, right-click on startup.bat, and select Copy. Then
go to your development directory, right-click in the window, and select Paste
Shortcut (not just Paste). Repeat the process for
install_dir/bin/shutdown.bat. On Unix, you would use
ln -s to make a symbolic link to startup.sh,
tomcat.sh (needed even though you don't directly invoke this file), and
shutdown.sh.
CLASSPATHjavac)
you use for development probably doesn't. So, if you don't set your
CLASSPATH, attempts to compile servlets, tag libraries, or other
classes that use the servlet API will fail with error messages about unknown
classes. The exact location of the servlet JAR file varies from server to
server, but with Tomcat it is install_dir/common/lib/servlet.jar.
Now, in addition to the servlet JAR file, you also need to put your
development directory in the CLASSPATH. Although this is not
necessary for simple packageless servlets, once you gain experience you will
almost certainly use packages. Compiling a file that is in a package and that
uses another class in the same package requires the CLASSPATH to
include the directory that is at the top of the package hierarchy. In this case,
that's the development directory I just discussed. Forgetting this setting is
perhaps the most common mistake made by beginning servlet programmers.
Finally, you should include "." (the current directory) in the
CLASSPATH. Otherwise, you will only be able to compile packageless
classes that are in the top-level development directory.
Here are two representative methods of setting the CLASSPATH.
They assume that your development directory is C:\ServletDevel. Replace
install_dir with the actual base installation location of the server.
Also, be sure to use the appropriate case for the filenames. Note that these
examples represent only one approach for setting the CLASSPATH.
Many Java integrated development environments have a global or project-specific
setting that accomplishes the same result. But these settings are totally
IDE-specific and won't be discussed here. And, you can also make a script
whereby -classpath ... is automatically appended onto calls to
javac.
Windows 98/Me
Put the following in your
autoexec.bat. (Note that this all goes on one line with no spaces--it is
broken here for readability.)
set CLASSPATH=.;
C:\ServletDevel;
install_dir\common\lib\servlet.jar
Windows NT/2000/XPCLASSPATH value from the
previous bullet.
javax.servlet packages.
So, open install_dir/webapps/tomcat-docs/servletapi/index.html in your browser and then add it to your bookmarks (Netscape) or favorites (Internet Explorer) list. If Tomcat is running, you can also access the API with http://localhost/tomcat-docs/servletapi/index.html. However, you almost certainly will want access to the API even when the server is not running, so I recommend you open the file directly from disk and bookmark that location.
| Compile and Test Some Simple Servlets |
|---|
OK, so your environment is all set. At least you think it is. It would be nice to confirm that hypothesis. Verifying this involves the following three steps:
| What about install_dir/classes? |
|---|
| "Hey, wait! Shouldn't I use install_dir/classes
instead of install_dir/webapps/ROOT/WEB-INF/classes?"
Nope. There are two reasons why it is preferable to use install_dir/webapps/ROOT/WEB-INF/classes: 1. It is standard. The ROOT directory follows the normal structure of a Web application (see Section 4.2 of More Servlets and JSP): HTML/JSP files go in the main directory, the web.xml file (see Chapter 5 of More Servlets and JSP) goes in WEB-INF, unjarred Java classes go in WEB-INF/classes, and JAR files go in WEB-INF/lib. So, if you use WEB-INF/classes, you are using a structure that works on all servers that support servlets 2.2 and later. OTOH, install_dir/classes is a Tomcat-specific location that is supported on few other servers. 2. It is specific to a Web application. Once you become comfortable with the basics, you will almost certainly divide your projects up into separate Web applications (see Chapters 4-6 of More Servlets and JSP). By putting your code in WEB-INF/classes, you are ready for this, since your code is already part of a Web application (the default one for Tomcat). So, the code can easily be to another Web application, and it will not interfere with any future applications. OTOH, install_dir/classes results in code that is shared by all Web applications on your server. This is almost never what you want. |
CLASSPATH settings (see
the
earlier section on this topic)--you most likely erred in listing the
location of the JAR file that contains the servlet classes (i.e.,
install_dir/common/lib/servlet.jar). Once you compile
HelloServlet.java, put HelloServlet.class in
install_dir/webapps/ROOT/WEB-INF/classes. After compiling the code,
access the servlet with the URL http://localhost/servlet/HelloServlet (or
http://localhost:8080/servlet/HelloServlet if you chose not to
change the port number as described
earlier). You should get a simple HTML page that says "Hello". If this URL
fails but the test of
the server itself succeeded, you probably put the class file in the wrong
directory.
moreservlets package, it should go in
the moreservlets directory both during development and when deployed to
the server. If you get compilation errors, go back and check your CLASSPATH
settings--you most likely forgot to include "." (the current directory).
Once you compile HelloServlet2.java, put HelloServlet2.class in
install_dir/webapps/ROOT/WEB-INF/classes/moreservlets. For now, you can
simply copy the class file from the development directory to the deployment
directory. However, an
upcoming section will provide some options for simplifying the deployment
process.
Once you have placed the servlet in the proper directory, access it with the URL http://localhost/servlet/moreservlets.HelloServlet2. You should get a simple HTML page that says "Hello (2)". If this test fails, you probably either typed the URL wrong (e.g., used a slash instead of a dot after the package name) or put HelloServlet2.class in the wrong location (e.g., directly in install_dir/webapps/ROOT/WEB-INF/classes directory instead of in the moreservlets subdirectory).
moreservlets package that uses the ServletUtilities
class to simplify the generation of the DOCTYPE (specifies the
HTML version--useful when using HTML validators) and HEAD
(specifies the title) portions of the HTML page. Those two parts of the page are
useful (technically required, in fact), but are tedious to generate with servlet
println statements.
Since both the servlet and the utility class are in the
moreservlets package, they should go in the moreservlets
directory. If you get compilation errors, go back and check your CLASSPATH
settings--you most likely forgot to include the top-level development
directory. I've said it before, but I'll say it again: your
CLASSPATH must include the top-level directory of your package
hierarchy before you can compile a packaged class that makes use of another
class from the same package. This requirement is not particular to servlets;
it is the way packages work on the Java platform in general. Nevertheless, many
servlet developers are unaware of this fact, and it is one of the (perhaps
the) most common errors beginning developers encounter.
Once you compile HelloServlet3.java (which will automatically cause ServletUtilities.java to be compiled), put HelloServlet3.class and ServletUtilities.class in install_dir/webapps/ROOT/WEB-INF/classes/moreservlets. Then, access the servlet with the URL http://localhost/servlet/moreservlets.HelloServlet3. You should get a simple HTML page that says "Hello (3)".
| Establish a Simplified Deployment Method |
|---|
OK, so you have a development directory. You can compile servlets with or without packages. You know which directory the servlet classes belong in. You know the URL that should be used to access them. (Actually, http://hostname/servlet/ServletName is just the default URL; you can also use the web.xml file to customize that URL. Use of web.xml is discussed in detail in Chapter 5 of More Servlets and JavaServer Pages.) But how do you move the class files from the development directory to the deployment directory? Copying each one by hand every time is tedious and error prone. Once you start using Web applications, copying individual files becomes even more cumbersome.
There are several options to simplify the process. Here are a few of the most popular ones. If you are just beginning with servlets and JSP, you probably want to start with the first option and use it until you become comfortable with the development process. Note that I do not list the option of putting your code directly in the server's deployment directory. Although this is one of the most common choices among beginners, it scales so poorly to advanced tasks that I recommend you steer clear of it from the start.
-d option of javac.
ant or a similar tool. ln
-s) in a manner similar to that for Windows shortcuts.
An advantage of this approach is that it is simple. So, it is good for beginners who want to concentrate on learning servlets and JSP, not deployment tools. Another advantage is that a variation applies once you start using your own Web applications. (See Chapters 4-6 of More Servlets and JSP for details on Web applications). For instance, with Tomcat, you can easily make your own Web application by putting a copy of the install_dir/webapps/ROOT directory into your development directory and renaming it (for example, to testApp). Now, to deploy your Web application, just make a shortcut to install_dir/webapps and copy the entire Web application directory (e.g., testApp) each time by using the right mouse to drag the directory that contains your Web application onto this shortcut and selecting Copy (say Yes when asked if you want to replace existing files). Almost everything stays the same as it was without Web applications: just add the name of the directory to the URL after the hostname (e.g., replace http://locahost/blah/blah with http://locahost/testApp/blah/blah). Just note that you'll have to restart the server the very first time you deploy the directory into install_dir/webapps.
One disadvantage of this approach is that it requires repeated copying if you use multiple servers. For example, I usually have Tomcat, JRun, and ServletExec on my desktop system and regularly test my code with all three servers. A second disadvantage is that this approach copies both the Java source code files and the class files to the server, whereas only the class files are needed. This does not matter on your desktop server, but when you get to the "real" deployment server, you won't want to include the source code files.
-d Option of
javacjavac)
places class files in the same directory as the source code files that they came
from. However, javac has an option (-d) that lets you
designate a different location for the class files. You need only specify the
top-level directory for class files--javac will automatically put
packaged classes in subdirectories that match the package names. So, for
example, I could compile the HelloServlet2 servlet as follows (line
break added only for clarity; omit it in real life). javac -d install_dir/webapps/ROOT/WEB-INF/classes
HelloServlet2.java
You could even make a Windows batch file or Unix shell script or alias
that makes a command like servletc expand to javac -d
install_dir/.../classes. See http://java.sun.com/j2se/1.4/docs/tooldocs/win32/javac.html
for more details on -d and other javac options.
An advantage of this approach is that it requires no manual copying of class
files. Furthermore, the exact same command can be used for classes in different
packages since javac automatically puts the class files in a
subdirectory matching the package.
The main disadvantage is that this approach applies only to Java class files; it won't work for deploying HTML and JSP pages, much less entire Web applications.
An advantage of this approach, at least in some IDEs, is that it can deploy HTML and JSP pages and even entire Web applications, not just Java class files. A disadvantage is that it is an IDE-specific technique and thus is not portable across systems.
ant or a Similar Toolant is a tool similar
to the Unix make utility. However, ant is written in
the Java programming language (and thus is portable) and is touted to be both
simpler to use and more powerful than make. Many servlet and JSP
developers use ant for compiling and deploying. The use of
ant is especially popular among Tomcat users and with those
developing Web applications.
For general information on using ant, see http://jakarta.apache.org/ant/manual/.
See http://jakarta.apache.org/tomcat/tomcat-4.1-doc/appdev/processes.html
for specific guidance on using ant with Tomcat.
The main advantage of this approach is flexibility: ant is
powerful enough to handle everything from compiling the Java source code to
copying files to producing WAR files (MSAJSP Section 4.3). The disadvantage of
ant is the overhead of learning to use it; there is more of a
learning curve with ant than with the other techniques in this
section.
| More Information |
|---|
|
|