Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
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 theWEB-INF
directory of the WAR file. Usually, you will want to use theAnt
build tool to compile the classes, build the necessary files into the WAR, and deploy the WAR file. TheAnt
tool is included in the Java WSDP. You configure how theAnt
build tool builds your WAR file with abuild.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
. TheFacesServlet
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 theWEB-INF
directory. See Configuring Web Applications (page 82) to find out what a standardweb.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 thecardemo
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 theFacesServlet
, which processes the lifecycle of the application. Theload-on-startup
element has a value oftrue
, which indicates that theFacesServlet
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 thejavax.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)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. Theweb.xml
,faces-config.xml
, and extra TLD files should be in theWEB-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 temporarybuild
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 thebuild
directory into the WAR file while preserving the directory structure contained in thebuild
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 theFacesServlet
in the URL to the first JSP page. You define the path in theurl-pattern
element nested inside theservlet-mapping
element of theweb.xml
file. In the exampleweb.xml
file in section Writing the web.xml File, the path to theFacesServlet
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:
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:
- 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. Thedemo-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.
Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
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.