Seam - Contextual Components A Framework for Enterprise Java

Arya MirSoftware and s/w Development

Apr 27, 2012 (6 years and 5 months ago)

2,627 views

Introduction to JBoss Seam Seam is an application framework for Enterprise Java. It is inspired by the following principles:

Seam - Contextual Components
A Framework for
Enterprise Java
2.0.3.CR1
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
iii
Introduction to JBoss Seam .............................................................................................. xv
1. Contribute to Seam ............................................................................................. xix
1. Seam Tutorial .............................................................................................................. 1
1.1. Try the examples ................................................................................................ 1
1.1.1. Running the examples on JBoss AS ......................................................... 1
1.1.2. Running the examples on Tomcat ............................................................. 1
1.1.3. Running the example tests ....................................................................... 2
1.2. Your first Seam application: the registration example ............................................ 2
1.2.1. Understanding the code ........................................................................... 2
1.2.2. How it works .......................................................................................... 14
1.3. Clickable lists in Seam: the messages example .................................................. 15
1.3.1. Understanding the code .......................................................................... 15
1.3.2. How it works .......................................................................................... 21
1.4. Seam and jBPM: the todo list example ............................................................... 21
1.4.1. Understanding the code .......................................................................... 22
1.4.2. How it works .......................................................................................... 29
1.5. Seam pageflow: the numberguess example ........................................................ 29
1.5.1. Understanding the code .......................................................................... 30
1.5.2. How it works .......................................................................................... 38
1.6. A complete Seam application: the Hotel Booking example ................................... 38
1.6.1. Introduction ............................................................................................ 38
1.6.2. Overview of the booking example ............................................................ 40
1.6.3. Understanding Seam conversations ......................................................... 40
1.6.4. The Seam UI control library .................................................................... 49
1.6.5. The Seam Debug Page .......................................................................... 49
1.7. A complete application featuring Seam and jBPM: the DVD Store example ........... 50
1.8. An example of Seam with Hibernate: the Hibernate Booking example ................... 52
1.9. A RESTful Seam application: the Blog example .................................................. 53
1.9.1. Using "pull"-style MVC ............................................................................ 53
1.9.2. Bookmarkable search results page .......................................................... 55
1.9.3. Using "push"-style MVC in a RESTful application ..................................... 58
2. Getting started with Seam, using seam-gen .............................................................. 63
2.1. Before you start ................................................................................................ 63
2.2. Setting up a new Eclipse project ........................................................................ 64
2.3. Creating a new action ....................................................................................... 67
2.4. Creating a form with an action ........................................................................... 68
2.5. Generating an application from an existing database ........................................... 69
2.6. Generating an application from existing JPA/EJB3 entities ................................... 70
2.7. Deploying the application as an EAR ................................................................. 70
2.8. Seam and incremental hot deployment ............................................................... 70
2.9. Using Seam with JBoss 4.0 ............................................................................... 71
2.9.1. Install JBoss 4.0 .................................................................................... 71
2.9.2. Install the JSF 1.2 RI ............................................................................. 72
3. Getting started with Seam, using JBoss Tools .......................................................... 73
Seam - Contextual Components
iv
3.1. Before you start ................................................................................................ 73
3.2. Setting up a new Seam project .......................................................................... 73
3.3. Creating a new action ....................................................................................... 89
3.4. Creating a form with an action ........................................................................... 91
3.5. Generating an application from an existing database ........................................... 92
3.6. Seam and incremental hot deployment with JBoss Tools ..................................... 94
4. The contextual component model ............................................................................. 95
4.1. Seam contexts .................................................................................................. 95
4.1.1. Stateless context .................................................................................... 95
4.1.2. Event context ......................................................................................... 96
4.1.3. Page context .......................................................................................... 96
4.1.4. Conversation context .............................................................................. 96
4.1.5. Session context ...................................................................................... 97
4.1.6. Business process context ....................................................................... 97
4.1.7. Application context ................................................................................. 97
4.1.8. Context variables ................................................................................... 97
4.1.9. Context search priority ............................................................................ 98
4.1.10. Concurrency model .............................................................................. 98
4.2. Seam components ............................................................................................ 99
4.2.1. Stateless session beans ......................................................................... 99
4.2.2. Stateful session beans ........................................................................... 99
4.2.3. Entity beans ......................................................................................... 100
4.2.4. JavaBeans ........................................................................................... 100
4.2.5. Message-driven beans .......................................................................... 101
4.2.6. Interception .......................................................................................... 101
4.2.7. Component names ............................................................................... 102
4.2.8. Defining the component scope .............................................................. 103
4.2.9. Components with multiple roles ............................................................. 103
4.2.10. Built-in components ............................................................................ 104
4.3. Bijection .......................................................................................................... 104
4.4. Lifecycle methods ........................................................................................... 107
4.5. Conditional installation ..................................................................................... 108
4.6. Logging .......................................................................................................... 109
4.7. The Mutable interface and @ReadOnly ............................................................. 110
4.8. Factory and manager components ................................................................... 113
5. Configuring Seam components ............................................................................... 117
5.1. Configuring components via property settings ................................................... 117
5.2. Configuring components via components.xml ................................................... 117
5.3. Fine-grained configuration files ........................................................................ 121
5.4. Configurable property types ............................................................................. 122
5.5. Using XML Namespaces ................................................................................. 123
6. Events, interceptors and exception handling ........................................................... 129
6.1. Seam events .................................................................................................. 129
6.2. Page actions ................................................................................................... 130
v
6.3. Page parameters ............................................................................................ 131
6.3.1. Mapping request parameters to the model ............................................. 131
6.4. Propagating request parameters ...................................................................... 131
6.5. Conversion and Validation ............................................................................... 132
6.6. Navigation ...................................................................................................... 133
6.7. Fine-grained files for definition of navigation, page actions and parameters .......... 137
6.8. Component-driven events ................................................................................ 137
6.9. Contextual events ........................................................................................... 139
6.10. Seam interceptors ......................................................................................... 141
6.11. Managing exceptions ..................................................................................... 143
6.11.1. Exceptions and transactions ................................................................ 143
6.11.2. Enabling Seam exception handling ...................................................... 144
6.11.3. Using annotations for exception handling ............................................. 144
6.11.4. Using XML for exception handling ....................................................... 145
6.11.5. Some common exceptions .................................................................. 147
7. Conversations and workspace management ........................................................... 149
7.1. Seam's conversation model ............................................................................. 149
7.2. Nested conversations ...................................................................................... 152
7.3. Starting conversations with GET requests ......................................................... 152
7.4. Using <s:link> and <s:button> ..................................................................... 154
7.5. Success messages ......................................................................................... 155
7.6. Natural conversation ids .................................................................................. 156
7.7. Creating a natural conversation ....................................................................... 157
7.8. Redirecting to a natural conversation ............................................................... 158
7.9. Workspace management ................................................................................. 159
7.9.1. Workspace management and JSF navigation ......................................... 159
7.9.2. Workspace management and jPDL pageflow .......................................... 160
7.9.3. The conversation switcher ..................................................................... 160
7.9.4. The conversation list ............................................................................ 161
7.9.5. Breadcrumbs ........................................................................................ 162
7.10. Conversational components and JSF component bindings ............................... 162
7.11. Concurrent calls to conversational components ............................................... 163
7.11.1. RichFaces Ajax .................................................................................. 165
8. Pageflows and business processes ......................................................................... 167
8.1. Pageflow in Seam ........................................................................................... 167
8.1.1. The two navigation models ................................................................... 167
8.1.2. Seam and the back button .................................................................... 171
8.2. Using jPDL pageflows ..................................................................................... 172
8.2.1. Installing pageflows .............................................................................. 172
8.2.2. Starting pageflows ................................................................................ 173
8.2.3. Page nodes and transitions ................................................................... 174
8.2.4. Controlling the flow ............................................................................... 175
8.2.5. Ending the flow .................................................................................... 175
8.2.6. Pageflow composition ........................................................................... 176
Seam - Contextual Components
vi
8.3. Business process management in Seam .......................................................... 176
8.4. Using jPDL business process definitions ........................................................... 177
8.4.1. Installing process definitions .................................................................. 177
8.4.2. Initializing actor ids ............................................................................... 178
8.4.3. Initiating a business process ................................................................. 178
8.4.4. Task assignment .................................................................................. 179
8.4.5. Task lists ............................................................................................. 179
8.4.6. Performing a task ................................................................................. 180
9. Seam and Object/Relational Mapping ...................................................................... 183
9.1. Introduction ..................................................................................................... 183
9.2. Seam managed transactions ............................................................................ 184
9.2.1. Disabling Seam-managed transactions .................................................. 185
9.2.2. Configuring a Seam transaction manager ............................................... 185
9.2.3. Transaction synchronization .................................................................. 186
9.3. Seam-managed persistence contexts ............................................................... 186
9.3.1. Using a Seam-managed persistence context with JPA ............................ 187
9.3.2. Using a Seam-managed Hibernate session ............................................ 187
9.3.3. Seam-managed persistence contexts and atomic conversations .............. 188
9.4. Using the JPA "delegate" ................................................................................ 190
9.5. Using EL in EJB-QL/HQL ................................................................................ 191
9.6. Using Hibernate filters ..................................................................................... 191
10. JSF form validation in Seam .................................................................................. 193
11. Groovy integration ................................................................................................. 199
11.1. Groovy introduction ....................................................................................... 199
11.2. Writing Seam applications in Groovy .............................................................. 199
11.2.1. Writing Groovy components ................................................................ 199
11.2.2. seam-gen ........................................................................................... 201
11.3. Deployment ................................................................................................... 201
11.3.1. Deploying Groovy code ....................................................................... 202
11.3.2. Native .groovy file deployment at development time .............................. 202
11.3.3. seam-gen ........................................................................................... 202
12. The Seam Application Framework ......................................................................... 203
12.1. Introduction ................................................................................................... 203
12.2. Home objects ................................................................................................ 205
12.3. Query objects ................................................................................................ 210
12.4. Controller objects .......................................................................................... 213
13. Seam and JBoss Rules .......................................................................................... 215
13.1. Installing rules ............................................................................................... 215
13.2. Using rules from a Seam component .............................................................. 216
13.3. Using rules from a jBPM process definition ..................................................... 217
14. Security .................................................................................................................. 221
14.1. Overview ...................................................................................................... 221
14.1.1. Which mode is right for my application? ............................................... 221
14.2. Requirements ................................................................................................ 221
vii
14.3. Disabling Security ......................................................................................... 222
14.4. Authentication ............................................................................................... 222
14.4.1. Configuration ...................................................................................... 222
14.4.2. Writing an authentication method ......................................................... 223
14.4.3. Writing a login form ............................................................................ 225
14.4.4. Simplified Configuration - Summary ..................................................... 226
14.4.5. Handling Security Exceptions .............................................................. 226
14.4.6. Login Redirection ................................................................................ 227
14.4.7. HTTP Authentication ........................................................................... 228
14.4.8. Advanced Authentication Features ....................................................... 229
14.5. Error Messages ............................................................................................. 229
14.6. Authorization ................................................................................................. 230
14.6.1. Core concepts .................................................................................... 230
14.6.2. Securing components ......................................................................... 230
14.6.3. Security in the user interface ............................................................... 232
14.6.4. Securing pages .................................................................................. 233
14.6.5. Securing Entities ................................................................................ 234
14.7. Writing Security Rules ................................................................................... 237
14.7.1. Permissions Overview ......................................................................... 237
14.7.2. Configuring a rules file ........................................................................ 237
14.7.3. Creating a security rules file ................................................................ 238
14.8. SSL Security ................................................................................................. 240
14.9. CAPTCHA .................................................................................................... 241
14.9.1. Configuring the CAPTCHA Servlet ....................................................... 241
14.9.2. Adding a CAPTCHA to a form ............................................................. 242
14.9.3. Customising the CAPTCHA algorithm .................................................. 242
14.10. Security Events ........................................................................................... 243
14.11. Run As ....................................................................................................... 243
14.12. Extending the Identity component ................................................................. 244
15. Internationalization, localization and themes ......................................................... 247
15.1. Internationalizing your app ............................................................................. 247
15.1.1. Application server configuration ........................................................... 247
15.1.2. Translated application strings .............................................................. 247
15.1.3. Other encoding settings ...................................................................... 248
15.2. Locales ......................................................................................................... 248
15.3. Labels .......................................................................................................... 249
15.3.1. Defining labels .................................................................................... 250
15.3.2. Displaying labels ................................................................................ 251
15.3.3. Faces messages ................................................................................ 251
15.4. Timezones .................................................................................................... 252
15.5. Themes ........................................................................................................ 252
15.6. Persisting locale and theme preferences via cookies ....................................... 253
16. Seam Text .............................................................................................................. 255
16.1. Basic fomatting ............................................................................................. 255
Seam - Contextual Components
viii
16.2. Entering code and text with special characters ................................................ 257
16.3. Links ............................................................................................................ 258
16.4. Entering HTML .............................................................................................. 259
17. iText PDF generation ............................................................................................. 261
17.1. Using PDF Support ....................................................................................... 261
17.1.1. Creating a document .......................................................................... 261
17.1.2. Basic Text Elements ........................................................................... 262
17.1.3. Headers and Footers .......................................................................... 267
17.1.4. Chapters and Sections ........................................................................ 268
17.1.5. Lists ................................................................................................... 269
17.1.6. Tables ................................................................................................ 270
17.1.7. Document Constants .......................................................................... 273
17.1.8. Configuring iText ................................................................................ 273
17.2. Charting ........................................................................................................ 274
17.3. Bar codes ..................................................................................................... 282
17.4. Rendering Swing/AWT components ................................................................ 283
17.5. Further documentation ................................................................................... 284
18. Email ...................................................................................................................... 285
18.1. Creating a message ...................................................................................... 285
18.1.1. Attachments ....................................................................................... 286
18.1.2. HTML/Text alternative part .................................................................. 288
18.1.3. Multiple recipients ............................................................................... 288
18.1.4. Multiple messages .............................................................................. 288
18.1.5. Templating ......................................................................................... 288
18.1.6. Internationalisation .............................................................................. 289
18.1.7. Other Headers .................................................................................... 290
18.2. Receiving emails ........................................................................................... 290
18.3. Configuration ................................................................................................. 291
18.3.1. mailSession ...................................................................................... 291
18.4. Meldware ...................................................................................................... 292
18.5. Tags ............................................................................................................. 293
19. Asynchronicity and messaging .............................................................................. 297
19.1. Asynchronicity ............................................................................................... 297
19.1.1. Asynchronous methods ....................................................................... 298
19.1.2. Asynchronous methods with the Quartz Dispatcher ............................... 301
19.1.3. Asynchronous events .......................................................................... 304
19.2. Messaging in Seam ....................................................................................... 304
19.2.1. Configuration ...................................................................................... 304
19.2.2. Sending messages ............................................................................. 304
19.2.3. Receiving messages using a message-driven bean .............................. 305
19.2.4. Receiving messages in the client ......................................................... 305
20. Caching .................................................................................................................. 307
20.1. Using JBossCache in Seam ........................................................................... 308
20.2. Page fragment caching .................................................................................. 309
ix
21. Web Services ......................................................................................................... 311
21.1. Configuration and Packaging ......................................................................... 311
21.2. Conversational Web Services ........................................................................ 311
21.2.1. A Recommended Strategy .................................................................. 312
21.3. An example web service ................................................................................ 313
22. Remoting ................................................................................................................ 315
22.1. Configuration ................................................................................................. 315
22.2. The "Seam" object ........................................................................................ 316
22.2.1. A Hello World example ....................................................................... 316
22.2.2. Seam.Component ............................................................................... 318
22.2.3. Seam.Remoting .................................................................................. 320
22.3. Evaluating EL Expressions ............................................................................ 320
22.4. Client Interfaces ............................................................................................ 321
22.5. The Context .................................................................................................. 322
22.5.1. Setting and reading the Conversation ID .............................................. 322
22.5.2. Remote calls within the current conversation scope .............................. 322
22.6. Batch Requests ............................................................................................. 322
22.7. Working with Data types ................................................................................ 323
22.7.1. Primitives / Basic Types ...................................................................... 323
22.7.2. JavaBeans ......................................................................................... 323
22.7.3. Dates and Times ................................................................................ 324
22.7.4. Enums ............................................................................................... 324
22.7.5. Collections ......................................................................................... 325
22.8. Debugging .................................................................................................... 325
22.9. The Loading Message ................................................................................... 326
22.9.1. Changing the message ....................................................................... 326
22.9.2. Hiding the loading message ................................................................ 326
22.9.3. A Custom Loading Indicator ................................................................ 326
22.10. Controlling what data is returned .................................................................. 326
22.10.1. Constraining normal fields ................................................................. 327
22.10.2. Constraining Maps and Collections .................................................... 328
22.10.3. Constraining objects of a specific type ............................................... 328
22.10.4. Combining Constraints ...................................................................... 328
22.11. JMS Messaging ........................................................................................... 329
22.11.1. Configuration .................................................................................... 329
22.11.2. Subscribing to a JMS Topic ............................................................... 329
22.11.3. Unsubscribing from a Topic ............................................................... 329
22.11.4. Tuning the Polling Process ................................................................ 330
23. Seam and the Google Web Toolkit ........................................................................ 331
23.1. Configuration ................................................................................................. 331
23.2. Preparing your component ............................................................................. 331
23.3. Hooking up a GWT widget to the Seam component ......................................... 332
23.4. GWT Ant Targets .......................................................................................... 334
24. Spring Framework integration ............................................................................... 337
Seam - Contextual Components
x
24.1. Injecting Seam components into Spring beans ................................................ 337
24.2. Injecting Spring beans into Seam components ................................................ 339
24.3. Making a Spring bean into a Seam component ............................................... 339
24.4. Seam-scoped Spring beans ........................................................................... 340
24.5. Using Spring PlatformTransactionManagement ............................................... 341
24.6. Using a Seam Managed Persistence Context in Spring .................................... 342
24.7. Using a Seam Managed Hibernate Session in Spring ...................................... 344
24.8. Spring Application Context as a Seam Component .......................................... 344
24.9. Using a Spring TaskExecutor for @Asynchronous ........................................... 345
25. Hibernate Search ................................................................................................... 347
25.1. Introduction ................................................................................................... 347
25.2. Configuration ................................................................................................. 347
25.3. Usage ........................................................................................................... 349
26. Configuring Seam and packaging Seam applications ............................................ 353
26.1. Basic Seam configuration .............................................................................. 353
26.1.1. Integrating Seam with JSF and your servlet container ........................... 353
26.1.2. Using facelets .................................................................................... 354
26.1.3. Seam Resource Servlet ...................................................................... 354
26.1.4. Seam servlet filters ............................................................................. 355
26.1.5. Integrating Seam with your EJB container ............................................ 359
26.1.6. Don't forget! ....................................................................................... 360
26.2. Using Alternate JPA Providers ....................................................................... 360
26.3. Configuring Seam in Java EE 5 ..................................................................... 361
26.3.1. Packaging .......................................................................................... 361
26.4. Configuring Seam in J2EE ............................................................................. 363
26.4.1. Boostrapping Hibernate in Seam ......................................................... 364
26.4.2. Boostrapping JPA in Seam ................................................................. 364
26.4.3. Packaging .......................................................................................... 364
26.5. Configuring Seam in Java SE, without JBoss Embedded ................................. 365
26.6. Configuring Seam in Java SE, with JBoss Embedded ...................................... 366
26.6.1. Installing Embedded JBoss ................................................................. 366
26.6.2. Packaging .......................................................................................... 367
26.7. Configuring jBPM in Seam ............................................................................. 368
26.7.1. Packaging .......................................................................................... 369
26.8. Configuring SFSB and Session Timeouts in JBoss AS ..................................... 370
26.9. Running Seam in a Portlet ............................................................................. 371
27. Seam annotations .................................................................................................. 373
27.1. Annotations for component definition .............................................................. 373
27.2. Annotations for bijection ................................................................................ 376
27.3. Annotations for component lifecycle methods .................................................. 380
27.4. Annotations for context demarcation ............................................................... 381
27.5. Annotations for use with Seam JavaBean components in a J2EE environment ... 385
27.6. Annotations for exceptions ............................................................................. 386
27.7. Annotations for Seam Remoting ..................................................................... 386
xi
27.8. Annotations for Seam interceptors .................................................................. 387
27.9. Annotations for asynchronicity ........................................................................ 387
27.10. Annotations for use with JSF ....................................................................... 388
27.10.1. Annotations for use with dataTable ................................................... 389
27.11. Meta-annotations for databinding .................................................................. 390
27.12. Annotations for packaging ............................................................................ 390
27.13. Annotations for integrating with the servlet container ...................................... 391
28. Built-in Seam components ..................................................................................... 393
28.1. Context injection components ........................................................................ 393
28.2. Utility components ......................................................................................... 393
28.3. Components for internationalization and themes .............................................. 395
28.4. Components for controlling conversations ....................................................... 396
28.5. jBPM-related components .............................................................................. 397
28.6. Security-related components .......................................................................... 399
28.7. JMS-related components ............................................................................... 399
28.8. Mail-related components ................................................................................ 400
28.9. Infrastructural components ............................................................................. 400
28.10. Miscellaneous components .......................................................................... 403
28.11. Special components .................................................................................... 403
29. Seam JSF controls ................................................................................................. 407
29.1. Tags ............................................................................................................. 407
29.1.1. Navigation Controls ............................................................................ 407
29.1.2. Converters and Validators ................................................................... 410
29.1.3. Formatting .......................................................................................... 413
29.1.4. Seam Text ......................................................................................... 416
29.1.5. Dropdowns ......................................................................................... 417
29.1.6. Other ................................................................................................. 418
29.2. Annotations ................................................................................................... 422
30. JBoss EL ................................................................................................................ 425
30.1. Parameterized Expressions ............................................................................ 425
30.1.1. Usage ................................................................................................ 425
30.1.2. Limitations and Hints .......................................................................... 426
30.2. Projection ...................................................................................................... 427
31. Testing Seam applications ..................................................................................... 429
31.1. Unit testing Seam components ....................................................................... 429
31.2. Integration testing Seam components ............................................................. 430
31.2.1. Using mocks in integration tests .......................................................... 431
31.3. Integration testing Seam application user interactions ...................................... 432
31.3.1. Configuration ...................................................................................... 436
31.3.2. Using SeamTest with another test framework ....................................... 436
31.3.3. Integration Testing with Mock Data ...................................................... 437
31.3.4. Integration Testing Seam Mail ............................................................. 438
32. Seam tools ............................................................................................................. 441
32.1. jBPM designer and viewer ............................................................................. 441
Seam - Contextual Components
xii
32.1.1. Business process designer .................................................................. 441
32.1.2. Pageflow viewer ................................................................................. 441
33. Seam on OC4J ....................................................................................................... 443
33.1. Installation and operation of OC4J ................................................................. 443
33.2. The jee5/booking example ......................................................................... 444
33.2.1. Booking Example Dependencies ......................................................... 444
33.2.2. Configuration file changes ................................................................... 446
33.2.3. Building the jee5/booking example ................................................... 447
33.3. Deploying the Seam application to OC4J ........................................................ 447
33.4. Deploying an application created using seam-gen to OC4J .............................. 448
33.4.1. Generating a basic seam-gen application ............................................ 449
33.4.2. Changes needed for deployment to OC4J ............................................ 451
33.4.3. Building and deploying the seam-gen'd application to OC4J .................. 456
33.4.4. Extending example with reverse engineered CRUD and Drools ............. 457
33.5. Finishing up .................................................................................................. 459
34. Seam on BEA's Weblogic ...................................................................................... 461
34.1. Installation and operation of Weblogic ............................................................ 461
34.1.1. Installing 10.0.MP1 ............................................................................. 462
34.1.2. Creating your Weblogic domain ........................................................... 462
34.1.3. How to Start/Stop/Access your domain ................................................ 463
34.2. The jee5/booking Example ......................................................................... 464
34.2.1. EJB3 Issues with Weblogic ................................................................. 464
34.2.2. Getting the jee5/booking Working ..................................................... 465
34.3. The jpa booking example ............................................................................ 471
34.3.1. Building and deploying jpa booking example ....................................... 471
34.3.2. What's different with Weblogic 10.x ...................................................... 472
34.4. Deploying an application created using seam-gen on Weblogic 10.x .................. 474
34.4.1. Running seam-gen setup ..................................................................... 475
34.4.2. What to change for Weblogic 10.X ...................................................... 477
34.4.3. Building and Deploying your application ............................................... 479
35. Seam on IBM's Websphere .................................................................................... 481
35.1. Websphere environment and deployment information ...................................... 481
35.1.1. Installation versions and tips ............................................................... 481
35.1.2. Required custom properties ................................................................. 482
35.2. The jee5/booking example ......................................................................... 482
35.2.1. Configuration file changes ................................................................... 482
35.2.2. Building the jee5/booking example .................................................... 486
35.2.3. Deploying the application to Websphere ............................................... 488
35.3. The jpa booking example ............................................................................ 490
35.3.1. Building the jpa example .................................................................... 490
35.3.2. Deploying the jpa example ................................................................. 491
35.3.3. Whats different for Websphere 6.1 ...................................................... 491
35.4. Deploying an application created using seam-gen on Websphere 6.1.0.13 ......... 493
35.4.1. Running seam-gen Setup .................................................................... 493
xiii
35.4.2. Changes needed for deployment to Websphere .................................... 495
36. Dependencies ......................................................................................................... 503
36.1. Project Dependencies .................................................................................... 503
36.1.1. Core .................................................................................................. 503
36.1.2. RichFaces .......................................................................................... 504
36.1.3. Seam Mail .......................................................................................... 504
36.1.4. Seam PDF ......................................................................................... 504
36.1.5. JBoss Rules ....................................................................................... 504
36.1.6. JBPM ................................................................................................. 505
36.1.7. GWT .................................................................................................. 505
36.1.8. Spring ................................................................................................ 505
36.1.9. Groovy ............................................................................................... 505
36.2. Dependency Management using Maven ......................................................... 506
xiv
xv
Introduction to JBoss Seam
Seam is an application framework for Enterprise Java. It is inspired by the following principles:
One kind of "stuff"
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. You can layer your application according to whatever architecture you devise, rather
than being forced to shoehorn your application logic into an unnatural layering scheme forced
upon you by whatever combination of stovepipe frameworks you're using today.
Unlike plain Java EE or J2EE components, Seam components may simultaneously access
state associated with the web request and state held in transactional resources (without the
need to propagate web request state manually via method parameters). You might object that
the application layering imposed upon you by the old J2EE platform was a Good Thing. Well,
nothing stops you creating an equivalent layered architecture using Seam—the difference is
that 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 best new features of Java EE 5. EJB3 is a brand new
component model for server side business and persistence logic. Meanwhile, JSF is a great
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 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 letting the
developer think about 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 coarse-grained, so-called "heavyweight" objects.
However, version 3.0 has completely changed the nature of EJB from the point of view of
the developer. An EJB is a fine-grained object—nothing more complex than an annotated
JavaBean. Seam even encourages you to use session beans 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 "lightweight" container, and more, for any component, EJB or otherwise.
Introduction to JBoss Seam
xvi
Integrated AJAX
Seam supports the best open source JSF-based AJAX solutions: JBoss RichFaces and
ICEfaces. These solutions let you add AJAX capability to your user interface without the need
to write any JavaScript code.
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 fine-grained, 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. You
won't believe how easy it is to implement complex workflows, collaboration and and task
management using jBPM and Seam.
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
We're all used to the concept of declarative transaction management and declarative
security from the early days of EJB. EJB 3.0 even 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'll 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'll rarely have to see a
LazyInitializationException. Have you ever had problems with the refresh button? The
xvii
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.
Bijection
The notion of Inversion of Control or dependency injection exists in both JSF and EJB3, as
well as in numerous so-called "lightweight 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 in a single window!
Prefer annotations to XML
Traditionally, the Java community has been in a state of deep confusion about precisely what
kinds of meta-information counts as configuration. J2EE and popular "lightweight" containers
have provided XML-based deployment descriptors both for things which are truly configurable
between different deployments of the system, and for any other kinds or declaration 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 lets you eliminate the noisy JSF managed bean declarations and reduce 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
Introduction to JBoss Seam
xviii
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.
The specs ain't perfect
We think the latest incarnation of Java EE is great. But 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. And then they leave you hanging. A truly complete web application
framework should address problems like persistence, concurrency, asynchronicity, state
management, security, email, messaging, PDF and chart 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
lightweight asychronicity, jBPM for workflow, JBoss Rules for business rules, Meldware Mail
for email, Hibernate Search and Lucene for full text search, JMS for messaging and JBoss
Cache for page fragment caching. Seam layers an innovative rule-based security framework
over JAAS and JBoss Rules. There's even 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!
Contribute to Seam
xix
1. Contribute to Seam
Visit SeamFramework.org [http://www.seamframework.org/Community/Contribute] to find out
how to contribute to Seam!
xx
Chapter 1.
1
Seam Tutorial
1.1. Try the examples
In this tutorial, we'll assume that you have downloaded JBoss AS 4.2. You should also have a
copy of Seam downloaded and extracted to a work directory.
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 JBoss AS 4.2 installation in the build.properties
file in the root folder of your Seam installation. 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/ [http://localhost:8080/
seam-registration/] with your web browser.
1.1.2. Running the examples on Tomcat
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 Tomcat 6.0 installation in the build.properties file
in the root folder of your Seam installation. You will need to follow the instructions in Section 26.6.1,
“Installing Embedded JBoss” for installing JBoss Embedded on Tomcat 6.0. JBoss Embedded is
required to run the Seam demo applications on Tomcat. (However, it is possible to use Seam on
Tomcat without JBoss Embedded.)
Now, build and deploy the example by typing ant tomcat.deploy in the examples/registration
directory.
Finally, start Tomcat.
Try it out by accessing http://localhost:8080/jboss-seam-registration/ [http://
localhost:8080/jboss-seam-registration/] with your web browser.
Chapter 1. Seam Tutorial
2
When you deploy the example to Tomcat, any EJB3 components will run inside the JBoss
Embeddable EJB3 container, a complete standalone EJB3 container environment.
1.1.3. Running the example tests
Most of the examples come with a suite of TestNG integration tests. The easiest way to run the
tests is to run ant testexample inside the examples/registration directory. It is also possible
to run the tests inside your IDE using the TestNG plugin.
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 cool
functionality of Seam. However, it demonstrates the use of an EJB3 session bean as a JSF action
listener, and basic configuration of Seam.
We'll go slowly, since we realize you might not yet be 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.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
declaratively, via annotations. It also needs some extra annotations that define the class as a
Seam component.
Example 1.1.
@Entity &lt;co id="registration-entity-annotation"/&gt;
@Name("user")
@Scope(SESSION)
@Table(name="users")
public class User implements Serializable
{
private static final long serialVersionUID = 1881413500711441951L;

Chapter 1. Seam Tutorial
4
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)
Understanding the code
5
{
this.username = username;
}
}
registration-
entity-
annotation:
???
The EJB3 standard @Entity annotation indicates that the User class is an entity bean.
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 both 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'll 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).
Chapter 1. Seam Tutorial
6
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!
Example 1.2.
@Stateless
@Name("register")
public class RegisterAction implements Register
{
@In
private User user;

@PersistenceContext
private EntityManager em;

@Logger
private Log log;

public String register()
{
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;
Understanding the code
7
}
}
}
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 templated log messages.
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) redisplays 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 templated 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,
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.
Chapter 1. Seam Tutorial
8
1.2.1.3. The session bean local interface: Register.java
Naturally, our session bean needs a local interface.
Example 1.3.
@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:
Example 1.4.
<?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>
Understanding the code
9
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.
Example 1.5.
<?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"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
<!-- Seam -->
<listener>
<listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
</listener>
<!-- JSF -->

