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

Determining Whether You Need a Custom Component or Renderer

When to Use a Custom Component

When to Use a Custom Renderer

Component, Renderer, and Tag Combinations

Steps for Creating a Custom Component

Creating Custom Component Classes

Specifying the Component Family

Performing Encoding

Performing Decoding

Enabling Component Properties to Accept Expressions

Saving and Restoring State

Delegating Rendering to a Renderer

Creating the Renderer Class

Identifying the Renderer Type

Implementing an Event Listener

Implementing Value-Change Listeners

Implementing Action Listeners

Handling Events for Custom Components

Defining the Custom Component Tag in a Tag Library Descriptor

Using a Custom Component

Creating and Using a Custom Converter

Creating a Custom Converter

Using a Custom Converter

Creating and Using a Custom Validator

Implementing the Validator Interface

Specifying a Custom Tag

Using a Custom Validator

Binding Component Values and Instances to Managed Bean Properties

Binding a Component Value to a Property

Binding a Component Value to an Implicit Object

Binding a Component Instance to a Bean Property

Binding Converters, Listeners, and Validators to Managed Bean Properties

14.  Configuring JavaServer Faces Applications

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



Understanding the Image Map Example

Duke's Bookstore includes a custom image map component on the index.xhtml page. This image map displays a selection of six book titles. When the user clicks one of the book titles in the image map, the application goes to a page that displays the title of the selected book as well as information about a featured book. The page allows the user to add either book (or none) to the shopping cart.

Why Use JavaServer Faces Technology to Implement an Image Map?

JavaServer Faces technology is an ideal framework to use for implementing this kind of image map because it can perform the work that must be done on the server without requiring you to create a server-side image map.

In general, client-side image maps are preferred over server-side image maps for several reasons. One reason is that the client-side image map allows the browser to provide immediate feedback when a user positions the mouse over a hotspot. Another reason is that client-side image maps perform better because they don’t require round-trips to the server. However, in some situations, your image map might need to access the server to retrieve data or to change the appearance of non-form controls, tasks that a client-side image map cannot do.

Because the image map custom component uses JavaServer Faces technology, it has the best of both styles of image maps: It can handle the parts of the application that need to be performed on the server, while allowing the other parts of the application to be performed on the client side.

Understanding the Rendered HTML

Here is an abbreviated version of the form part of the HTML page that the application needs to render:

<form id="j_idt13" name="j_idt13" method="post"
        action="/dukesbookstore/faces/index.xhtml" ... >
    <img id="j_idt13:mapImage"
        alt="Choose a Book from our Catalog"
        usemap="#bookMap" />
    <map name="bookMap">
    <area alt="Duke"                        
"document.forms[0]['bookMap_current'].value='Duke'; document.forms[0].submit()"
    <input type="hidden" name="bookMap_current">

The img tag associates an image (book_all.jpg) with the image map referenced in the usemap attribute value.

The map tag specifies the image map and contains a set of area tags.

Each area tag specifies a region of the image map. The onmouseover, onmouseout, and onclick attributes define which JavaScript code is executed when these events occur. When the user moves the mouse over a region, the onmouseover function associated with the region displays the map with that region highlighted. When the user moves the mouse out of a region, the onmouseout function redisplays the original image. If the user clicks on a region, the onclick function sets the value of the input tag to the ID of the selected area and submits the page.

The input tag represents a hidden control that stores the value of the currently selected area between client-server exchanges so that the server-side component classes can retrieve the value.

The server-side objects retrieve the value of bookMap_current and set the locale in the javax.faces.context.FacesContext instance according to the region that was selected.

Understanding the Facelets Page

Here is an abbreviated form of the Facelets page that the image map component uses to generate the HTML page shown in the preceding section. It uses custom bookstore:map and bookstore:area tags to represent the custom components:

    <h:graphicImage id="mapImage" 
                    usemap="#bookMap" />
    <bookstore:map id="bookMap" 
            type="dukesbookstore.listeners.MapBookChangeListener" />
        <bookstore:area id="map1" value="#{Book201}"
                        targetImage="mapImage" />
        <bookstore:area id="map2" value="#{Book202}" 

The alt attribute of the h:graphicImage tag maps to the localized string "Choose a Book from our Catalog".

