JavaServer Faces 2.0: The Complete Reference

JavaServer

Faces

2.0:

The

_Complete

Reference

TIB/UB Hannover 89 133 219 50X

Contents

Acknowledgments

xxiii

Introduction

, xxv

Part §

The JavaServer

Faces Framework

1 Introductionto

_JavaServer

Faces 3

What Is

_JavaServer

Faces? 3

The

_History

of

_JavaServer

Faces . 4

TheCommon

_Gateway

Interface , 4

TheServlet API

₅

JavaServer Pages

5

Apache

Struts 6

The

_Spring

Framework and

_Spring

MVC 6

The Birth of

_JavaServer

Faces 6

The

_JavaServer

Faces

_Design

Goals 7

JSF

Application

Architecture 9

The

JSF

Request

Processing Lifecycle

. 10

The

_{JSF Navigation}

Model 12

2

_Building

a

Simple

JavaServer

Faces

_Application

. 15

Application

Overview 15

The

_{JSFReg Application}

Files 16

The

_JSF

Software Stack 17

Assembling

the

_{JSFReg Application}

18

The

_{Configuration}

File 19

TheFacelets

_Pages

20

Building

and

_Running

the

_Application

30

Deploying

and

_Running

the

_Application

32

Reviewing

the

_Key

Portionsof the

_Application

32

3 The

_JavaServer

Faces

_{Request Processing Lifecycle}

35

A

_High-Level

Overview of the

_JSF

_{Request Processing Lifecycle}

35

What

_Exactly

Doesthe

_{Request Processing Lifecycle}

Do? 36 HowDoes It DifferfromOtherWeb

_{Technologies?}

36 Automatic Server-SideView

_Management

and

_{Synchronization}

... 37

The

_{Request Processing Lifecycle}

Phases .. 38

Observing

the

_{Request Processing Lifecycle}

in Action 46 Advanced

_Topics

Relatedtothe

_{Request Processing Lifecycle}

... 50

Using

the immediate Attribute 50

X JavaServer Faces 2.0: The

_Complete

Reference

PhaseListeners 52

Exception

Handler 52

Lifecycle

Concepts

toRemember 53

4 TheFacelets View Declaration

_Language

55

ThePower of

_Templating

in Faces 56

Similarities and Differences Between

_JSP

and Facelets 57

Templating

with Facelets 58

Guideto Facelets

_Templating

_Tags

62

uixomposition

62 ukdecorate 62 ukdefine 62 ukinserl 62 ui:include 64

uiparam

65

Guideto

_{Nontemplating}

Facelets

_Tags

65

ukcomponent

65

ui:fragment

65

ui:remove 65

ukdebug

66

5

_Managed

Beans and the

_JSF

_{Expression Language}

67

What Are

_Managed

Beans? 68

A

_{Simple Managed}

Bean

_Example

68

Initializing Managed

Bean

_Properties

70

Declaring

Lists and

_Maps

_Directly

as

Managed

Beans 78

Managed

Bean

_{Interdependence}

78

Setting

Managed

Properties

Using

EL 80

Controlling Managed

Bean Life

_Spans

81

The

_JSF

_Expression

_Language

84

Important Expression Languages

Changes

Between

_JSF

1.1 and

_JSF

1.2 84

Unified EL

_Concepts

86

Value

_Expressions

87

Expression Operators

93

Method

_Expressions

94

Web

_{Application Development}

Details on

Managed

Beans 97

HowtoAccess

_Managed

Beans

_{Programmatically}

98

Using Managed

Beansas

Backing

Beansfor

JSF

Pages

99

6 The

_Navigation

Model 103

Using Implicit Navigation

103

Overview of the

_{JSF Navigation System}

106

Recalling

MVC—The Controller 107

The

_{NavigationHandler—Behind}

the Scenes 107

Contents

_xi

Building

Navigation

Rules ₁₀₉

A Static

_Navigation

_Example

_Ill

A

_{Dynamic Navigation Example}

₁₁₂

More

_{Sophisticated}

_Navigation

