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 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)

> To run your application standalone, you need to:

> - 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:

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

> 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:

>     http://localhost:8080/myApp

> ### 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.

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.