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 web.xml file. 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 web.xml (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 Sun Java System Application Server Platform Edition 8. You configure how the asant build tool builds your WAR file via a build.xml file. Each example in the download 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

Specifying a 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 the FacesServlet. The FacesServlet 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, copy 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 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 the 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 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 is invoked, you must include the path to the FacesServlet in the URL to the first JSP page. You define the path in the url-pattern element nested inside the servlet-mapping element of the web.xml file.

The mapping to the 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 the 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 the 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

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, 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, the FacesServlet will map 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:

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.

The context parameter specifies that state must be saved in the client. 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 server by default.

Restricting Access to JavaServer Faces Components

In addition to identifying the FacesServlet and providing a mapping to it, you should also ensure that all applications use the 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 the first JSP page in your application, such as /greeting.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 is bundled in the 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 and can configure the mapping for it.

Including the Classes, Pages, and Other Resources

All application classes and properties files should be copied into the WEB-INF/classes directory of the WAR file during the build process. JSP pages should be at the top level of the WAR file. The web.xml, faces-config.xml, and extra TLD files should be in the WEB-INF directory. Other resources, such as images, can be at the top level or in a separate directory of the WAR file.

You can apply the instructions for packaging the Duke's Bookstore application using deploytool when you build your own JavaServer Faces application.