SeamFramework.orgCommunity Documentation

Seam - Contextual Components

A Framework for Enterprise Java

by Gavin King (Project Lead), Pete Muir, Norman Richards, Shane Bryzak, Michael Yuan, Mike Youngstrom, Christian Bauer, Jay Balunas, Dan Allen, Max Rydahl Andersen, and Emmanuel Bernard
edited by Samson Kittoli
and thanks to James Cobb (Graphic Design), Cheyenne Weaver (Graphic Design), Mark Newton, and Steve Ebersole

2.1.0.BETA1

Introduction to JBoss Seam
1. Contribute to Seam
1. Seam Tutorial
1.1. Try the examples
1.1.1. Running the examples on JBoss AS
1.1.2. Running the examples on Tomcat
1.1.3. 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 UI control library
1.6.5. The Seam Debug Page
1.7. A complete application featuring Seam and jBPM: the DVD Store example
1.8. An example of Seam with Hibernate: the Hibernate Booking example
1.9. A RESTful Seam application: 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 Eclipse 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
2.9. Using Seam with JBoss 4.0
2.9.1. Install JBoss 4.0
2.9.2. Install the JSF 1.2 RI
3. Getting started with Seam, using JBoss Tools
3.1. Before you start
3.2. Setting up a new Seam 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. Seam and incremental hot deployment with JBoss Tools
4. The contextual component model
4.1. Seam contexts
4.1.1. Stateless context
4.1.2. Event context
4.1.3. Page context
4.1.4. Conversation context
4.1.5. Session context
4.1.6. Business process context
4.1.7. Application context
4.1.8. Context variables
4.1.9. Context search priority
4.1.10. Concurrency model
4.2. Seam components
4.2.1. Stateless session beans
4.2.2. Stateful session beans
4.2.3. Entity beans
4.2.4. JavaBeans
4.2.5. Message-driven beans
4.2.6. Interception
4.2.7. Component names
4.2.8. Defining the component scope
4.2.9. Components with multiple roles
4.2.10. Built-in components
4.3. Bijection
4.4. Lifecycle methods
4.5. Conditional installation
4.6. Logging
4.7. The Mutable interface and @ReadOnly
4.8. Factory and manager components
5. Configuring Seam components
5.1. Configuring components via property settings
5.2. Configuring components via components.xml
5.3. Fine-grained configuration files
5.4. Configurable property types
5.5. Using XML Namespaces
6. Events, interceptors and exception handling
6.1. Seam events
6.2. Page actions
6.3. Page parameters
6.3.1. Mapping request parameters to the model
6.4. Propagating request parameters
6.5. Conversion and Validation
6.6. Navigation
6.7. Fine-grained files for definition of navigation, page actions and parameters
6.8. Component-driven events
6.9. Contextual events
6.10. Seam interceptors
6.11. Managing exceptions
6.11.1. Exceptions and transactions
6.11.2. Enabling Seam exception handling
6.11.3. Using annotations for exception handling
6.11.4. Using XML for exception handling
6.11.5. Some common exceptions
7. Conversations and workspace management
7.1. Seam's conversation model
7.2. Nested conversations
7.3. Starting conversations with GET requests
7.4. Using <s:link> and <s:button>
7.5. Success messages
7.6. Natural conversation ids
7.7. Creating a natural conversation
7.8. Redirecting to a natural conversation
7.9. Workspace management
7.9.1. Workspace management and JSF navigation
7.9.2. Workspace management and jPDL pageflow
7.9.3. The conversation switcher
7.9.4. The conversation list
7.9.5. Breadcrumbs
7.10. Conversational components and JSF component bindings
7.11. Concurrent calls to conversational components
7.11.1. RichFaces Ajax
8. Pageflows and business processes
8.1. Pageflow in Seam
8.1.1. The two navigation models
8.1.2. Seam and the back button
8.2. Using jPDL pageflows
8.2.1. Installing pageflows
8.2.2. Starting pageflows
8.2.3. Page nodes and transitions
8.2.4. Controlling the flow
8.2.5. Ending the flow
8.2.6. Pageflow composition
8.3. Business process management in Seam
8.4. Using jPDL business process definitions
8.4.1. Installing process definitions
8.4.2. Initializing actor ids
8.4.3. Initiating a business process
8.4.4. Task assignment
8.4.5. Task lists
8.4.6. Performing a task
9. Seam and Object/Relational Mapping
9.1. Introduction
9.2. Seam managed transactions
9.2.1. Disabling Seam-managed transactions
9.2.2. Configuring a Seam transaction manager
9.2.3. Transaction synchronization
9.3. Seam-managed persistence contexts
9.3.1. Using a Seam-managed persistence context with JPA
9.3.2. Using a Seam-managed Hibernate session
9.3.3. Seam-managed persistence contexts and atomic conversations
9.4. Using the JPA "delegate"
9.5. Using EL in EJB-QL/HQL
9.6. Using Hibernate filters
10. JSF form validation in Seam
11. Groovy integration
11.1. Groovy introduction
11.2. Writing Seam applications in Groovy
11.2.1. Writing Groovy components
11.2.2. seam-gen
11.3. Deployment
11.3.1. Deploying Groovy code
11.3.2. Native .groovy file deployment at development time
11.3.3. seam-gen
12. Writing your presentation layer using Apache Wicket
12.1. Adding Seam to your wicket application
12.1.1. Bijection
12.1.2. Orchestration
12.2. Setting up your project
12.2.1. Defining the Application
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
16. Internationalization, localization and themes
16.1. Internationalizing your app
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
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. Rendering Swing/AWT components
18.5. Configuring iText
18.6. Further documentation
19. the Microsoft® Excel® spreadsheet application
19.1. the Microsoft® Excel® spreadsheet application support
19.2. Creating a simple workbook
19.3. Workbooks
19.4. Worksheets
19.5. Columns
19.6. Cells
19.6.1. Fonts
19.6.2. Backgrounds
19.6.3. Borders
19.6.4. Validation
19.6.5. 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. Templates
19.13.1. Cell templates
19.13.2. Worksheet setting templates
19.14. Datatable exporter
19.14.1. CSS
19.14.2. Templates
19.15. 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. Internationalisation
20.1.7. Other Headers
20.2. Receiving emails
20.3. Configuration
20.3.1. mailSession
20.4. Meldware
20.5. 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.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
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. The Loading Message
24.9.1. Changing the message
24.9.2. Hiding the loading message
24.9.3. A Custom Loading Indicator
24.10. Controlling what data is returned
24.10.1. Constraining normal fields
24.10.2. Constraining Maps and Collections
24.10.3. Constraining objects of a specific type
24.10.4. Combining Constraints
24.11. JMS Messaging
24.11.1. Configuration
24.11.2. Subscribing to a JMS Topic
24.11.3. Unsubscribing from a Topic
24.11.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. Don't forget!
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. Installing Embedded JBoss
28.6.2. 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. Utility components
30.3. Components for internationalization and themes
30.4. Components for controlling conversations
30.5. jBPM-related components
30.6. Security-related components
30.7. JMS-related components
30.8. Mail-related components
30.9. Infrastructural components
30.10. Miscellaneous components
30.11. 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. Dropdowns
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. Testing Seam applications
33.1. Unit testing Seam components
33.2. Integration testing Seam components
33.2.1. Using mocks in integration tests
33.3. Integration testing Seam application user interactions
33.3.1. Configuration
33.3.2. Using SeamTest with another test framework
33.3.3. Integration Testing with Mock Data
33.3.4. Integration Testing Seam Mail
34. Seam tools
34.1. jBPM designer and viewer
34.1.1. Business process designer
34.1.2. Pageflow viewer
35. Seam on OC4J
35.1. Installation and operation of OC4J
35.2. The jee5/booking example
35.2.1. Booking Example Dependencies
35.2.2. Configuration file changes
35.2.3. Building the jee5/booking example
35.3. Deploying the Seam application to OC4J
35.4. Deploying an application created using seam-gen to OC4J
35.4.1. Generating a basic seam-gen application
35.4.2. Changes needed for deployment to OC4J
35.4.3. Building and deploying the seam-gen'd application to OC4J
35.4.4. Extending example with reverse engineered CRUD and Drools
35.5. Finishing up
36. Seam on BEA's Weblogic
36.1. Installation and operation of Weblogic
36.1.1. Installing 10.0.MP1
36.1.2. Creating your Weblogic domain
36.1.3. How to Start/Stop/Access your domain
36.2. The jee5/booking Example
36.2.1. EJB3 Issues with Weblogic
36.2.2. Getting the jee5/booking Working
36.3. The jpa booking example
36.3.1. Building and deploying jpa booking example
36.3.2. What's different with Weblogic 10.x
36.4. Deploying an application created using seam-gen on Weblogic 10.x
36.4.1. Running seam-gen setup
36.4.2. What to change for Weblogic 10.X
36.4.3. Building and Deploying your application
37. Seam on IBM's Websphere
37.1. Websphere environment and deployment information
37.1.1. Installation versions and tips
37.1.2. Required custom properties
37.2. The jee5/booking example
37.2.1. Configuration file changes
37.2.2. Building the jee5/booking example
37.2.3. Deploying the application to Websphere
37.3. The jpa booking example
37.3.1. Building the jpa example
37.3.2. Deploying the jpa example
37.3.3. Whats different for Websphere 6.1
37.4. Deploying an application created using seam-gen on Websphere 6.1.0.13
37.4.1. Running seam-gen Setup
37.4.2. Changes needed for deployment to Websphere
38. Dependencies
38.1. JDK Dependencies
38.1.1. Sun's JDK 6 Considerations
38.2. Project Dependencies
38.2.1. Core
38.2.2. RichFaces
38.2.3. Seam Mail
38.2.4. Seam PDF
38.2.5. Seam Microsoft® Excel®
38.2.6. JBoss Rules
38.2.7. JBPM
38.2.8. GWT
38.2.9. Spring
38.2.10. Groovy
38.3. Dependency Management using Maven