<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>
Chapter 1. Seam Tutorial
10
</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 configration: 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 templating engine.
Example 1.6.
<?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">
<!-- Facelets support -->
<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.
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.
Understanding the code
11
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>
Chapter 1. Seam Tutorial
12
<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.
Example 1.7.
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:s="http://jboss.com/products/seam/taglib"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:f="http://java.sun.com/jsf/core">
<head>
<title>Register New User</title>
</head>
<body>
<f:view>
<h:form>
<s:validateAll>
<h:panelGrid columns="2">
Username: <h:inputText value="#{user.username}" required="true"/>
Real Name: <h:inputText value="#{user.name}" required="true"/>
Password: <h:inputSecret value="#{user.password}" required="true"/>
</h:panelGrid>
</s:validateAll>
<h:messages/>
<h:commandButton value="Register" action="#{register.register}"/>
</h:form>
</f:view>
</body>
</html>
Understanding the code
13
The only thing here that is specific to Seam is the <s:validateAll> tag. This JSF component tells
JSF to validate all the contained input fields against the Hibernate Validator annotations specified
on the entity bean.
Example 1.8.
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:f="http://java.sun.com/jsf/core">
<head>
<title>Successfully Registered New User</title>
</head>
<body>
<f:view>
Welcome, #{user.name}, you are successfully registered as #{user.username}.
</f:view>
</body>
</html>
This is a boring old Facelets page using some embedded EL. There is nothing specific to Seam
here.
1.2.1.10. The EAR deployment descriptor: application.xml
Finally, since our application is deployed as an EAR, we need a deployment descriptor there, too.
Example 1.9. registration application
<?xml version="1.0" encoding="UTF-8"?>
<application 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/application_5.xsd"
version="5">

