4.2. Structure of a Web Application

The process of registering a Web application is not standardized; it frequently involves server-specific configuration files or user interfaces. However, the Web application itself has a completely standardized format and is totally portable across all Web or application servers that support version 2.2 or later of the servlet specification. The top-level directory of a Web application is simply a directory with a name of your choosing. Within that directory, certain types of content go in designated locations. This section provides details on the type of content that is placed in various locations; it also gives a sample Web application layout.

Locations for Various File Types

Quick summary: JSP pages and other normal Web documents go in the top-level directory, unbundled Java classes go in the WEB-INF/classes directory, JAR files go in WEB-INF/lib, and the web.xml file goes in WEB-INF. Figure 4-9 shows a representative example. For details or a more explicit sample hierarchy, check out the following subsections.

JSP Pages

JSP pages should be placed in the top-level Web application directory or in a subdirectory with any name other than WEB-INF or META-INF. Servers are prohibited from serving files from WEB-INF or META-INF to the user. When you register a Web application (see Section 4.1), you tell the server the URL prefix that designates the Web app and define where the Web app directory is located. It is common, but by no means mandatory, to use the name of the main Web application directory as the URL prefix. Once you register a prefix, JSP pages are then accessed with URLs of the form http://hostname/webAppPrefix/filename.jsp (if the pages are in the top-level directory of the Web application) or http://hostname/webAppPrefix/subdirectory/filename.jsp (if the pages are in a subdirectory).

