McGraw hill javaserver faces 2 0 the complete reference

JavaServer Faces 2.0:
The Complete Reference


About the Authors

Ed Burns is a senior staff engineer at Sun Microsystems.
Ed has worked on a wide variety of client- and serverside Web technologies since 1994, including NCSA
Mosaic, Mozilla, the Sun Java Plugin, Jakarta Tomcat,
and most recently, JavaServer Faces. Ed is currently the
co-spec lead for JavaServer Faces. Find Ed’s blog and
other goodies at />Chris Schalk is a Developer Advocate and works
to promote Google’s APIs and technologies. He is
currently engaging the international Web development
community with the new Google App Engine and
OpenSocial APIs. Before joining Google, Chris was a
Principal Product Manager and technology evangelist
at Oracle in the Java development tools group.

About the Contributing Author

Neil Griffin represents Liferay on the JSR 314
(JSF 2.0) expert group and has 15 years of professional
experience in software engineering. As a Liferay
project committer, Neil is responsible for interfacing
with ICEsoft in order to ensure that ICEfaces
integrates properly within Liferay Portal. Neil is the
cofounder of the PortletFaces project, which makes
JSF portlet development easier. He has authored
training classes for Liferay and ICEsoft and has

served as a consultant for clients implementing
JSF and ICEfaces portlets.


JavaServer Faces 2.0:
The Complete Reference
Ed Burns
Chris Schalk
with Neil Griffin

New York Chicago San Francisco
Lisbon London Madrid Mexico City
Milan New Delhi San Juan
Seoul Singapore Sydney Toronto


Copyright © 2010 by The McGraw-Hill Companies. All rights reserved. Except as permitted under the United States Copyright Act of 1976, no part
of this publication may be reproduced or distributed in any form or by any means, or stored in a database or retrieval system, without the prior
written permission of the publisher.
ISBN: 978-0-07-162510-4
MHID: 0-07-162510-0
The material in this eBook also appears in the print version of this title: ISBN: 978-0-07-162509-8, MHID: 0-07-162509-7.
All trademarks are trademarks of their respective owners. Rather than put a trademark symbol after every occurrence of a trademarked name, we
use names in an editorial fashion only, and to the benefit of the trademark owner, with no intention of infringement of the trademark. Where such
designations appear in this book, they have been printed with initial caps.
McGraw-Hill eBooks are available at special quantity discounts to use as premiums and sales promotions, or for use in corporate training programs.
To contact a representative please e-mail us at
Information has been obtained by McGraw-Hill from sources believed to be reliable. However, because of the possibility of human or mechanical
error by our sources, McGraw-Hill, or others, McGraw-Hill does not guarantee the accuracy, adequacy, or completeness of any information and is
not responsible for any errors or omissions or the results obtained from the use of such information.

TERMS OF USE
This is a copyrighted work and The McGraw-Hill Companies, Inc. (“McGraw-Hill”) and its licensors reserve all rights in and to the work. Use of
this work is subject to these terms. Except as permitted under the Copyright Act of 1976 and the right to store and retrieve one copy of the work,
you may not decompile, disassemble, reverse engineer, reproduce, modify, create derivative works based upon, transmit, distribute, disseminate, sell,
publish or sublicense the work or any part of it without McGraw-Hill’s prior consent. You may use the work for your own noncommercial and
personal use; any other use of the work is strictly prohibited. Your right to use the work may be terminated if you fail to comply with these terms.
THE WORK IS PROVIDED “AS IS.” McGRAW-HILL AND ITS LICENSORS MAKE NO GUARANTEES OR WARRANTIES AS TO THE
ACCURACY, ADEQUACY OR COMPLETENESS OF OR RESULTS TO BE OBTAINED FROM USING THE WORK, INCLUDING ANY
INFORMATION THAT CAN BE ACCESSED THROUGH THE WORK VIA HYPERLINK OR OTHERWISE, AND EXPRESSLY DISCLAIM
ANY WARRANTY, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE. McGraw-Hill and its licensors do not warrant or guarantee that the functions contained in the work
will meet your requirements or that its operation will be uninterrupted or error free. Neither McGraw-Hill nor its licensors shall be liable to you or
anyone else for any inaccuracy, error or omission, regardless of cause, in the work or for any damages resulting therefrom. McGraw-Hill has no
responsibility for the content of any information accessed through the work. Under no circumstances shall McGraw-Hill and/or its licensors be liable
for any indirect, incidental, special, punitive, consequential or similar damages that result from the use of or inability to use the work, even if any
of them has been advised of the possibility of such damages. This limitation of liability shall apply to any claim or cause whatsoever whether such
claim or cause arises in contract, tort or otherwise.