_Examples

₁₁₆

Using

Wildcards ₁₁₆

Using

Conditional

_Navigation

₁₁₇

Using

Redirects ₁₁₈

XML

_{Configuration}

forView

Parameters

132

Using JSF Components

on a Servlet Error

_Page

₁₃₃

7 The User Interface

_Component

Model ₁₃₅

WhatAre UI

_Components?

₁₃₅

TheRise of

_{Component-Based}

Web

_Development

136

The Goal of

_JavaServer

Faces UI

_Components

138

Introducing

the

_JSF

UI

_Component

Architecture 138

The UI

_Component

Tree

_(View)

143

The UI

_Component

and ItsAssociated

_"Moving

Parts" 145

Component

Resources ₁₄₇

UI

_Components

andFacelets 147

Accessing

UI

_{Components Programmatically}

147

Helpful

Advicefor

_Binding

UI

_Components

in

_JSF

Views 151

8

_Converting

and

_Validating

Data ₁₅₅

SomeValidation andConversion

_Examples

156

Conversion andValidation Under the Covers 158

The FacesConverter

_System

162

DateTimeConverter 163

NumberConverter 164

Associating

aConverter witha

UlComponent

Instance 164

The Lifetime ofaConverter 170

Custom Converters 170

The Faces Validation

_System

175

LongRangeValidator

177

DoubleRangeValidator

177

LengthValidator

177

The

_{"required" Facility}

and the

_{RequiredValidator}

178

RegExValidator

179

BeanValidator 179

How toAssociateaValidator witha

UlComponent

Instance 179

Using Markup

toAssociateaValidator with

a

UlComponent

Instance 180

Using Markup

and the validator AttributetoAssociate

aValidator witha

UlComponent

Instance 181

Programmatically Associating

a Validator with

Xlj

JavaServer Faces 2.0: The

Complete

Reference

The Lifetimeofa Validator 183

Custom Validators 183

Using

Bean Validationfrom

JSF

185

WhatIsBean Validation? 185

Differences Between

JSF

Validationand BeanValidation 186

Details on

Using

Bean Validation from

JSF

187

Validating

JSF

Managed

Bean

_Properties

with Bean Validation .... 189

Tie It All

_{Together: Messages}

ina View 190

FacesMessage-Related

MethodsonFacesContext 190

The UIViewRoot and ItsLocale

_Property

192

When and How

_FacesMessage

Instances

AreCreated and Addedto theFacesContext 192

How

_{FacesMessages}

AreRendered 193

Messages

and Bean Validation 196

9 The

_JSF

EventModel 199

A

_High-Level

Overview of the

_JSF

Event Model 199

Some Event

_Examples

200

How

_JSF

Events Work 203

The Faces Event ListenerInterfacesand EventClasses 204

When AreFacesEventsProcessed? 205

Application

Events 209

The

_Anatomy

ofaValue

Change

Event 211

Writing

Custom Action and Value

_Change

Listeners 212

More Faces Event

_Examples

215

Using

aValue

Change

Event to Auto-FillFields 215

Extending

the Value

_Change

_Example

219

Working

with PhaseEvents and Listeners 221

Using

aPhaseListener toObserve the Faces

_Lifecycle

in Action .. . 221

Working

with

_SystemEvents

and Listeners 224

How

_SystemEvents

Are Published 227

Howto Subscribe to

_SystemEvents

227

General Rules for

_Creating

Custom

_Application

Events and Listeners .... 229

Creating

Custom

_SystemEvent

and

ComponentSystemEvent

Classes 230

Part ii

_Extending

JavaServer Faces

10

_{Applying JSF: Introducing}

the VirtualTrainer

_Application

235

A

Quick

Tourof the VirtualTrainer

_Application

236

Registering

and

_Logging

In to theVirtual Trainer

_Application

236

Creating

aNew

_Training

Event WorkoutPlan 237

Choosing

Your Trainer 239

ActionsAvailable

_Only

to Trainers 239

The VirtualTrainer

_{Application Requirements}

243