It depends on the server whether a default file such as index.jsp can be accessed with a URL that specifies only a directory (e.g., http://hostname/webAppPrefix/) without the developer first making an entry in the Web app’s WEB-INF/web.xml file. If you want index.jsp to be the default filename, I strongly recommend that you make an explicit welcome-file-list entry in your Web app’s web.xml file. For example, the following web.xml entry specifies that if a URL gives a directory name but no filename, the server should try index.jsp first and index.html second. If neither is found, the result is server specific (e.g., a directory listing).

<welcome-file-list> 
  <welcome-file>index.jsp</welcome-file> 
  <welcome-file>index.html</welcome-file> 
</welcome-file-list> 

For details, see Section 5.7 (Specifying Welcome Pages).

HTML Documents, Images, and Other Regular Web Content

As far as the servlet and JSP engine is concerned, HTML files, GIF and JPEG images, style sheets, and other Web documents follow exactly the same rules as do JSP pages. They are placed in exactly the same locations and accessed with URLs of exactly the same form. In deployment scenarios, however, a servlet or JSP engine such as JRun, ServletExec, Tomcat, or Resin is often plugged into a regular Web server like Microsoft IIS, Apache, or older versions of the Netscape Web server. In such a case, the regular Web server usually serves regular Web pages more quickly than does the servlet and JSP engine. So, if your static Web documents are accessed extremely frequently, you are faced with a portability vs. performance trade-off. Putting the static documents in the Web application hierarchy lets you move the servlets, the JSP pages, and the static documents from server to server with a minimum of changes. Putting the static resources in the regular Web server’s hierarchy increases performance but requires server-specific changes when you move the Web app to another server. Fortunately, this issue is important only for the highest-traffic pages.

It depends on the server whether a default file such as index.html can be accessed with a URL that specifies only a directory (e.g., http://hostname/webAppPrefix/>) without the developer first making an entry in the Web app’s WEB-INF/web.xml file. If you want index.html to be the default filename, I recommend that you make an explicit welcome-file-list entry in web.xml. For details, see Section 5.7 (Specifying Welcome Pages).

Servlets, Beans, and Helper Classes (Unbundled)

Servlets and other.class files are placed either in WEB-INF/classes or in a subdirectory of WEB-INF/classes that matches their package name. During development, don’t forget that your CLASSPATH should include the classes directory. The server already knows about this location, but your development environment does not. In order to compile servlets that are in packages, the compiler needs to know the location of the top-level directory of your package hierarchy. See Section 1.6 (Set Up Your Development Environment) for details.

The default way to access servlets is with URLs of the form http://hostname/webAppPrefix/servlet/ServletName or http://hostname/webAppPrefix/servlet/packageName.ServletName. To designate a different URL, you use the servlet-mapping element in the web.xml deployment descriptor file that is located within the WEB-INF directory of the Web application. See Section 5.3 (Assigning Names and Custom URLs) for details.

Servlets, Beans, and Helper Classes (Bundled in JAR Files)

If the servlets or other.class files are bundled inside JAR files, then the JAR files should be placed in WEB-INF/lib. If the classes are in packages, then within the JAR file they should be in a directory that matches their package name.

Deployment Descriptor

The deployment descriptor file, web.xml, should be placed in the WEB-INF subdirectory of the main Web application directory. For details on using web.xml, see Chapter 5 (Controlling Web Application Behavior with web.xml). Note that a few servers (e.g., Tomcat) have a global web.xml file that applies to all Web applications. That file is entirely server specific; the only standard web.xml file is the per-application one that is placed within the WEB-INF directory of the Web app.

Tag Library Descriptor Files

TLD files can be placed almost anywhere within the Web application. However, I recommend that you put them in a tlds directory within WEB-INF. Grouping them in a common directory (e.g., tlds) simplifies their management. Placing that directory within WEB-INF prevents end users from retrieving them. JSP pages, however, can access TLD files that are in WEB-INF. They just use a taglib element as follows

<%@ taglib uri="/WEB-INF/tlds/myTaglibFile.tld"...%> 

Since it is the server, not the client, that accesses the TLD file in this case, the prohibition that content inside of WEB-INF is not Web accessible does not apply.

WAR Manifest File

When you create a WAR file (see Section 4.3), a MANIFEST.MF file is placed in the META-INF subdirectory. Normally, the jar utility automatically creates MANIFEST.MF and places it in the META-INF directory, and you ignore it if you unpack the WAR file. Occasionally, however, you modify MANIFEST.MF explicitly (see Section 4.4), so it is useful to know where it is stored.

Sample Hierarchy

Suppose you have a Web application that is in a directory named widgetStore and is registered (see Section 4.1) with the URL prefix /widgetStore. Following is one possible structure for the Web app.

widgetStore/orders.jsp

widgetStore/specials.html

These files would be accessed with the URLs http://hostname/widgetStore/orders.jsp and http://hostname/widgetStore/specials.html, respectively.

widgetStore/info/company-profile.jsp

widgetStore/info/contacts.html

These files would be accessed with the URLs http://hostname/widgetStore/info/company-profile.jsp and http://hostname/widgetStore/info/contacts.html, respectively.

widgetStore/founder.jpg

Since the orders.jsp and specials.html files are in the same directory as this file, they would use a simple relative URL to refer to the image, as below.

<IMG SRC="founder.jpg" ...> 

Since company-profile.jsp and contacts.html are in a lower-level directory, they would use a relative URL that contains “..”, as below.

<IMG SRC="../founder.jpg" ...> 

But what if you want to support the flexibility of moving a JSP page to a different directory without changing the URL that refers to the image? Or what if a servlet wants to refer to this image? This is slightly more complicated; see Section 4.5 (Handling Relative URLs in Web Applications) for a discussion of the problem and its solutions.

widgetStore/images/button1.gif

Since the orders.jsp and specials.html files are in the parent directory of this file, they would refer to the image by using a relative URL that contains the directory name, as below.

<IMG SRC="images/button1.gif" ...> 

Since company-profile.jsp and contacts.html are in a sibling directory, they would use a relative URL that contains “..” and the directory name, as below.

<IMG SRC="../images/founder.gif" ...> 

Again, if you want to be able to move the JSP page without changing the image URL or if you want to refer to the image from a servlet, things are a bit complicated. See Section 4.5 (Handling Relative URLs in Web Applications) for a discussion of the problem and its solutions.

widgetStore/WEB-INF/tlds/widget-taglib.tld

This tag library descriptor file would be referenced from a JSP page by use of a taglib element as follows.

<%@ taglib uri="/WEB-INF/tlds/widget-taglib.tld"...%> 

Note that the JSP page that uses this TLD file can be located anywhere within the widgetStore Web app directory. Note, too, that there is no potential problem regarding relative URLs as there is with images (as mentioned in the previous two subsections). Also note that it is legal (recommended, in fact) to place the tlds directory within the WEB-INF directory, even though the WEB-INF directory is not accessible to Web clients. It is legal because the server, not the client, retrieves the TLD file.

widgetStore/WEB-INF/web.xml

This is the deployment descriptor. It is not accessible by Web clients; it is used only by the server itself. See Chapter 5 (Controlling Web Application Behavior with web.xml) for details on its use.

widgetStore/WEB-INF/classes/CheckoutServlet.class

This packageless servlet would be accessed either with the URL http://hostname/widgetStore/servlet/CheckoutServlet or with a custom URL that starts with http://hostname/widgetStore/. The web.xml file would define the custom URL; see Section 5.3 (Assigning Names and Custom URLs) for details.

widgetStore/WEB-INF/classes/cart/ShowCart.class

This servlet from the cart package would be accessed either with the URL http://hostname/widgetStore/servlet/cart.ShowCart or with a custom URL that starts with http://hostname/widgetStore/. Again, the web.xml file would define the custom URL. Remember that dots, not slashes, separate package names from class names in URLs that refer to servlets. So be sure to use http://hostname/widgetStore/servlet/cart.ShowCart, not http://hostname/widgetStore/servlet/cart/ShowCart.

widgetStore/WEB-INF/lib/Utils.jar

The Utils.jar file could contain utility classes used by the servlets and by various JSP pages. If the classes are in packages, they should be in subdirectories within the JAR file, and the servlets or JSP pages that use them must utilize import statements.