table of contents

Setting Up Your Development Environment

For Developers That are Not Using an IDE


Executive Summary

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.

  1. Creating a development directory
  2. Making shortcuts to the Tomcat startup and shutdown scripts
  3. Setting your CLASSPATH
  4. Bookmarking the servlet & JSP javadocs
  5. Establishing a simplified deployment system

Except for Bookmarking the javadocs, these steps are not necessary if you are using Eclipse or MyEclipse (highly recommended!). After you set up your development environment, be sure to come back and verify that you can compile and run servlets.


1. Create a Development Directory

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.

2. Make 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.

3. Set Your CLASSPATH

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
  • Sample file to download and modify: autoexec.bat

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.

4. Bookmark the Servlet and JSP API Documentation

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.

Here are the standard locations:

5. 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 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.

  1. Copy to a shortcut or symbolic link.
  2. Use the -d option of javac.
  3. Let your IDE take care of deployment.
  4. Use ant or a similar tool.

Details on these four options are given below.

1. Copy to a Shortcut or Symbolic Link

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.

2. Use the -d Option of javac

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).

	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.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.

3. Let Your IDE Take Care of Deployment

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.

4. Use ant or a Similar Tool

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.

For general information on using ant, see http://jakarta.apache.org/ant/manual/. See Tomcat Documentation 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 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.


More Information

Java

JSF (JavaServer Faces)

Servlets & JSP
Ajax, GWT, & JavaScript

Spring, Hibernate, & JPA

Struts