To Amy, my best friend, partner, and wife.
Thank you for helping me
achieve my dreams.
—Ed Burns
For my dad, Frank, the coolest
engineer/rocket scientist/cold warrior
there ever was!
As you used to say,
“If you’re going to do something,
do it with Audace!”
—Chris Schalk

To my beloved wife Liz,
and to my dear children, Pauly and Anna.
—Neil Griffin


This page intentionally left blank


Contents at a Glance
Part I The JavaServer Faces Framework
1
2
3
4
5
6
7
8
9

Introduction to JavaServer Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building a Simple JavaServer Faces Application . . . . . . . . . . . . . . . . . . . . .
The JavaServer Faces Request Processing Lifecycle . . . . . . . . . . . . . . . . . . .
The Facelets View Declaration Language . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managed Beans and the JSF Expression Language . . . . . . . . . . . . . . . . . . .
The Navigation Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The User Interface Component Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Converting and Validating Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The JSF Event Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3
15
35
55
67
103
135
155
199

Part II Extending JavaServer Faces
10
11
12
13
14

Applying JSF: Introducing the Virtual Trainer Application . . . . . . . . . . . .
Building Custom UI Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JSF and Ajax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building Non-UI Custom Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Securing JavaServer Faces Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

235
295
339
359
399

Part III JavaServer Faces Tools and Libraries

15
16
A

Configuring JavaServer Faces Applications . . . . . . . . . . . . . . . . . . . . . . . . . .
The Standard JSF Component Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JSF Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

423
525
659

Index

693

...........................................................

vii


This page intentionally left blank


Contents
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xxiii
xxv

Part I The JavaServer Faces Framework
1

Introduction to JavaServer Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What Is JavaServer Faces? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The History of JavaServer Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Common Gateway Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Servlet API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JavaServer Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Apache Struts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Spring Framework and Spring MVC . . . . . . . . . . . . . . . . . . . . . . .
The Birth of JavaServer Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The JavaServer Faces Design Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JSF Application Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The JSF Request Processing Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . .
The JSF Navigation Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3
3
4
4
5
5
6
6
6
7
9
10

12

2

Building a Simple JavaServer Faces Application . . . . . . . . . . . . . . . . . . . . .
Application Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The JSFReg Application Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The JSF Software Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assembling the JSFReg Application . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Facelets Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building and Running the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deploying and Running the Application . . . . . . . . . . . . . . . . . . . . . . .
Reviewing the Key Portions of the Application . . . . . . . . . . . . . . . . . . . . . . . .

15
15
16
17
18
19
20
30
32
32

3

The JavaServer Faces Request Processing Lifecycle . . . . . . . . . . . . . . . . . . .
A High-Level Overview of the JSF Request Processing Lifecycle . . . . . . . . .

What Exactly Does the Request Processing Lifecycle Do? . . . . . . . . .
How Does It Differ from Other Web Technologies? . . . . . . . . . . . . . .
Automatic Server-Side View Management and Synchronization . . .
The Request Processing Lifecycle Phases . . . . . . . . . . . . . . . . . . . . . . .
Observing the Request Processing Lifecycle in Action . . . . . . . . . . . . . . . . . .
Advanced Topics Related to the Request Processing Lifecycle . . . . . . . . . . .
Using the immediate Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

35
35
36
36
37
38
46
50
50

ix


x

JavaServer Faces 2.0: The Complete Reference

Phase Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exception Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Lifecycle Concepts to Remember . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

52

52
53

4

The Facelets View Declaration Language . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Power of Templating in Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Similarities and Differences Between JSP and Facelets . . . . . . . . . . . . . . . . . .
Templating with Facelets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Guide to Facelets Templating Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ui:composition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ui:decorate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ui:define . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ui:insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ui:include . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ui:param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Guide to Nontemplating Facelets Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ui:component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ui:fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ui:remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ui:debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

