Document Information


Part I Introduction

1.  Overview

2.  Using the Tutorial Examples

Part II The Web Tier

3.  Getting Started with Web Applications

4.  Java Servlet Technology

5.  JavaServer Pages Technology

6.  JavaServer Pages Documents

7.  JavaServer Pages Standard Tag Library

8.  Custom Tags in JSP Pages

9.  Scripting in JSP Pages

10.  JavaServer Faces Technology

11.  Using JavaServer Faces Technology in JSP Pages

The Example JavaServer Faces Application

Setting Up a Page

Using the Core Tags

Adding UI Components to a Page Using the HTML Component Tags

UI Component Tag Attributes

The id Attribute

The immediate Attribute

The rendered Attribute

The style and styleClass Attributes

The value and binding Attributes

Adding a Form Component

Using Text Components

Rendering a Text Field with the inputText Tag

Rendering a Label with the outputLabel Tag

Rendering a Hyperlink with the outputLink Tag

Displaying a Formatted Message with the outputFormat Tag

Rendering a Password Field with the inputSecret Tag

Using Command Components for Performing Actions and Navigation

Rendering a Button with the commandButton Tag

Rendering a Hyperlink with the commandLink Tag

Using Data-Bound Table Components

Adding Graphics and Images with the graphicImage Tag

Laying Out Components with the UIPanel Component

Rendering Components for Selecting One Value

Displaying a Check Box Using the selectBooleanCheckbox Tag

Displaying a Menu Using the selectOneMenu Tag

Rendering Components for Selecting Multiple Values

The UISelectItem, UISelectItems, and UISelectItemGroup Components

Using the selectItems Tag

Using the selectItem Tag

Displaying Error Messages with the message and messages Tags

Using Localized Data

Loading a Resource Bundle

Referencing Localized Static Data

Referencing Error Messages

Using the Standard Converters

Converting a Component's Value

Using DateTimeConverter

Using NumberConverter

Registering Listeners on Components

Registering a Value-Change Listener on a Component

Registering an Action Listener on a Component

Using the Standard Validators

Validating a Component's Value

Using the LongRangeValidator

Binding Component Values and Instances to External Data Sources

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 Backing Bean Properties

Referencing a Backing Bean Method

Referencing a Method That Performs Navigation

Referencing a Method That Handles an Action Event

Referencing a Method That Performs Validation

Referencing a Method That Handles a Value-change Event

12.  Developing with JavaServer Faces Technology

13.  Creating Custom UI Components

14.  Configuring JavaServer Faces Applications

15.  Internationalizing and Localizing Web Applications

Part III Web Services

16.  Building Web Services with JAX-WS

17.  Binding between XML Schema and Java Classes

18.  Streaming API for XML

19.  SOAP with Attachments API for Java

Part IV Enterprise Beans

20.  Enterprise Beans

21.  Getting Started with Enterprise Beans

22.  Session Bean Examples

23.  A Message-Driven Bean Example

Part V Persistence

24.  Introduction to the Java Persistence API

25.  Persistence in the Web Tier

26.  Persistence in the EJB Tier

27.  The Java Persistence Query Language

Part VI Services

28.  Introduction to Security in the Java EE Platform

29.  Securing Java EE Applications

30.  Securing Web Applications

31.  The Java Message Service API

32.  Java EE Examples Using the JMS API

33.  Transactions

34.  Resource Connections

35.  Connector Architecture

Part VII Case Studies

36.  The Coffee Break Application

37.  The Duke's Bank Application

Part VIII Appendixes

A.  Java Encoding Schemes

B.  About the Authors



Using Custom Objects

As a page author, you might need to use custom converters, validators, or components packaged with the application on your JSP pages.

A custom converter is applied to a component in one of the following ways:

  • Reference the converter from the component tag’s converter attribute.

  • Nest a converter tag inside the component’s tag and reference the custom converter from one of the converter tag’s attributes.

A custom validator is applied to a component in one of the following ways:

  • Nest a validator tag inside the component’s tag and reference the custom validator from the validator tag.

  • Nest the validator’s custom tag (if there is one) inside the component’s tag.

To use a custom component, you add the custom tag associated with the component to the page.

As explained in Setting Up a Page, you must ensure that the TLD that defines any custom tags is packaged in the application if you intend to use the tags in your pages. TLD files are stored in the WEB-INF/ directory or subdirectory of the WAR file or in the META-INF/ directory or subdirectory of a tag library packaged in a JAR file.

You also need to include a taglib declaration in the page so that the page has access to the tags. All custom objects for the Duke’s Bookstore application are defined in bookstore.tld. Here is the taglib declaration that you would include on your page so that you can use the tags from this TLD:

