16.12.1.1 Identifying the Servlet for Lifecycle Processing

A requirement of a JavaServer Faces application is that all requests to the application that reference previously saved JavaServer Faces components must go through javax.faces.webapp.FacesServlet. A FacesServlet instance manages the request-processing lifecycle for web applications and initializes the resources required by JavaServer Faces technology.

Before a JavaServer Faces application can launch its first web page, the web container must invoke the FacesServlet instance in order for the application lifecycle process to start. See The Lifecycle of a JavaServer Faces Application for more information.

The following example shows the default configuration of the FacesServlet:

<servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
</servlet>

You will provide a mapping configuration entry to make sure that the FacesServlet instance is invoked. The mapping to FacesServlet can be a prefix mapping, such as /faces/*, or an extension mapping, such as *.xhtml. The mapping is used to identify a page as having JavaServer Faces content. Because of this, the URL to the first page of the application must include the URL pattern mapping.

The following elements specify a prefix mapping:

<servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>/faces/*</url-pattern>
</servlet-mapping>
...
<welcome-file-list>
    <welcome-file>faces/greeting.xhtml</welcome-file>
</welcome-file-list>

The following elements, used in the tutorial examples, specify an extension mapping:

<servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>*.xhtml</url-pattern>
</servlet-mapping>
...
<welcome-file-list>
    <welcome-file>index.xhtml</welcome-file>
</welcome-file-list>

When you use this mechanism, users access the application as shown in the following example:

http://localhost:8080/guessNumber

In the case of extension mapping, if a request comes to the server for a page with an .xhtml extension, the container will send the request to the FacesServlet instance, which will expect a corresponding page of the same name containing the content to exist.

If you are using NetBeans IDE to create your application, a web deployment descriptor is automatically created for you with default configurations. If you created your application without an IDE, you can create a web deployment descriptor.

16.12.1.2 To Specify 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 tab.

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, click General at the top of the editor window.

5. Expand the Context Parameters node.

6. Click Add.

7. In the Add Context Parameter dialog box:

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

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

   3. Click OK.

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

16.12.1.3 To Specify Where State Is Saved

For all the components in a web application, you can specify in your deployment descriptor where you want the state to be saved, on either client or server. You do this by setting a context parameter in your deployment descriptor. By default, state is saved on the server, so you need to specify this context parameter only if you want to save state on the client. See Saving and Restoring State for information on the advantages and disadvantages of each location.

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

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

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

3. Double-click web.xml.

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

5. Expand the Context Parameters node.

6. Click Add.

7. In the Add Context Parameter dialog box:

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

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

   3. Click OK.

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. Duke's Forest saves its state on the client.