<display-name>Seam Registration</display-name>
<module>
<web>
Chapter 1. Seam Tutorial
14
<web-uri>jboss-seam-registration.war</web-uri>
<context-root>/seam-registration</context-root>
</web>
</module>
<module>
<ejb>jboss-seam-registration.jar</ejb>
</module>
<module>
<ejb>jboss-seam.jar</ejb>
</module>
<module>
<java>jboss-el.jar</java>
</module>
</application>
This deployment descriptor links modules in the enterprise archive and binds the web application
to the context root /seam-registration.
We've now seen all the files in the entire application!
1.2.2. How it works
When the form is submitted, JSF asks Seam to resolve the variable named user. Since there is no
value already bound to that name (in any Seam context), Seam instantiates the user component,
and returns the resulting User entity bean instance to JSF after storing it in the Seam session
context.
The form input values are now validated against the Hibernate Validator constraints specified on
the User entity. If the constraints are violated, JSF redisplays the page. Otherwise, JSF binds the
form input values to properties of the User entity bean.
Next, JSF asks Seam to resolve the variable named register. Seam finds the RegisterAction
stateless session bean in the stateless context and returns it. JSF invokes the register() action
listener method.
Seam intercepts the method call and injects the User entity from the Seam session context, before
continuing the invocation.
The register() method checks if a user with the entered username already exists. If so, an error
message is queued with the FacesMessages component, and a null outcome is returned, causing
a page redisplay. The FacesMessages component interpolates the JSF expression embedded in
the message string and adds a JSF FacesMessage to the view.
If no user with that username exists, the "/registered.xhtml" outcome triggers a browser
redirect to the registered.xhtml page. When JSF comes to render the page, it asks Seam to
Clickable lists in Seam: the messages example
15
resolve the variable named user and uses property values of the returned User entity from Seam's
session scope.
1.3. Clickable lists in Seam: the messages example
Clickable lists of database search results are such an important part of any online application that
Seam provides special functionality on top of JSF to make it easier to query data using EJB-QL
or HQL and display it as a clickable list using a JSF <h:dataTable>. The messages example
demonstrates this functionality.
1.3.1. Understanding the code
The message list example has one entity bean, Message, one session bean, MessageListBean
and one JSP.
Chapter 1. Seam Tutorial
16
1.3.1.1. The entity bean: Message.java
The Message entity defines the title, text, date and time of a message, and a flag indicating whether
the message has been read:
Example 1.10.
@Entity
@Name("message")
@Scope(EVENT)
public class Message implements Serializable
{
private Long id;
private String title;
private String text;
private boolean read;
private Date datetime;

@Id @GeneratedValue
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}

@NotNull @Length(max=100)
public String getTitle() {
return title;
}
public void setTitle(String title) {
this.title = title;
}

@NotNull @Lob
public String getText() {
return text;
}
public void setText(String text) {
this.text = text;
}

@NotNull
public boolean isRead() {
Understanding the code
17
return read;
}
public void setRead(boolean read) {
this.read = read;
}

@NotNull
@Basic @Temporal(TemporalType.TIMESTAMP)
public Date getDatetime() {
return datetime;
}
public void setDatetime(Date datetime) {
this.datetime = datetime;
}

}
1.3.1.2. The stateful session bean: MessageManagerBean.java
Just like in the previous example, we have a session bean, MessageManagerBean, which defines
the action listener methods for the two buttons on our form. One of the buttons selects a message
from the list, and displays that message. The other button deletes a message. So far, this is not
so different to the previous example.
But MessageManagerBean is also responsible for fetching the list of messages the first time we
navigate to the message list page. There are various ways the user could navigate to the page,
and not all of them are preceded by a JSF action—the user might have bookmarked the page, for