Contents

xiii

Facelet

_Pages

244

Pages

inthe Web

_Application

Root 244

Pages

in the

/user

_Directory

244

Pages

in the

/trainer

_Directory

245

Pages

in the

/

resources

_Directory

245

Backing

Beans , 246

Persistence and Transaction

Architecture

248

Navigation

Concerns 252

Creating

a

Simple

Authentication

_System

255

Revisiting

JSFReg:

Building

the

_{Registration System}

259

Building

the Core

_Pages

ofthe Virtual Trainer

_Application

263

Creating

the

allEvents.xhtml

_Page

263

The TrainerVersion of

_{editTrainingEvent.xhtml}

266

Creating

the viewTrainees.xhtml

and

_{viewTrainingSessionsForUser.xhtml Pages}

269

The

_UserRegistry

and

_{EventRegistry}

272

Accessing

and

_Initializing

the

_UserRegistry

Instance 272

Reading

and

_Writing

User Instances 273

Reading

and

_{Writing TrainingSession}

Instances 275

Accessing

and

_Initializing

the

_{EventRegistry}

Instance 277

Reading

and

_Writing

Event Instances 278

JPA

and the

_Entity

Classesin Virtual Trainer 280

JPA

XML

_{Configuration}

File:

_{persistence.xml}

281

A Custom

_{ExceptionHandler}

_Example

282

Internationalizing

the VirtualTrainer

_Application

284

Localization 285

Final CommentsonVirtual Trainer 294

11

_Building

Custom UI

_Components

295

Deciding

Whento Build aCustom UI

_Component

295

WhatAre UI

_Components?

296

A

_Simple

_JSFU1

_Component

297

The Code Behind the

_Markup

of This

_Simple

_JSF

UI

_Component

299

IntroductiontoResource Libraries 300

Adding

Behaviortoa

_{Composite Component}

301

A First Look into the Details of

_{Composite Components}

303

The

#{cc)

Implicit Object

305

ThePartsofaUI

_Component

306

A

_Noncomposite

_JSF

Custom

_UlComponent

307

Building

theHtmlHelloWorld

_Example

307

AHelloWorld UI

_Component

That

_Accepts

Form

_Input

312

A

JSF

Stock

Quote

Component

314

State

_Management

with Custom

_Components

316

Writing

toa

StateHelper

317

Reading

froma

StateHelper

318

Xiv Ja vaSe r v e r Faces 2.0: The

Complete

Reference

Extracting Rendering

Code into a Renderer 318

Creating

a CustomFacelet

Tag Library TagHandler

320

Using

a RenderKit to

Support Multiple

Client Device

Types

322

Advanced

_{Composite Component Development}

330

Creating

a

Backing

Class for

<vt:loginPanel>

330

Composite Component

Feature Review 335

Packaging

JSF

Components

into aSelf-Contained

Jar

335

Packaging

a

Composite Component

intoa

Jar

336

Packaging

a

Composite

Component

Facelet File 336

Declaring

aCustom

Namespace

URL for

a

Composite Component Library

336

Packaging Backing

Classes for a

_Composite

Component

337

Packaging

a

Noncomposite

Component

intoa

Jar

337

How the

JSF

RuntimeLoads

_{faces-config.xml}

Files 337

How the

JSP

Runtime Loads T LD Files 338

12 JSF and

Aj

ax 339

Ajax

Overview 339

A

_Simple

_Ajax

_Example

from

_JSFReg

341

Ajax

JSFReg

Behind theScenes 343

The

_{<f:ajax> Tag}

and ItsAttributes 349

The Standard

_JavaScript

Resource 356

Advanced

_Topics

on

JSF

and

Ajax

357

13

_Building

Non-UI Custom

_Components

359

Non-UICustom

_Components

and Decorationin

_JSF

359

Wrapper

Classes 362

Non-View Custom

_{Components Explained}

363

PhaseListener 363

Interfaceto

_Implement

363

Registering

aPhaseListener 364

Converter and Validator 364

Interfaces to

_Implement

364

