Home | Download | PDF | API | FAQ | Search | Feedback | History

Basic Requirements of a JavaServer Faces Application

In addition to configuring your application, you must satisfy other requirements of JavaServer Faces applications, including properly packaging all the necessary files and providing a deployment descriptor. This section describes how to perform these administrative tasks.

JavaServer Faces applications must be compliant with the Servlet specification, version 2.3 (or later) and the JavaServer Pages specification, version 1.2 (or later). All applications compliant with these specifications are packaged in a WAR file, which must conform to specific requirements in order to execute across different containers. At a minimum, a WAR file for a JavaServer Faces application must contain the following:

A web application deployment descriptor, called web.xml, to configure resources required by a web application
A specific set of JAR files containing essential classes
A set of application classes, JavaServer Faces pages, and other required resources, such as image files
An application configuration resource file, which configures application resources

The WAR file typically has this directory structure:

index.html
JSP pages
WEB-INF/
   web.xml
   faces-config.xml
   tag library descriptors (optional)
   classes/
      class files
     Properties files
   lib/
      JAR files 

The web.xml file (or deployment descriptor), the set of JAR files, and the set of application files must be contained in the WEB-INF directory of the WAR file. Usually, you will want to use the asant build tool to compile the classes. You will use deploytool to package the necessary files into the WAR and deploy the WAR file.

The asant tool and deploytool are included in the Application Server. You configure how the asant build tool builds your WAR file via a build.xml file. Each example in the tutorial has its own build file, to which you can refer when creating your own build file.

Configuring an Application Using deploytool

Web applications are configured via elements contained in the web application deployment descriptor. The deploytool utility generates the descriptor when you create a WAR and adds elements when you create web components and associated classes. You can modify the elements via the inspectors associated with the WAR.

The deployment descriptor for a JavaServer Faces application must specify certain configurations, which include the following:

The servlet used to process JavaServer Faces requests
The servlet mapping for the processing servlet
The path to the configuration resource file if it is not located in a default location

The deployment descriptor can also specify other, optional configurations, including:

Specifying where component state is saved
Restricting Access to pages containing JavaServer Faces tags
Turning on XML validation
Verifying custom objects

This section gives more details on these configurations and explains how to configure them in deploytool.

Identifying the Servlet for Life Cycle Processing

One requirement of a JavaServer Faces application is that all requests to the application that reference previously saved JavaServer Faces components must go through FacesServlet. A FacesServlet instance manages the request processing life cycle for web applications and initializes the resources required by JavaServer Faces technology. To comply with this requirement, follow these steps.

