Top

table of contents

• Executive Summary
• Verify that you can start the server.
• Check that you can access your own HTML & JSP pages.
• Set up your development environment.
• Try compiling and deploying servlets.
• More Information

Testing Server Setup

For Manual Tomcat Installation (No IDE)

Executive Summary

After you set up Tomcat, make sure you can run it and that you can execute HTML pages, JSP pages, and servlets. Here is a quick summary; see the next sections for details.

1. Verify that you can start the server. Double-click install_dir/bin/startup.bat and try accessing http://localhost/.
2. Check that you can access your own HTML & JSP pages. Drop some simple HTML and JSP pages into install_dir/webapps/ROOT and access them with http://localhost/filename.
3. Set up your development environment. Make sure your CLASSPATH is set for your editor; make sure you have an easy system for moving compiled servlets to the server.
4. Try compiling and deploying servlets.

1. Verify That the Server Can Start

Before trying your own servlets or JSP pages, you should make sure that the server is installed and configured properly. For Tomcat, click on install_dir/bin/startup.bat (or execute install_dir/bin/startup.sh on Unix/Linux). Next, enter the URL http://localhost/ in your browser and make sure you get the Tomcat welcome page, not an error message saying that the page could not be displayed or that the server could not be found. If you chose not to change the port number to 80 as described in the detailed configuration page, you will need to use a URL like http://localhost:8080/ that includes the port number.

If this does not work, there are a couple of things to check:

• Did the Tomcat window pop up and stay open? If not, the error messages are lost and it is hard to know what you did wrong. So, open a DOS window, go to install_dir/bin and type "catalina run" to start Tomcat without popping up a new window. Now, the error messages should help you figure out the problem (e.g., JAVA_HOME not set properly or IIS already reserving port 80).
• Does the server appear to be running but you cannot access the home page? Maybe your browser is using a proxy and you have not set it to bypass proxies for local addresses? To fix this:
  • On Internet Explorer, go to Tools, Internet Options, Connections, and LAN Settings. If the "Use a proxy server" checkbox is selected, make sure the "Bypass proxy server for local addresses" box is also selected.
  • On Netscape 6/7, go to the Edit menu, then select Preferences, Advanced, and Proxies. Then enter "localhost" in the textfield labeled "No Proxy for:".
  • On Mozilla Firefox go to Tools, Internet Options, and Connections. Make sure "localhost" is in the textfield labeled "No Proxy for:". Note that this entry is the default with Firefox, so you probably do not need to change it.

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 put them on the desktop, you can assign keyboard shortcuts, which is convenient.

2. Try Some Simple HTML and JSP Pages

After you have verified that the server is running, you should make sure that you can install and access simple HTML and JSP pages. This test, if successful, shows two important things. First, successfully accessing an HTML page shows that you understand which directories should hold HTML and JSP files, and what URLs correspond to them. Second, successfully accessing a new JSP page shows that the Java compiler (not just the Java virtual machine) is configured properly.

Eventually, you will almost certainly want to create and use your own Web applications, 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.

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 link to download these two files to your system. If you download the files using Internet Explorer, be careful that it does not try to change the file extension, yielding Hello.htm instead of Hello.html. Note also that the preconfigured Tomcat version already contains all the test files, and has shortcuts from the development directory to the deployment locations.

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

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

1. Testing a packageless servlet
2. Testing a servlet that uses packages
3. Testing a servlet that uses packages and utility classes

Details on each step are given below.

Test 1: A Servlet That Does Not Use Packages

The first servlet to try is a basic one: no packages or utility (helper) classes. Rather than writing your own test servlet, you can just download HelloServlet.java into your development directory, compile it, and copy the .class file to install_dir/webapps/ROOT/WEB-INF/classes. Right-click on the link to download 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 some versions of Tomcat (including Tomcat 6.0.10), the system doesn't create the classes 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 Apache Tomcat version already contains the classes directory and already has the sample servlets.

If you get compilation errors, go back and check your CLASSPATH settings (see the section on this topic)--you most likely erred in listing the location of the JAR files that contains the servlet and JSP classes. 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 or forgot to enable the invoker servlet.

Test 2: A Servlet That Uses Packages

The second servlet to try is one that uses packages but not utility classes. Again, rather than writing your own test, you can download and install HelloServlet2.java. Since this servlet is in the coreservlets package, it should go in the coreservlets directory both during development and when deployed to the server. Once you compile HelloServlet2.java, put HelloServlet2.class in install_dir/webapps/ROOT/WEB-INF/classes/coreservlets. For now, you can simply copy (not move!) the coreservlets subdirectory from the development directory to install_dir/webapps/ROOT/WEB-INF/classes. An upcoming section will provide some other options for the deployment process.

Once you have placed the servlet in the proper directory, access it with the URL http://localhost/servlet/coreservlets.HelloServlet2. You should get a simple HTML page that says "Hello (2)". If the first test succeeded but this test failed, 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 coreservlets subdirectory).

Test 3: A Servlet That Uses Packages and Utilities

The final servlet you should test to verify the configuration of your server and development environment is one that uses both packages and utility classes. HelloServlet3.java is a servlet in the coreservlets 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 coreservlets package, they should go in the coreservlets directory.

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 a user-defined 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.

Once you compile HelloServlet3.java (which will automatically cause ServletUtilities.java to be compiled), copy (don't move!) the entire coreservlets subdirectory from your development location to install_dir/webapps/ROOT/WEB-INF/classes. Then, access the servlet with the URL http://localhost/servlet/coreservlets.HelloServlet3 (again, note that it is a dot, not a slash, between the package name and the servlet name). You should get a simple HTML page that says "Hello (3)".