Registering

a ConverterorValidator 365

ViewHandler ₃₆₅

AbstractClasstoExtend 365

Registering

aViewHandler 365

VariableResolverand

_{PropertyResolver}

366

Abstract Classes toExtend 367

Registering

aVariableResolveror

_{PropertyResolver}

368

ELResolver(JSF1.2)

369

TheELResolver Chain of

_{Responsibility}

369

Abstract ClasstoExtend 372

Contents _XV

NavigationHandler

378

AbstractClass toExtend 378

Registering

a

_{NavigationHandler}

or

ConfigurableNavigationHandler

379 ActionListener ₃₇₉ Interface to

_Implement

₃₈₀

Registering

anActionListener 380

StateManager

380

Abstract Classto Extend in

_JSF

1.1 and1.0 380

AbstractClassto Extend in

_JSF

1.2 382

Registering

a

StateManager

382 RenderKit ₃₈₂ Factories in

_JSF

₃₈₃

Registering

a

Factory

384

RenderKitFactory

386

ExceptionHandlerFactory

388

FacesContextFactory

388

ExternalContextFactory

389

LifecycleFactory

390

PartialViewContextFactory

391

ViewDeclarationLanguageFactory

391

VisitContextFactory

392

Application Factory

393

Additional

_{Non-UIComponent}

_Topics

₃₉₆

Telling

the

_JSF

Runtime Where You Are

in theSoftware

_{Development Lifecycle:}

_ProjectStage

396

Custom

_Scopes

397

14

_Securing

_JavaServer

Faces

_Applications

399

Aspects

and

_{Implementation}

of Web

_{Application Security}

399

Container-Managed Security

400

Container-Managed

Authentication 400

BasicAuthentication and the

_Concept

ofa "Realm" 401

Form-Based Authentication 402

Certificate Authentication 405

Container-Managed

Authorization and the

_Concept

of Roles 407

Container-Managed

Data

_Security

408

A Small

_{Security Improvement}

inthe Virtual Trainer 410

Application-Managed

Security

with

_JavaServer

Faces 411

Leveraging

J

AAS froma

JSF

Application

411

Xvi

JavaServer Faces 2.0: The

_Complete

Reference

Part II!

JavaServer

Faces

Tools and Libraries

15

_Configuring

_JavaServer

Faces

_Applications

423

Understanding

XML Schemas 425

Understanding

How

_{Configuration}

FilesAreProcessed 425

Ordering

of

_{faces-config.xml}

Files 426

How the

_JSF

Runtime ScansClasses for

_{Configuration}

Annotations 427

TheFaces

_{Configuration}

Elements 427

The

_{absolute-ordering}

Element 437

The action-listener Element 437

The

after

Element 438

The

_application

Element 439

The

_{application-factory}

Element 440

The attribute Element 440

The attribute-class Element 443

The attribute-name Element 443

The base-name Element 444

The before Element 445

The behavior Element 445

The behavior-class Element 446

The behavior-id Element 447

The client-behavior-renderer Element 448

The client-behavior-renderer-classElement 449

The

_{client-behavior-renderer-type}

Element 449

The

_component

Element 450

The

_{component-class}

Element 451

The

_{component-family}

Element 451

The

_{component-type}

Element 452

The converterElement 453

The converter-class Element 454

The converter-for-dass Element 454

The converter-id Element 455

The default-locale Element 456

The default-render-kit-id Element 457

The default-validators Element 458

The default-value Element 459

The el-resolver Element 460

The

_{exception-handler-factory}

Element 460

The

_{external-context-factory}

Element 461 The

_faces-config

Element 462 The

_{faces-context-factory}

Element 463

ThefacetElement 463

The facet-nameElement 465

Contents

_xvii

The from-action Element 466

The from-outcome Element 467

Thefrom-view-id Element 467

The if Element 468

The

_key

Element 469

The

_key-class

Element 470 The

_lifecycle

Element 471 The

_{lifecycle-factory}

Element 471

Thelist-entries Element 472

The

_{locale-config}

