4.2 Web Application Deployment and Runtime Environment

A JSF-based application consists of a lot of different pieces: user interface template files (e.g., JSP pages), static HTML files and image files, as well as class files for business logic, custom components, and so on. All pieces are packaged and deployed as a web application archive (WAR). The servlet specification describes the internal structure of the WAR and an application deployment descriptor containing configuration and metadata for the application.

The WAR structure contains directories for files accessed directly by browsers, such as HTML files and JSP pages, and directories for configuration files and classes seen only by the application. Here's part of the WAR structure for the example application we'll develop in this book:

/cover.gif

/index.html

/expense/reports.jsp

...

/WEB-INF/web.xml

/WEB-INF/classes/JSPSourceServlet.class

...

/WEB-INF/lib/commons-logging.jar

/WEB-INF/lib/jsf-api.jar

/WEB-INF/lib/jsf-ri.jar

/WEB-INF/lib/jsfbook.jar

...

The top level in this structure is the document root for all public web application files; in other words, all the files requested directly by the browser. For instance, the index.html file is a page with links to all book examples, and the expense/reports.jsp file is a JSP page used as a template in an example application.

The WEB-INF directory is the root for internal application files and it's inaccessible to a browser. This directory contains the application deployment descriptor (web.xml), as well as subdirectories for other types of resources, such as Java class files and configuration files. Two WEB-INF subdirectories have special meaning: lib and classes. All application class files must be stored in these two directories. The lib directory is for Java archive (JAR) files (compressed archives of Java class files). Class files that aren't packaged in JAR files must be stored in the classes directory, which can be convenient during development. The files must be stored in subdirectories of the classes directory that mirror their package structure, following the standard Java conventions. For instance, a class in a package named com.mycompany.expense.model must be stored in the WEB-INF/classes/com/mycompany/expense/model directory.

You can add other subdirectories under WEB-INF directory to organize the application files, but they have no special meaning except that they can't be accessed directly by a browser.

As with pretty much everything related to Java, directory and filenames in the web application structure are case-sensitive. If something doesn't work right, the first thing to check is that the WEB-INF directory is created with all caps, and that the case used for a page in the request URL matches exactly the case used in the filename. On a Windows platform, you may want to use a Command Prompt window and the DIR command to check this, because the names shown in the Windows Explorer tool adjusts the names and sometimes shows a directory name like WEB-INF as Web-inf.

A WAR file has a .war file extension and can be created with the Java jar command or a ZIP utility program, such as WinZip (the same file format is used for both JAR and ZIP files).

4.2.1 Web Containers and Servlet Contexts

The WAR file is deployed to what's called a web container. A web container provides the runtime environment for a Java web application. For instance, it translates request and response data between the raw protocol format and the Java object representations the web application works with and maintains shared resources (such as database connection pools and logfiles). All web containers provide tools for installing a WAR file, or a special directory where a WAR file is automatically picked up (such as the webapps directory in Tomcat). Most containers also support web applications deployed directly in a filesystem using the same file structure as is defined for the WAR file, which can be convenient during development.

There are many different types of web containers. Some containers are called add-ons, or plug-ins, and are used to add support for Java web applications to regular web servers (such as Apache and IIS). They can run in the same operating-system process as the web server or in a separate process. Other containers are standalone servers. A standalone server includes web server functionality to provide full support for HTTP in addition to the web application runtime environment. Containers can also be embedded in other servers, such as a climate-control system, to offer a web-based interface to the system. A container bundled as part of an application server typically distributes the execution over multiple hosts and can provide fail-over capabilities in case a host crashes.

Within the container, each web application is represented by a servlet context. Each context is self-contained and doesn't know anything about other applications running in the same container. References between the servlets and JSP pages in the application are commonly relative to the context path, and therefore are referred to as context-relative paths. By using context-relative paths within the application, a web application can be deployed using any context path.

The servlet context (i.e., the web application) is assigned a unique URI path prefix called the context path when the application is deployed. Figure 4-4 shows how the context path is used by the container to send the request to the right application.

Figure 4-4. Request dispatching based on context paths

In Figure 4-4, a human resources application is associated with the context path /hr and a sales tracking system with the context path /sales. This allows the web container to distinguish between the different applications it serves and dispatch requests like /sales/report?month=Jan to the sales-tracking application and /hr/emplist to the human-resources application.

The remaining URI path is then used within the selected context to decide how to process the request by comparing it to path-mapping rules defined by the application's deployment descriptor. Rules can be defined to send all requests starting with /report to one servlet and all requests starting with /forecast to another. Another type of mapping rule can say that one servlet handles all requests with paths ending with a specific file extension, such as .jsp. This is how JSP page requests are handled. Figure 4-4 shows how the different parts of the URI path are used to direct the request processing to the right resource through the container and context.