55
56
57
58
62
62
62
62

62
64
65
65
65
65
65
66

5

Managed Beans and the JSF Expression Language . . . . . . . . . . . . . . . . . . .
What Are Managed Beans? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A Simple Managed Bean Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initializing Managed Bean Properties . . . . . . . . . . . . . . . . . . . . . . . . . .
Declaring Lists and Maps Directly as Managed Beans . . . . . . . . . . . .
Managed Bean Interdependence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Managed Properties Using EL . . . . . . . . . . . . . . . . . . . . . . . . . .
Controlling Managed Bean Life Spans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The JSF Expression Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Important Expression Languages Changes
Between JSF 1.1 and JSF 1.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unified EL Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Value Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Expression Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Method Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Web Application Development Details on Managed Beans . . . . . . . . . . . . .
How to Access Managed Beans Programmatically . . . . . . . . . . . . . . .
Using Managed Beans as Backing Beans for JSF Pages . . . . . . . . . . .

67
68
68
70
78
78
80
81
84

The Navigation Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Implicit Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview of the JSF Navigation System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Recalling MVC—The Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The NavigationHandler—Behind the Scenes . . . . . . . . . . . . . . . . . . . .
A Note on Faces Action Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

103
103
106
107
107
109

6

84
86
87
93

94
97
98
99


Contents

Building Navigation Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A Static Navigation Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A Dynamic Navigation Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
More Sophisticated Navigation Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Conditional Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Redirects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XML Configuration for View Parameters . . . . . . . . . . . . . . . . . . . . . . .
Using JSF Components on a Servlet Error Page . . . . . . . . . . . . . . . . .

109
111
112
116
116
117
118
132
133

7

The User Interface Component Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What Are UI Components? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Rise of Component-Based Web Development . . . . . . . . . . . . . . .
The Goal of JavaServer Faces UI Components . . . . . . . . . . . . . . . . . . .
Introducing the JSF UI Component Architecture . . . . . . . . . . . . . . . . . . . . . .
The UI Component Tree (View) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The UI Component and Its Associated “Moving Parts” . . . . . . . . . . .
Component Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UI Components and Facelets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing UI Components Programmatically . . . . . . . . . . . . . . . . . . .
Helpful Advice for Binding UI Components in JSF Views . . . . . . . .

135
135
136
138
138
143
145
147
147
147
151

8

Converting and Validating Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Some Validation and Conversion Examples . . . . . . . . . . . . . . . . . . . . . . . . . .
Conversion and Validation Under the Covers . . . . . . . . . . . . . . . . . . . . . . . . .
The Faces Converter System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

DateTimeConverter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NumberConverter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Associating a Converter with a UIComponent Instance . . . . . . . . . .
The Lifetime of a Converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Custom Converters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Faces Validation System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LongRangeValidator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DoubleRangeValidator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LengthValidator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The “required” Facility and the RequiredValidator . . . . . . . . . . . . . .
RegExValidator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BeanValidator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Associate a Validator with a UIComponent Instance . . . . . . . . . . . .
Using Markup to Associate a Validator with
a UIComponent Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Markup and the validator Attribute to Associate
a Validator with a UIComponent Instance . . . . . . . . . . . . . . . . . . .
Programmatically Associating a Validator with
a UIComponent Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

155
156
158
162
163
164
164
170
170
175

177
177
177
178
179
179
179
180
181
182

xi


xii

JavaServer Faces 2.0: The Complete Reference

9

The Lifetime of a Validator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Custom Validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Bean Validation from JSF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What Is Bean Validation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Differences Between JSF Validation and Bean Validation . . . . . . . . .
Details on Using Bean Validation from JSF . . . . . . . . . . . . . . . . . . . . .
Validating JSF Managed Bean Properties with Bean Validation . . . .
Tie It All Together: Messages in a View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FacesMessage-Related Methods on FacesContext . . . . . . . . . . . . . . . .
The UIViewRoot and Its Locale Property . . . . . . . . . . . . . . . . . . . . . . .

When and How FacesMessage Instances
Are Created and Added to the FacesContext . . . . . . . . . . . . . . . . .
How FacesMessages Are Rendered . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Messages and Bean Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

183
183
185
185
186
187
189
190
190
192

