JBoss Enterprise Application Platform 4.3 Seam 2 Reference Guide

classypalmInternet και Εφαρμογές Web

12 Νοε 2013 (πριν από 3 χρόνια και 11 μήνες)

1.320 εμφανίσεις

JBoss Enterprise
Application Platform 4.3
Seam 2 Reference Guide
for Use with JBoss Enterprise Application Platform 4.3.0
Gavin King
Pete Muir
Norman Richards
Shane Bryzak
Michael Yuan
Mike Youngstrom
Christian Bauer
Jay Balunas
Seam 2 Reference Guide
Dan Allen
Max Rydahl Andersen
Emmanuel Bernard
JBoss Enterprise Application Platform 4.3 Seam 2 Reference
Guide
for Use with JBoss Enterprise Application Platform 4.3.0
Edition 4.3.10
Author
Gavin King
Author
Pete Muir
Author
Norman Richards
Author
Shane Bryzak
Author
Michael Yuan
Author
Mike Youngstrom
Author
Christian Bauer
Author
Jay Balunas
Author
Dan Allen
Author
Max Rydahl Andersen
Author
Emmanuel Bernard
Editor
Samson Kittoli
Editor
Marek Novotny
Editor
Isaac Rooskov
James Cobb
Cheyenne Weaver
Mark Newton
Steve Ebersole
Daisuke Sano
Kojiro Miyamoto
Shoko Miyamoto
Takeshi Maruyama
Yoshiro Kaneko
Ai Suzuki
Shinobu Nogami
Junnichi Tanabe
Keita Higashi
Fusayuki Minamoto
Takayoshi Kimura
Takayoshi Osawa
Reiko Ohtsuka
Syunpei Shiraishi
Toshiya Kobayashi
Shigeaki Wakizaka
Ken Yamada
Noriko Mizumoto
Copyright © 2011 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons
Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available
at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this
document or an adaptation of it, you must provide the URL for the original version.
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.
Seam 2 Reference Guide
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.
All other trademarks are the property of their respective owners.
This book is a Reference Guide to Seam 2.0.2 for use with JBoss Enterprise Application Platform 4.3
and its patch releases.
v
Preface xv
1. Document Conventions .................................................................................................. xv
1.1. Typographic Conventions .................................................................................... xv
1.2. Pull-quote Conventions ....................................................................................... xvi
1.3. Notes and Warnings .......................................................................................... xvii
2. Getting Help and Giving Feedback ................................................................................ xvii
2.1. Do You Need Help? .......................................................................................... xvii
2.2. Give us Feedback ............................................................................................ xviii
Introduction to JBoss Seam xix
1. Seam Tutorial 1
1.1. Try the examples ......................................................................................................... 1
1.1.1. Running the examples on JBoss AS ................................................................... 1
1.2. Your first Seam application: the registration example ...................................................... 1
1.2.1. Understanding the code ..................................................................................... 2
1.2.2. How it works ................................................................................................... 10
1.3. Clickable lists in Seam: the messages example ........................................................... 10
1.3.1. Understanding the code ................................................................................... 11
1.3.2. How it works ................................................................................................... 15
1.4. Seam and jBPM: the todo list example ........................................................................ 15
1.4.1. Understanding the code ................................................................................... 16
1.5. Seam pageflow: the numberguess example ................................................................. 21
1.5.1. Understanding the code ................................................................................... 21
1.6. A complete Seam application: the Hotel Booking example ............................................ 27
1.6.1. Introduction ..................................................................................................... 27
1.6.2. Overview of the booking example ..................................................................... 29
1.6.3. Understanding Seam conversations .................................................................. 29
1.6.4. The Seam UI control library ............................................................................. 35
1.6.5. The Seam Debug Page ................................................................................... 36
1.7. A complete application featuring Seam and jBPM: the DVD Store example ..................... 37
1.8. An example of Seam with Hibernate: the Hibernate Booking example ............................ 38
1.9. A RESTful Seam application: the Blog example ........................................................... 38
1.9.1. Using "pull"-style MVC ..................................................................................... 39
1.9.2. Bookmarkable search results page ................................................................... 40
1.9.3. Using "push"-style MVC in a RESTful application ............................................... 42
2. Getting started with Seam, using seam-gen 45
2.1. Before you start ......................................................................................................... 45
2.2. Setting up a new Eclipse project ................................................................................. 45
2.3. Creating a new action ................................................................................................ 48
2.4. Creating a form with an action .................................................................................... 49
2.5. Generating an application from an existing database .................................................... 49
2.6. Generating an application from existing JPA/EJB3 entities ............................................ 50
2.7. Deploying the application as an EAR ........................................................................... 50
2.8. Seam and incremental hot deployment ........................................................................ 50
3. Getting started with Seam, using JBoss Tools 53
3.1. Before you start ......................................................................................................... 53
3.2. Setting up a new Seam project ................................................................................... 53
3.3. Creating a new action ................................................................................................ 66
3.4. Creating a form with an action .................................................................................... 68
3.5. Generating an application from an existing database .................................................... 69
3.6. Seam and incremental hot deployment with JBoss Tools ............................................... 70
4. Migrating from Seam 1.2 to Seam 2 73
Seam 2 Reference Guide
vi
4.1. Creating a new project skeleton using seam-gen .......................................................... 73
4.2. In place migration ....................................................................................................... 73
4.2.1. Migrating to JSF 1.2 ........................................................................................ 73
4.2.2. Migrating web.xml to Seam 2 ......................................................................... 74
4.2.3. Migrating faces-config.xml to Seam 2 ........................................................ 75
4.2.4. Deployment structure changes ......................................................................... 76
4.2.5. Migration to JBoss Embedded .......................................................................... 76
4.3. Updating your code .................................................................................................... 77
4.3.1. Built-in Component changes ............................................................................. 77
4.3.2. Annotation changes in Seam 2 ......................................................................... 81
4.3.3. Other changes needed to components.xml .................................................... 82
4.3.4. Migration to jBPM 3.2 ...................................................................................... 83
4.3.5. Migration to RichFaces 3.1 ............................................................................... 83
4.3.6. Changes to Seam UI ....................................................................................... 83
4.3.7. Changes to seam-gen ...................................................................................... 84
5. The contextual component model 85
5.1. Seam contexts ........................................................................................................... 85
5.1.1. Stateless context ............................................................................................. 85
5.1.2. Event context .................................................................................................. 85
5.1.3. Page context ................................................................................................... 86
5.1.4. Conversation context ....................................................................................... 86
5.1.5. Session context ............................................................................................... 86
5.1.6. Business process context ................................................................................. 87
5.1.7. Application context ........................................................................................... 87
5.1.8. Context variables ............................................................................................. 87
5.1.9. Context search priority ..................................................................................... 87
5.1.10. Concurrency model ........................................................................................ 88
5.2. Seam components ..................................................................................................... 88
5.2.1. Stateless session beans .................................................................................. 88
5.2.2. Stateful session beans ..................................................................................... 89
5.2.3. Entity beans .................................................................................................... 89
5.2.4. JavaBeans ...................................................................................................... 90
5.2.5. Message-driven beans ..................................................................................... 90
5.2.6. Interception ..................................................................................................... 90
5.2.7. Component names .......................................................................................... 91
5.2.8. Defining the component scope ......................................................................... 92
5.2.9. Components with multiple roles ........................................................................ 92
5.2.10. Built-in components ........................................................................................ 93
5.3. Bijection ..................................................................................................................... 93
5.4. Lifecycle methods ....................................................................................................... 95
5.5. Conditional installation ................................................................................................ 95
5.6. Logging ...................................................................................................................... 96
5.7. The Mutable interface and @ReadOnly ..................................................................... 97
5.8. Factory and manager components .............................................................................. 99
6. Configuring Seam components 101
6.1. Configuring components via property settings ............................................................. 101
6.2. Configuring components via components.xml ......................................................... 101
6.3. Fine-grained configuration files .................................................................................. 104
6.4. Configurable property types ...................................................................................... 104
6.5. Using XML Namespaces ........................................................................................... 105
7. Events, interceptors and exception handling 109
7.1. Seam events ............................................................................................................ 109
vii
7.2. Page actions ............................................................................................................ 109
7.3. Page parameters ...................................................................................................... 110
7.3.1. Mapping request parameters to the model ....................................................... 110
7.4. Propagating request parameters ................................................................................ 111
7.5. Conversion and Validation ......................................................................................... 111
7.6. Navigation ................................................................................................................ 112
7.7. Fine-grained files for definition of navigation, page actions and parameters ................... 114
7.8. Component-driven events ......................................................................................... 115
7.9. Contextual events ..................................................................................................... 116
7.10. Seam interceptors ................................................................................................... 118
7.11. Managing exceptions .............................................................................................. 119
7.11.1. Exceptions and transactions ......................................................................... 119
7.11.2. Enabling Seam exception handling ................................................................ 120
7.11.3. Using annotations for exception handling ....................................................... 120
7.11.4. Using XML for exception handling ................................................................. 121
7.11.5. Some common exceptions ............................................................................ 121
8. Conversations and workspace management 123
8.1. Seam's conversation model ....................................................................................... 123
8.2. Nested conversations ............................................................................................... 125
8.3. Starting conversations with GET requests .................................................................. 125
8.4. Using <s:link> and <s:button> .......................................................................... 126
8.5. Success messages ................................................................................................... 127
8.6. Natural conversation ids ............................................................................................ 128
8.7. Creating a natural conversation ................................................................................. 128
8.8. Redirecting to a natural conversation ......................................................................... 129
8.9. Workspace management ........................................................................................... 130
8.9.1. Workspace management and JSF navigation .................................................. 130
8.9.2. Workspace management and jPDL pageflow ................................................... 130
8.9.3. The conversation switcher .............................................................................. 131
8.9.4. The conversation list ...................................................................................... 132
8.9.5. Breadcrumbs ................................................................................................. 132
8.10. Conversational components and JSF component bindings ......................................... 133
8.11. Concurrent calls to conversational components ......................................................... 133
8.11.1. How should we design our conversational AJAX application? .......................... 134
8.11.2. Dealing with errors ....................................................................................... 135
8.11.3. RichFaces Ajax ............................................................................................ 136
9. Pageflows and business processes 137
9.1. Pageflow in Seam .................................................................................................... 137
9.1.1. The two navigation models ............................................................................. 137
9.1.2. Seam and the back button ............................................................................. 140
9.2. Using jPDL pageflows ............................................................................................... 141
9.2.1. Installing pageflows ........................................................................................ 141
9.2.2. Starting pageflows ......................................................................................... 141
9.2.3. Page nodes and transitions ............................................................................ 142
9.2.4. Controlling the flow ........................................................................................ 143
9.2.5. Ending the flow .............................................................................................. 143
9.2.6. Pageflow composition .................................................................................... 143
9.3. Business process management in Seam .................................................................... 144
9.4. Using jPDL business process definitions .................................................................... 145
9.4.1. Installing process definitions ........................................................................... 145
9.4.2. Initializing actor ids ........................................................................................ 145
9.4.3. Initiating a business process ........................................................................... 145
9.4.4. Task assignment ............................................................................................ 145
Seam 2 Reference Guide
viii
9.4.5. Task lists ....................................................................................................... 146
9.4.6. Performing a task .......................................................................................... 146
10. Seam and Object/Relational Mapping 149
10.1. Introduction ............................................................................................................ 149
10.2. Seam managed transactions ................................................................................... 149
10.2.1. Disabling Seam-managed transactions .......................................................... 150
10.2.2. Configuring a Seam transaction manager ...................................................... 150
10.2.3. Transaction synchronization .......................................................................... 151
10.3. Seam-managed persistence contexts ....................................................................... 152
10.3.1. Using a Seam-managed persistence context with JPA .................................... 152
10.3.2. Using a Seam-managed Hibernate session ................................................... 152
10.3.3. Seam-managed persistence contexts and atomic conversations ...................... 153
10.4. Using the JPA delegate ........................................................................................... 154
10.5. Using EL in EJB-QL/HQL ........................................................................................ 155
10.6. Using Hibernate filters ............................................................................................. 155
11. JSF form validation in Seam 157
12. Groovy integration 163
12.1. Groovy introduction ................................................................................................. 163
12.2. Writing Seam applications in Groovy ........................................................................ 163
12.2.1. Writing Groovy components .......................................................................... 163
12.2.2. seam-gen .................................................................................................... 165
12.3. Deployment ............................................................................................................ 165
12.3.1. Deploying Groovy code ................................................................................ 165
12.3.2. Native .groovy file deployment at development time ........................................ 165
12.3.3. seam-gen .................................................................................................... 165
13. The Seam Application Framework 167
13.1. Introduction ............................................................................................................ 167
13.2. Home objects ......................................................................................................... 168
13.3. Query objects ......................................................................................................... 172
13.4. Controller objects .................................................................................................... 173
14. Seam and JBoss Rules 175
14.1. Installing rules ........................................................................................................ 175
14.2. Using rules from a Seam component ....................................................................... 176
14.3. Using rules from a jBPM process definition .............................................................. 176
15. Security 179
15.1. Overview ................................................................................................................ 179
15.1.1. Which mode is right for my application? ........................................................ 179
15.2. Requirements ......................................................................................................... 179
15.3. Disabling Security ................................................................................................... 179
15.4. Authentication ......................................................................................................... 180
15.4.1. Configuration ............................................................................................... 180
15.4.2. Writing an authentication method .................................................................. 180
15.4.3. Writing a login form ...................................................................................... 182
15.4.4. Simplified Configuration - Summary .............................................................. 182
15.4.5. Handling Security Exceptions ........................................................................ 183
15.4.6. Login Redirection ......................................................................................... 183
15.4.7. HTTP Authentication .................................................................................... 184
15.4.8. Advanced Authentication Features ................................................................ 185
15.5. Error Messages ...................................................................................................... 185
15.6. Authorization .......................................................................................................... 185
15.6.1. Core concepts ............................................................................................. 185
ix
15.6.2. Securing components ................................................................................... 186
15.6.3. Security in the user interface ........................................................................ 187
15.6.4. Securing pages ............................................................................................ 188
15.6.5. Securing Entities .......................................................................................... 189
15.7. Writing Security Rules ............................................................................................. 191
15.7.1. Permissions Overview .................................................................................. 191
15.7.2. Configuring a rules file ................................................................................. 191
15.7.3. Creating a security rules file ......................................................................... 192
15.8. SSL Security .......................................................................................................... 193
15.9. CAPTCHA .............................................................................................................. 194
15.9.1. Configuring the CAPTCHA Servlet ................................................................ 194
15.9.2. Adding a CAPTCHA to a form ...................................................................... 194
15.9.3. Customizing the CAPTCHA algorithm ............................................................ 195
15.10. Security Events ..................................................................................................... 195
15.11. Run As ................................................................................................................. 196
15.12. Extending the Identity component .......................................................................... 196
16. Internationalization, localization and themes 199
16.1. Internationalizing your app ...................................................................................... 199
16.1.1. Application server configuration .................................................................... 199
16.1.2. Translated application strings ........................................................................ 199
16.1.3. Other encoding settings ................................................................................ 200
16.2. Locales .................................................................................................................. 200
16.3. Labels .................................................................................................................... 201
16.3.1. Defining labels ............................................................................................. 201
16.3.2. Displaying labels .......................................................................................... 202
16.3.3. Faces messages .......................................................................................... 202
16.4. Timezones .............................................................................................................. 202
16.5. Themes .................................................................................................................. 203
16.6. Persisting locale and theme preferences via cookies ................................................. 204
17. Seam Text 205
17.1. Basic formatting ...................................................................................................... 205
17.2. Entering code and text with special characters ......................................................... 206
17.3. Links ...................................................................................................................... 207
17.4. Entering HTML ....................................................................................................... 207
18. iText PDF generation 209
18.1. Using PDF Support ................................................................................................. 209
18.1.1. Creating a document .................................................................................... 209
18.1.2. Basic Text Elements ..................................................................................... 210
18.1.3. Headers and Footers ................................................................................... 214
18.1.4. Chapters and Sections ................................................................................. 215
18.1.5. Lists ............................................................................................................ 216
18.1.6. Tables ......................................................................................................... 218
18.1.7. Document Constants .................................................................................... 220
18.1.8. Configuring iText .......................................................................................... 220
18.2. Charting ................................................................................................................. 221
18.3. Bar codes .............................................................................................................. 229
18.4. Rendering Swing/AWT components ......................................................................... 230
18.5. Further documentation ............................................................................................ 231
19. Email 233
19.1. Creating a message ................................................................................................ 233
19.1.1. Attachments ................................................................................................. 234
19.1.2. HTML/Text alternative part ............................................................................ 235
Seam 2 Reference Guide
x
19.1.3. Multiple recipients ........................................................................................ 235
19.1.4. Multiple messages ....................................................................................... 235
19.1.5. Templates .................................................................................................... 235
19.1.6. Internationalization ....................................................................................... 236
19.1.7. Other Headers ............................................................................................. 236
19.2. Receiving emails .................................................................................................... 236
19.3. Configuration .......................................................................................................... 237
19.3.1. mailSession ............................................................................................ 238
19.4. Tags ....................................................................................................................... 238
20. Asynchronous and messaging 241
20.1. Asynchronously ...................................................................................................... 241
20.1.1. Asynchronous methods ................................................................................ 241
20.1.2. Asynchronous methods with the Quartz Dispatcher ........................................ 243
20.1.3. Asynchronous events ................................................................................... 245
20.2. Messaging in Seam ................................................................................................ 245
20.2.1. Configuration ............................................................................................... 245
20.2.2. Sending messages ....................................................................................... 246
20.2.3. Receiving messages using a message-driven bean ........................................ 246
20.2.4. Receiving messages in the client .................................................................. 247
21. Caching 249
21.1. Using JBossCache in Seam .................................................................................... 249
21.2. Page fragment caching ........................................................................................... 250
22. Web Services 253
22.1. Configuration and Packaging ................................................................................... 253
22.2. Conversational Web Services .................................................................................. 253
22.2.1. A Recommended Strategy ............................................................................ 254
22.3. An example web service ......................................................................................... 254
23. Remoting 257
23.1. Configuration .......................................................................................................... 257
23.2. The "Seam" object .................................................................................................. 257
23.2.1. A Hello World example ................................................................................. 258
23.2.2. Seam.Component ........................................................................................ 259
23.2.3. Seam.Remoting ........................................................................................... 260
23.3. Evaluating EL Expressions ...................................................................................... 261
23.4. Client Interfaces ..................................................................................................... 261
23.5. The Context ........................................................................................................... 262
23.5.1. Setting and reading the Conversation ID ....................................................... 262
23.5.2. Remote calls within the current conversation scope ........................................ 262
23.6. Batch Requests ...................................................................................................... 262
23.7. Working with Data types ......................................................................................... 263
23.7.1. Primitives / Basic Types ................................................................................ 263
23.7.2. JavaBeans ................................................................................................... 263
23.7.3. Dates and Times ......................................................................................... 264
23.7.4. Enums ......................................................................................................... 264
23.7.5. Collections ................................................................................................... 264
23.8. Debugging .............................................................................................................. 265
23.9. The Loading Message ............................................................................................ 265
23.9.1. Changing the message ................................................................................ 265
23.9.2. Hiding the loading message ......................................................................... 265
23.9.3. A Custom Loading Indicator ......................................................................... 265
23.10. Controlling what data is returned ........................................................................... 265
23.10.1. Constraining normal fields .......................................................................... 266
xi
23.10.2. Constraining Maps and Collections .............................................................. 266
23.10.3. Constraining objects of a specific type ......................................................... 267
23.10.4. Combining Constraints ............................................................................... 267
23.11. JMS Messaging .................................................................................................... 267
23.11.1. Configuration .............................................................................................. 267
23.11.2. Subscribing to a JMS Topic ......................................................................... 267
23.11.3. Unsubscribing from a Topic ......................................................................... 268
23.11.4. Tuning the Polling Process ......................................................................... 268
24. Spring Framework integration 269
24.1. Injecting Seam components into Spring beans ......................................................... 269
24.2. Injecting Spring beans into Seam components ......................................................... 270
24.3. Making a Spring bean into a Seam component ......................................................... 271
24.4. Seam-scoped Spring beans .................................................................................... 271
24.5. Using Spring PlatformTransactionManagement ......................................................... 272
24.6. Using a Seam Managed Persistence Context in Spring ............................................. 272
24.7. Using a Seam Managed Hibernate Session in Spring ............................................... 274
24.8. Spring Application Context as a Seam Component ................................................... 274
24.9. Using a Spring TaskExecutor for @Asynchronous ..................................................... 275
25. Hibernate Search 277
25.1. Introduction ............................................................................................................ 277
25.2. Configuration .......................................................................................................... 277
25.3. Usage .................................................................................................................... 278
26. Configuring Seam and packaging Seam applications 281
26.1. Basic Seam configuration ........................................................................................ 281
26.1.1. Integrating Seam with JSF and your servlet container ..................................... 281
26.1.2. Using facelets .............................................................................................. 282
26.1.3. Seam Resource Servlet ................................................................................ 282
26.1.4. Seam servlet filters ...................................................................................... 282
26.1.5. Integrating Seam with your EJB container ..................................................... 285
26.1.6. The Final Item ............................................................................................. 286
26.2. Using Alternate JPA Providers ................................................................................. 287
26.3. Configuring Seam in Java EE 5 ............................................................................... 288
26.3.1. Packaging .................................................................................................... 288
26.4. Configuring Seam in J2EE ...................................................................................... 289
26.4.1. Boostrapping Hibernate in Seam ................................................................... 290
26.4.2. Boostrapping JPA in Seam ........................................................................... 290
26.4.3. Packaging .................................................................................................... 290
26.5. Configuring Seam in Java SE, without JBoss Embedded ........................................... 291
26.6. Configuring jBPM in Seam ...................................................................................... 291
26.6.1. Packaging .................................................................................................... 292
26.7. Configuring SFSB and Session Timeouts in JBoss AS .............................................. 292
26.8. Running Seam in a Portlet ...................................................................................... 293
27. Seam annotations 295
27.1. Annotations for component definition ....................................................................... 295
27.2. Annotations for bijection .......................................................................................... 297
27.3. Annotations for component lifecycle methods ........................................................... 300
27.4. Annotations for context demarcation ........................................................................ 301
27.5. Annotations for use with Seam JavaBean components in a J2EE environment ............ 303
27.6. Annotations for exceptions ...................................................................................... 304
27.7. Annotations for Seam Remoting .............................................................................. 305
27.8. Annotations for Seam interceptors ........................................................................... 305
27.9. Annotations for asynchronously ............................................................................... 305
Seam 2 Reference Guide
xii
27.10. Annotations for use with JSF ................................................................................. 306
27.10.1. Annotations for use with dataTable .......................................................... 306
27.11. Meta-annotations for databinding ........................................................................... 307
27.12. Annotations for packaging ..................................................................................... 308
27.13. Annotations for integrating with the servlet container ............................................... 308
28. Built-in Seam components 309
28.1. Context injection components .................................................................................. 309
28.2. Utility components .................................................................................................. 309
28.3. Components for internationalization and themes ....................................................... 311
28.4. Components for controlling conversations ................................................................ 312
28.5. jBPM-related components ....................................................................................... 313
28.6. Security-related components ................................................................................... 314
28.7. JMS-related components ......................................................................................... 315
28.8. Mail-related components ......................................................................................... 315
28.9. Infrastructural components ...................................................................................... 315
28.10. Miscellaneous components .................................................................................... 317
28.11. Special components .............................................................................................. 318
29. Seam JSF controls 321
29.1. Tags ....................................................................................................................... 321
29.1.1. Navigation Controls ...................................................................................... 321
29.1.2. Converters and Validators ............................................................................. 323
29.1.3. Formatting ................................................................................................... 326
29.1.4. Seam Text ................................................................................................... 328
29.1.5. Dropdowns .................................................................................................. 329
29.1.6. Other ........................................................................................................... 330
29.2. Annotations ............................................................................................................ 333
30. JBoss EL 335
30.1. Parametrized Expressions ....................................................................................... 335
30.1.1. Usage ......................................................................................................... 335
30.1.2. Limitations and Hints .................................................................................... 336
30.2. Projection ............................................................................................................... 337
31. Testing Seam applications 339
31.1. Unit testing Seam components ................................................................................ 339
31.2. Integration testing Seam components ...................................................................... 340
31.2.1. Using mocks in integration tests ................................................................... 340
31.3. Integration testing Seam application user interactions ............................................... 341
31.3.1. Configuration ............................................................................................... 344
31.3.2. Using SeamTest with another test framework ................................................. 344
31.3.3. Integration Testing with Mock Data ................................................................ 345
31.3.4. Integration Testing Seam Mail ....................................................................... 346
32. Seam tools 347
32.1. jBPM designer and viewer ...................................................................................... 347
32.1.1. Business process designer ........................................................................... 347
32.1.2. Pageflow viewer ........................................................................................... 347
33. Dependencies 349
33.1. JDK Dependencies ................................................................................................. 349
33.1.1. Sun's JDK 6 Considerations ......................................................................... 349
33.2. Project Dependencies ............................................................................................. 349
33.2.1. Core ............................................................................................................ 349
33.2.2. RichFaces ................................................................................................... 350
33.2.3. Seam Mail ................................................................................................... 350
xiii
33.2.4. Seam PDF .................................................................................................. 351
33.2.5. JBoss Rules ................................................................................................ 351
33.2.6. JBPM .......................................................................................................... 351
33.2.7. GWT ........................................................................................................... 351
33.2.8. Spring ......................................................................................................... 352
33.2.9. Groovy ........................................................................................................ 352
33.3. Dependency Management using Maven ................................................................... 352
A. Revision History 355
xiv
xv
Preface
1. Document Conventions
This manual uses several conventions to highlight certain words and phrases and draw attention to
specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts
1
set. The
Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not,
alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes
the Liberation Fonts set by default.
1.1. Typographic Conventions
Four typographic conventions are used to call attention to specific words and phrases. These
conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight
keycaps and key combinations. For example:
To see the contents of the file my_next_bestselling_novel in your current
working directory, enter the cat my_next_bestselling_novel command at the
shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a keycap, all presented in mono-spaced bold
and all distinguishable thanks to context.
Key combinations can be distinguished from keycaps by the hyphen connecting each part of a key
combination. For example:
Press Enter to execute the command.
Press Ctrl+Alt+F2 to switch to the first virtual terminal. Press Ctrl+Alt+F1 to
return to your X-Windows session.
The first paragraph highlights the particular keycap to press. The second highlights two key
combinations (each a set of three keycaps with each set pressed simultaneously).
If source code is discussed, class names, methods, functions, variable names and returned values
mentioned within a paragraph will be presented as above, in mono-spaced bold. For example:
File-related classes include filesystem for file systems, file for files, and dir for
directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialog box text;
labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose System ® Preferences ® Mouse from the main menu bar to launch Mouse
Preferences. In the Buttons tab, click the Left-handed mouse check box and click
1
https://fedorahosted.org/liberation-fonts/
Preface
xvi
Close to switch the primary mouse button from the left to the right (making the mouse
suitable for use in the left hand).
To insert a special character into a gedit file, choose Applications ® Accessories
® Character Map from the main menu bar. Next, choose Search ® Find… from the
Character Map menu bar, type the name of the character in the Search field and click
Next. The character you sought will be highlighted in the Character Table. Double-
click this highlighted character to place it in the Text to copy field and then click the
Copy button. Now switch back to your document and choose Edit ® Paste from the
gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific
menu names; and buttons and text found within a GUI interface, all presented in proportional bold and
all distinguishable by context.
Mono-spaced Bold Italic or Proportional Bold Italic
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or
variable text. Italics denotes text you do not input literally or displayed text that changes depending on
circumstance. For example:
To connect to a remote machine using ssh, type ssh username@domain.name at
a shell prompt. If the remote machine is example.com and your username on that
machine is john, type ssh john@example.com.
The mount -o remount file-system command remounts the named file
system. For example, to remount the /home file system, the command is mount -o
remount /home.
To see the version of a currently installed package, use the rpm -q package
command. It will return a result as follows: package-version-release.
Note the words in bold italics above — username, domain.name, file-system, package, version and
release. Each word is a placeholder, either for text you enter when issuing a command or for text
displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and
important term. For example:
Publican is a DocBook publishing system.
1.2. Pull-quote Conventions
Terminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in mono-spaced roman and presented thus:
books Desktop documentation drafts mss photos stuff svn
books_tests Desktop1 downloads images notes scripts svgs
Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows:
package org.jboss.book.jca.ex1;
import javax.naming.InitialContext;
Notes and Warnings
xvii
public class ExClient
{
public static void main(String args[])
throws Exception
{
InitialContext iniCtx = new InitialContext();
Object ref = iniCtx.lookup("EchoBean");
EchoHome home = (EchoHome) ref;
Echo echo = home.create();
System.out.println("Created Echo");
System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
}
}
1.3. Notes and Warnings
Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
Note
Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should
have no negative consequences, but you might miss out on a trick that makes your life easier.
Important
Important boxes detail things that are easily missed: configuration changes that only apply to
the current session, or services that need restarting before an update will apply. Ignoring a box
labeled 'Important' will not cause data loss but may cause irritation and frustration.
Warning
Warnings should not be ignored. Ignoring warnings will most likely cause data loss.
2. Getting Help and Giving Feedback
2.1. Do You Need Help?
If you experience difficulty with a procedure described in this documentation, visit the Red Hat
Customer Portal at http://access.redhat.com. Through the customer portal, you can:
• search or browse through a knowledgebase of technical support articles about Red Hat products.
• submit a support case to Red Hat Global Support Services (GSS).
Preface
xviii
• access other product documentation.
Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and
technology. You can find a list of publicly available mailing lists at https://www.redhat.com/mailman/
listinfo. Click on the name of any mailing list to subscribe to that list or to access the list archives.
2.2. Give us Feedback
If you find a typographical error, or know how this guide can be improved, we would love to hear from
you. Submit a report in Bugzilla against the product JBoss Enterprise Application Platform
4 and the component doc-Seam2_Ref_Guide. The following link will take you to a pre-filled bug
report for this product: http://bugzilla.redhat.com/
2
.
Fill out the following template in Bugzilla's Description field. Be as specific as possible when
describing the issue; this will help ensure that we can fix it quickly.
Document URL:
Section Number and Name:
Describe the issue:
Suggestions for improvement:
Additional information:
Be sure to give us your name so that you can receive full credit for reporting the issue.
2
https://bugzilla.redhat.com/enter_bug.cgi?product=JBoss%20Enterprise%20Application%20Platform%204&component=doc-
Seam2_Ref_Guide&version=4.3&short_desc=Bug%20in%20Seam%20Reference%20Guide
xix
Introduction to JBoss Seam
Seam is an application framework for Enterprise Java. It is inspired by the following principles:
A uniform component model
Seam defines a uniform component model for all business logic in your application. A Seam
component may be stateful, with the state associated with any one of several well-defined
contexts, including the long-running, persistent, business process context and the conversation
context, which is preserved across multiple web requests in a user interaction.
There is no distinction between presentation tier components and business logic components
in Seam. Your application can be layered according to whatever architecture you devise, rather
than forcing your application logic into an unnatural layering scheme forced upon you by whatever
combination of frameworks you are using today.
Unlike plain Java EE or J2EE components, Seam components may simultaneously access the
state associated with the web request and the state held in transactional resources (without the
need to propagate a web request state manually via method parameters). Seam grants you the
ability to create a layered architecture in the case that the old J2EE platform is not up-to-date with
your needs. In doing this you get to architect your own application and decide what the layers are
and how they work together.
Integrate JSF with EJB 3.0
JSF and EJB 3.0 are two of the most outstanding new features of Java EE 5. EJB3 is a brand new
component model for server side business and persistence logic. Meanwhile, JSF is an excellent
component model for the presentation tier. Unfortunately, neither component model is able to
solve all problems in computing by itself. Indeed, JSF and EJB3 work best when used together.
But the Java EE 5 specification provides no standard way to integrate the two component models.
Fortunately, the creators of both models foresaw this situation and provided standard extension
points to allow extension and integration with other frameworks.
Seam unifies the component models of JSF and EJB3, eliminating glue code, and allowing the
developer to concentrate on the business problem.
It is possible to write Seam applications where everything is an EJB. This may come as a surprise
if you're used to thinking of EJBs as unrefined objects. However, version 3.0 has completely
changed the nature of EJB from the point of view of the developer. An EJB is a refined object;
nothing more complex than an annotated JavaBean. Furthermore it is encouraged that sessions
beans are used as JSF action listeners.
On the other hand, if you prefer not to adopt EJB 3.0 at this time, you don't have to. Virtually any
Java class may be a Seam component, and Seam provides all the functionality that you expect
from a simplistic container (and more) for any component, EJB or otherwise.
Integrated AJAX
Seam supports the finest open source JSF-based AJAX solutions: JBoss RichFaces and
ICEfaces. These solutions allow you to add AJAX capability to your user interface without the
need to write any JavaScript code.
Introduction to JBoss Seam
xx
Technology preview
Icefaces integration in Seam is marked as technology preview, so standard support is not
guaranteed.
Alternatively, Seam provides a built-in JavaScript remoting layer that lets you call components
asynchronously from client-side JavaScript without the need for an intermediate action layer. You
can even subscribe to server-side JMS topics and receive messages via AJAX push.
Neither of these approaches would work well, were it not for Seam's built-in concurrency and state
management, which ensures that many concurrent, asynchronous AJAX requests are handled
safely and efficiently on the server side.
Business process as a first class construct
Optionally, Seam provides transparent business process management via jBPM allowing for
implemention of complex workflows, collaboration and task management using jBPM and Seam to
be relatively simple.
Seam even allows you to define presentation tier pageflow using the same language (jPDL) that
jBPM uses for business process definition.
JSF provides an incredibly rich event model for the presentation tier. Seam enhances this
model by exposing jBPM's business process related events via exactly the same event handling
mechanism, providing a uniform event model for Seam's uniform component model.
Declarative state management
The concept of declarative transaction management and declarative security has been present
since the early days of EJB. EJB 3.0 now introduces declarative persistence context management.
These are three examples of a broader problem of managing state that is associated with a
particular context, while ensuring that all needed cleanup occurs when the context ends. Seam
takes the concept of declarative state management much further and applies it to application state.
Traditionally, J2EE applications implement state management manually, by getting and setting
servlet session and request attributes. This approach to state management is the source of many
bugs and memory leaks when applications fail to clean up session attributes, or when session
data associated with different workflows collides in a multi-window application. Seam has the
potential to almost entirely eliminate this class of bugs.
Declarative application state management is made possible by the richness of the context model
defined by Seam. Seam extends the context model defined by the servlet spec (request, session,
application) with two new contexts (conversation and business process) that are more meaningful
from the point of view of the business logic.
You will be amazed at how many things become easier once you start using conversations. Have
you ever suffered pain dealing with lazy association fetching in an ORM solution like Hibernate
or JPA? Seam's conversation-scoped persistence contexts mean you will rarely have to see a
LazyInitializationException. Have you ever had problems with the refresh button? The
back button? With duplicate form submission? With propagating messages across a post-then-
redirect? Seam's conversation management solves these problems without you even needing to
really think about them. They're all symptoms of the broken state management architecture that
has been prevalent since the earliest days of the web.
xxi
Bijection
The notion of Inversion of Control or dependency injection exists in both JSF and EJB3, as well as
in numerous simplistic containers. Most of these containers emphasize injection of components
that implement stateless services. Even when injection of stateful components is supported (such
as in JSF), it is virtually useless for handling application state because the scope of the stateful
component cannot be defined with sufficient flexibility, and because components belonging to
wider scopes may not be injected into components belonging to narrower scopes.
Bijection differs from IoC in that it is dynamic, contextual, and bidirectional. You can think of it as a
mechanism for aliasing contextual variables (names in the various contexts bound to the current
thread) to attributes of the component. Bijection allows auto-assembly of stateful components by
the container. It even allows a component to safely and easily manipulate the value of a context
variable, just by assigning it to an attribute of the component.
Workspace management and multi-window browsing
Seam applications let the user freely switch between multiple browser tabs, each associated with
a different, safely isolated, conversation. Applications may even take advantage of workspace
management, allowing the user to switch between conversations (workspaces) in a single browser
tab. Seam provides not only correct multi-window operation, but also multi-window-like operation
within a single window.
Prefer annotations to XML
Traditionally, the Java community has been in a state of deep confusion about precisely what
kind of meta-information counts as configuration. J2EE and popular simplistic containers have
provided XML-based deployment descriptors for code which is truly configurable between
different deployments of the system, and for all other kinds or declarations which can not easily be
expressed in Java; Java 5 annotations changed all this.
EJB 3.0 embraces annotations and configuration by exception as the easiest way to provide
information to the container in a declarative form. Unfortunately, JSF is still heavily dependent on
verbose XML configuration files. Seam extends the annotations provided by EJB 3.0 with a set of
annotations for declarative state management and declarative context demarcation. This allows for
the elimination of the noisy JSF managed bean declarations and reduces the required XML to just
that information which truly belongs in XML (the JSF navigation rules).
Integration testing is easy
Seam components, being plain Java classes, are by nature unit testable. But for complex
applications, unit testing alone is insufficient. Integration testing has traditionally been a messy
and difficult task for Java web applications. Therefore, Seam provides for testability of Seam
applications as a core feature of the framework. You can easily write JUnit or TestNG tests that
reproduce a whole interaction with a user, exercising all components of the system apart from the
view (the JSP or Facelets page). You can run these tests directly inside your IDE, where Seam will
automatically deploy EJB components using JBoss Embedded.
Improving upon Java EE
The latest incarnation of Java EE is a great step forward and we know it's never going to be
perfect. Where there are holes in the specifications (for example, limitations in the JSF lifecycle
for GET requests), Seam fixes them. And the authors of Seam are working with the JCP expert
groups to make sure those fixes make their way back into the next revision of the standards.
There's more to a web application than serving HTML pages
Today's web frameworks think too small. They let you get user input off a form and into your Java
objects. A truly complete web application framework should address problems like persistence,
concurrency, asynchronously, state management, security, email, messaging, PDF and chart
Introduction to JBoss Seam
xxii
generation, workflow, wikitext rendering, webservices, caching and more. Once you scratch the
surface of Seam, you'll be amazed at how many problems become simpler.
Seam integrates JPA and Hibernate3 for persistence, the EJB Timer Service and Quartz for simple
asynchronous operations, jBPM for workflow, Meldware Mail for email, Hibernate Search and
Lucene for full text search, JMS for messaging, JBoss Cache for page fragment caching and
JBoss Rules for business rules, layering an innovative rule-based security framework over JAAS
and JBoss Rules. Also included is JSF tag libraries for rendering PDF, outgoing email, charts and
wikitext. Seam components may be called synchronously as a Web Service, asynchronously from
client-side JavaScript or Google Web Toolkit or, of course, directly from JSF.
Get started now!
Seam works in any Java EE application server, and even works in Tomcat. If your environment
supports EJB 3.0, great! If it doesn't, no problem, you can use Seam's built-in transaction
management with JPA or Hibernate3 for persistence. Or, you can deploy JBoss Embedded in
Tomcat, and get full support for EJB 3.0.
It turns out that the combination of Seam, JSF and EJB3 is the simplest way to write a complex web
application in Java. You won't believe how little code is required!
Chapter 1.
1
Seam Tutorial
1.1. Try the examples
In this tutorial, we will assume that you are using JBoss EAP 4.3.
The directory structure of each example in Seam follows this pattern:
• Web pages, images and stylesheets may be found in examples/registration/view
• Resources such as deployment descriptors and data import scripts may be found in
examples/registration/resources
• Java source code may be found in examples/registration/src
• The Ant build script is examples/registration/build.xml
1.1.1. Running the examples on JBoss AS
First, make sure you have Ant correctly installed, with $ANT_HOME and $JAVA_HOME set
correctly. Next, make sure you set the location of your EAP embedded JBoss AS installation in the
build.properties file in the root folder of your Seam installation, predefined location is /var/
lib/jboss-as. If you haven't already done so, start JBoss AS now by typing bin/run.sh or bin/
run.bat in the root directory of your JBoss installation.
Now, build and deploy the example by typing ant deploy in the examples/registration
directory.
Try it out by accessing http://localhost:8080/seam-registration/
1
with your web
browser.
1.2. Your first Seam application: the registration example
The registration example is a fairly trivial application that lets a new user store his username, real
name and password in the database. The example isn't intended to show off all of the interesting
functionality of Seam. However, it demonstrates the use of an EJB3 session bean as a JSF action
listener, and basic configuration of Seam.
We will go slowly, so you can become familiar with EJB 3.0.
The start page displays a very basic form with three input fields. Try filling them in and then submitting
the form. This will save a user object in the database.
1
http://localhost:8080/seam-registration/
Chapter 1. Seam Tutorial
2
1.2.1. Understanding the code
The example is implemented with two JSP pages, one entity bean and one stateless session bean.
Understanding the code
3
Let's take a look at the code, starting from the "bottom".
1.2.1.1. The entity bean: User.java
We need an EJB entity bean for user data. This class defines persistence and validation decoratively,
via annotations. It also needs some extra annotations that define the class as a Seam component.
@Entity <co id="registration-entity-annotation"/>
@Name("user")
@Scope(SESSION)
@Table(name="users")
public class User implements Serializable
{
private static final long serialVersionUID = 1881413500711441951L;

private String username;
private String password;
private String name;

public User(String name, String password, String username)
{
this.name = name;
this.password = password;
this.username = username;
}

public User() {}

@NotNull @Length(min=5, max=15)
public String getPassword()
{
return password;
}
public void setPassword(String password)
{
this.password = password;
}

@NotNull
public String getName()
{
return name;
}
public void setName(String name)
{
this.name = name;
}

@Id @NotNull @Length(min=5, max=15)
public String getUsername()
{
return username;
}
public void setUsername(String username)
{
this.username = username;
}
}
The EJB3 standard @Entity annotation indicates that the User class is an entity bean.
Chapter 1. Seam Tutorial
4
A Seam component needs a component name specified by the @Name annotation. This name must be
unique within the Seam application. When JSF asks Seam to resolve a context variable with a name
that is the same as a Seam component name, and the context variable is currently undefined (null),
Seam will instantiate that component, and bind the new instance to the context variable. In this case,
Seam will instantiate a User the first time JSF encounters a variable named user.
Whenever Seam instantiates a component, it binds the new instance to a context variable in the
component's default context. The default context is specified using the @Scope annotation. The User
bean is a session scoped component.
The EJB standard @Table annotation indicates that the User class is mapped to the users table.
name, password and username are the persistent attributes of the entity bean. All of our persistent
attributes define accessor methods. These are needed when this component is used by JSF in the
render response and update model values phases.
An empty constructor is required by both the EJB specification and by Seam.
The @NotNull and @Length annotations are part of the Hibernate Validator framework. Seam
integrates Hibernate Validator and lets you use it for data validation (even if you are not using
Hibernate for persistence).
The EJB standard @Id annotation indicates the primary key attribute of the entity bean.
The most important things to notice in this example are the @Name and @Scope annotations. These
annotations establish that this class is a Seam component.
We will see below that the properties of our User class are bound directly to JSF components and
are populated by JSF during the update model values phase. We don't need any tedious glue code to
copy data back and forth between the JSP pages and the entity bean domain model.
However, entity beans shouldn't do transaction management or database access. So we can't use this
component as a JSF action listener. For that we need a session bean.
1.2.1.2. The stateless session bean class: RegisterAction.java
Most Seam application use session beans as JSF action listeners (you can use JavaBeans instead if
you like).
We have exactly one JSF action in our application, and one session bean method attached to it. In this
case, we'll use a stateless session bean, since all the state associated with our action is held by the
User bean.
This is the only really interesting code in the example!
@Stateless
@Name("register")
public class RegisterAction implements Register
{
@In
private User user;

@PersistenceContext
private EntityManager em;

@Logger
private Log log;

public String register()
Understanding the code
5
{
List existing = em.createQuery(
"select username from User where username=#{user.username}")
.getResultList();

if (existing.size()==0)
{
em.persist(user);
log.info("Registered new user #{user.username}");
return "/registered.xhtml";
}
else
{
FacesMessages.instance().add("User #{user.username} already exists");
return null;
}
}
}
The EJB standard @Stateless annotation marks this class as a stateless session bean.
The @In annotation marks an attribute of the bean as injected by Seam. In this case, the attribute is
injected from a context variable named user (the instance variable name).
The EJB standard @PersistenceContext annotation is used to inject the EJB3 entity manager.
The Seam @Logger annotation is used to inject the component's Log instance.
The action listener method uses the standard EJB3 EntityManager API to interact with the
database, and returns the JSF outcome. Note that, since this is a session bean, a transaction is
automatically begun when the register() method is called, and committed when it completes.
Notice that Seam lets you use a JSF EL expression inside EJB-QL. Under the covers, this results in
an ordinary JPA setParameter() call on the standard JPA Query object. Nice, huh?
The Log API lets us easily display log messages created from templates.
JSF action listener methods return a string-valued outcome that determines what page will be
displayed next. A null outcome (or a void action listener method) re-displays the previous page. In
plain JSF, it is normal to always use a JSF navigation rule to determine the JSF view id from the
outcome. For complex application this indirection is useful and a good practice. However, for very
simple examples like this one, Seam lets you use the JSF view id as the outcome, eliminating the
requirement for a navigation rule. Note that when you use a view id as an outcome, Seam always
performs a browser redirect.
Seam provides a number of built-in components to help solve common problems. The
FacesMessages component makes it easy to display template error or success messages. Built-in
Seam components may be obtained by injection, or by calling an instance() method.
Note that we did not explicitly specify a @Scope this time. Each Seam component type has a default
scope if not explicitly specified. For stateless session beans, the default scope is the stateless context.
Actually, all stateless session beans belong in the stateless context.
Our session bean action listener performs the business and persistence logic for our mini-application.
In more complex applications, we might need to layer the code and refactor persistence logic into a
dedicated data access component. That's perfectly trivial to do. But notice that Seam does not force
you into any particular strategy for application layering.
Furthermore, notice that our session bean has simultaneous access to context associated with
the web request (the form values in the User object, for example), and state held in transactional
resources (the EntityManager object). This is a break from traditional J2EE architectures. Again,
Chapter 1. Seam Tutorial
6
if you are more comfortable with the traditional J2EE layering, you can certainly implement that in a
Seam application. But for many applications, it's simply not very useful.
1.2.1.3. The session bean local interface: Register.java
Naturally, our session bean needs a local interface.
@Local
public interface Register
{
public String register();
}
That's the end of the Java code. Now onto the deployment descriptors.
1.2.1.4. The Seam component deployment descriptor: components.xml
If you've used many Java frameworks before, you'll be used to having to declare all your component
classes in some kind of XML file that gradually grows more and more unmanageable as your project
matures. You'll be relieved to know that Seam does not require that application components be
accompanied by XML. Most Seam applications require a very small amount of XML that does not grow
very much as the project gets bigger.
Nevertheless, it is often useful to be able to provide for some external configuration of some
components (particularly the components built in to Seam). You have a couple of options here, but the
most flexible option is to provide this configuration in a file called components.xml, located in the
WEB-INF directory. We'll use the components.xml file to tell Seam how to find our EJB components
in JNDI:
<?xml version="1.0" encoding="UTF-8"?>
<components xmlns="http://jboss.com/products/seam/components"
xmlns:core="http://jboss.com/products/seam/core"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"http://jboss.com/products/seam/core http://jboss.com/products/seam/
core-2.1.xsd
http://jboss.com/products/seam/components http://jboss.com/products/seam/
components-2.1.xsd">

