Download PDF Home History |  | API Search Feedback FAQ

> ## 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 must be compliant with the Servlet specification, version 2.3 (or later) and the JavaServer Pages specification, version 1.2 (or later). All applications compliant with these specifications are packaged in a WAR file, which must conform to specific requirements in order 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
> - An application configuration resource file, which configures application resources

> The WAR file typically has this directory structure:

>     index.html
>     JSP pages
>     WEB-INF/
>        web.xml
>        faces-config.xml
>        tag library descriptors (optional)
>        classes/
>           class files
>          Properties files
>        lib/
>           JAR files

> The `web.xml` file (or 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. Usually, you will want to use the `asant` build tool to compile the classes. You will use `deploytool` to package the necessary files into the WAR and deploy the WAR file.

> The `asant` tool and `deploytool` are included in the Sun Java System Application Server Platform Edition 8. You configure how the `asant` build tool builds your WAR file via a `build.xml` file. Each example in the tutorial has its own build file, to which you can refer when creating your own build file.

> ### Configuring an Application Using deploytool

> Web applications are configured via elements contained in the Web application deployment descriptor. The `deploytool` utility generates the descriptor when you create a WAR and adds elements when you create Web components and associated classes. You can modify the elements via the inspectors associated with the WAR.

> The deployment descriptor for a JavaServer Faces application must specify certain configurations, which include the following:

> - The servlet used to process JavaServer Faces requests
> - The servlet mapping for the processing servlet
> - The path to the configuration resource file if it is not located in a default location

> The deployment descriptor can also specify other, optional configurations, including:

> - Specifying where component state is saved
> - Restricting Access to pages containing JavaServer Faces tags
> - Turning on XML validation
> - Verifying custom objects

> This section gives more details on these configurations and explains how to configure them in `deploytool`.

> #### Identifying the Servlet for Life Cycle Processing

> One requirement of a JavaServer Faces application is that all requests to the application that reference previously saved JavaServer Faces components must go through `FacesServlet`. A `FacesServlet` instance manages the request processing life cycle for Web applications and initializes the resources required by JavaServer Faces technology. To comply with this requirement, follow these steps.

> 1. While using the Edit Contents dialog box from the Web Component wizard, add the `jsf-api.jar` file from `<J2EE_HOME>``/lib/` to your WAR file. This JAR file is needed so that you have access to the `FacesServlet` instance when configuring your application with `deploytool`.
> 2. In the Choose Component Type dialog box of the Web Component wizard, select the Servlet radio button and click Next.
> 3. Select `FacesServlet` from the Servlet Class combo box.
> 4. In the Startup Load Sequence Position combo box, enter 1, indicating that the `FacesServlet` should be loaded when the application starts. Click Finish.
> 5. Select the `FacesServlet` Web component from the tree.
> 6. Select the Aliases tab and click Add.
> 7. Enter a path in the Aliases field. This path will be the path to `FacesServlet`. Users of the application will include this path in the URL when they access the application. For the `guessNumber` application, the path is `/guess/*`.

> Before a JavaServer Faces application can launch the first JSP page, the Web container must invoke the `FacesServlet` instance in order for the application life cycle process to start. The application life cycle is described in the section The Life Cycle of a JavaServer Faces Page.

> To make sure that the `FacesServlet` instance is invoked, you provide a mapping to it using the Aliases tab, as described in steps 5 through 7 above.

> The mapping to `FacesServlet` described in the foregoing steps uses a prefix mapping to identify a JSP page as having JavaServer Faces content. Because of this, the URL to the first JSP page of the application must include the mapping. There are two ways to accomplish this:

> - The page author can include an HTML page in the application that has the URL to the first JSP page. This URL must include the path to `FacesServlet`, as shown by this tag, which uses the mapping defined in the `guessNumber` application:

> `<a href="guess/greeting.jsp">`

> - Users of the application can include the path to `FacesServlet` in the URL to the first page when they enter it in their browser, as shown by this URL that accesses the `guessNumber` application:

> `http://localhost:8080/guessNumber/guess/greeting.jsp`

> The second method allows users to start the application from the first JSP page, rather than start it from an HTML page. However, the second method requires users to identify the first JSP page. When you use the first method, users need only enter

>     http://localhost:8080/guessNumber

> You could define an extension mapping, such as `*.faces`, instead of the prefix mapping `/guess/*`. If a request comes to the server for a JSP page with a `.faces` extension, the container will send the request to the `FacesServlet` instance, which will expect a corresponding JSP page of the same name to exist containing the content. For example, if the request URL is `http://localhost/bookstore6/bookstore.faces`, `FacesServlet` will map it to the `bookstore.jsp` page.

> #### Specifying 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 paths to the files using `deploytool` follow these steps:

> 1. Select the WAR from the tree.
> 2. Select the Context tabbed pane and click Add.
> 3. Enter `javax.faces.application.CONFIG_FILES` in the Coded Parameter field.
> 4. Enter the path to your application configuration resource file in the Value field. For example, the path to the `guessNumber` application's application configuration resource file is `/WEB-INF/faces-config.xml`
> 5. Repeat steps 2 through 4 for each application configuration resource file that your application contains.

> #### Specifying Where State Is Saved

> When implementing the state-holder methods (described in Saving and Restoring State), you specify in your deployment descriptor where you want the state to be saved, either client or server. You do this by setting a context parameter with `deploytool`:

> 1. While running `deploytool`, select the Web application from the tree.
> 2. Select the Context tabbed pane and click Add.
> 3. Enter `javax.faces.STATE_SAVING_METHOD` in the Coded Parameter field.
> 4. Enter either `client` or `server` in the Value field, depending on whether you want state saved in the client or the server.

> If state is saved on the client, the state of the entire view is rendered to a hidden field on the page. The JavaServer Faces implementation saves the state on the client by default. Duke's Bookstore saves its state in the client.

> #### Restricting Access to JavaServer Faces Components

> In addition to identifying the `FacesServlet` instance and providing a mapping to it, you should also ensure that all applications use `FacesServlet` to process JavaServer Faces components. You do this by setting a security constraint:

> 1. Select your WAR file from the tree.
> 2. Select the Security tabbed pane.
> 3. Click Add Constraints and enter `Restricts Access to JSP Pages` in the Security Constraints field.
> 4. Click Add Collections and enter `Restricts Access to JSP Pages` in the Web Resource Collections field.
> 5. Click Edit Collections.
> 6. In the Edit Collections of Web Resource Collections dialog box, click Add URL Pattern and enter the path to a JSP page to which you want to restrict access, such as `/response.jsp`.
> 7. Continue to click Add URL Pattern again, and enter paths to all the JSP pages in your application and click OK.

> #### Turning On Validation of XML Files

> Your application contains one or more application configuration resource files written in XML. You can force the JavaServer Faces implementation to validate the XML of these files by setting the `validateXML` flag to `true`:

> 1. Select your WAR file from the tree.
> 2. Select the Context tabbed pane and click Add.
> 3. Enter `com.sun.faces.validateXml` in the Coded Parameter field.
> 4. Enter `true` in the Value field. The default value is `false`.

> #### Verifying Custom Objects

> If your application includes custom objects, such as components, converters, validators, and renderers, you can verify when the application starts that they can be created. To do this, you set the `verifyObjects` flag to `true`:

> 1. Select your WAR file from the tree
> 2. Select the Context tabbed pane and click Add.
> 3. Enter `com.sun.faces.verifyObjects` in the Coded Parameter field.
> 4. Enter `true` in the Value field. The default value is `false`.

> Normally, this flag should be set to `false` during development because it takes extra time to check the objects.

> ### Including the Required JAR Files

> JavaServer Faces applications require several JAR files to run properly. These JAR files are as follows:

> - `jsf-api.jar` (contains the `javax.faces.*` API classes)
> - `jsf-impl.jar` (contains the implementation classes of the JavaServer Faces implementation)
> - `jstl.jar` (required to use JSTL tags and referenced by JavaServer Faces 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)

> The `jsf-api.jar` and the `jsf-impl.jar` files are located in `<J2EE_HOME>``/lib`. The `jstl.jar` file is bundled in `appserv-jstl.jar`. The other JAR files are bundled in the `appserv-rt.jar`, also located in `<J2EE_HOME>``/lib/`.

> When packaging and deploying your JavaServer Faces application with `deploytool`, you do not need to package any of the JAR files, except the `jsf-api.jar` file, with your application. The `jsf-api.jar` file must be packaged with your application so that you have access to the `FacesServlet` instance and can configure the mapping for it.

> ### Including the Classes, Pages, and Other Resources

> When packaging Web applications using `deploytool`, you'll notice that `deploytool` automatically packages many of your Web application's files in the appropriate directories in the WAR file. All JSP pages are placed at the top level of the WAR file. The TLD files and the `web.xml` that `deploytool` creates are packaged in the `WEB-INF` directory. All packages are stored in the `WEB-INF/classes` directory. All JAR files are packaged in the `WEB-INF/lib` directory. However, `deploytool` does not copy `faces-config.xml` to the `WEB-INF` directory as it should. Therefore, when packaging your Web applications, you need to drag `faces-config.xml` to the `WEB-INF` directory.

Download PDF Home History |  | API Search Feedback FAQ

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