The JSF Event Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A High-Level Overview of the JSF Event Model . . . . . . . . . . . . . . . . . . . . . . .
Some Event Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How JSF Events Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Faces Event Listener Interfaces and Event Classes . . . . . . . . . . .
When Are Faces Events Processed? . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Anatomy of a Value Change Event . . . . . . . . . . . . . . . . . . . . . . . .
Writing Custom Action and Value Change Listeners . . . . . . . . . . . . . . . . . . .
More Faces Event Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using a Value Change Event to Auto-Fill Fields . . . . . . . . . . . . . . . . .
Extending the Value Change Example . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Phase Events and Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using a PhaseListener to Observe the Faces Lifecycle in Action . . .

Working with SystemEvents and Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . .
How SystemEvents Are Published . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Subscribe to SystemEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General Rules for Creating Custom Application Events and Listeners . . . .
Creating Custom SystemEvent and
ComponentSystemEvent Classes . . . . . . . . . . . . . . . . . . . . . . . . . . .

199
199
200
203
204
205
209
211
212
215
215
219
221
221
224
227
227
229

192
193
196

230

Part II Extending JavaServer Faces
10

Applying JSF: Introducing the Virtual Trainer Application . . . . . . . . . . . .
A Quick Tour of the Virtual Trainer Application . . . . . . . . . . . . . . . . . . . . . . .
Registering and Logging In to the Virtual Trainer Application . . . . .
Creating a New Training Event Workout Plan . . . . . . . . . . . . . . . . . .
Choosing Your Trainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Actions Available Only to Trainers . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Virtual Trainer Application Requirements . . . . . . . . . . . . . . . . . . . . . . . .
The Virtual Trainer Application Architecture . . . . . . . . . . . . . . . . . . . . . . . . . .

235
236
236
237
239
239
243
243


Contents

11

Facelet Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Pages in the Web Application Root . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Pages in the /user Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Pages in the /trainer Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Pages in the /resources Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Backing Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Persistence and Transaction Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Navigation Concerns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Simple Authentication System . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Revisiting JSFReg: Building the Registration System . . . . . . . . . . . . . . . . . . .
Building the Core Pages of the Virtual Trainer Application . . . . . . . . . . . . .
Creating the allEvents.xhtml Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Trainer Version of editTrainingEvent.xhtml . . . . . . . . . . . . . . . . .
Creating the viewTrainees.xhtml
and viewTrainingSessionsForUser.xhtml Pages . . . . . . . . . . . . . . .
The UserRegistry and EventRegistry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing and Initializing the UserRegistry Instance . . . . . . . . . . . . .
Reading and Writing User Instances . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reading and Writing TrainingSession Instances . . . . . . . . . . . . . . . . .
Accessing and Initializing the EventRegistry Instance . . . . . . . . . . . . . . . . . .
Reading and Writing Event Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JPA and the Entity Classes in Virtual Trainer . . . . . . . . . . . . . . . . . . . . . . . . . .
JPA XML Configuration File: persistence.xml . . . . . . . . . . . . . . . . . . .
A Custom ExceptionHandler Example . . . . . . . . . . . . . . . . . . . . . . . . .
Internationalizing the Virtual Trainer Application . . . . . . . . . . . . . . . . . . . . .
Localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Final Comments on Virtual Trainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

244
244
244
245

245
246
248
252
255
259
263
263
266

Building Custom UI Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deciding When to Build a Custom UI Component . . . . . . . . . . . . . . . . . . . . .
What Are UI Components? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A Simple JSF UI Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Code Behind the Markup of This Simple JSF UI Component . . . . . . . .
Introduction to Resource Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Behavior to a Composite Component . . . . . . . . . . . . . . . . . . . . . . . . .
A First Look into the Details of Composite Components . . . . . . . . . .
The #{cc} Implicit Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Parts of a UI Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A Noncomposite JSF Custom UIComponent . . . . . . . . . . . . . . . . . . . . . . . . . .
Building the HtmlHelloWorld Example . . . . . . . . . . . . . . . . . . . . . . . .
A HelloWorld UI Component That Accepts Form Input . . . . . . . . . .
A JSF Stock Quote Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
State Management with Custom Components . . . . . . . . . . . . . . . . . . . . . . . .
Writing to a StateHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reading from a StateHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing Values from a StateHelper . . . . . . . . . . . . . . . . . . . . . . . . . .

