JavaServer Faces

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.

Warning

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).