Element 473

The

_managed-bean

Element 474

The

_{managed-bean-class}

Element 475

The

_{managed-bean-name}

Element 475

The

_{managed-bean-scope}

Element 476

The

_{managed-property}

Element 477

The

_map-entries

Element 479

The

_map-entry

Element 480

The

_{message-bundle}

Element 481

ThenameElement 482

The

_{navigation-case}

Element 483

The

_{navigation-handler}

Element 484

The

_{navigation-rule}

Element 485

Thenull-value Element 486

The

_ordering

Element 488

Theothers Element 488

The

_{partial-view-context-factory}

Element 489

The

_{phase-listener}

Element 490

The

_property

Element 491

The

_{property-class}

Element 492

The

_{property-name}

Element 493

The

_{property-resolver}

Element 494

The redirect Element 494

The

referenced-bean

Element 495

The

referenced-bean-class

Element 496

The referenced-bean-name Element 497

The render-kit Element 498

The render-kit-classElement 499

The

_{render-kit-factory}

Element 499

The render-kit-idElement 500

TherendererElement 501

Therenderer-classElement 502

The

_{renderer-type}

Element 503

Theresource-bundleElement 503

XVlii

JavaServer Faces 2.0: The

Complete

Reference

The source-classElement 504

The

_{state-manager}

Element 505

The

_{suggested-value}

Element 506

The

_{supported-locale}

Element 507

The

_{system-event-class}

Element 508

The

_{system-event-listener}

Element 509

The

_{system-event-listener-class}

Element 510

The

_{tag-handler-delegate-factory}

Element 510

The to-view-idElement 511

The validator Element 511

Thevalidator-class Element 512

Thevalidator-id Element 513

The valueElement 514

The value-classElement 516

ThevarElement 517

Thevariable-resolver Element 518

The

_{view-declaration-language-factory}

Element 518

Theview-handler Element 519

The

_view-param

Element 520

The

_{visit-context-factory}

Element 521

ExtensionElements 521

Metadata Elements 523

16 The Standard

_{JSF Component Library}

525

ABrief Review of

JSF, Facelets,

and

_JSP

_Tag

Nomenclature 525

Acquiring

and

_Installing

the Standard Libraries 526

What You Get

_(Binary)

527

What You Get

_(Source)

527

The

_Tag

_Library

Reference 527

TheStandard Core

_Library

527

The hactionListener

_Tag

530

The

_f:ajax

_{Tag (2.0)}

531

The f:attribute

_Tag

533

The fxonvertDateTime

_Tag

533

The fxonvertNumber

_Tag

535

The f:converter

_Tag

537

The f:event

_{Tag (2.0)}

538

The f:facet

_Tag

538

The hloadBundle

_Tag

539

The ^metadata

_{Tag (2.0)}

540

The

_f:param

_Tag

540

The

_{f:phaseListener}

_Tag

_(1.2,2.0)

541

The f:selectltem

_Tag

541

The hselectltems

_Tag

542

Contents

The f:subview

_Tag

545

Thef:validateBeanTag(2.0)

547

The

_{f:validateDoubleRange Tag}

549

The

_{f:validateLength Tag}

550

The

_{f:validateLongRange Tag}

551

The

_{f:validateRegex Tag (2.0)}

552

The

_{f:validateRequired Tag (2.0)}

552

The f:validator

_Tag

553

The

_{f:valueChangeListener}

_Tag

554

Thef:verbatim

_Tag

555

Thef:view

_Tag

556

The f:viewParam

_{Tag (2.0)}

557

The Standard HTML

_Library

559

Theh:bodyTag(2.0)

562

The h:button

_Tag

(2.0)

563

The h:column

_Tag

565

The hxommandButton

_Tag

567

The hxommandLink

_Tag

570

The h:dataTable

_Tag

573

Theh:formTag

576

The

_{h:graphiclmage}

_Tag

578

Theh:headTag(2.0)

580

The

_{h:inputHidden Tag}

581

The

_{h:inputSecret}

_Tag

582

The

