Recipe 1.4 Packaging Servlets and JSPs

Problem

You want to set up a directory structure for packaging and creating a Web ARchive (WAR) file for servlets and JSPs.

Solution

Set up a directory structure in your filesystem, then use the jar tool or Ant to create the WAR.

Discussion

Except in the rarest of circumstances, you'll usually develop a servlet or JSP as part of a web application. It is relatively easy to set up a directory structure on your filesystem to hold web-application components, which include HTML files, servlets, JSPs, graphics, JAR libraries, possibly movies and sound files, as well as XML configuration files (such as the deployment descriptor; see Recipe 1.5).

The simplest organization for this structure is to create the exact layout of a web application on your filesystem, then use the jar tool to create a WAR file.

A WAR file is like a ZIP archive. You deploy your web application into a web container by deploying the WAR. See Chapter 2 for recipes about various deployment scenarios.

The web application structure involving the WEB-INF subdirectory is standard to all Java web applications and specified by the servlet API specification (in the section named Web Applications. Here is what this directory structure looks like, given a top-level directory name of myapp:

/myapp
    /images
    /WEB-INF
        /classes
        /lib

The servlet specification specifies a WEB-INF subdirectory and two child directories, classes and lib. The WEB-INF subdirectory contains the application's deployment descriptor, named web.xml. The JSP files and HTML live in the top-level directory (myapp). Servlet classes, JavaBean classes, and any other utility classes are located in the WEB-INF/classes directory, in a structure that matches their package name. If you have a fully qualified class name of com.myorg.MyServlet, then this servlet class must be located in WEB-INF/classes/com/myorg/MyServlet.class.

The WEB-INF/lib directory contains any JAR libraries that your web application requires, such as database drivers, the log4j.jar, and the required JARs for using the JavaServer Pages Standard Tag Library (see Chapter 23).

Once you are ready to test the application in WAR format, change to the top-level directory. Type the following command, naming the WAR file after the top-level directory of your application. These command-line phrases work on both Windows and Unix systems (I used them with Windows NT 4 and Mac OS X 10.2):

jar cvf myapp.war .

Don't forget the final dot (.) character, which specifies to the jar tool to include the current directory's contents and its subdirectories in the WAR file. This command creates the myapp.war file in the current directory.

The WAR name becomes the application name and context path for your web application. For example, myapp.war is typically associated with a context path of /myapp when you deploy the application to a web container.

If you want to view the contents of the WAR at the command line, type this:

jar tvf alpine-final.war

If the WAR file is very large and you want to view its contents one page at a time, use this command:

jar tvf alpine-final.war |more

Here is example output from this command:

H:\classes\webservices\finalproj\dist>jar tvf alpine-final.war
     0 Mon Nov 18 14:10:36 EST 2002 META-INF/
    48 Mon Nov 18 14:10:36 EST 2002 META-INF/MANIFEST.MF
   555 Tue Nov 05 17:08:16 EST 2002 request.jsp
   914 Mon Nov 18 08:53:00 EST 2002 response.jsp
     0 Mon Nov 18 14:10:36 EST 2002 WEB-INF/
     0 Mon Nov 18 14:10:36 EST 2002 WEB-INF/classes/
     0 Tue Nov 05 11:09:34 EST 2002 WEB-INF/classes/com/
     0 Tue Nov 05 11:09:34 EST 2002 WEB-INF/classes/com/parkerriver/
     CONTINUED...

Many development teams are using Ant to compile and create WAR files for their servlets and JSPs. Recipe 2.6 describes using Ant for developing and updating web applications.

I jumpstart your progress toward that recipe by showing the kind of directory structure you might use for a comprehensive web application, one that contains numerous servlets, JSPs, static HTML files, as well as various graphics and multimedia components. When using Ant to build a WAR file from this kind of directory structure, you can filter out the directories that you do not want to include in the final WAR, such as the top-level src, dist, and meta directories.

myapp
    /build
    /dist
    /lib
    /meta
    /src
    /web
            /images
            /multimedia
    /WEB-INF
            /classes
            /lib
            /tlds
            /jspf

The WEB-INF/tlds and WEB-INF/jspf optional directories may contain Tag Library Descriptor files and JSP fragments (chunks of JSPs that are designed to be included in other JSPs, such as server-side includes), respectively.

Recipe 1.4 Packaging Servlets and JSPs

Problem

Solution

Discussion

See Also