<core:init jndi-pattern="@jndiPattern@"/>

</components>
This code configures a property named jndiPattern of a built-in Seam component named
org.jboss.seam.core.init. The funny @ symbols are there because our Ant build script puts the
correct JNDI pattern in when we deploy the application.
1.2.1.5. The web deployment description: web.xml
The presentation layer for our mini-application will be deployed in a WAR. So we'll need a web
deployment descriptor.
<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
Understanding the code
7
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

<listener>
<listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
</listener>


<listener>
<listener-class>com.sun.faces.config.ConfigureListener</listener-class>
</listener>

<context-param>
<param-name>javax.faces.DEFAULT_SUFFIX</param-name>
<param-value>.xhtml</param-value>
</context-param>

<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>*.seam</url-pattern>
</servlet-mapping>

<session-config>
<session-timeout>10</session-timeout>
</session-config>
</web-app>
This web.xml file configures Seam and JSF. The configuration you see here is pretty much identical
in all Seam applications.
1.2.1.6. The JSF configuration: faces-config.xml
Most Seam applications use JSF views as the presentation layer. So usually we'll need faces-
config.xml. In our case, we are going to use Facelets for defining our views, so we need to tell JSF
to use Facelets as its template engine.
<?xml version="1.0" encoding="UTF-8"?>
<faces-config version="1.2"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/
javaee/web-facesconfig_1_2.xsd">

