4.3 The Web Application Directory Structure

A web application typically consists of a structured hierarchy of directories. Although the Servlet specification does not require servlet containers to support a hierarchical structure, it recommends that they do so, and most, if not all, comply with this recommendation. The root directory of the hierarchy serves as the document root for the web application. As discussed earlier, requests made using a web application's root context path are served out of the directory for that web application.

Within the web application directory hierarchy, a special directory named WEB-INF must be created. This directory is the repository for meta-information relating to the web application. It is a private directory; no resource within it is accessible to a client. However, the resources in the WEB-INF directory are visible to servlets and Java classes that reside within the web application.

Because the Servlet specification requires that the WEB-INF directory should not be visible to a web client, this is an ideal location for files and other resources that you do not want to expose outside the application. Web application resources such as XML configuration files and other private application resources should be placed within this directory. As you'll see later in this chapter, the Struts configuration file is also normally located here.

The WEB-INF directory is where the deployment descriptor for the web application should be placed. The deployment descriptor is covered in detail in the next section.

There are two special directories underneath WEB-INF that get special treatment by the web container. The WEB-INF/classes directory is used for servlets and utility classes that can be used by the web application. If the Java classes are scoped within a Java package, the classes directory must contain the proper subdirectories that match the package name. For example, suppose you had a Java servlet named com.oreilly.struts.framework.StorefrontController for a web application named Storefront. The StorefrontController.class file would have to be placed in the framework directory as shown in Figure 4-2.

Figure 4-2. Java classes must be in the proper directories

The other special subdirectory is WEB-INF/lib . This subdirectory is where Java Archive (JAR) files can be deployed and will be picked up by the class loader for the web application.

Based on the 2.3 Servlet specification, the web application class loader must load classes first from the WEB-INF/classes directory, then from library JARs located in the WEB-INF/lib directory.

Other than these special requirements, the directory structure for a web application is left up to the developer. It should be based on the functional and nonfunctional needs of the application. With smaller web applications, files and resources may be combined into a few common directories. For larger web applications, however, each component may need to have a separate directory underneath the web application root directory. This will allow for easier development and maintenance. Figure 4-3 shows the directory structure for the Storefront web application.

Figure 4-3. The directory structure for the Storefront web application

Here are a few things to consider when choosing the directories for your Struts application:

· Keep optional components separate from required ones so that partial deployment will be easier to support.

· Take into account the size of the development team and the necessity of preventing file and checkout contention.

· Be careful to consider file and resource dependencies, and make sure to take advantage of reuse and include files.

· Make the directory structure and package-naming convention as intuitive and self-evident as possible.

For many containers, directory and file names are case-sensitive. Make sure that you are consistent with whatever case convention you choose for your application.

4.3.1 Web Application Archive Files

Web applications are often packaged as web archive (WAR) files, which must have an extension of .war. For example, if we packaged the Storefront application as a WAR file, it would be named storefront.war. When a web application is packaged as a WAR file, it must maintain its relative directory structure, as illustrated in Figure 4-3.

Although there are some subtle differences, a WAR file is really just a ZIP file with a different extension. In fact, you can also use a ZIP utility application such as WinZip to create and unpack WAR files.

Web containers are capable of loading a WAR file and exploding the resources back into the structure required by the container. The WAR file format is most useful when you need to distribute an application. It also can be part of a much larger distributable file called an enterprise archive (EAR) file. Chapter 16 discusses the best practices of packaging your application using these different formats.