SeamFramework.orgCommunity Documentation

Seam - Contextual Components

A Framework for Enterprise Java

by 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, Denis Forveille, Marek Novotny, and Jozef Hartinger
edited by Samson Kittoli
and thanks to 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), and Japan JBoss User Group (Japanese Translation)

2.3.1.Final

Introduction to JBoss Seam
1. Contribute to Seam
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. Getting started with Seam, using seam-gen
2.1. Before you start
2.2. Setting up a new project
2.3. Creating a new action
2.4. Creating a form with an action
2.5. Generating an application from an existing database
2.6. Generating an application from existing JPA/EJB3 entities
2.7. Deploying the application as an EAR
2.8. Seam and incremental hot deployment
3. Getting started with Seam, using JBoss Tools
3.1. Before you start
4. Migration from 2.2 to 2.3
4.1. Migration of XML Schemas
4.1.1. Seam schema migration
4.1.2. Java EE 6 schema changes
4.2. Java EE 6 upgrade
4.2.1. Using Bean Validation standard instead of Hibernate Validator
4.2.2. Migration of JSF 1 to JSF 2 Facelets templates
4.2.3. Migration to JPA 2.0
4.2.4. Using compatible JNDI for resources
4.3. JBoss AS 7.1 deployment
4.3.1. Deployment changes
4.3.2. Datasource migration
4.4. Changes in testing framework
4.5. Dependency changes with using Maven
4.5.1. Seam Bill of Materials
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 definition of 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
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-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. Writing your presentation layer using Apache Wicket
13.1. Adding Seam to your wicket application
13.1.1. Bijection
13.1.2. Orchestration
13.2. Setting up your project
13.2.1. Runtime instrumentation
13.2.2. Compile-time instrumentation
13.2.3. The @SeamWicketComponent annotation
13.2.4. Defining the Application
14. The Seam Application Framework
14.1. Introduction
14.2. Home objects
14.3. Query objects
14.4. Controller objects
15. Seam and JBoss Rules
15.1. Installing rules
15.2. Using rules from a Seam component
15.3. Using rules from a jBPM process definition
16. Security
16.1. Overview
16.2. Disabling Security
16.3. Authentication
16.3.1. Configuring an Authenticator component
16.3.2. Writing an authentication method
16.3.3. Writing a login form
16.3.4. Configuration Summary
16.3.5. Remember Me
16.3.6. Handling Security Exceptions
16.3.7. Login Redirection
16.3.8. HTTP Authentication
16.3.9. Advanced Authentication Features
16.4. Identity Management
16.4.1. Configuring IdentityManager
16.4.2. JpaIdentityStore
16.4.3. LdapIdentityStore
16.4.4. Writing your own IdentityStore
16.4.5. Authentication with Identity Management
16.4.6. Using IdentityManager
16.5. Error Messages
16.6. Authorization
16.6.1. Core concepts
16.6.2. Securing components
16.6.3. Security in the user interface
16.6.4. Securing pages
16.6.5. Securing Entities
16.6.6. Typesafe Permission Annotations
16.6.7. Typesafe Role Annotations
16.6.8. The Permission Authorization Model
16.6.9. RuleBasedPermissionResolver
16.6.10. PersistentPermissionResolver
16.7. Permission Management
16.7.1. PermissionManager
16.7.2. Permission checks for PermissionManager operations
16.8. SSL Security
16.8.1. Overriding the default ports
16.9. CAPTCHA
16.9.1. Configuring the CAPTCHA Servlet
16.9.2. Adding a CAPTCHA to a form
16.9.3. Customising the CAPTCHA algorithm
16.10. Security Events
16.11. Run As
16.12. Extending the Identity component
16.13. OpenID
16.13.1. Configuring OpenID
16.13.2. Presenting an OpenIdDLogin form
16.13.3. Logging in immediately
16.13.4. Deferring login
16.13.5. Logging out
17. Internationalization, localization and themes
17.1. Internationalizing your app
17.1.1. Application server configuration
17.1.2. Translated application strings
17.1.3. Other encoding settings
17.2. Locales
17.3. Labels
17.3.1. Defining labels
17.3.2. Displaying labels
17.3.3. Faces messages
17.4. Timezones
17.5. Themes
17.6. Persisting locale and theme preferences via cookies
18. Seam Text
18.1. Basic fomatting
18.2. Entering code and text with special characters
18.3. Links
18.4. Entering HTML
18.5. Using the SeamTextParser
19. iText PDF generation
19.1. Using PDF Support
19.1.1. Creating a document
19.1.2. Basic Text Elements
19.1.3. Headers and Footers
19.1.4. Chapters and Sections
19.1.5. Lists
19.1.6. Tables
19.1.7. Document Constants
19.2. Charting
19.3. Bar codes
19.4. Fill-in-forms
19.5. Rendering Swing/AWT components
19.6. Configuring iText
19.7. Further documentation
20. The Microsoft® Excel® spreadsheet application
20.1. The Microsoft® Excel® spreadsheet application support
20.2. Creating a simple workbook
20.3. Workbooks
20.4. Worksheets
20.5. Columns
20.6. Cells
20.6.1. Validation
20.6.2. Format masks
20.7. Formulas
20.8. Images
20.9. Hyperlinks
20.10. Headers and footers
20.11. Print areas and titles
20.12. Worksheet Commands
20.12.1. Grouping
20.12.2. Page breaks
20.12.3. Merging
20.13. Datatable exporter
20.14. Fonts and layout
20.14.1. Stylesheet links
20.14.2. Fonts
20.14.3. Borders
20.14.4. Background
20.14.5. Column settings
20.14.6. Cell settings
20.14.7. The datatable exporter
20.14.8. Layout examples
20.14.9. Limitations
20.15. Internationalization
20.16. Links and further documentation
21. RSS support
21.1. Installation
21.2. Generating feeds
21.3. Feeds
21.4. Entries
21.5. Links and further documentation
22. Email
22.1. Creating a message
22.1.1. Attachments
22.1.2. HTML/Text alternative part
22.1.3. Multiple recipients
22.1.4. Multiple messages
22.1.5. Templating
22.1.6. Internationalisation
22.1.7. Other Headers
22.2. Receiving emails
22.3. Configuration
22.3.1. mailSession
22.4. Tags
23. Asynchronicity and messaging
23.1. Messaging in Seam
23.1.1. Configuration
23.1.2. Sending messages
23.1.3. Receiving messages using a message-driven bean
23.1.4. Receiving messages in the client
23.2. Asynchronicity
23.2.1. Asynchronous methods
23.2.2. Asynchronous methods with the Quartz Dispatcher
23.2.3. Asynchronous events
23.2.4. Handling exceptions from asynchronous calls
24. Caching
24.1. Using Caching in Seam
24.2. Page fragment caching
25. Web Services
25.1. Configuration and Packaging
25.2. Conversational Web Services
25.2.1. A Recommended Strategy
25.3. An example web service
25.4. RESTful HTTP webservices with RESTEasy
25.4.1. RESTEasy configuration and request serving
25.4.2. Resources as Seam components
25.4.3. Securing resources
25.4.4. Mapping exceptions to HTTP responses
25.4.5. Exposing entities via RESTful API
25.4.6. Testing resources and providers
26. Remoting
26.1. Configuration
26.2. The "Seam" object
26.2.1. A Hello World example
26.2.2. Seam.Component
26.2.3. Seam.Remoting
26.3. Client Interfaces
26.4. The Context
26.4.1. Setting and reading the Conversation ID
26.4.2. Remote calls within the current conversation scope
26.5. Batch Requests
26.6. Working with Data types
26.6.1. Primitives / Basic Types
26.6.2. JavaBeans
26.6.3. Dates and Times
26.6.4. Enums
26.6.5. Collections
26.7. Debugging
26.8. Handling Exceptions
26.9. The Loading Message
26.9.1. Changing the message
26.9.2. Hiding the loading message
26.9.3. A Custom Loading Indicator
26.10. Controlling what data is returned
26.10.1. Constraining normal fields
26.10.2. Constraining Maps and Collections
26.10.3. Constraining objects of a specific type
26.10.4. Combining Constraints
26.11. Transactional Requests
26.12. JMS Messaging
26.12.1. Configuration
26.12.2. Subscribing to a JMS Topic
26.12.3. Unsubscribing from a Topic
26.12.4. Tuning the Polling Process
27. Seam and the Google Web Toolkit
27.1. Configuration
27.2. Preparing your component
27.3. Hooking up a GWT widget to the Seam component
27.4. GWT Ant Targets
27.5. GWT Maven plugin
28. Spring Framework integration
28.1. Injecting Seam components into Spring beans
28.2. Injecting Spring beans into Seam components
28.3. Making a Spring bean into a Seam component
28.4. Seam-scoped Spring beans
28.5. Using Spring PlatformTransactionManagement
28.6. Using a Seam Managed Persistence Context in Spring
28.7. Using a Seam Managed Hibernate Session in Spring
28.8. Spring Application Context as a Seam Component
28.9. Using a Spring TaskExecutor for @Asynchronous
29. Guice integration
29.1. Creating a hybrid Seam-Guice component
29.2. Configuring an injector
29.3. Using multiple injectors
30. Hibernate Search
30.1. Introduction
30.2. Configuration
30.3. Usage
31. Configuring Seam and packaging Seam applications
31.1. Basic Seam configuration
31.1.1. Integrating Seam with JSF and your servlet container
31.1.2. Seam Resource Servlet
31.1.3. Seam servlet filters
31.1.4. Integrating Seam with your EJB container
31.1.5. Don't forget!
31.2. Using Alternate JPA Providers
31.3. Configuring Seam in Java EE 6
31.3.1. Packaging
31.4. Configuring Seam without EJB
31.4.1. Boostrapping Hibernate in Seam
31.4.2. Boostrapping JPA in Seam
31.4.3. Packaging
31.5. Configuring Seam in Java SE
31.6. Configuring jBPM in Seam
31.6.1. Packaging
31.7. Deployment in JBoss AS 7
31.8. Configuring SFSB and Session Timeouts in JBoss AS 7
31.9. Running Seam in a Portlet
31.10. Deploying custom resources
32. Seam annotations
32.1. Annotations for component definition
32.2. Annotations for bijection
32.3. Annotations for component lifecycle methods
32.4. Annotations for context demarcation
32.5. Annotations for use with Seam JavaBean components in a J2EE environment
32.6. Annotations for exceptions
32.7. Annotations for Seam Remoting
32.8. Annotations for Seam interceptors
32.9. Annotations for asynchronicity
32.10. Annotations for use with JSF
32.10.1. Annotations for use with dataTable
32.11. Meta-annotations for databinding
32.12. Annotations for packaging
32.13. Annotations for integrating with the servlet container
33. Built-in Seam components
33.1. Context injection components
33.2. JSF-related components
33.3. Utility components
33.4. Components for internationalization and themes
33.5. Components for controlling conversations
33.6. jBPM-related components
33.7. Security-related components
33.8. JMS-related components
33.9. Mail-related components
33.10. Infrastructural components
33.11. Miscellaneous components
33.12. Special components
34. Seam JSF controls
34.1. Tags
34.1.1. Navigation Controls
34.1.2. Converters and Validators
34.1.3. Formatting
34.1.4. Seam Text
34.1.5. Form support
34.1.6. Other
34.2. Annotations
35. JBoss EL
35.1. Parameterized Expressions
35.1.1. Usage
35.1.2. Limitations and Hints
35.2. Projection
36. Clustering and EJB Passivation
36.1. Clustering
36.1.1. Programming for clustering
36.1.2. Deploying a Seam application to a JBoss AS cluster with session replication
36.2. EJB Passivation and the ManagedEntityInterceptor
36.2.1. The friction between passivation and persistence
36.2.2. Case #1: Surviving EJB passivation
36.2.3. Case #2: Surviving HTTP session replication
36.2.4. ManagedEntityInterceptor wrap-up
37. Performance Tuning
37.1. Bypassing Interceptors
38. Testing Seam applications
38.1. Unit testing Seam components
38.2. Integration testing Seam components
38.2.1. Configuration
38.2.2. Using JUnitSeamTest with Arquillian
38.2.3. Integration testing Seam application user interactions
39. Dependencies
39.1. JDK Dependencies
39.1.1. Oracle's JDK 6 Considerations
39.2. Project Dependencies
39.2.1. Core
39.2.2. RichFaces
39.2.3. Seam Mail
39.2.4. Seam PDF
39.2.5. Seam Microsoft Excel
39.2.6. Seam RSS support
39.2.7. Drools
39.2.8. JBPM
39.2.9. GWT
39.2.10. Spring
39.2.11. Groovy
39.3. Dependency Management using Maven