Download
FAQ
History
PrevHomeNext API
Search
Feedback
Divider

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:

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, to which you can refer when creating your own 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 (page 82) 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 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:

To run your application standalone, you need to:

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:

<target name="build.war" depends="build"
  <jar jarfile="${example}.war" 
    basedir="${build}/${example}" />
  <copy todir=".." file="{example}.war" />
  <delete file="${example}.war" />
</target> 

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 (page 791).

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 in section Writing the web.xml File, 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:

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:

http://localhost:8080/myApp 

Setting Up The Application Configuration File

The application configuration file is new with this release. It is an XML file, usually 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 (page 807). 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:

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:

Divider
Download
FAQ
History
PrevHomeNext API
Search
Feedback
Divider

All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.