While using the Edit Contents dialog box from the Web Component wizard, add the jsf-api.jar file from <J2EE_HOME>/lib/ to your WAR file. This JAR file is needed so that you have access to the FacesServlet instance when configuring your application with deploytool.
In the Choose Component Type dialog box of the Web Component wizard, select the Servlet radio button and click Next.
Select FacesServlet from the Servlet Class combo box.
In the Startup Load Sequence Position combo box, enter 1, indicating that the FacesServlet should be loaded when the application starts. Click Finish.
Select the FacesServlet web component from the tree.
Select the Aliases tab and click Add.
Enter a path in the Aliases field. This path will be the path to FacesServlet. Users of the application will include this path in the URL when they access the application. For the guessNumber application, the path is /guess/*.

Before a JavaServer Faces application can launch the first JSP page, the web container must invoke the FacesServlet instance in order for the application life cycle process to start. The application life cycle is described in the section The Life Cycle of a JavaServer Faces Page.

To make sure that the FacesServlet instance is invoked, you provide a mapping to it using the Aliases tab, as described in steps 5 through 7 above.

The mapping to FacesServlet described in the foregoing steps uses a prefix mapping to identify a JSP page as having JavaServer Faces content. Because of this, the URL to the first JSP page of the application must include the mapping. There are two ways to accomplish this:

The page author can include an HTML page in the application that has the URL to the first JSP page. This URL must include the path to FacesServlet, as shown by this tag, which uses the mapping defined in the guessNumber application:

<a href="guess/greeting.jsp">

Users of the application can include the path to FacesServlet in the URL to the first page when they enter it in their browser, as shown by this URL that accesses the guessNumber application:

http://localhost:8080/guessNumber/guess/greeting.jsp

The second method allows users to start the application from the first JSP page, rather than start it from an HTML page. However, the second method requires users to identify the first JSP page. When you use the first method, users need only enter

http://localhost:8080/guessNumber 

You could define an extension mapping, such as *.faces, instead of the prefix mapping /guess/*. If a request comes to the server for a JSP page with a .faces extension, the container will send the request to the FacesServlet instance, which will expect a corresponding JSP page of the same name to exist containing the content. For example, if the request URL is http://localhost/bookstore6/bookstore.faces, FacesServlet will map it to the bookstore.jsp page.

Specifying a Path to an Application Configuration Resource File

As explained in Application Configuration Resource File, an application can have multiple application configuration resource files. If these files are not located in the directories that the implementation searches by default or the files are not named faces-config.xml, you need to specify paths to these files. To specify paths to the files using deploytool follow these steps:

Select the WAR from the tree.
Select the Context tabbed pane and click Add.
Enter javax.faces.application.CONFIG_FILES in the Coded Parameter field.
Enter the path to your application configuration resource file in the Value field. For example, the path to the guessNumber application's application configuration resource file is /WEB-INF/faces-config.xml
Repeat steps 2 through 4 for each application configuration resource file that your application contains.

Specifying Where State Is Saved

When implementing the state-holder methods (described in Saving and Restoring State), you specify in your deployment descriptor where you want the state to be saved, either client or server. You do this by setting a context parameter with deploytool:

While running deploytool, select the web application from the tree.
Select the Context tabbed pane and click Add.
Enter javax.faces.STATE_SAVING_METHOD in the Coded Parameter field.
Enter either client or server in the Value field, depending on whether you want state saved in the client or the server.

If state is saved on the client, the state of the entire view is rendered to a hidden field on the page. The JavaServer Faces implementation saves the state on the client by default. Duke's Bookstore saves its state in the client.

Restricting Access to JavaServer Faces Components

In addition to identifying the FacesServlet instance and providing a mapping to it, you should also ensure that all applications use FacesServlet to process JavaServer Faces components. You do this by setting a security constraint:

Select your WAR file from the tree.
Select the Security tabbed pane.
Click Add Constraints and enter Restricts Access to JSP Pages in the Security Constraints field.
Click Add Collections and enter Restricts Access to JSP Pages in the Web Resource Collections field.
Click Edit Collections.
In the Edit Collections of Web Resource Collections dialog box, click Add URL Pattern and enter the path to a JSP page to which you want to restrict access, such as /response.jsp.
Continue to click Add URL Pattern again, and enter paths to all the JSP pages in your application and click OK.

Turning On Validation of XML Files

Your application contains one or more application configuration resource files written in XML. You can force the JavaServer Faces implementation to validate the XML of these files by setting the validateXML flag to true:

Select your WAR file from the tree.
Select the Context tabbed pane and click Add.
Enter com.sun.faces.validateXml in the Coded Parameter field.
Enter true in the Value field. The default value is false.

Verifying Custom Objects

If your application includes custom objects, such as components, converters, validators, and renderers, you can verify when the application starts that they can be created. To do this, you set the verifyObjects flag to true:

Select your WAR file from the tree
Select the Context tabbed pane and click Add.
Enter com.sun.faces.verifyObjects in the Coded Parameter field.
Enter true in the Value field. The default value is false.

Normally, this flag should be set to false during development because it takes extra time to check the objects.

Including the Required JAR Files

JavaServer Faces applications require several JAR files to run properly. These JAR files are as follows:

jsf-api.jar (contains the javax.faces.* API classes)
jsf-impl.jar (contains the implementation classes of the JavaServer Faces implementation)
jstl.jar (required to use JSTL tags and referenced by JavaServer Faces implementation classes)
standard.jar (required to use JSTL tags and referenced by JavaServer Faces reference implementation classes)
commons-beanutils.jar (utilities for defining and accessing JavaBeans component properties)
commons-digester.jar (for processing XML documents)
commons-collections.jar (extensions of the Java 2 SDK Collections Framework)
commons-logging.jar (a general-purpose, flexible logging facility to allow developers to instrument their code with logging statements)

The jsf-api.jar and the jsf-impl.jar files are located in <J2EE_HOME>/lib. The jstl.jar file is bundled in appserv-jstl.jar. The other JAR files are bundled in the appserv-rt.jar, also located in <J2EE_HOME>/lib/.

When packaging and deploying your JavaServer Faces application with deploytool, you do not need to package any of the JAR files, except the jsf-api.jar file, with your application. The jsf-api.jar file must be packaged with your application so that you have access to the FacesServlet instance and can configure the mapping for it.

Including the Classes, Pages, and Other Resources

When packaging web applications using deploytool, you'll notice that deploytool automatically packages many of your web application's files in the appropriate directories in the WAR file. All JSP pages are placed at the top level of the WAR file. The TLD files and the web.xml that deploytool creates are packaged in the WEB-INF directory. All packages are stored in the WEB-INF/classes directory. All JAR files are packaged in the WEB-INF/lib directory. However, deploytool does not copy faces-config.xml to the WEB-INF directory as it should. Therefore, when packaging your web applications, you need to drag faces-config.xml to the WEB-INF directory.

All of the material in The J2EE(TM) 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.