The Java EE 5 Tutorial

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.

Configuring an Application with a Deployment Descriptor

Web applications are configured using elements contained in the web application deployment descriptor. 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

• Encrypting state saved on the client

• Compressing state saved on the client

• Restricting access to pages containing JavaServer Faces tags

• Turning on XML validation

• Verifying custom objects

This section gives more details on these configurations. Where appropriate, it also describes how you can make these configurations using NetBeans IDE.

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.

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. The mapping to FacesServlet can be a prefix mapping, such as /guess/*, or an extension mapping, such as *.faces. The mapping is used 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.

In the case of prefix 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

In the case of extension mapping, 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.

If you are using NetBeans IDE, the time to map the FacesServlet instance is when you create your JavaServer Faces project with NetBeans IDE:

1. In NetBeans IDE, select File→New Project.

2. In the New Project dialog, select Web from the Categories tree.

3. Select Web Application from the Projects panel.

4. Click Next.

5. Fill out the information in the Name and Location screen of the wizard.

6. Click Next.

7. Select the JavaServer Faces check box in the Framewoks screen.

8. Enter the mapping, such as *.faces, to the FacesServlet instance in the Servlet URL Mapping field.

9. Click Finish.

After your project is open in NetBeans IDE, you can change the mapping to the FacesServlet instance by doing the following:

1. Expand the node of your project in the Projects pane.

2. Expand the Web Pages and WEB-INF nodes that are under the project node.

3. Double-click web.xml.

4. After the web.xml file appears in the editor pane, click Servlets at the top of the editor pane. The FacesServlet configuration appears in the editor pane.

If you prefer to edit the web.xml file directly, perform the following steps to configure a mapping to the FacesServlet instance:

1. Include a servlet element in the deployment descriptor.

2. Inside the servlet element, include a display-name element and set it to FacesServlet.

3. Also inside the servlet element, add a servlet-name element and set it to FacesServlet.

4. Add a third element, called servlet-class, inside the servlet element and set it to javax.faces.webapp.FacesServlet. This is the fully-qualified class name of the FacesServlet class.

5. After the servlet element, add a servlet-mapping element.

6. Inside the servlet-mapping element, add a servlet-name element and set it to FacesServlet. This must match the name identified by the servlet-name element described in step 3.

7. Also inside the servlet-mapping element, add a url-pattern element and set it to whatever mapping you prefer. This 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/*.

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 these paths using NetBeans IDE, do the following:

1. Expand the node of your project in the Projects pane.

2. Expand the Web Pages and WEB-INF nodes that are under the project node.

3. Double-click web.xml.

4. After the web.xml file appears in the editor pane, click General at the top of the editor pane.

5. Expand the Context Parameters node.

6. Click Add.

7. In the Add Context Parameter dialog:

   1. Enter javax.faces.CONFIG_FILES in the Param Name field.

   2. Enter the path to your configuration file in the Param Value field.

   3. Click OK.

8. Repeat steps 1 through 7 for each configuration file.

To specify paths to the files by editing the deployment descriptor directly follow these steps:

1. Add a context-param element to the deployment descriptor.

2. Add a param-value element inside the context-param element and call it javax.faces.CONFIG_FILES.

3. Add a param-value element inside the context-param element and give it the path to your configuration file. For example, the path to the guessNumber application’s application configuration resource file is /WEB-INF/faces-config.xml.

4. Repeat steps 2 and 3 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 in your deployment descriptor.

To specify where state is saved using NetBeans IDE, do the following:

1. Expand the node of your project in the Projects pane.

2. Expand the Web Pages and WEB-INF nodes that are under the project node.

3. Double-click web.xml.

4. After the web.xml file appears in the editor pane, click General at the top of the editor pane.

5. Expand the Context Parameters node.

6. Click Add.

7. In the Add Context Parameter dialog:

   1. Enter javax.faces.STATE_SAVING_METHOD in the Param Name field.

   2. Enter client or server in the Param Value field.

   3. Click OK.

To specify where state is saved by editing the deployment descriptor directly follow these steps:

1. Add a context-param element to the deployment descriptor.

2. Add a param-name element inside the context-param element and give it the name javax.faces.STATE_SAVING_METHOD.

3. Add a param-value element to the context-param element and give it the value client or server, 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.

Encrypting Client State

When you are choosing to save state on the client, you are essentially saying that you want state to be sent over the wire and saved on the client in a hidden field. Clearly, this opens the door to potential tampering with the state information. To prevent this from happening, you can specify that the state must be encrypted before it is transmitted to the client.

To specify that state must be encrypted using NetBeans IDE, do the following:

1. Expand the node of your project in the Projects pane.

2. Expand the Web Pages and WEB-INF nodes that are under the project node.

3. Double-click web.xml.

4. After the web.xml file appears in the editor pane, click References at the top of the editor pane.

5. Expand the Environment Entries node.

6. Click Add.

7. In the Add Environment Entry dialog:

   1. Enter com.sun.faces.ClientStateSavingPassword in the Entry Name field.

   2. Select java.lang.String from the Entry Type menu.

   3. Click OK.

To specify that state must be encrypted by editing the deployment descriptor directly, do the following:

1. Add an env-entry element to your deployment descriptor.

2. Add an env-entry-name element to the env-entry element and give it the name com.sun.faces.ClientStateSavingPassword.

3. Add an env-entry-value element to the env-entry element, and give it your password. The password that you provide is used to generate keys and ciphers for encryption.

4. Add an env-entry-type element and give it the type of your password, which must be java.lang.String.

If your deployment descriptor does not contain this environment entry then no encryption of client-side state will occur.

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.

To set a security constraint using NetBeans IDE, do the following:

1. Expand the node of your project in the Projects pane.

2. Expand the Web Pages and WEB-INF nodes that are under the project node.

3. Double-click web.xml.

4. After the web.xml file appears in the editor pane, click Security at the top of the editor pane.

5. Click Add Security Constraint.

6. Enter a name for the constraint in the Display Name field.

7. Click Add to add a web resource collection.

8. In the Add Web Resource dialog:

   1. Enter a name for the web resource collection in the Resource Name field.

   2. In the URL pattern field, enter the path to a JSP page to which you want to restrict access, such as /response.jsp. Use commas to separate multiple patterns.

   3. Click OK.

To set a security constraint by editing the deployment descriptor directly, add a security-constraint element, and inside the security-constraint element, add the following:

1. Add a display-name element to identify the name of the constraint.

2. Add a web-resource-collection element.

3. Inside the web-resource-collection element, add a web-resource-name element that identifies the purpose of the collection.

4. Add a url-pattern element inside the web-resource-collection element and enter the path to a JSP page to which you want to restrict access, such as /response.jsp.

5. Continue to add URL patterns for all the JSP pages to which you want to restrict access.

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.

To set the flag using NetBeans IDE, do the following:

1. Expand the node of your project in the Projects pane.

2. Expand the Web Pages and WEB-INF nodes that are under the project node.

3. Double-click web.xml.

4. After the web.xml file appears in the editor pane, click General at the top of the editor pane.

5. Expand the Context Parameters node.

6. Click Add.

7. In the Add Context Parameter dialog:

   1. Enter com.sun.faces.validateXml in the Param Name field.

   2. Enter true in the Param Value field.

   3. Click OK.

To set the flag in the deployment descriptor directly, do the following:

1. Add a context-param element to the deployment descriptor.

2. Add a param-name element inside the context-param element and give it the name com.sun.faces.validateXml.

3. Add a param-value element to the context-param element and give it the value true. The default value is false.

Verifying Custom Objects

If your application includes custom objects, such as custom 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.

To set the flag using NetBeans IDE, do the following:

1. Expand the node of your project in the Projects pane.

2. Expand the Web Pages and WEB-INF nodes that are under the project node.

3. Double-click web.xml.

4. After the web.xml file appears in the editor pane, click General at the top of the editor pane.

5. Expand the Context Parameters node.

6. Click Add.

7. In the Add Context Parameter dialog:

   1. Enter com.sun.faces.verifyObjects in the Param Name field.

   2. Enter true in the Param Value field.

   3. Click OK.

To set the flag in the deployment descriptor directly, do the following:

1. Add a context-param element to the deployment descriptor.

2. Add a param-name element inside the context-param element and give it the name com.sun.faces.verifyObjects.

3. Add a param-value element to the context-param element and give it the value true. 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 as-install/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 as-install/lib/.

When packaging and deploying your JavaServer Faces application, you do not need to explicitly package any of the JAR files.

Including the Classes, Pages, and Other Resources

When packaging web applications using the included build scripts, you’ll notice that the scripts package resources as described here:

• All JSP pages are placed at the top level of the WAR file.

• The TLD files, the faces-config.xml file, and the web.xml file 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.

When packaging your own applications, you can use NetBeans IDE or you can use the build scripts included with the tutorial examples, as explained throughout the preceding chapters. You can modify the build scripts to fit your situation. However, it is recommended that you continue to package your WAR files as described in this section because this technique complies with commonly-accepted practice for packaging web applications.