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 Introduction to JavaServer Faces 3 What Is JavaServer Faces? 3 The History of JavaServer Faces. The Common Gateway Interface, 4 4 The Servlet API 5 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 The Facelets Pages 20 Building and Running the Application 30 Deploying and Running the Application 32 Reviewing the Key Portions of the Application 32 3 The JavaServer Faces Request Processing Lifecycle 35 A High-Level Overview of the JSF Request Processing Lifecycle 35 What Exactly Does the Request Processing Lifecycle Do? 36 How Does It Differ from Other Web Technologies? 36 Automatic Server-Side View Management and Synchronization 37... The Request Processing Lifecycle Phases 38.. Observing the Request Processing Lifecycle in Action 46 Advanced Topics Related to the Request Processing Lifecycle 50... Using the immediate Attribute 50 ix

X JavaServer Faces 2.0: The Complete Reference Phase Listeners 52 Exception Handler 52 Lifecycle Concepts to Remember 53 4 The Facelets View Declaration Language 55 The Power of Templating in Faces 56 Similarities and Differences Between JSP and Facelets 57 Templating with Facelets 58 Guide to Facelets Templating Tags 62 uixomposition 62 ukdecorate 62 ukdefine 62 ukinserl 62 ui:include 64 uiparam 65 Guide to 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 How to Access Managed Beans Programmatically 98 Using Managed Beans as Backing Beans for 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 A Note on Faces Action Methods 109

Contents xi Building Navigation Rules 109 A Static Navigation Example Ill A Dynamic Navigation Example 112 More Sophisticated Navigation Examples 116 Using Wildcards 116 Using Conditional Navigation 117 Using Redirects 118 XML Configuration for View Parameters 132 Using JSF Components on a Servlet Error Page 133 7 The User Interface Component Model 135 What Are UI Components? 135 The Rise 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 Its Associated "Moving Parts" 145 Component Resources 147 UI Components and Facelets 147 Accessing UI Components Programmatically 147 Helpful Advice for Binding UI Components in JSF Views 151 8 Converting and Validating Data 155 Some Validation and Conversion Examples 156 Conversion and Validation Under the Covers 158 The Faces Converter System 162 DateTimeConverter 163 NumberConverter 164 Associating a Converter with a UlComponent Instance 164 The Lifetime of a Converter 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 to Associate a Validator with a UlComponent Instance 179 Using Markup to Associate a Validator with a UlComponent Instance 180 Using Markup and the validator Attribute to Associate a Validator with a UlComponent Instance 181 Programmatically Associating a Validator with a UlComponent Instance 182

Xlj JavaServer Faces 2.0: The Complete Reference The Lifetime of a Validator 183 Custom Validators 183 Using Bean Validation from JSF 185 What Is Bean Validation? 185 Differences Between JSF Validation and Bean Validation 186 Details on Using Bean Validation from JSF 187 Validating JSF Managed Bean Properties with Bean Validation 189... Tie It All Together: Messages in a View 190 FacesMessage-Related Methods on FacesContext 190 The UIViewRoot and Its Locale Property 192 When and How FacesMessage Instances Are Created and Added to the FacesContext 192 How FacesMessages Are Rendered 193 Messages and Bean Validation 196 9 The JSF Event Model 199 A High-Level Overview of the JSF Event Model 199 Some Event Examples 200 How JSF Events Work 203 The Faces Event Listener Interfaces and Event Classes 204 When Are Faces Events Processed? 205 Application Events 209 The Anatomy of a Value Change Event 211 Writing Custom Action and Value Change Listeners 212 More Faces Event Examples 215 Using a Value Change Event to Auto-Fill Fields 215 Extending the Value Change Example 219 Working with Phase Events and Listeners 221 Using a PhaseListener to Observe the Faces Lifecycle in Action 221... Working with SystemEvents and Listeners 224 How SystemEvents Are Published 227 How to 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 Virtual Trainer Application 235 A Quick Tour of the Virtual Trainer Application 236 Registering and Logging In to the Virtual Trainer Application 236 Creating a New Training Event Workout Plan 237 Choosing Your Trainer 239 Actions Available Only to Trainers 239 The Virtual Trainer Application Requirements 243 The Virtual Trainer Application Architecture 243

Contents xiii Facelet Pages 244, 246 Pages in the Web Application Root 244 Pages in the /user Directory 244 Pages in the /trainer Directory 245 Pages in the / resources Directory 245 Backing Beans 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 of the Virtual Trainer Application 263 Creating the allevents.xhtml Page 263 The Trainer Version 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 Classes in Virtual Trainer 280 JPA XML Configuration File: persistence.xml 281 A Custom ExceptionHandler Example 282 Internationalizing the Virtual Trainer Application 284 Localization 285 Final Comments on Virtual Trainer 294 11 Building Custom UI Components 295 Deciding When to Build a Custom UI Component 295 What Are UI Components? 296 A Simple JSFU1 Component 297 The Code Behind the Markup of This Simple JSF UI Component 299 Introduction to Resource Libraries 300 Adding Behavior to a Composite Component 301 A First Look into the Details of Composite Components 303 The #{cc) Implicit Object 305 The Parts of a UI Component 306 A Noncomposite JSF Custom UlComponent 307 Building the HtmlHelloWorld Example 307 A HelloWorld UI Component That Accepts Form Input 312 A JSF Stock Quote Component 314 State Management with Custom Components 316 Writing to a StateHelper 317 Reading from a StateHelper 318 Removing Values from a StateHelper 318

