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 can be packaged in a WAR file, which must conform to specific requirements 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

A WAR file may also contain:
- A set of tag library descriptor files
  
  For example, a Java Server Faces web application WAR file using Facelets typically has the following directory structure:
```
$PROJECT_DIR
[Web Pages]
+- /[xhtml documents]
+- /resources
+- /WEB-INF
   +- /classes
   +- /lib
   +- /web.xml
   +- /faces-config.xml (optional)
   +- /*.taglib.xml (optional)
   +- /glassfish-web.xml 
```
  The web.xml file (or web 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 Web Deployment Descriptor
  
  Web applications are commonly configured using elements contained in the web application deployment descriptor, web.xml . The deployment descriptor for a JavaServer Faces application must specify certain configurations, including the following:
  - The path to the configuration resource file, if it exists and is not located in a default location
    
    The deployment descriptor can also include other, optional configurations, such as:
    - 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 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>FacesServlet</servlet-name>
        <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
        </servlet>
```
      You provide a mapping configuration entry to make sure 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, commonly used in the tutorial examples, specify a prefix mapping:
```
<servlet-mapping>
    <servlet-name>FacesServlet</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, also commonly 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.
      
      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.
    - Expand the node of your project in the Projects pane.
    - Expand the Web Pages and WEB-INF nodes that are under the project node.
    - Double-click web.xml .
    - After the web.xml file appears in the editor pane, click General at the top of the editor pane.
    - Expand the Context Parameters node.
    - Click Add.
    - In the Add Context Parameter dialog:
      1. Type javax.faces.CONFIG_FILES in the Param Name field.
      2. Type the path to your configuration file in the Param Value field.
      3. Click OK.
    - Repeat steps 1 through 7 for each configuration file.
    - Expand the node of your project in the Projects pane.
    - Expand the Web Pages and WEB-INF nodes under the project node.
    - Double-click web.xml .
    - After the web.xml file appears in the editor pane, click General at the top of the editor pane.
    - Expand the Context Parameters node.
    - In the Add Context Parameter dialog:
      1. Type javax.faces.STATE_SAVING_METHOD in the Param Name field.
      2. Type client or server in the Param Value field.
      3. Click OK.