_h:inputText

_Tag

585

The

_{h:inputTextarea Tag}

588

The Mink

_{Tag (2.0)}

591

The

_{h:message Tag}

594

The_messages

_Component

596

Theh.-outputFormatTag

597

The

_{h:outputLabel Tag}

598

The

_h:outputLink

_Tag

600

The

_{h:outputScript Tag (2.0)}

602

The

_{h:outputStylesheet Tag (2.0)}

603

The

_{h:outputText Tag}

605

The

_{h:panelGrid Tag}

606

The

_{h:panelGroup Tag}

608

The hrselectBooleanCheckbox

Tag

609

The

_{h:selectManyCheckbox Tag}

612

The

_{h:selectManyListbox Tag}

615

The

_{h:selectManyMenu Tag}

618

The h:selectOneListbox

Tag

621

The kselectOneMenu

Tag

624

XX lavaServer Faces

2.0:

The

Complete

Reference

The Standard Facelets

_Templating

_Library

(2.0)

631

Example

Website

_Project

632

The

_uixomponent

_Tag

_(2.0)

636

The ui

_composition

_{Tag (2.0)}

637

The

_{ui:debug Tag}

_(2.0)

637

The ui:decorate

_Tag

_(2.0)

638

The ui:define

_Tag

_(2.0)

639

Theui:fragmentTag(2.0)

639

The uidnclude

_Tag

_(2.0)

640

The ui:insert

_Tag

(2.0)

640

The

_{uiparam Tag}

_(2.0)

641

The ui.'remove

_Tag

(2.0)

641

The

_{ui:repeat Tag}

(2.0)

642

The Standard Facelets

_{Composite Component Library}

(2.0)

643

Example Project

645

The ccactionSource

_Tag

(2.0)

650

The ccattribute

_Tag

(2.0)

651

The cceditableValueHolder

_Tag

(2.0)

652

Theccextension

_{Tag (2.0)}

653

TheccfacetTag (2.0)

654

The

_{complementation Tag}

(2.0)

654

Thecc.insertChildren

_Tag

_(2.0)

655

The ccinsertFacet

_Tag

_(2.0)

655

The ccinterface

_{Tag (2.0)}

656

ThecerenderFacet

_{Tag (2.0)}

657

The ccvalueHolder

_Tag

_(2.0)

658

A

_JSFPortlets

659

Overview of Portlet 1.0 and2.0 659

Portlet

_Lifecycle

659

Portlet Modes 660

Portlet Window States 661

Portlet Preferences 661

Inter-Portlet Communication 662

JSF

Portlet

_Development

663

JSF

Portlet

_Bridges

663

JSF

Portlet View Handlers 667

JSF

ExternalContext and thePortlet API 668

JSF

and Portlet Preferences 668

JSF

and Inter-Portlet Communication 670

ICEfacesPortlet

_Development

672

ICEfaces

_Ajax

with Partial Submit 672

ICEfaces Direct-to-DOM RenderKit 673

The

_{ice:portlet Tag}

673

Contents

_xxi

ICEfaces 1.xD2DFaceletViewHandler 674

ICEfaces 1.x and Portlet WindowStates 675

ICEfaces Portlets and ConcurrentDOM Views 675

ICEfaces 1.xExtended

_{Request Scope}

675

ICEfaces

_Ajax

Push andInter-PortletCommunication 676

ICEfaces Themes and PortalThemes 679

ICEfaces Themesand

_Liferay

Themes 680

ICEfaces

_Ajax

_Bridge

and

_Liferay

Portal 681

ICEfaces Portletsand

_{Liferay Request}

Attributes 682

PortletFaces ₆₈₂

Downloading

PortletFaces 683

PortletFacesContext ₆₈₄

PortletFaces

_Tags

₆₈₅

PortletFacesand PortletPreferences 686

PortletFaces

_{Expression Language}

Additions 687

PortletFaces and Localization 689

Liferay

Language

Portlet

_Integration

690

Improved Integration

Between

_Liferay

and ICEfaces 1.x 690