[ Team LiB ] Previous Section Next Section

20.1 Servlet Setup

In order to run the examples in this chapter, you need the following:

  • A web server to host the examples.

  • A servlet container, or servlet engine, which the web server uses to run the servlets. In order to run the JSP examples, your servlet container must also support JSP pages. Note that most of the JSP examples in this chapter rely on the new features of JSP 2.0. Servlet containers sometimes invert the architecture and include a web server.

  • An implementation of the Java Standard Tag Library, so that the JSP examples that use those tag libraries can run correctly.

  • The class files for the servlet API, so you can compile servlet classes.

  • A deployment descriptor that tells your servlet container how to map URLs to servlet classes.

This list looks more daunting than it actually is, as you'll see in the sections that follow.

20.1.1 The Servlet Container

Just as there are many web servers available, there are numerous servlet containers to choose from. I use and recommend Tomcat, an open source product of the Jakarta project. Jakarta is itself a project of the Apache Software Foundation, the organization that produces the open source Apache web server. Tomcat has benefited from substantial contributions by Sun, and the official reference implementations for Sun's Servlet and JSP specifications are built upon the Tomcat codebase. The core of Tomcat is a servlet and JSP container that can be used with the Apache web server, as well as with various commercial web servers. For servlet development, however, Tomcat also includes a powerful pure-Java web server you can run on your local machine.

If you choose to use Tomcat, you can download it from http://jakarta.apache.org/tomcat. At the time of this writing, the current version of Tomcat is 5.x, which implements the Servlet 2.4 and JSP 2.0 specifications. The examples in this chapter were tested with Tomcat 5 and its built-in web server.

Servlets are part of the J2EE platform, and if you have a J2EE 1.4 implementation, then you already have a servlet container (probably Tomcat) suitable for use with the examples in this chapter. This chapter assumes, however, that you have the J2SE platform and are augmenting it with a servlet container, without adopting the entire J2EE platform.

Installing, configuring, and starting a servlet container is beyond the scope of this chapter; you'll need to read the appropriate documentation supplied with your container. If you use Tomcat, however, the process may be as simple as unpacking the download archive and running a startup script from the bin/ directory. By default, the Tomcat web server listens on port 8080, so once you have started Tomcat, point your web browser at http://localhost:8080/ or http://127.0.0.1:8080/. If everything is working correctly, you should see an introductory page with information about Tomcat. Of course, you should read the instructions that come with your version for full details.

If you already have a working web server and servlet container, go ahead and use it (after you've read the documentation carefully). Note, however, that the examples in this chapter are written to the Servlet 2.4 and JSP 2.0 specifications. If your servlet container does not support these versions of the specifications, some of the examples (particularly the JSP examples) will not work.

20.1.2 Compiling Servlets

In order to compile servlets, you need the class files for the servlet API. If you do not have J2EE installed, you'll need to get these files from your servlet container. With Tomcat 5, they are located in common/lib/servlet-api.jar. You need this JAR file to be able to compile the classes in this chapter. Either edit your CLASSPATH environment variable to include the file or, more simply, place a copy of the file in the jre/lib/ext/ directory of your Java SDK, where the Java VM can find it automatically. Once you have done this, you can compile servlet classes with javac, just as you would compile other Java classes.

20.1.3 Using Tag Libraries

Some of the JSP pages in this chapter use the core module of the Java Standard Tag Library (JSTL). They declare that they do this with a line like the following:

<%@taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>

The URI in this line is the official identifier for the core module of Version 1.1 of the JSTL. To make it work, you'll need the JAR files that implement JSTL 1.1. These JAR files include the implementation classes, as well as the c.tld tag library descriptor file that describes the tags in the core module. (It is this c.tld file that specifies the URI that officially identifies the library.)

At the time of this writing, the JSTL 1.1 is in the final stages of development. It is not bundled with Tomcat, and there does not yet appear to be a stable home for releases of the library. By the time you read this, the situation ought to be resolved, however. If you have a J2EE 1.4 environment, you should already have a JSTL 1.1 implementation. If an implementation is not included with your servlet container, you should be able to find one at http://jakarta.apache.org/taglibs or from http://java.sun.com/products/jsp/jstl. At the time of this writing, the JSTL implementation takes the form of two JAR files, named jstl.jar and standard.jar. You do not need to put these in the jre/lib/ext directory, since you never need to compile against them. Instead, you can make them available just to your servlet container. For example, with Tomcat 5, place them in the common/lib/ directory of the Tomcat installation directory.

20.1.4 Installing and Running Servlets

Once you've obtained and set up a servlet container and the servlet API and taglib JAR files you'll need, you're ready to deploy and run your servlets. Version 2.2 of the Servlet specification standardized servlet deployment, so the process is similar with all servlet containers. Cooperating sets of servlets and the auxiliary files they require are bundled into a "web application" that is deployed into the servlet container. Most web applications include a file named WEB-INF/web.xml that provides all the necessary servlet deployment details (simple web applications that consist solely of static HTML pages and JSP pages do not require a web.xml file). For ease of distribution and deployment, web applications may be packaged into WAR archives using the JAR archive format. We'll discuss the directory hierarchy for a web application and the contents of the web.xml file at the end of this chapter. For now, however, we'll consider just the details you need to run the examples as you read the chapter.

The Java classes in this chapter are in a package named je3.servlet, and the online archive of examples for this book includes those classes and other files from this chapter located in and beneath the directory je3/servlet/. The files are organized in a directory hierarchy that is close to the hierarchy required for servlet deployment. To bundle all the examples from the chapter into a single web application, follow these steps:

# Compile all classes and put the class files under WEB-INF/classes
# This creates WEB-INF/classes/je3/servlet/*.class
javac -d WEB-INF/classes/ *.java

# Use the jar tool to bundle all necessary files into the je3.war file
# Note that this is a single command line broken across multiple lines.
jar cMf je3.war \
        index.html *.jsp *.jspx \
        ListManager/*.jsp \
        WEB-INF/web.xml \
        WEB-INF/tags/*.tag \
        WEB-INF/classes

These javac and jar commands create a file named je3.war, which should contain everything necessary to run all the examples from the chapter. Deploy this file to your servlet container as directed in its documentation. For Tomcat, you simply need to copy the je3.war file into the webapps/ directory in the Tomcat distribution. If Tomcat is running, it should automatically notice and deploy the new web application, and you can force it to do so by stopping and restarting. (You can also deploy web applications in Tomcat using the Tomcat Manager web application included with Tomcat, although running the manager requires some additional Tomcat configuration steps.) If you modify the servlets, you'll need to rebuild the WAR file and redeploy it. Before doing this, you'll need to delete the old WAR file and the unpacked version that Tomcat creates in the webapps/je3/ directory.

Note that you do not have to create a WAR file to deploy a web application: you can also deploy your working directory. If you want to edit and make changes to the examples in this chapter, it may be easiest to recursively copy the contents of the je3/servlets/ directory to the Tomcat webapps/je3 directory and make that your working directory.

With WAR archives, the name of the WAR file is used as a URL prefix for all the servlets and other files in the archive. For example, suppose you deploy the je3.war archive in Tomcat's webapps/ directory. The WAR archive contains a file named index.html at the root level, and (assuming that Tomcat is deployed locally) the URL you use to access this file is:

http://localhost:8080/je3/index.html

Servlet container configuration and web application deployment can be tricky, and this chapter cannot provide a step-by-step tutorial on the process. If the URL just shown does not work for you after building and deploying je3.war, you'll want to read your servlet container documentation thoroughly, examine any log files it generates, or consult an experienced servlet guru!

    [ Team LiB ] Previous Section Next Section