<application>
<view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
</application>

</faces-config>
Note that we don't need any JSF managed bean declarations! Our managed beans are annotated
Seam components. In Seam applications, the faces-config.xml is used much less often than in
plain JSF.
Chapter 1. Seam Tutorial
8
In fact, once you have all the basic descriptors set up, the only XML you need to write as you add new
functionality to a Seam application is orchestration: navigation rules or jBPM process definitions. Seam
takes the view that process flow and configuration data are the only things that truly belong in XML.
In this simple example, we don't even need a navigation rule, since we decided to embed the view id
in our action code.
1.2.1.7. The EJB deployment descriptor: ejb-jar.xml
The ejb-jar.xml file integrates Seam with EJB3, by attaching the SeamInterceptor to all
session beans in the archive.
<ejb-jar xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd"
version="3.0">

<interceptors>
<interceptor>
<interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
</interceptor>
</interceptors>

<assembly-descriptor>
<interceptor-binding>
<ejb-name>*</ejb-name>
<interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
</interceptor-binding>
</assembly-descriptor>

</ejb-jar>
1.2.1.8. The EJB persistence deployment descriptor: persistence.xml
The persistence.xml file tells the EJB persistence provider where to find the datasource, and
contains some vendor-specific settings. In this case, enables automatic schema export at startup time.
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
version="1.0">
<persistence-unit name="userDatabase">
<provider>org.hibernate.ejb.HibernatePersistence</provider>
<jta-data-source>java:/DefaultDS</jta-data-source>
<properties>
<property name="hibernate.hbm2ddl.auto" value="create-drop">
</properties>
</persistence-unit>

</persistence>
1.2.1.9. The view: register.xhtml and registered.xhtml
The view pages for a Seam application could be implemented using any technology that supports JSF.
In this example we use Facelets, because we think it's better than JSP.
Understanding the code
9
<?xml version="1.0" encoding="utf-8"?>