JBoss Enterprise Web Platform 5

Seam Reference Guide

for use with JBoss Enterprise Web Platform 5

Edition 5.1.1

Gavin King

Pete Muir

Norman Richards

Shane Bryzak

Michael Yuan

Mike Youngstrom

Christian Bauer

Jay Balunas

Dan Allen

Max Rydahl Andersen

Emmanuel Bernard

Nicklas Karlsson

Daniel Roth

Matt Drees

Jacob Orshalick

Marek Novotny

James Cobb

Graphic Design

Cheyenne Weaver

Graphic Design

Mark Newton

Steve Ebersole

Michael Courcy

French Translation

Nicola Benaglia

Italian Translation

Stefano Travelli

Italian Translation

Francesco Milesi

Italian Translation

Japan JBoss User Group

Japanese Translation

Edited by

Samson Kittoli

Edited by

Laura Bailey

Edited by

Elspeth Thorne

Edited by

Elspeth Thorne

Legal Notice

Copyright © 2011 Red Hat, Inc.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.

Abstract

This book is a Reference Guide for JBoss Enterprise Web Platform 5 and its patch releases.
Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Getting Help and Giving Feedback
2.1. Do You Need Help?
2.2. Give us Feedback
1. Seam Tutorial
1.1. Using the Seam examples
1.1.1. Running the examples on JBoss AS
1.1.2. Running the example tests
1.2. Your first Seam application: the registration example
1.2.1. Understanding the code
1.2.2. How it works
1.3. Clickable lists in Seam: the messages example
1.3.1. Understanding the code
1.3.2. How it works
1.4. Seam and jBPM: the todo list example
1.4.1. Understanding the code
1.4.2. How it works
1.5. Seam pageflow: the numberguess example
1.5.1. Understanding the code
1.5.2. How it works
1.6. A complete Seam application: the Hotel Booking example
1.6.1. Introduction
1.6.2. Overview of the booking example
1.6.3. Understanding Seam conversations
1.6.4. The Seam Debug Page
1.7. Nested conversations: extending the Hotel Booking example
1.7.1. Introduction
1.7.2. Understanding Nested Conversations
1.8. A complete application featuring Seam and jBPM: the DVD Store example
1.9. Bookmarkable URLs with the Blog example
1.9.1. Using "pull"-style MVC
1.9.2. Bookmarkable search results page
1.9.3. Using "push"-style MVC in a RESTful application
2. Migration
2.1. Migrating from Seam 1.2.x to Seam 2.0
2.1.1. Migrating to JavaServer Faces 1.2
2.1.2. Code Migration
2.1.3. Migrating components.xml
2.1.4. Migrating to Embedded JBoss
2.1.5. Migrating to jBPM 3.2
2.1.6. Migrating to RichFaces 3.1
2.1.7. Changes to Components
2.2. Migrating from Seam 2.0 to Seam 2.1 or 2.2
2.2.1. Changes to dependency jar names
2.2.2. Changes to Components
3. Getting started with Seam, using seam-gen
3.1. Before you start
3.2. Setting up a new project
3.3. Creating a new action
3.4. Creating a form with an action
3.5. Generating an application from an existing database
3.6. Generating an application from existing JPA/EJB3 entities
3.7. Deploying the application as an EAR
3.8. Seam and incremental hot deployment
4. Getting started with Seam, using JBoss Developer Studio
4.1. Before you start
4.2. Setting up a new Seam project
4.3. Creating a new action
4.4. Creating a form with an action
4.5. Generating an application from an existing database
4.6. Seam and incremental hot deployment with JBoss Developer Studio
5. The contextual component model
5.1. Seam contexts
5.1.1. Stateless context
5.1.2. Event context
5.1.3. Page context
5.1.4. Conversation context
5.1.5. Session context
5.1.6. Business process context
5.1.7. Application context
5.1.8. Context variables
5.1.9. Context search priority
5.1.10. Concurrency model
5.2. Seam components
5.2.1. Stateless session beans
5.2.2. Stateful session beans
5.2.3. Entity beans
5.2.4. JavaBeans
5.2.5. Message-driven beans
5.2.6. Interception
5.2.7. Component names
5.2.8. Defining the component scope
5.2.9. Components with multiple roles
5.2.10. Built-in components
5.3. Bijection
5.4. Lifecycle methods
5.5. Conditional installation
5.6. Logging
5.7. The Mutable interface and @ReadOnly
5.8. Factory and manager components
6. Configuring Seam components
6.1. Configuring components via property settings
6.2. Configuring components via components.xml
6.3. Fine-grained configuration files
6.4. Configurable property types
6.5. Using XML Namespaces
7. Events, interceptors and exception handling
7.1. Seam events
7.2. Page actions
7.3. Page parameters
7.3.1. Mapping request parameters to the model
7.4. Propagating request parameters
7.5. URL rewriting with page parameters
7.6. Conversion and Validation
7.7. Navigation
7.8. Fine-grained files for defining navigation, page actions and parameters
7.9. Component-driven events
7.10. Contextual events
7.11. Seam interceptors
7.12. Managing exceptions
7.12.1. Exceptions and transactions
7.12.2. Enabling Seam exception handling
7.12.3. Using annotations for exception handling
7.12.4. Using XML for exception handling
7.12.5. Some common exceptions
8. Conversations and workspace management
8.1. Seam's conversation model
8.2. Nested conversations
8.3. Starting conversations with GET requests
8.4. Requiring a long-running conversation
8.5. Using <s:link> and <s:button>
8.6. Success messages
8.7. Natural conversation IDs
8.8. Creating a natural conversation
8.9. Redirecting to a natural conversation
8.10. Workspace management
8.10.1. Workspace management and JSF navigation
8.10.2. Workspace management and jPDL pageflow
8.10.3. The conversation switcher
8.10.4. The conversation list
8.10.5. Breadcrumbs
8.11. Conversational components and JSF component bindings
8.12. Concurrent calls to conversational components
8.12.1. How should we design our conversational AJAX application?
8.12.2. Dealing with errors
8.12.3. RichFaces (Ajax4jsf)
9. Pageflows and business processes
9.1. Pageflow in Seam
9.1.1. The two navigation models
9.1.2. Seam and the back button
9.2. Using jPDL pageflows
9.2.1. Installing pageflows
9.2.2. Starting pageflows
9.2.3. Page nodes and transitions
9.2.4. Controlling the flow
9.2.5. Ending the flow
9.2.6. Pageflow composition
9.3. Business process management in Seam
9.4. Using jPDL business process definitions
9.4.1. Installing process definitions
9.4.2. Initializing actor IDs
9.4.3. Initiating a business process
9.4.4. Task assignment
9.4.5. Task lists
9.4.6. Performing a task
10. Seam and Object/Relational Mapping
10.1. Introduction
10.2. Seam managed transactions
10.2.1. Disabling Seam-managed transactions
10.2.2. Configuring a Seam transaction manager
10.2.3. Transaction synchronization
10.3. Seam-managed persistence contexts
10.3.1. Using a Seam-managed persistence context with JPA
10.3.2. Using a Seam-managed Hibernate session
10.3.3. Seam-managed persistence contexts and atomic conversations
10.4. Using the JPA "delegate"
10.5. Using EL in EJB-QL/HQL
10.6. Using Hibernate filters
11. JSF form validation in Seam
12. Groovy integration
12.1. Groovy introduction
12.2. Writing Seam applications in Groovy
12.2.1. Writing Groovy components
12.2.2. Seam component
12.2.3. seam-gen
12.3. Deployment
12.3.1. Deploying Groovy code
12.3.2. Native .groovy file deployment at development time
12.3.3. seam-gen
13. The Seam Application Framework
13.1. Introduction
13.2. Home objects
13.3. Query objects
13.4. Controller objects
14. Seam and JBoss Rules
14.1. Installing rules
14.2. Using rules from a Seam component
14.3. Using rules from a jBPM process definition
15. Security
15.1. Overview
15.2. Disabling Security
15.3. Authentication
15.3.1. Configuring an Authenticator component
15.3.2. Writing an authentication method
15.3.3. Writing a login form
15.3.4. Configuration Summary
15.3.5. Remember Me
15.3.6. Handling Security Exceptions
15.3.7. Login Redirection
15.3.8. HTTP Authentication
15.3.9. Advanced Authentication Features
15.4. Identity Management
15.4.1. Configuring IdentityManager
15.4.2. JpaIdentityStore
15.4.3. LdapIdentityStore
15.4.4. Writing your own IdentityStore
15.4.5. Authentication with Identity Management
15.4.6. Using IdentityManager
15.5. Error Messages
15.6. Authorization
15.6.1. Core concepts
15.6.2. Securing components
15.6.3. Security in the user interface
15.6.4. Securing pages
15.6.5. Securing Entities
15.6.6. Typesafe Permission Annotations
15.6.7. Typesafe Role Annotations
15.6.8. The Permission Authorization Model
15.6.9. RuleBasedPermissionResolver
15.6.10. PersistentPermissionResolver
15.7. Permission Management
15.7.1. PermissionManager
15.7.2. Permission checks for PermissionManager operations
15.8. SSL Security
15.8.1. Overriding the default ports
15.9. CAPTCHA
15.9.1. Configuring the CAPTCHA Servlet
15.9.2. Adding a CAPTCHA to a form
15.9.3. Customising the CAPTCHA algorithm
15.10. Security Events
15.11. Run As
15.12. Extending the Identity component
15.13. OpenID
15.13.1. Configuring OpenID
15.13.2. Presenting an OpenIdLogin form
15.13.3. Logging in immediately
15.13.4. Deferring login
15.13.5. Logging out
16. Internationalization, localization and themes
16.1. Internationalizing your application
16.1.1. Application server configuration
16.1.2. Translated application strings
16.1.3. Other encoding settings
16.2. Locales
16.3. Labels
16.3.1. Defining labels
16.3.2. Displaying labels
16.3.3. Faces messages
16.4. Timezones
16.5. Themes
16.6. Persisting locale and theme preferences via cookies
17. Seam Text
17.1. Basic fomatting
17.2. Entering code and text with special characters
17.3. Links
17.4. Entering HTML
17.5. Using the SeamTextParser
18. iText PDF generation
18.1. Using PDF Support
18.1.1. Creating a document
18.1.2. Basic Text Elements
18.1.3. Headers and Footers
18.1.4. Chapters and Sections
18.1.5. Lists
18.1.6. Tables
18.1.7. Document Constants
18.2. Charting
18.3. Bar codes
18.4. Fill-in-forms
18.5. Rendering Swing/AWT components
18.6. Configuring iText
18.7. Further documentation
19. The Microsoft® Excel® spreadsheet application
19.1. Microsoft Excel support
19.2. Creating a simple workbook
19.3. Workbooks
19.4. Worksheets
19.5. Columns
19.6. Cells
19.6.1. Validation
19.6.2. Format masks
19.7. Formulas
19.8. Images
19.9. Hyperlinks
19.10. Headers and footers
19.11. Print areas and titles
19.12. Worksheet Commands
19.12.1. Grouping
19.12.2. Page breaks
19.12.3. Merging
19.13. Datatable exporter
19.14. Fonts and layout
19.14.1. Stylesheet links
19.14.2. Fonts
19.14.3. Borders
19.14.4. Background
19.14.5. Column settings
19.14.6. Cell settings
19.14.7. The datatable exporter
19.14.8. Limitations
19.15. Internationalization
19.16. Links and further documentation
20. Email
20.1. Creating a message
20.1.1. Attachments
20.1.2. HTML/Text alternative part
20.1.3. Multiple recipients
20.1.4. Multiple messages
20.1.5. Templating
20.1.6. Internationalization
20.1.7. Other Headers
20.2. Receiving emails
20.3. Configuration
20.3.1. mailSession
20.4. Tags
21. Asynchronicity and messaging
21.1. Asynchronicity
21.1.1. Asynchronous methods
21.1.2. Asynchronous methods with the Quartz Dispatcher
21.1.3. Asynchronous events
21.1.4. Handling exceptions from asynchronous calls
21.2. Messaging in Seam
21.2.1. Configuration
21.2.2. Sending messages
21.2.3. Receiving messages using a message-driven bean
21.2.4. Receiving messages in the client
22. Caching
22.1. Using Caching in Seam
22.2. Page fragment caching
23. Web Services
23.1. Configuration and Packaging
23.2. Conversational Web Services
23.2.1. A Recommended Strategy
23.3. An example web service
23.4. RESTful HTTP webservices with RESTEasy
23.4.1. RESTEasy configuration and request serving
23.4.2. Resources and providers as Seam components
23.4.3. Securing resources
23.4.4. Mapping exceptions to HTTP responses
23.4.5. Exposing entities via RESTful API
23.4.6. Testing resources and providers
24. Remoting
24.1. Configuration
24.2. The Seam object
24.2.1. A Hello World example
24.2.2. Seam.Component
24.2.3. Seam.Remoting
24.3. Evaluating EL Expressions
24.4. Client Interfaces
24.5. The Context
24.5.1. Setting and reading the Conversation ID
24.5.2. Remote calls within the current conversation scope
24.6. Batch Requests
24.7. Working with Data types
24.7.1. Primitives / Basic Types
24.7.2. JavaBeans
24.7.3. Dates and Times
24.7.4. Enums
24.7.5. Collections
24.8. Debugging
24.9. Handling Exceptions
24.10. The Loading Message
24.10.1. Changing the message
24.10.2. Hiding the loading message
24.10.3. A Custom Loading Indicator
24.11. Controlling what data is returned
24.11.1. Constraining normal fields
24.11.2. Constraining Maps and Collections
24.11.3. Constraining objects of a specific type
24.11.4. Combining Constraints
24.12. Transactional Requests
24.13. JMS Messaging
24.13.1. Configuration
24.13.2. Subscribing to a JMS Topic
24.13.3. Unsubscribing from a Topic
24.13.4. Tuning the Polling Process
25. Seam and the Google Web Toolkit
25.1. Configuration
25.2. Preparing your component
25.3. Hooking up a GWT widget to the Seam component
25.4. GWT Ant Targets
26. Spring Framework integration
26.1. Injecting Seam components into Spring beans
26.2. Injecting Spring beans into Seam components
26.3. Making a Spring bean into a Seam component
26.4. Seam-scoped Spring beans
26.5. Using Spring PlatformTransactionManagement
26.6. Using a Seam-Managed Persistence Context in Spring
26.7. Using a Seam-Managed Hibernate Session in Spring
26.8. Spring Application Context as a Seam Component
26.9. Using a Spring TaskExecutor for @Asynchronous
27. Hibernate Search
27.1. Introduction
27.2. Configuration
27.3. Usage
28. Configuring Seam and packaging Seam applications
28.1. Basic Seam configuration
28.1.1. Integrating Seam with JSF and your servlet container
28.1.2. Using Facelets
28.1.3. Seam Resource Servlet
28.1.4. Seam Servlet filters
28.1.5. Integrating Seam with your EJB container
28.1.6. Remember
28.2. Using Alternate JPA Providers
28.3. Configuring Seam in Java EE 5
28.3.1. Packaging
28.4. Configuring Seam in J2EE
28.4.1. Boostrapping Hibernate in Seam
28.4.2. Boostrapping JPA in Seam
28.4.3. Packaging
28.5. Configuring Seam in Java SE, without JBoss Embedded
28.6. Configuring Seam in Java SE, with JBoss Embedded
28.6.1. Packaging
28.7. Configuring jBPM in Seam
28.7.1. Packaging
28.8. Configuring SFSB and Session Timeouts in JBoss AS
28.9. Running Seam in a Portlet
28.10. Deploying custom resources
29. Seam annotations
29.1. Annotations for component definition
29.2. Annotations for bijection
29.3. Annotations for component lifecycle methods
29.4. Annotations for context demarcation
29.5. Annotations for use with Seam JavaBean components in a J2EE environment
29.6. Annotations for exceptions
29.7. Annotations for Seam Remoting
29.8. Annotations for Seam interceptors
29.9. Annotations for asynchronicity
29.10. Annotations for use with JSF
29.10.1. Annotations for use with dataTable
29.11. Meta-annotations for databinding
29.12. Annotations for packaging
29.13. Annotations for integrating with the Servlet container
30. Built-in Seam components
30.1. Context injection components
30.2. JSF-related components
30.3. Utility components
30.4. Components for internationalization and themes
30.5. Components for controlling conversations
30.6. jBPM-related components
30.7. Security-related components
30.8. JMS-related components
30.9. Mail-related components
30.10. Infrastructural components
30.11. Miscellaneous components
30.12. Special components
31. Seam JSF controls
31.1. Tags
31.1.1. Navigation Controls
31.1.2. Converters and Validators
31.1.3. Formatting
31.1.4. Seam Text
31.1.5. Form support
31.1.6. Other
31.2. Annotations
32. JBoss EL
32.1. Parameterized Expressions
32.1.1. Usage
32.1.2. Limitations and Hints
32.2. Projection
33. Clustering and EJB Passivation
33.1. Clustering
33.1.1. Programming for clustering
33.1.2. Deploying a Seam application to a JBoss AS cluster with session replication
33.1.3. Tutorial
33.1.4. Validating the distributable services of an application running in a JBoss AS cluster
33.2. EJB Passivation and the ManagedEntityInterceptor
33.2.1. The friction between passivation and persistence
33.2.2. Case #1: Surviving EJB passivation
33.2.3. Case #2: Surviving HTTP session replication
34. Performance Tuning
34.1. Bypassing Interceptors
35. Testing Seam applications
35.1. Unit testing Seam components
35.2. Integration testing Seam components
35.2.1. Using mocks in integration tests
35.3. Integration testing Seam application user interactions
35.3.1. Configuration
35.3.2. Using SeamTest with another test framework
35.3.3. Integration Testing with Mock Data
35.3.4. Integration Testing Seam Mail
36. Seam tools
36.1. jBPM designer and viewer
36.1.1. Business process designer
36.1.2. Pageflow viewer
37. Dependencies
37.1. Java Development Kit Dependencies
37.1.1. Sun's JDK 6 Considerations
37.2. Project Dependencies
37.2.1. Core
37.2.2. RichFaces
37.2.3. Seam Mail
37.2.4. Seam PDF
37.2.5. Seam Microsoft® Excel®
37.2.6. JBoss Rules
37.2.7. JBPM
37.2.8. GWT
37.2.9. Spring
37.2.10. Groovy
37.3. Dependency Management using Maven
A. Revision History