If you are compiling and deploying manually (e.g., using
an editor like TextPad or UltraEdit
instead of an IDE like Eclipse or NetBeans), you need to configure
your development environment. Here is a quick summary;
see the next sections for details.
The first thing you should do is create a directory in which to place the servlets and
JSP pages that you develop. This directory can be in your home directory (e.g.,
C:\Documents and Settings\Your Name\My Documents\Servlets+JSP
on Windows 2000) or in a convenient general location
(e.g., C:\Servlets+JSP). It should not, however,
be in the Tomcat deployment directory (e.g., anywhere
within install_dir/webapps).
Eventually, you will organize this development directory into
different Web applications.
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. Some 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.
Note that the preconfigured Tomcat version
already contains all the test files, has shortcuts from the development directory
to the deployment locations, and has shortcuts to start and stop the server.
Since I find myself frequently restarting the server, I find it convenient to place
shortcuts to the server startup and shutdown scripts inside my main development
directory or on my desktop. You will likely find it convenient to do the same.
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.
Since servlets and JSP are not part of the Java 2
platform, standard edition, you have
to identify the servlet classes to the compiler.
The server already knows about the
servlet classes, but the compiler (i.e., javac)
you use for development probably
doesn't. So, if you don't set your CLASSPATH (either via
an environment variable, an operating system setting, or an IDE setting),
attempts to compile servlets, tag libraries, filters, Web app listeners,
or other classes that use the servlet and JSP APIs will fail with error messages about
unknown classes. Again, please remember that this process is only for manual editing; as
explained in the Eclipse section, if you use Eclipse
for development (highly recommended), it will take care of this for you.
Here are the standard Tomcat locations:
install_dir/lib/servlet-api.jar
install_dir/lib/jsp-api.jar
install_dir/lib/el-api.jar
Now, in addition to the servlet and JSP JAR files,
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 a
user-defined 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 Tomcat installation
path (e.g., C:\apache-tomcat-6.0.10). Also, be sure to use the appropriate
case for the filenames, and enclose your pathnames in double
quotes if they contain spaces.
Any Windows Version from Windows 98/Me Onward.
Use the autoexec.bat file.
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-api.jar; install_dir\common\lib\jsp-api.jar
Note that these examples represent only one approach for
setting the CLASSPATH. Many
Java integrated development environments have global or project-specific settings
that accomplish the same result. But these settings are totally IDE-specific and
won't be discussed here. Another alternative is to make a .bat file or
ant build script whereby
-classpath ... is automatically appended onto calls to javac.
Windows NT/2000/XP. You could use the autoexec.bat file as above, or you can
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.
Just as no serious programmer should develop general-purpose Java applications
without access to the
JDK API documentation (in Javadoc format), no serious programmer
should develop servlets or JSP pages
without access to the API for classes in the javax.servlet packages.
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 used
for practicing and learning; for real projects you
use the web.xml file to customize that URL. For details,
see the Web app section.)
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 should either use an IDE (see the
Eclipse and MyEclipse
sections) or 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.
Go to install_dir/webapps/ROOT/WEB-INF, right-click on
the classes directory, and select Copy. Then go to your development directory, right-click, and select Paste Shortcut (not just Paste).
Note that if you use my
preconfigured Jakarta Tomcat version,
this shortcut is already in your C:\Servlets+JSP directory.
Now, whenever you compile a packageless
servlet, just drag the class files onto the shortcut.
When you develop in packages, use
the right mouse to drag the entire package directory
(e.g., the coreservlets directory) onto
the shortcut, release the mouse, and select Copy. On Unix/Linux, you can use symbolic
links (created with 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.
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). The URL
stays almost the same as it was without Web applications:
just insert the name of the directory after
the hostname (e.g., replace http://localhost/blah/blah with
http:/localhost/testApp/blah/blah).
Note that the
preconfigured Tomcat version
already contains all the test files, has shortcuts from the development directory
to the deployment locations, and has shortcuts to start and stop the server.
One disadvantage of this approach is that it requires repeated copying if you use
multiple servers. For example, I previously had
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.
By default, the Java compiler (javac) places
class files in the same directory as the
source code files from which they came. 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).
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.5.0/docs/tooldocs/windows/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.,
Eclipse, MyEclipse, NetBeans, JBuilder, Java Studio Creator, etc.) 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). It is not that difficult
to get started with these IDEs, and they provide huge advantages in
development, debugging, and deployment. I recommend that you start with
one of them from the very beginning.
An advantage of this approach 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.
Developed by the Apache foundation's Jakarta project, ant 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.
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.
