Professional Documents
Culture Documents
Training Courses: JSP, Servlets, Jakarta Struts, JSF, AJAX, & Java
5
Customized
Jakarta Struts JavaServer
Onsite Training
Programming with & Faces (JSF)
Courses at Your
Servlets & JSP Advanced JSP & Apache
Location
June 20-23, 2006 June 26-30, MyFaces
Dates Flexible.
2006 July 11-13, 2006
Any country
Contents
Introduction
Following is a guide to installing and configuring Apache Tomcat for use
as a standalone Web server (for development) that supports servlets 2.3
and JSP 1.2 (Tomcat 4) or servlets 2.4 and JSP 2.0 (Tomcat 5). (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.
More Servlets & JSP
The information here is adapted from the introductory setup and
configuration chapter of Core Servlets and JavaServer Pages, 2nd Edition,
Volume 1 from Sun Microsystems Press and Prentice Hall. For the book table of contents, index, source
code, etc., please see http://volume1.coreservlets.com/. For information on servlets, JSP, Apache Struts,
JSF, and Java training courses (either at public venues or on-site at your company) taught by the author
of the book and this Tomcat tutorial, please see http://courses.coreservlets.com. To report errors or
omissions in this writeup or to inquire about on-site training courses on servlets/JSP/Struts/JSF/Java,
please contact Marty Hall at hall@coreservlets.com.
Executive Summary
I give extremely detailed instructions in the following sections. If
you're pretty experienced and just want a short summary, this section
JSP, Servlet, Struts, &
will probably be enough for you. You can also download JSF Training
preconfigured Tomcat versions that incorporate all of the Looking for hands-on training?
modifications of this tutorial and include sample development Tired of inexperienced
directories, shortcuts, and autoexec.bat files. instructors teaching someone
else's course materials? Want a
1. Install the JDK. Make sure JDK 1.3 or 1.4 is installed and choice of public or onsite
your PATH is set so that both "java -version" and courses? Check out
"javac -help" give a result. courses.coreservlets.com.
2. Configure Tomcat. Distinctive features:
● Personally developed and
1. Download the software. Go to
taught by Marty Hall, an
http://jakarta.apache.org/site/binindex.cgi and
experienced developer,
download and unpack the zip file for the current
award-winning instructor,
release build of Tomcat 4 or 5. Also see the
4-time JavaOne speaker,
preconfigured Tomcat versions.
and author of Core
2. Set the JAVA_HOME variable. Set it to refer to the Servlets and JSP, More
base JDK directory, not the bin subdirectory. Servlets and JSP, and this
3. Enable the ROOT context. Edit Tomcat tutorial.
install_dir/conf/server.xml and uncomment this line: ● Available onsite at your
2. Use the -d option of javac. Use -d to tell Java where the deployment directory is.
3. Let your IDE take care of deployment. Tell your IDE where the deployment directory is
and let it copy the necessary files.
4. Use ant or a similar tool. Use the Apache make-like tool to automate copying of files.
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
Configuring Tomcat involves nine steps:
JSP, Servlet, Struts, &
1.Downloading the Jakarta Tomcat software. JSF Training
2.Setting the JAVA_HOME variable. Looking for hands-on training?
3.Enabling the ROOT context. Tired of inexperienced
4.Telling Tomcat to reload servlets when they are modified. instructors teaching someone
else's course materials? Want a
5.Changing the port from 8080 to 80.
choice of public or onsite
6.Enabling the invoker servlet
courses? Check out
7.Changing the DOS memory settings. (Win98/Me only) courses.coreservlets.com.
8.Setting the CATALINA_HOME variable. (Optional) Distinctive features:
9.Using a preconfigured version of Tomcat with these changes ● Personally developed and
Alternatively, you can use my preconfigured Tomcat versions. These versions already have the port
changed to 80, servlet reloading enabled, and the invoker servlet turned on. The preconfigured versions
also come with a sample development directory and autoexec.bat file.
set JAVA_HOME=C:\j2sdk1.4.2_05
On Windows XP, you could also go to the Start menu, select Control Panel, choose System, click on the
Advanced tab, press the Environment Variables button at the bottom, and enter the JAVA_HOME
variable and value directly. On Windows 2000 and NT, you do Start, Settings, Control Panel, System,
then Environment. If you prefer, you can use C:\autoexec.bat on those versions of Windows also (unless
a system administrator has set your PC to ignore it).
Note that in most early versions of Tomcat 5, the commented out entry distributed with Apache Tomcat
is in error: it is missing the trailing slash (i.e., <Context ... debug="0" > instead of the proper
<Context ... debug="0" />). So, you will need to insert the slash. You can also:
● Download my modified server.xml for Tomcat 4. Incorporates all of the changes of this tutorial.
From Tomcat 4.1.29, but should work on most versions of Tomcat 4. Right-click or shift-click on
the link to download the file.
● Download my modified server.xml for Tomcat 5. From Tomcat 5.0.27, but should work on most
<DefaultContext reloadable="true"/>
Be sure to make a backup copy of server.xml before making the above change. You can also:
● Download my modified server.xml for Tomcat 4. Incorporates all of the changes of this tutorial.
From Tomcat 4.1.29, but should work on most versions of Tomcat 4. Right-click or shift-click on
the link to download the file.
● Download my modified server.xml for Tomcat 5. From Tomcat 5.0.27, but should work on most
To change the port, edit install_dir/conf/server.xml and change the port attribute of the Connector
element from 8080 to 80, yielding a result similar to that below. Note that the exact form of the
Connector element varies in different Tomcat versions. Just search for a non-comment occurrence of
"8080".
From Tomcat 4.1.29, but should work on most versions of Tomcat 4. Right-click or shift-click on
the link to download the file.
● Download my modified server.xml for Tomcat 5. From Tomcat 5.0.27, but should work on most
To enable the invoker servlet, uncomment the following servlet and servlet-mapping
elements in install_dir/conf/web.xml. Note that the filename is web.xml, not server.xml as in the previous
bullets. Also, 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. Finally, remember to make a backup copy of the
original version of this file before you make the changes.
<servlet>
<servlet-name>invoker</servlet-name>
<servlet-class>
org.apache.catalina.servlets.InvokerServlet
</servlet-class>
...
</servlet>
...
<servlet-mapping>
<servlet-name>invoker</servlet-name>
<url-pattern>/servlet/*</url-pattern>
</servlet-mapping>
From Tomcat 4.1.29, but should work on most versions of Tomcat 4. Right-click or shift-click on
the link to download the file.
● Download my modified web.xml for Tomcat 5. From Tomcat 5.0.27, but should work on most
versions of Tomcat 5. Right-click or shift-click on the link to download the file.
● Use my preconfigured Tomcat versions. Tomcat 4.1.29 or 5.0.27 with all server.xml and web.xml
changes, plus the sample HTML, JSP, Java files.
changes in server.xml for you. However, since you still need to edit server.xml to enable servlet
reloading and the invoker servlet, this is not much of a help.
● It will set JAVA_HOME for you. The installer hunts for your Java installation and tries to set
you can go to the Start Menu, select Apache Tomcat 5.0, select Monitor Tomcat, and select Start
or Stop, as shown below. I prefer startup.bat and shutdown.bat so that I can put shortcuts in my
development directory (easier to invoke) and/or the desktop (where I can associate keyboard
shortcuts).
that the server is installed and configured properly. For Tomcat, click Looking for hands-on training?
on install_dir/bin/startup.bat (or execute install_dir/bin/startup.sh Tired of inexperienced
on Unix/Linux). Next, enter the URL http://localhost/ in your instructors teaching someone
browser and make sure you get the Tomcat welcome page, not an else's course materials? Want a
error message saying that the page could not be displayed or that the choice of public or onsite
server could not be found. If you chose not to change the port courses? Check out
number to 80 as described above, you will need to use a URL like courses.coreservlets.com.
http://localhost:8080/ that includes the port number. Distinctive features:
● Personally developed and
If this does not work, there are a couple of things to check: taught by Marty Hall, an
experienced developer,
● Did the Tomcat window pop up and stay open? If not, the award-winning instructor,
error messages are lost and it is hard to know what you did 4-time JavaOne speaker,
wrong. So, open a DOS window, go to install_dir/bin and and author of Core
type "catalina run" to start Tomcat without popping up Servlets and JSP, More
a new window. Now, the error messages should help you Servlets and JSP, and this
figure out the problem (e.g., JAVA_HOME not set properly or Tomcat tutorial.
IIS already reserving port 80). ● Available onsite at your
● Does the server appear to be running but you cannot organization or at public
access the home page? Maybe your browser is using a proxy venues.
and you have not set it to bypass proxies for local addresses? ● Well-tested, having been
To fix this: used by Marty for courses
❍ On Internet Explorer, go to Tools, Internet Options,
for dozens of clients in the
Connections, and LAN Settings. If the "Use a proxy USA, Canada, Australia,
server" checkbox is selected, make sure the "Bypass Japan, Puerto Rico, and
proxy server for local addresses" box is also selected. the Philippines.
❍ On Netscape 6/7, go to the Edit menu, then select
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.
Eventually, you will almost certainly want to create and use your own Web applications (see Section
2.11 of the book), but for initial testing many people prefer to use the default Web application. With
Tomcat 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 some Tomcat versions create install_dir/webapps/ROOT
only 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. If you
download the files using Internet Explorer, just be careful that it does not try to change the file extension,
yielding Hello.htm instead of Hello.html. The code for these files, as well as all the code from the book,
is available online at http://volume1.coreservlets.com. That Web site also contains book updates,
additions, information on servlet and JSP short courses, and the full text of the first edition 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 you successfully started the server as described above, but 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
or you forgot to enable the ROOT context. If the HTML file works but the JSP file fails, you probably
have incorrectly specified the base JDK directory (i.e., with the JAVA_HOME variable).
Eventually, you will organize this development directory into different Web applications (each with a
common structure--see Section 2.11 of the book for details). 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. If you put the shortcuts on your
desktop, you can also assign keyboard shortcuts to invoke them. On Unix, you would use ln -s to
make a symbolic link to startup.sh, catalina.sh (needed even though you don't directly invoke this file),
and shutdown.sh.
messages about unknown classes. Here are the standard Tomcat locations:
● Tomcat 4: 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:\Servlets+JSP. Replace install_dir with the actual base installation location of the server.
Also, be sure to use the appropriate case for the filenames, and enclose your pathnames in double quotes
if they contain spaces.
■ Sample code: (Note that this all goes on one line with no spaces--it is broken here
only for readability.)
set CLASSPATH=.;
C:\Servlets+JSP;
install_dir\common\lib\servlet.jar
■ Sample file to download and modify: autoexec.bat
❍ Tomcat 5
Sample code: (Note that this all goes on one line with no spaces--it is broken here
■
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. Another
alternative is to make a script whereby -classpath ... is automatically appended onto calls
to javac.
● Windows NT/2000/XP. You could use the autoexec.bat file as above, but a more common
approach is to use system settings. On WinXP, go to the Start menu and select Control Panel, then
System, then the Advanced tab, then the Environment Variables button. On Win2K/WinNT, go to
the Start menu and select Settings, then Control Panel, then System, then Environment. Either
way, enter the CLASSPATH value from the previous bullet.
You can access the documentation from the Tomcat home page, but you probably will want access to the
API even when the server is not running. So, I recommend you open the top-level file directly from disk
and bookmark that location. Here are the standard locations:
● Tomcat 4.
❍ Servlet and JSP APIs: install_dir/webapps/tomcat-docs/servletapi/index.html
● Tomcat 5.
❍ Servlet API: install_dir/webapps/tomcat-docs/servletapi/index.html
❍ JSP API: install_dir/webapps/tomcat-docs/jspapi/index.html
the file to your system. Note: in all versions of Apache Tomcat, the location for servlets in the default
Web application is install_dir/webapps/ROOT/WEB-INF/classes. However, in recent versions of
Tomcat, the system doesn't create the directory for you automatically. No problem: just create it yourself.
(Remember that case matters: WEB-INF is upper case, classes is lower case.) Note that my preconfigured
Tomcat versions already contain the classes directory and already have the sample servlets installed.
If you get compilation errors such as "Unresolved symbol: ServletUtilities", check the
following two things.
● That you put the classes in the coreservlets subdirectory, not directly in your development
directory. Packaged Java code should always be placed in a subdirectory matching the package
name.
● That your CLASSPATH is set properly. If this is the cause of your problem, you most likely
forgot to include the top-level development directory (i.e., the directory above the package-
specific subdirectory). 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.
Please don't send me email about unresolved symbol errors until you have confirmed that
HelloServlet3.java and ServletUtilities.java are in a subdirectory called coreservlets, and that the
directory above this is in the CLASSPATH.
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.
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://localhost/blah/blah with http:/localhost/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 Apache Tomcat, Macromedia JRun, and Caucho Resin 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 development server, but when you get to the "real" deployment server,
you won't want to include the source code files.
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 subdirectories matching the package names.
The main disadvantage of this approach is that it applies only to Java class files; it won't work for
deploying HTML and JSP pages, much less entire Web applications.
Most servlet- and JSP-savvy development environments (e.g., IBM WebSphere Studio, Eclipse, Borland
JBuilder) have options that let you tell the IDE where to deploy class files for your project. Then, when
you tell the IDE to build the project, the class files are automatically deployed to the proper location
(package-specific subdirectories and all).
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.
The main advantage of this approach is flexibility: ant is powerful enough to handle everything from
compiling the Java source code files, to copying class files, to producing WAR files. 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.
● Have the ROOT context enabled (so that you can use the default Web application).
● Have servlet reloading turned on (so you do not have to restart the server if you change a servlet
.class file).
● Have the port changed from 8080 to 80 (so you do not have to type the port number in the URL).
● Have the invoker servlet enabled (so you can invoke servlets with
http://localhost/servlet/ServletName, without making changes to web.xml or restarting the server).
● Include the sample HTML page, JSP page, servlets, and utility classes needed to test your setup.
● Include a sample development directory with shortcuts to ROOT, ROOT/WEB-INF/classes,
However, the preconfigured Tomcat versions are not necessarily as up-to-date as the versions on the
Apache site, so you should go to the Apache site if you want the very latest version.
● Preconfigured Tomcat 4:
jakarta-tomcat-4.1.29-preconfigured.zip.
● Preconfigured Tomcat 5:
jakarta-tomcat-5.0.27-preconfigured.zip.
More Information