<%@ taglib uri="/WEB-INF/bookstore.tld" prefix="bookstore" %>

When including the custom tag in the page, you can consult the TLD to determine which attributes the tag supports and how they are used.

The next three sections describe how to use the custom converter, validator, and UI components included in the Duke’s Bookstore application.

Using a Custom Converter

As described in the previous section, to apply the data conversion performed by a custom converter to a particular component’s value, you must either reference the custom converter from the component tag’s converter attribute or from a converter tag nested inside the component tag.

If you are using the component tag’s converter attribute, this attribute must reference the Converter implementation’s identifier or the fully-qualified class name of the converter. The application architect provides this identifier when registering the Converter implementation with the application, as explained in Registering a Custom Converter. Creating a Custom Converter explains how a custom converter is implemented.

The identifier for the credit card converter is CreditCardConverter. The CreditCardConverter instance is registered on the ccno component, as shown in this tag from the bookcashier.jsp page:

<h:inputText id="ccno"

By setting the converter attribute of a component’s tag to the converter’s identifier or its class name, you cause that component’s local value to be automatically converted according to the rules specified in the Converter implementation.

Instead of referencing the converter from the component tag’s converter attribute, you can reference the converter from a converter tag nested inside the component’s tag. To reference the custom converter using the converter tag, you do one of the following:

Using a Custom Validator

To register a custom validator on a component, you must do one of the following:

  • Nest the validator’s custom tag inside the tag of the component whose value you want to be validated.

  • Nest the standard validator tag within the tag of the component and reference the custom Validator implementation from the validator tag.

Here is the custom formatValidator tag from the ccno field on the bookcashier.jsp page of the Duke’s Bookstore application:

<h:inputText id="ccno" size="19"
         formatPatterns="9999999999999999|9999 9999 9999 9999|
        9999-9999-9999-9999" />
<h:message styleClass="validationMessage"  for="ccno"/>

This tag validates the input of the ccno field against the patterns defined by the page author in the formatPatterns attribute.

You can use the same custom validator for any similar component by simply nesting the custom validator tag within the component tag.

Creating a Custom Validator describes how to create the custom validator and its custom tag.

If the application developer who created the custom validator prefers to configure the attributes in the Validator implementation rather than allow the page author to configure the attributes from the page, the developer will not create a custom tag for use with the validator.

In this case, the page author must nest the validator tag inside the tag of the component whose data needs to be validated. Then the page author needs to do one of the following:

  1. Set the validator tag’s validatorId attribute to the ID of the validator that is defined in the application configuration resource file. Registering a Custom Validator explains how to configure the validator in the application configuration resource file.

  2. Bind the custom Validator implementation to a backing bean property using the validator tag’s binding attribute, as described in Binding Converters, Listeners, and Validators to Backing Bean Properties.

The following tag registers a hypothetical validator on a component using a validator tag and references the ID of the validator:

<h:inputText id="name" value="#{}"
            size="10" ... >
    <f:validator validatorId="customValidator" />

Using a Custom Component

In order to use a custom component in a page, you need to declare the tag library that defines the custom tag that renders the custom component, as explained in Using Custom Objects, and you add the component’s tag to the page.

The Duke’s Bookstore application includes a custom image map component on the chooselocale.jsp page. This component allows you to select the locale for the application by clicking on a region of the image map:

<h:graphicImage id="mapImage" url="/template/world.jpg"
    usemap="#worldMap" />
    <bookstore:map id="worldMap" current="NAmericas"
        <bookstore:area id="NAmerica" value="#{NA}"
            targetImage="mapImage" />
        <bookstore:area id="France" value="#{fraA}"
            targetImage="mapImage" />

The standard graphicImage tag associates an image (world.jpg) with an image map that is referenced in the usemap attribute value.

The custom map tag that represents the custom component, MapComponent, specifies the image map, and contains a set of area tags. Each custom area tag represents a custom AreaComponent and specifies a region of the image map.

On the page, the onmouseover and onmouseout attributes specify the image that is displayed when the user performs the actions described by the attributes. The page author defines what these images are. The custom renderer also renders an onclick attribute.

In the rendered HTML page, 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. When the user clicks a region, the onclick function sets the value of a hidden input tag to the ID of the selected area and submits the page.

When the custom renderer renders these attributes in HTML, it also renders the JavaScript code. The custom renderer also renders the entire onclick attribute rather than let the page author set it.

The custom renderer that renders the map tag also renders a hidden input component that holds the current area. The server-side objects retrieve the value of the hidden input field and set the locale in the FacesContext instance according to which region was selected.

Chapter 13, Creating Custom UI Components describes the custom tags in more detail and also explains how to create the custom image map components, renderers, and tags.