295

295
296
297
299
300
301
303
305
306
307
307
312
314
316
317
318
318

269
272
272
273
275
277
278
280
281
282
284
285

294

xiii


xiv

JavaServer Faces 2.0: The Complete Reference

Extracting Rendering Code into a Renderer . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Custom Facelet Tag Library TagHandler . . . . . . . . . . . . . .
Using a RenderKit to Support Multiple Client Device Types . . . . . .
Advanced Composite Component Development . . . . . . . . . . . . . . . . . . . . . .
Creating a Backing Class for <vt:loginPanel> . . . . . . . . . . . . . . . . . . .
Composite Component Feature Review . . . . . . . . . . . . . . . . . . . . . . . .
Packaging JSF Components into a Self-Contained Jar . . . . . . . . . . . . . . . . . .
Packaging a Composite Component into a Jar . . . . . . . . . . . . . . . . . . . . . . . .
Packaging a Composite Component Facelet File . . . . . . . . . . . . . . . . .
Declaring a Custom Namespace URL for
a Composite Component Library . . . . . . . . . . . . . . . . . . . . . . . . . . .
Packaging Backing Classes for a Composite Component . . . . . . . . .
Packaging a Noncomposite Component into a Jar . . . . . . . . . . . . . . . . . . . . .
How the JSF Runtime Loads faces-config.xml Files . . . . . . . . . . . . . .
How the JSP Runtime Loads TLD Files . . . . . . . . . . . . . . . . . . . . . . . .

318
320
322
330
330

335
335
336
336

12

JSF and Ajax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ajax Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A Simple Ajax Example from JSFReg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ajax JSFReg Behind the Scenes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The <f:ajax> Tag and Its Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Standard JavaScript Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Advanced Topics on JSF and Ajax . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

339
339
341
343
349
356
357

13