The f:actionListener tag within the bookstore:map tag points to a listener class for an action event. The processAction method of the listener places the book ID for the selected map area into the session map. The way this event is handled is explained more in Handling Events for Custom Components.

The action attribute of the bookstore:map tag specifies a logical outcome String, "bookstore", which by implicit navigation rules sends the application to the page bookstore.xhtml. For more information on navigation, see the section Configuring Navigation Rules.

The immediate attribute of the bookstore:map tag is set to true, which indicates that the default javax.faces.event.ActionListener implementation should execute during the Apply Request Values phase of the request-processing lifecycle, instead of waiting for the Invoke Application phase. Because the request resulting from clicking the map does not require any validation, data conversion, or server-side object updates, it makes sense to skip directly to the Invoke Application phase.

The current attribute of the bookstore:map tag is set to the default area, which is map1 (the book My Early Years: Growing Up on Star7, by Duke).

Notice that the bookstore:area tags do not contain any of the JavaScript, coordinate, or shape data that is displayed on the HTML page. The JavaScript is generated by the dukesbookstore.renderers.AreaRenderer class. The onmouseover and onmouseout attribute values indicate the image to be loaded when these events occur. How the JavaScript is generated is explained more in Performing Encoding.

The coordinate, shape, and alternate text data are obtained through the value attribute, whose value refers to an attribute in application scope. The value of this attribute is a bean, which stores the coords, shape, and alt data. How these beans are stored in the application scope is explained more in the next section.

Configuring Model Data

In a JavaServer Faces application, data such as the coordinates of a hotspot of an image map is retrieved from the value attribute through a bean. However, the shape and coordinates of a hotspot should be defined together because the coordinates are interpreted differently depending on what shape the hotspot is. Because a component’s value can be bound only to one property, the value attribute cannot refer to both the shape and the coordinates.

To solve this problem, the application encapsulates all of this information in a set of ImageArea objects. These objects are initialized into application scope by the managed bean creation facility (see Managed Beans in JavaServer Faces Technology). Here is part of the managed bean declaration for the ImageArea bean corresponding to the South America hotspot:

<managed-bean eager="true">
    <managed-bean-name> Book201 </managed-bean-name>
    <managed-bean-class> dukesbookstore.model.ImageArea /managed-bean-class>
    <managed-bean-scope> application </managed-bean-scope>

For more information on initializing managed beans with the managed bean creation facility, see the section Application Configuration Resource File.

The value attributes of the bookstore:area tags refer to the beans in the application scope, as shown in this bookstore:area tag from index.xhtml:

<bookstore:area id="map1" value="#{Book201}"
                targetImage="mapImage" />

To reference the ImageArea model object bean values from the component class, you implement a getValue method in the component class. This method calls super.getValue. The superclass of tut-install/examples/case-studies/dukes-bookstore/src/java/dukesbookstore/components/, UIOutput, has a getValue method that does the work of finding the ImageArea object associated with AreaComponent. The AreaRenderer class, which needs to render the alt, shape, and coords values from the ImageArea object, calls the getValue method of AreaComponent to retrieve the ImageArea object.

ImageArea iarea = (ImageArea) area.getValue();

ImageArea is a simple bean, so you can access the shape, coordinates, and alternative text values by calling the appropriate accessor methods of ImageArea. Creating the Renderer Class explains how to do this in the AreaRenderer class.

Summary of the Image Map Application Classes

Table 13-2 summarizes all the classes needed to implement the image map component.

Table 13-2 Image Map Classes




The javax.faces.event.ActionEvent indicating that an AreaComponent from the MapComponent has been selected.


The class that defines AreaComponent, which corresponds to the bookstore:area custom tag.


The class that defines MapComponent, which corresponds to the bookstore:map custom tag.


This javax.faces.render.Renderer performs the delegated rendering for AreaComponent.


The bean that stores the shape and coordinates of the hotspots.


The action listener for the MapComponent.

The Duke's Bookstore source directory, called bookstore-dir, is tut-install/examples/case-studies/dukes-bookstore/src/java/dukesbookstore/. The event and listener classes are located in bookstore-dir/listeners/. The component classes are located in bookstore-dir/components/. The renderer classes are located in bookstore-dir/renderers/. ImageArea is located in bookstore-dir/model/.