Xiv J a v a S e r v e r Faces 2.0: The Complete Reference Extracting Rendering Code into a Renderer 318 Creating a Custom Facelet 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 a Self-Contained Jar 335 Packaging a Composite Component into a Jar 336 Packaging a Composite Component Facelet File 336 Declaring a Custom Namespace URL for a Composite Component Library 336 Packaging Backing Classes for a Composite Component 337 Packaging a Noncomposite Component into a Jar 337 How the JSF Runtime Loads 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 the Scenes 343 The <f:ajax> Tag and Its Attributes 349 The Standard JavaScript Resource 356 Advanced Topics on JSF and Ajax 357 13 Building Non-UI Custom Components 359 Non-UI Custom Components and Decoration in JSF 359 Wrapper Classes 362 Non-View Custom Components Explained 363 PhaseListener 363 Interface to Implement 363 Registering a PhaseListener 364 Converter and Validator 364 Interfaces to Implement 364 Registering a Converter or Validator 365 ViewHandler 365 Abstract Class to Extend 365 Registering a ViewHandler 365 VariableResolver and PropertyResolver 366 Abstract Classes to Extend 367 Registering a VariableResolver or PropertyResolver 368 ELResolver(JSF1.2) 369 The ELResolver Chain of Responsibility 369 Abstract Class to Extend 372 Registering an ELResolver 374

Contents XV NavigationHandler 378 Abstract Class to Extend 378 Registering a NavigationHandler or ConfigurableNavigationHandler 379 ActionListener 379 Interface to Implement 380 Registering an ActionListener 380 StateManager 380 Abstract Class to Extend in JSF 1.1 and 1.0 380 Abstract Class to Extend in JSF 1.2 382 Registering a StateManager 382 RenderKit 382 Factories in JSF 383 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 396 Telling the JSF Runtime Where You Are in the Software 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 Basic Authentication and the Concept of a "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 in the Virtual Trainer 410 Application-Managed Security with JavaServer Faces 411 Leveraging JAAS from a JSF Application 411 To Learn More about Security 419

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 Files Are Processed 425 Ordering of faces-config.xml Files 426 How the JSF Runtime Scans Classes for Configuration Annotations 427 The Faces 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-cl ass Element 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 converter Element 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 The facet Element 463 The facet-name Element 465 The factory Element 465

Contents xvii The from-action Element 466 The from-outcome Element 467 The from-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 The list-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 The name Element 482 The navigation-case Element 483 The navigation-handler Element 484 The navigation-rule Element 485 The null-value Element 486 The ordering Element 488 The others 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-class Element 499 The render-kit-factory Element 499 The render-kit-id Element 500 The renderer Element 501 The renderer-class Element 502 The renderer-type Element 503 The resource-bundle Element 503 The resource-handler Element 504

XVlii JavaServer Faces 2.0: The Complete Reference The source-class Element 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-id Element 511 The validator Element 511 The validator-class Element 512 The validator-id Element 513 The value Element 514 The value-class Element 516 The var Element 517 The variable-resolver Element 518 The view-declaration-language-factory Element 518 The view-handler Element 519 The view-param Element 520 The visit-context-factory Element 521 Extension Elements 521 Metadata Elements 523 16 The Standard JSF Component Library 525 A Brief 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 The Standard 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 The f:setpropertyactionlistener Tag (1.2, 2.0 Only) 544

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 The f:verbatim Tag 555 The f: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 The h:selectonelistbox Tag 621 The kselectonemenu Tag 624 The h:selectoneradio Tag 618 627

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 The ccextension Tag (2.0) 653 TheccfacetTag (2.0) 654 The complementation Tag (2.0) 654 The cc.insertchildren Tag (2.0) 655 The ccinsertfacet Tag (2.0) 655 The ccinterface Tag (2.0) 656 The cerenderfacet Tag (2.0) 657 The ccvalueholder Tag (2.0) 658 A JSFPortlets 659 Overview of Portlet 1.0 and 2.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 the Portlet API 668 JSF and Portlet Preferences 668 JSF and Inter-Portlet Communication 670 ICEfaces Portlet Development 672 ICEfaces Ajax with Partial Submit 672 ICEfaces Direct-to-DOM RenderKit 673 The ice:portlet Tag 673 ICEfaces 1.x Portlet Bridge 674

Contents xxi ICEfaces 1.x D2DFaceletViewHandler 674 ICEfaces 1.x and Portlet Window States 675 ICEfaces Portlets and Concurrent DOM Views 675 ICEfaces 1.x Extended Request Scope 675 ICEfaces Ajax Push and Inter-Portlet Communication 676 ICEfaces Themes and Portal Themes 679 ICEfaces Themes and Liferay Themes 680 ICEfaces Ajax Bridge and Liferay Portal 681 ICEfaces Portlets and Liferay Request Attributes 682 PortletFaces 682 Downloading PortletFaces 683 PortletFacesContext 684 PortletFaces Tags 685 PortletFaces and Portlet Preferences 686 PortletFaces Expression Language Additions 687 PortletFaces and Localization 689 Liferay Language Portlet Integration 690 Improved Integration Between Liferay and ICEfaces 1.x 690 Index 693