Document Information


Part I Introduction

1.  Overview

2.  Using the Tutorial Examples

Part II The Web Tier

3.  Getting Started with Web Applications

4.  JavaServer Faces Technology

5.  Introduction to Facelets

6.  Expression Language

7.  Using JavaServer Faces Technology in Web Pages

8.  Using Converters, Listeners, and Validators

9.  Developing with JavaServer Faces Technology

10.  JavaServer Faces Technology: Advanced Concepts

11.  Using Ajax with JavaServer Faces Technology

12.  Composite Components: Advanced Topics and Example

13.  Creating Custom UI Components and Other Custom Objects

14.  Configuring JavaServer Faces Applications

Using Annotations to Configure Managed Beans

Using Managed Bean Scopes

Eager Application-Scoped Beans

Application Configuration Resource File

Ordering of Application Configuration Resource Files

Configuring Managed Beans

Using the managed-bean Element

Initializing Properties Using the managed-property Element

Referencing a Java Enum Type

Referencing a Context Initialization Parameter

Initializing Map Properties

Initializing Array and List Properties

Initializing Managed Bean Properties

Initializing Maps and Lists

Registering Application Messages

Using FacesMessage to Create a Message

Referencing Error Messages

Using Default Validators

Registering a Custom Validator

Registering a Custom Converter

Configuring Navigation Rules

To Configure a Navigation Rule

Implicit Navigation Rules

Registering a Custom Renderer with a Render Kit

Registering a Custom Component

15.  Java Servlet Technology

16.  Uploading Files with Java Servlet Technology

17.  Internationalizing and Localizing Web Applications

Part III Web Services

18.  Introduction to Web Services

19.  Building Web Services with JAX-WS

20.  Building RESTful Web Services with JAX-RS

21.  JAX-RS: Advanced Topics and Example

Part IV Enterprise Beans

22.  Enterprise Beans

23.  Getting Started with Enterprise Beans

24.  Running the Enterprise Bean Examples

25.  A Message-Driven Bean Example

26.  Using the Embedded Enterprise Bean Container

27.  Using Asynchronous Method Invocation in Session Beans

Part V Contexts and Dependency Injection for the Java EE Platform

28.  Introduction to Contexts and Dependency Injection for the Java EE Platform

29.  Running the Basic Contexts and Dependency Injection Examples

30.  Contexts and Dependency Injection for the Java EE Platform: Advanced Topics

31.  Running the Advanced Contexts and Dependency Injection Examples

Part VI Persistence

32.  Introduction to the Java Persistence API

33.  Running the Persistence Examples

34.  The Java Persistence Query Language

35.  Using the Criteria API to Create Queries

36.  Creating and Using String-Based Criteria Queries

37.  Controlling Concurrent Access to Entity Data with Locking

38.  Using a Second-Level Cache with Java Persistence API Applications

Part VII Security

39.  Introduction to Security in the Java EE Platform

40.  Getting Started Securing Web Applications

41.  Getting Started Securing Enterprise Applications

42.  Java EE Security: Advanced Topics

Part VIII Java EE Supporting Technologies

43.  Introduction to Java EE Supporting Technologies

44.  Transactions

45.  Resources and Resource Adapters

46.  The Resource Adapter Example

47.  Java Message Service Concepts

48.  Java Message Service Examples

49.  Bean Validation: Advanced Topics

50.  Using Java EE Interceptors

Part IX Case Studies

51.  Duke's Bookstore Case Study Example

52.  Duke's Tutoring Case Study Example

53.  Duke's Forest Case Study Example



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 can be packaged in a WAR file, which must conform to specific requirements 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

A WAR file may also contain:

  • An application configuration resource file, which configures application resources

  • A set of tag library descriptor files

For example, a Java Server Faces web application WAR file using Facelets typically has the following directory structure:

[Web Pages]
+- /[xhtml documents]
+- /resources
   +- /classes
   +- /lib
   +- /web.xml
   +- /faces-config.xml (optional)
   +- /*.taglib.xml (optional)
   +- /glassfish-web.xml 

The web.xml file (or web 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.

Configuring an Application with a Web Deployment Descriptor

Web applications are commonly configured using elements contained in the web application deployment descriptor, web.xml. The deployment descriptor for a JavaServer Faces application must specify certain configurations, including 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 exists and is not located in a default location

The deployment descriptor can also include other, optional configurations, such as:

  • Specifying where component state is saved

  • Encrypting state saved on the client

  • Compressing state saved on the client

  • Restricting access to pages containing JavaServer Faces tags

  • Turning on XML validation

  • Specifying the Project Stage

  • Verifying custom objects

This section gives more details on these configurations. Where appropriate, it also describes how you can make these configurations using NetBeans IDE.

Identifying the Servlet for Lifecycle Processing

A requirement of a JavaServer Faces application is that all requests to the application that reference previously saved JavaServer Faces components must go through javax.faces.webapp.FacesServlet. A FacesServlet instance manages the request processing lifecycle for web applications and initializes the resources required by JavaServer Faces technology.

Before a JavaServer Faces application can launch its first web page, the web container must invoke the FacesServlet instance in order for the application lifecycle process to start. See The Lifecycle of a JavaServer Faces Application for more information.

The following example shows the default configuration of the FacesServlet:


You provide a mapping configuration entry to make sure the FacesServlet instance is invoked. The mapping to FacesServlet can be a prefix mapping, such as /faces/*, or an extension mapping, such as *.xhtml. The mapping is used to identify a page as having JavaServer Faces content. Because of this, the URL to the first page of the application must include the URL pattern mapping.

The following elements, commonly used in the tutorial examples, specify a prefix mapping:

    <url-pattern>/faces/* </url-pattern>

The following elements, also commonly used in the tutorial examples, specify an extension mapping:

    <servlet-name>Faces Servlet</servlet-name>

When you use this mechanism, users access the application as shown in the following example:


In the case of extension mapping, if a request comes to the server for a page with an .xhtml extension, the container will send the request to the FacesServlet instance, which will expect a corresponding page of the same name containing the content to exist.

If you are using NetBeans IDE to create your application, a web deployment descriptor is automatically created for you with default configurations. If you created your application without an IDE, you can create a web deployment descriptor.

To Specify 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 these paths using NetBeans IDE, do the following.

  1. Expand the node of your project in the Projects pane.
  2. Expand the Web Pages and WEB-INF nodes that are under the project node.
  3. Double-click web.xml.
  4. After the web.xml file appears in the editor pane, click General at the top of the editor pane.
  5. Expand the Context Parameters node.
  6. Click Add.
  7. In the Add Context Parameter dialog:
    1. Type javax.faces.CONFIG_FILES in the Param Name field.
    2. Type the path to your configuration file in the Param Value field.
    3. Click OK.
  8. Repeat steps 1 through 7 for each configuration file.

To Specify Where State Is Saved

For all the components in a web application, you can specify in your deployment descriptor where you want the state to be saved, on either client or server. You do this by setting a context parameter in your deployment descriptor. By default, state is saved on the server, so you need to specify this context parameter only if you want to save state on the client. See Saving and Restoring State for information on the advantages and disadvantages of each location.

To specify where state is saved using NetBeans IDE, do the following.

  1. Expand the node of your project in the Projects pane.
  2. Expand the Web Pages and WEB-INF nodes under the project node.
  3. Double-click web.xml.
  4. After the web.xml file appears in the editor pane, click General at the top of the editor pane.
  5. Expand the Context Parameters node.
  6. In the Add Context Parameter dialog:
    1. Type javax.faces.STATE_SAVING_METHOD in the Param Name field.
    2. Type client or server in the Param Value field.
    3. Click OK.

More Information
Implementation of State Saving

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 server by default. Duke’s Forest saves its state on the client.

Configuring Project Stage

Project Stage is a context parameter identifying the status of a JavaServer Faces application in the software lifecycle. The stage of an application can affect the behavior of the application. For example, error messages can be displayed during the Development stage but suppressed during the Production stage.

The possible Project Stage values are as follows:

  • Development

  • UnitTest

  • SystemTest

  • Production

Project Stage is configured through a context parameter in the web deployment descriptor file. Here is an example:


If no Project Stage is defined, the default stage is Development. You can also add custom stages according to your requirements.

Including the Classes, Pages, and Other Resources

When packaging web applications using the included build scripts, you’ll notice that the scripts package resources in the following ways:

  • All web pages are placed at the top level of the WAR file.

  • The faces-config.xml file and the web.xml file are packaged in the WEB-INF directory.

  • All packages are stored in the WEB-INF/classes/ directory.

  • All application JAR files are packaged in the WEB-INF/lib/ directory.

  • All resource files are either under the root of the web application /resources directory, or in the web application’s classpath, META-INF/resources/resourceIdentifier directory. For more information on resources, see Web Resources.

When packaging your own applications, you can use NetBeans IDE or you can use the build scripts such as those created for Ant. You can modify the build scripts to fit your situation. However, you can continue to package your WAR files by using the directory structure described in this section, because this technique complies with the commonly accepted practice for packaging web applications.