Building Non-UI Custom Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Non-UI Custom Components and Decoration in JSF . . . . . . . . . . . . . . . . . . .
Wrapper Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Non-View Custom Components Explained . . . . . . . . . . . . . . . . . . . . . . . . . . .
PhaseListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Interface to Implement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registering a PhaseListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Converter and Validator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interfaces to Implement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registering a Converter or Validator . . . . . . . . . . . . . . . . . . . . . . . . . . .
ViewHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Abstract Class to Extend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registering a ViewHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VariableResolver and PropertyResolver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Abstract Classes to Extend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registering a VariableResolver or PropertyResolver . . . . . . . . . . . . .
ELResolver (JSF 1.2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ELResolver Chain of Responsibility . . . . . . . . . . . . . . . . . . . . . . .
Abstract Class to Extend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registering an ELResolver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

359
359
362
363
363
363
364
364
364
365
365
365
365
366

367
368
369
369
372
374

336
337
337
337
338


Contents

14

NavigationHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Abstract Class to Extend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registering a NavigationHandler or
ConfigurableNavigationHandler . . . . . . . . . . . . . . . . . . . . . . . . . . .
ActionListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interface to Implement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registering an ActionListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
StateManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Abstract Class to Extend in JSF 1.1 and 1.0 . . . . . . . . . . . . . . . . . . . . . .
Abstract Class to Extend in JSF 1.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registering a StateManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RenderKit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Factories in JSF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registering a Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RenderKitFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ExceptionHandlerFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FacesContextFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ExternalContextFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LifecycleFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PartialViewContextFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ViewDeclarationLanguageFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VisitContextFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Additional Non-UIComponent Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Telling the JSF Runtime Where You Are
in the Software Development Lifecycle: ProjectStage . . . . . . . . . .
Custom Scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

378
378

Securing JavaServer Faces Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Aspects and Implementation of Web Application Security . . . . . . . . . . . . . .
Container-Managed Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Container-Managed Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . .
Basic Authentication and the Concept of a “Realm” . . . . . . . . . . . . .
Form-Based Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Certificate Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Container-Managed Authorization and the Concept of Roles . . . . .
Container-Managed Data Security . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A Small Security Improvement in the Virtual Trainer . . . . . . . . . . . .
Application-Managed Security with JavaServer Faces . . . . . . . . . . . . . . . . . .

Leveraging JAAS from a JSF Application . . . . . . . . . . . . . . . . . . . . . . .
To Learn More about Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

399
399
400
400
401
402
405
407
408
410
411
411
419

379
379
380
380
380
380
382
382
382
383
384
386
388

388
389
390
391
391
392
393
396
396
397

xv


xvi

JavaServer Faces 2.0: The Complete Reference

Part III JavaServer Faces Tools and Libraries
15

Configuring JavaServer Faces Applications . . . . . . . . . . . . . . . . . . . . . . . . . .
Understanding XML Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Understanding How Configuration Files Are Processed . . . . . . . . . . . . . . . .
Ordering of faces-config.xml Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How the JSF Runtime Scans Classes for Configuration Annotations . . . . . .
The Faces Configuration Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The absolute-ordering Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The action-listener Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The after Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The application Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The application-factory Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The attribute Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The attribute-class Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The attribute-name Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The base-name Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The before Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The behavior Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The behavior-class Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The behavior-id Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The client-behavior-renderer Element . . . . . . . . . . . . . . . . . . . . . . . . . .
The client-behavior-renderer-class Element . . . . . . . . . . . . . . . . . . . . .
The client-behavior-renderer-type Element . . . . . . . . . . . . . . . . . . . . .
The component Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The component-class Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The component-family Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The component-type Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The converter Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The converter-class Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The converter-for-class Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The converter-id Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The default-locale Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The default-render-kit-id Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The default-validators Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The default-value Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The el-resolver Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The exception-handler-factory Element . . . . . . . . . . . . . . . . . . . . . . . .
The external-context-factory Element . . . . . . . . . . . . . . . . . . . . . . . . . .
The faces-config Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The faces-context-factory Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The facet Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The facet-name Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The factory Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

423
425
425
426
427
427
437
437
438
439
440
440
443
443
444
445
445
446
447
448
449
449
450
451
451
452

453
454
454
455
456
457
458
459
460
460
461
462
463
463
465
465


Contents

The from-action Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The from-outcome Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The from-view-id Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The if Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The key Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The key-class Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The lifecycle Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The lifecycle-factory Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The list-entries Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The locale-config Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The managed-bean Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The managed-bean-class Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The managed-bean-name Element . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The managed-bean-scope Element . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The managed-property Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The map-entries Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The map-entry Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The message-bundle Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The name Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The navigation-case Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The navigation-handler Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The navigation-rule Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The null-value Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ordering Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The others Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The partial-view-context-factory Element . . . . . . . . . . . . . . . . . . . . . .
The phase-listener Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The property Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The property-class Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The property-name Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The property-resolver Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The redirect Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The referenced-bean Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The referenced-bean-class Element . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The referenced-bean-name Element . . . . . . . . . . . . . . . . . . . . . . . . . . .
The render-kit Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The render-kit-class Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The render-kit-factory Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The render-kit-id Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The renderer Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The renderer-class Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The renderer-type Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The resource-bundle Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The resource-handler Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

466
467
467
468
469
470
471
471
472
473
474
475
475
476
477
479
480
481
482
483
484
485
486
488
488

489
490
491
492
493
494
494
495
496
497
498
499
499
500
501
502
503
503
504

xvii


xviii

JavaServer Faces 2.0: The Complete Reference

16

The source-class Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The state-manager Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The suggested-value Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The supported-locale Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The system-event-class Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The system-event-listener Element . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The system-event-listener-class Element . . . . . . . . . . . . . . . . . . . . . . .
The tag-handler-delegate-factory Element . . . . . . . . . . . . . . . . . . . . . .
The to-view-id Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The validator Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The validator-class Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The validator-id Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The value Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The value-class Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The var Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The variable-resolver Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The view-declaration-language-factory Element . . . . . . . . . . . . . . . .
The view-handler Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The view-param Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The visit-context-factory Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Extension Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Metadata Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

504
505
506
507
508
509
510
510

511
511
512
513
514
516
517
518
518
519
520
521
521
523

The Standard JSF Component Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A Brief Review of JSF, Facelets, and JSP Tag Nomenclature . . . . . . . . . . . . .
Acquiring and Installing the Standard Libraries . . . . . . . . . . . . . . . . . . . . . . .
What You Get (Binary) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What You Get (Source) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Tag Library Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Standard Core Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:actionListener Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:ajax Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:attribute Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:convertDateTime Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:convertNumber Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:converter Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:event Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:facet Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The f:loadBundle Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:metadata Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:param Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:phaseListener Tag (1.2, 2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:selectItem Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:selectItems Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:setPropertyActionListener Tag (1.2, 2.0 Only) . . . . . . . . . . . . . .

525
525
526
527
527
527
527
530
531
533
533
535
537
538
538
539
540
540
541
541
542
544

Contents

The f:subview Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:validateBean Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:validateDoubleRange Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:validateLength Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:validateLongRange Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:validateRegex Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:validateRequired Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:validator Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:valueChangeListener Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:verbatim Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:view Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The f:viewParam Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Standard HTML Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:body Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:button Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:column Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:commandButton Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:commandLink Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:dataTable Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:form Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:graphicImage Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:head Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:inputHidden Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:inputSecret Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:inputText Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:inputTextarea Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The h:link Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:message Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The messages Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:outputFormat Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:outputLabel Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:outputLink Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:outputScript Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:outputStylesheet Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:outputText Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:panelGrid Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:panelGroup Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:selectBooleanCheckbox Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:selectManyCheckbox Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:selectManyListbox Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:selectManyMenu Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:selectOneListbox Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:selectOneMenu Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The h:selectOneRadio Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

545
547
549
550
551
552
552
553
554
555
556

557
559
562
563
565
567
570
573
576
578
580
581
582
585
588
591
594
596
597
598
600
602
603
605
606
608
609
612
615
618

621
624
627

xix


xx

JavaServer Faces 2.0: The Complete Reference

A

The Standard Facelets Templating Library (2.0) . . . . . . . . . . . . . . . . . . . . . . .
Example Website Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ui:component Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ui:composition Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ui:debug Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ui:decorate Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ui:define Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ui:fragment Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ui:include Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ui:insert Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ui:param Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ui:remove Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ui:repeat Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Standard Facelets Composite Component Library (2.0) . . . . . . . . . . . . .
Example Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The cc:actionSource Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The cc:attribute Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The cc:editableValueHolder Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . .
The cc:extension Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The cc:facet Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The cc:implementation Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The cc:insertChildren Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The cc:insertFacet Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The cc:interface Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The cc:renderFacet Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The cc:valueHolder Tag (2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

631
632
636
637
637
638
639
639
640
640
641
641
642
643
645
650
651
652
653
654

654
655
655
656
657
658

JSF Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview of Portlet 1.0 and 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Portlet Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Portlet Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Portlet Window States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Portlet Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inter-Portlet Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JSF Portlet Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JSF Portlet Bridges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JSF Portlet View Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JSF ExternalContext and the Portlet API . . . . . . . . . . . . . . . . . . . . . . . .
JSF and Portlet Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JSF and Inter-Portlet Communication . . . . . . . . . . . . . . . . . . . . . . . . . .
ICEfaces Portlet Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ICEfaces Ajax with Partial Submit . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ICEfaces Direct-to-DOM RenderKit . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ice:portlet Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ICEfaces 1.x Portlet Bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

659
659
659
660

661
661
662
663
663
667
668
668
670
672
672
673
673
674


Contents

ICEfaces 1.x D2DFaceletViewHandler . . . . . . . . . . . . . . . . . . . . . . . . .
ICEfaces 1.x and Portlet Window States . . . . . . . . . . . . . . . . . . . . . . . .
ICEfaces Portlets and Concurrent DOM Views . . . . . . . . . . . . . . . . . .
ICEfaces 1.x Extended Request Scope . . . . . . . . . . . . . . . . . . . . . . . . . .
ICEfaces Ajax Push and Inter-Portlet Communication . . . . . . . . . . . .
ICEfaces Themes and Portal Themes . . . . . . . . . . . . . . . . . . . . . . . . . .
ICEfaces Themes and Liferay Themes . . . . . . . . . . . . . . . . . . . . . . . . .
ICEfaces Ajax Bridge and Liferay Portal . . . . . . . . . . . . . . . . . . . . . . . .
ICEfaces Portlets and Liferay Request Attributes . . . . . . . . . . . . . . . .
PortletFaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Downloading PortletFaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PortletFacesContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PortletFaces Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PortletFaces and Portlet Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . .
PortletFaces Expression Language Additions . . . . . . . . . . . . . . . . . . .
PortletFaces and Localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Liferay Language Portlet Integration . . . . . . . . . . . . . . . . . . . . . . . . . .
Improved Integration Between Liferay and ICEfaces 1.x . . . . . . . . . .

674
675
675
675
676
679
680
681
682
682
683
684
685
686
687
689
690
690

Index

693

...........................................................

xxi


This page intentionally left blank


Acknowledgments

J

avaServer Faces is a foundation technology that builds on top of many other layers of
software technology. Like any foundation software product, it is the result of the hard
work and dedication of many individuals and organizations over many years of time.
It is the same way with books that document such technologies, and I’d like to take the
opportunity to thank some of the people who helped make this book, and JavaServer Faces
itself, possible.
In a world where more and more information is available only online, and much of that
information is coming from self-published individuals, I want to say that the publishing
system is still the best way to deliver high-quality useful information in a portable and easily
digestible way. A Web reference is no substitute for a dog-eared, marked-up, and well-worn
book. After working with the publishing team at McGraw-Hill, I know why this is so.
Our editor, Herb Schildt, has been my mentor as well as providing sure guidance as I made
my way through this large book. Thanks, Herb, for your veteran insights. Acquisitions
coordinator Joya Anthony did a great job keeping together all the disparate parts of the book.
McGraw-Hill editorial director Wendy Rinaldi went through plenty of ups and downs on
this project but never lost confidence; I am proud to deliver this book for her. Thanks to copy
editor Robert Campbell and project manager Smita Rajan.
To my wonderful wife, Amy. Thank you for your understanding and patience as I spent

all this time on this book; you picked up the slack in our family big-time. I could not have
done it without your help and commitment. Thanks also to my sons, Owen and Logan, for
understanding why Daddy was away all that time.
I need to thank those who brought me to, worked on, and helped complete JSF. Naturally,
JSF is a JCP project, so the expert group deserves prominent mention. Key members of the
JSF 2.0 expert group, in alphabetical order, include Dan Allen, Keith Donald, Mike Freedman,
David Geary, Ted Goddard, Jeremy Grelle, Roger Keays, Gavin King, Jason Lee, Ryan Lubke,
Craig McClanahan, Kito Mann, Martin Marinschek, Pete Muir, Joseph Ottinger, Ken Paulsen,
Andy Schwartz, Alexandr Smirnov, and Adam Winer. Not only is JSF a JCP project, it is also
a community-driven project, and there are many people to thank who have helped JSF
succeed in the developer community. Some of these people include Lincoln Baxter III,
Dennis Byrne, Çag˘atay Çivici, Hanspeter Dünnenberger, Alexander Jesse, Max Katz,
Alberto Lemos (Dr. Spock), Imre Oßwald, Hazem Saleh, Stan Silvert, Yara and Vinicius
Senger, and Matthias Weßendorf. George Drapeau recommended I interview for the job
of leading the implementation team back in 2001. Thanks, George! Amy Fowler, the
original spec lead, profoundly influenced the success of JSF and was a joy to work with.

xxiii


xxiv

JavaServer Faces 2.0: The Complete Reference

Jim Driscoll, Mimi Hills, Tony Ng, Sridatta Viswanath, and Barbara Louis have been
supportive managers throughout the development of JSF. To my original core JSF team
of Jayashri Visvanathan and Roger Kitain, I give deepest thanks. You are the soul of this
project and I have never worked with a better team. Ryan Lubke, Justyna Horwat, and
Jennifer Ball deserve thanks as the extended JSF implementation team. Ryan, you also
deserve special thanks for your unswerving commitment to quality and innovation in

continuing to lead Sun’s JSF implementation. I want to thank Jacob Hookom for his
contribution to the JSF ecosystem in the form of Facelets, and his continuing creativity in
establishing JSF as the best way to do AJAX.
I want to extend a special thank you to Neil Griffin for his writing Chapters 15, 16, and
the Appendix.
Of course, I have to thank Chris Schalk for bringing me in to this project and for being
a great collaborator. I know I am not the easiest person to work with at such close proximity,
and I thank you for your patience and continued advocacy of the novice user and reader.
Without you, there would be no book.
Finally, I want to thank the unswerving support team of Mom, Dad, Brendan Burns,
Lisa Lane, Diana Dean, Jeff Beckberger, Joe McCabe, and Vern Singleton.
—Ed Burns
Altamonte Springs, FL