Basic Requirements of a JavaServer Faces Application

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

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 file, which defines application resources

The web.xml, 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 Ant build tool to compile the classes, build the necessary files into the WAR, and deploy the WAR file. The Ant tool is included in the Java WSDP. You configure how the Ant build tool builds your WAR file with a build.xml file. Each example in the download has its own build file. Look at one of those build files for an example of writing a build file.

Another requirement is that all requests to a JavaServer Faces application that reference previously saved JavaServer Faces components must go through the FacesServlet. The FacesServlet manages the request processing lifecycle for Web applications and initializes the resources required by the JavaServer Faces implementation. To make sure your JavaServer Faces application complies with this requirement, see the section, Invoking the FacesServlet.

Writing the web.xml File

The web.xml file is located at the top level of the WEB-INF directory. See Configuring Web Applications to find out what a standard web.xml file should contain.

The web.xml file for a JavaServer Faces application must specify certain configurations, which include:

The servlet used to process JavaServer Faces requests

The servlet mapping for the processing servlet

The following XML markup defines the required configurations specific to
JavaServer Faces technology for the cardemo application:

<web-app>
...
  <!-- Faces Servlet -->
  <servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class>
      javax.faces.webapp.FacesServlet
    </servlet-class>
    <load-on-startup> 1 </load-on-startup>
  </servlet> 
  <!-- Faces Servlet Mapping -->
  <servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>/faces/*</url-pattern>
  </servlet-mapping>
</web-app>

Identifying the Servlet for Lifecycle Processing

The servlet element identifies the FacesServlet, which processes the lifecycle of the application. The load-on-startup element has a value of true, which indicates that the FacesServlet should be loaded when the application starts up.

Provide the Path to the Servlets

The servlet-mapping element lists each servlet name defined in the servlet element and gives the URL path to the servlet. Tomcat will map the path to the servlet when a request for the servlet is received.

JSP pages do not need an alias path defined for them because Web containers automatically map an alias path that ends in *.jsp.

Including the Required JAR Files

JavaServer Faces applications require several JAR files to run properly. If you are not running the application on the Java WSDP, which already has these JAR files, the WAR file for your JavaServer Faces application must include the following set of JAR files in the WEB-INF/lib directory:

jsf-api.jar (contains the javax.faces.* API classes)

jsf-ri.jar (contains the implementation classes of the JavaServer Faces RI)

jstl.jar (required to use JSTL tags and referenced by JavaServer Faces reference 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)

Comment out the build.wspack property and uncomment the build.standalone property in your build.properties file.

Comment out the jsp.jar, servlet.jar, jsf-api.jar, and jsf-ri.jar properties from the build.properties file.

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. JavaServer Faces 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.

The build target of the example build file copies all of these files to a temporary build directory. This directory contains an exact image of the binary distribution for your JavaServer Faces application:

<target name="build" depends="prepare" 
  description="Compile Java files and copy static files." >
  <javac srcdir="src" 
      destdir="${build}/${example}/WEB-INF/classes">
    <include name="**/*.java" />
    <classpath refid="classpath"/>
  </javac>
  <copy todir="${build}/${example}/WEB-INF">
    <fileset dir="web/WEB-INF"    >
      <include name="web.xml" />
      <include name="*.tld" />
      <include name="*.xml" />
    </fileset>
  </copy>
  <copy todir="${build}/${example}/">
    <fileset dir="web">
      <include name="*.html" />
      <include name="*.gif" />
      <include name="*.jpg" />
      <include name="*.jsp" />
      <include name="*.xml" />
      <include name="*.css" />
    </fileset>
  </copy>
  <copy 
    todir="${build}/${example}/WEB-INF/classes/${example}" >
    <fileset dir="src/${example}" >
      <include name="*properties"/>
    </fileset>
    <fileset dir="src/${example}" >
    <include name="*.xml"/>
    </fileset>
  </copy>
</target>

The build.war target packages all the files from the build directory into the WAR file while preserving the directory structure contained in the build directory:

When writing a build file for your Web application, you can follow the build files included with each example.

Invoking the FacesServlet

Before a JavaServer Faces application can launch the first JSP page, the Web container must invoke the FacesServlet in order for the application lifecycle process to start. The application lifecycle is described in the section, The Lifecycle of a JavaServer Faces Page.

To make sure that the FacesServlet is invoked, you need to 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. In the example web.xml file above, the path to the FacesServlet is /faces.

To include the path to the FacesServlet in the URL to the first JSP page, you must do one of two things:

Include an HTML page in your application that has the URL to the first JSP page, and include the path to the FacesServlet:

<a href="faces/First.jsp">

Include the path to the FacesServlet in the URL to the first page when you enter it in your browser:

http://localhost:8080/myApp/faces/First.jsp

The second method allows you to start your application from the first JSP page, rather than starting it from an HTML page. However, the second method requires your user to identify the first JSP page. When you use the first method, the user only has to enter:

Setting Up The Application Configuration File

The application configuration file is new with this release. It is an XML file, named faces-config.xml, whose purpose is to configure resources for an application. These resources include: navigation rules, converters, validators, render kits, and others. For a complete description of the application configuration file, see Application Configuration. This section explains the basic requirements of the application configuration file.

The Application Configuration file must be valid against the DTD located at http://java.sun.com/dtd/web-facesconfig_1_0.dtd. In addition, each file must include in this order:

The XML version number:
<?xml version="1.0"?>

This DOCTYPE declaration at the top of the file:

<!DOCTYPE faces-config PUBLIC
  "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
  "http://java.sun.com/dtd/web-facesconfig_1_0.dtd">

A faces-config tag enclosing all of the other declarations:

<faces-config>
...
</faces-config>

You can have more than one application configuration file, and there are three ways that you can make these files available to the application. The JavaServer Faces implementation finds the file or files by looking for:

A resource named /META-INF/faces-config.xml in any of the JAR files in the Web application's /WEB-INF/lib directory. If a resource with this name exists, it is loaded as a configuration resource. This method is practical for a packaged library containing some components and renderers. The demo-components.jar, located in <JWSDP_HOME>/jsf/samples uses this method.

A context init parameter, javax.faces.application.CONFIG_FILES that specifies one or more (comma-delimited) paths to multiple configuration files for your Web application. This method will most likely be used for enterprise-scale applications that delegate the responsibility for maintaining the file for each portion of a big application to separate groups.

A resource named faces-config.xml in the /WEB-INF/ directory of your application if you don't specify a context init parameter. This is the way most simple applications will make their configuration files available.