Ques2: What’re its main principles?
Ans2: They are:

(a) One kind of “stuff”: Seam defines a uniform component model for all business logic in your application.
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.

(b) 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. But the Java EE 5 specification provides no standard way to integrate the two component
models. 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. EJB3.0 is a fine-grained component & like an
annotated JavaBean component. With seam we can even use session beans as JSF action listeners!
We can use any Java class as a seam component & not just EJB3.0.

(c) 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.

(d) Business process as a first class construct: Optionally, Seam provides transparent business process management via jBPM.
It’s very easy to implement complex workflows, collaboration 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.

(e) 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. In all the three
cases associated with a particular context, we need to ensure 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’s proper handling 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.
Seam’s conversation-scoped persistence contexts mean you’ll rarely have to see a LazyInitializationException.
The 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.

(f) 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.

(g) 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 multiwindow-like operation in a single window!

(h) Prefer annotations to XML: 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).

(i) 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.

(j) 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.

(k) 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.

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!

Ques3: What’s the folder structure of the seam-based application?
Ans3: Suppose our project name is registration & it’s at the location examples/registration.
Below is the folder structure:
——————————
examples/registration/view: Contains Web pages, images and stylesheets.
examples/registration/resources: Resources such as deployment descriptors and data import scripts.
examples/registration/src: Java source code.
examples/registration/build.xml: The Ant build script.

Ques4: Before running the seam example on JBoss AS, what are the things need to be set?
Ans4: First, make sure you have Ant correctly installed, with $ANT_HOME and $JAVA_HOME set correctly.
Then set the JBoss AS 4.2 installation location  in the build.properties file in the root folder of your Seam project.
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.
Finally, try it with accessing http://localhost:8080/seam-registration/ [http://localhost:8080/seam-registration/] with
your web browser.

Ques5: How to run its test application?
Ans5: 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.

Ques6: Details of the deployment descriptors used in the seam application?
Ans6:
components.xml: Seam component deployment descriptor ->
——————————————————–
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. 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.

web.xml: The web deployment description ->
——————————————-
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”
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>
</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.

faces-config.xml: The JSF configration ->
——————————————
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.

<?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.

ejb-jar.xml: The EJB deployment descriptor ->
———————————————-
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>

persistence.xml: The EJB persistence deployment descriptor ->
————————————————————–
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>

application.xml: The EAR deployment descriptor ->
————————————————-
Finally, since our application is deployed as an EAR, we need a deployment descriptor there, too.

<?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>
<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.

Ques7: What are the commands we need to enter to get start with seam application?
Ans7:
(a) The Seam distribution includes a command line utility that makes it really easy to set up an Eclipse project, generate
some simple Seam skeleton code, and reverse engineer an application from a preexisting database. It works best with JBoss AS. You can also use the generated project
It works with other J2EE or Java EE 5 application servers by making a few manual changes to the project configuration. We can use it
without eclipse as well as in conjunction with Eclipse for debugging and integration testing.
Seam-gen is basically just a big ugly Ant script wrapped around Hibernate Tools, together with some templates. That makes it
easy to customize if you need to, so this’s how we can reverse engineer an application from a preexisting database.

Before you start: Make sure you have JDK 5 or JDK 6, JBoss AS 4.2 and Ant 1.6, along with recent versions of Eclipse, the
—————–
JBoss IDE plugin for Eclipse and the TestNG plugin for Eclipse correctly installed before starting. Add your JBoss
installation to the JBoss Server View in Eclipse. Start JBoss in debug mode. Finally, start a command prompt in the directory
where you unzipped the Seam distribution.

JBoss has sophisticated support for hot re-deployment of WARs and EARs. Unfortunately, due to bugs in the JVM, repeated
redeployment of an EAR—which is common during development—eventually causes the JVM to run out of perm gen space. For this
reason, we recommend running JBoss in a JVM with a large perm gen space at development time. If you’re running JBoss from
JBoss IDE, you can configure this in the server launch configuration, under “VM arguments”. We suggest the following values:
-Xms512m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512

If you don’t have so much memory available, the following is our minimum recommendation:
-Xms256m -Xmx512m -XX:PermSize=128m -XX:MaxPermSize=256

If you’re running JBoss from the command line, you can configure the JVM options in bin/run.conf. If you don’t want to bother
with this stuff now, you don’t have to—come back to it later, when you get your first OutOfMemoryException.

Setting up a new Eclipse project: Go to cd jboss-seam-2.0.x, then type ‘seam setup’; enter all the details then type
‘seam create-project’ to create a new project. Here all the information we have provided is stored in the file
seam-gen/build.properties, but we can also modify them simply by running seam setup a second time.
Now we can create a new project in our Eclipse workspace directory, by typing: ‘seam new-project’.
This copies the Seam jars, dependent jars and the JDBC driver jar to a new Eclipse project, and generates all needed
resources and configuration files, a facelets template file and stylesheet,along with Eclipse metadata and an Ant build
script.The Eclipse project will be automatically deployed to an exploded directory structure in JBoss AS as soon as you add
the project using New -> Project… -> General -> Project -> Next, typing the Project name (helloworld in this case), and
then clicking Finish. Do not select Java Project from the New Project wizard.

The generated project includes three database and persistence configurations. The persistence-test.xml and import-test.sql
files are used when running the TestNG unit tests against HSQLDB. The database schema and the test data in import-test.sql
is always exported to the database before running tests. The myproject-dev-ds.xml, persistence-dev.xmland import-dev.sql
files are for use when deploying the application to your development database. The schema might be exported automatically at
deployment, depending upon whether you told seam-gen that you are working with an existing database. The
myproject-prod-ds.xml, persistence-prod.xml and import-prod.sql files are for use when deploying the application to your
production database. The schema is not exported automatically at deployment.

Creating a new action: Type ‘seam new-action’ (To add a new seam component & corresponding page).

Creating a form with an action: Type ‘seam new-form’ (To create a new form).

Generating an application from an existing database: Type ‘seam generate-entities’
(it’s called reverse-engineering where from an existing database tables we get entity beans, session beans, pages etc).

Generating an application from existing JPA/EJB3 entities: First i need to place my existing, valid entity classes inside the
src/model. Now type ‘seam generate-ui’.
Restart the deployment, and go to http://localhost:8080/helloworld.

Deploying the application as an EAR:
By default, the application will be deployed with the dev profile. The EAR will include the persistence-dev.xml and
import-dev.sql files, and the myproject-dev-ds.xml file will be deployed. You can change the profile, and use the prod
profile, by typing: seam -Dprofile=prod deploy.

You can even define new deployment profiles for your application. Just add appropriately named files to your project—for
example, persistence-staging.xml, import-staging.sql and myproject-staging-ds.xml—and select the name of the profile
using -Dprofile=staging.

Seam and incremental hot deployment: When you deploy your Seam application as an exploded directory, you’ll get some support
for incremental hot deployment at development time. You need to enable debug mode in both Seam and Facelets, by adding this
line to components.xml: <core:init debug=”true”>.

Now, the following files may be redeployed without requiring a full restart of the web application:
• any facelets page
• any pages.xml file

But if we want to change any Java code, we still need to do a full restart of the application. (In JBoss this may be
accomplished by touching the top level deployment descriptor: application.xml for an EAR deployment, or web.xml for a WAR
deployment).

But if you really want a fast edit/compile/test cycle, Seam supports incremental redeployment of JavaBean components. To make
use of this functionality, you must deploy the JavaBean components into the WEB-INF/dev directory, so that they will be
loaded by a special Seam classloader, instead of by the WAR or EAR classloader.

You need to be aware of the following limitations:
• the components must be JavaBean components, they cannot be EJB3 beans (we are working on fixing this limitation).
• entities can never be hot-deloyed.
• components deployed via components.xml may not be hot-deployed.
• the hot-deployable components will not be visible to any classes deployed outside of WEB-INF/dev.
• Seam debug mode must be enabled and jboss-seam-debug.jar must be in WEB-INF/lib.
• You must have the Seam filter installed in web.xml.
• You may see errors if the system is placed under any load and debug is enabled.
If you create a WAR project using seam-gen, incremental hot deployment is available out of the box for classes in the
src/action source directory. However, seam-gen does not support incremental hot deployment for EAR projects.

Using Seam with JBoss 4.0:
Seam 2.0 was developed for JavaServer Faces 1.2. When using JBoss AS, we recommend using JBoss 4.2, which bundles the
JSF 1.2 reference implementation. However, it is still possible to use Seam 2.0 on the JBoss 4.0 platform. There are two
basic steps required to do this: install an EJB3-enabled version of JBoss 4.0 and replace MyFaces with the JSF 1.2 reference
implementation. Once you complete these steps, Seam 2.0 applications can be deployed to JBoss 4.0.

Install JBoss 4.0: JBoss 4.0 does not ship a default configuration compatible with Seam. To run Seam, you must install
JBoss 4.0.5 using the JEMS 1.2 installer with the ejb3 profile selected. Seam will not run with an installation that doesn’t
include EJB3 support. The JEMS installer can be downloaded from http://labs.jboss.com/jemsinstaller/downloads.

Install the JSF 1.2 RI: The web configuration for JBoss 4.0 can be found in the server/default/deploy/jbosswebtomcat55.sar.
You’ll need to delete myfaces-api.jar any myfaces-impl.jar from the jsflibs directory. Then, you’ll need to copy jsf-api.jar,
jsf-impl.jar, el-api.jar, and el-ri.jar to that directory. The JSF JARs can be found in the Seam lib directory. The el JARs
can be obtained from the Seam 1.2 release. You’ll also need to edit the conf/web.xml, replacing myfaces-impl.jar with
jsf-impl.jar.

Ques8: Show the architecture of the deployed ear file in the JBOSS deploy folder?
Ans7:It’s given below:

my-application.ear/
jboss-seam.jar
META-INF/
MANIFEST.MF
application.xml
my-application.war/
META-INF/
MANIFEST.MF
WEB-INF/
web.xml
components.xml
faces-config.xml
login.jsp
register.jsp
…
my-application.jar/
META-INF/
MANIFEST.MF
persistence.xml
seam.properties
org/
jboss/
myapplication/
User.class
Login.class
LoginBean.class
Register.class
RegisterBean.class
…

Make sure you reference jboss-seam.jar from manifests of the EJB-JAR and WAR.

Ques9: Configuring Seam components?
Ans9: Seam provides two basic approaches to configuring components: configuration via property settings in a properties file
or in web.xml, and configuration via components.xml.

Configuring components via property settings: Seam components may be provided with configuration properties either via
servlet context parameters or via a properties file named seam.properties in the root of the classpath.
The configurable Seam component must expose JavaBeans-style property setter methods for the configurable attributes. If a
Seam component named com.jboss.myapp.settings has a setter method named setLocale(), we can provide a property named
com.jboss.myapp.settings.locale in the seam.properties file or as a servlet context parameter, and Seam will set the value of
the locale attribute whenever it instantiates the component.
To set the conversation timeout, we provide a value for org.jboss.seam.core.manager.conversationTimeout in web.xml or
seam.properties.

Configuring components via components.xml: The components.xml file is a bit more powerful than property settings.
It lets you:

• Configure components that have been installed automatically—including both built-in components, and application components
that have been annotated with the @Name annotation and picked up by Seam’s deployment scanner.
• Install classes with no @Name annotation as Seam components—this is most useful for certain kinds of infrastructural
components which can be installed multiple times with different names (for example Seam-managed persistence contexts).
• Install components that do have a @Name annotation but are not installed by default because of an @Install annotation that
indicates the component should not be installed.
• Override the scope of a component.
A components.xml file may appear in one of three different places:
• The WEB-INF directory of a war.
• The META-INF directory of a jar.
• Any directory of a jar that contains classes with an @Name annotation.

Usually, Seam components are installed when the deployment scanner discovers a class with a @Name annotation sitting in an
archive with a seam.properties file or a META-INF/components.xml file. (Unless the component has an @Install annotation
indicating it should not be installed by default.) The components.xml file lets us handle special cases where we need
to override the annotations.

For example, the following components.xml file installs jBPM:
<components xmlns=”http://jboss.com/products/seam/components”
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xmlns:bpm=”http://jboss.com/products/seam/bpm”>
<bpm:jbpm/>
</components>

This example does the same thing:
<components>
<component/>
</components>

This one installs and configures two different Seam-managed persistence contexts:
<components xmlns=”http://jboss.com/products/seam/components”
xmlns:persistence=”http://jboss.com/products/seam/persistence”
<persistence:managed-persistence-context name=”customerDatabase”
persistence-unit-jndi-name=”java:/customerEntityManagerFactory”/>
<persistence:managed-persistence-context name=”accountingDatabase”
persistence-unit-jndi-name=”java:/accountingEntityManagerFactory”/>
</components>

As does this one:
<components>

<component name=”customerDatabase”>
<property name=”persistenceUnitJndiName”>java:/customerEntityManagerFactory</property>
</component>

<component name=”accountingDatabase”
class=”org.jboss.seam.persistence.ManagedPersistenceContext”>
<property name=”persistenceUnitJndiName”>java:/accountingEntityManagerFactory</
property>
</component>

</components>

This example creates a session-scoped Seam-managed persistence context (this is not recommended in practice):
<components xmlns=”http://jboss.com/products/seam/components”
xmlns:persistence=”http://jboss.com/products/seam/persistence”
<persistence:managed-persistence-context name=”productDatabase” scope=”session”
persistence-unit-jndi-name=”java:/productEntityManagerFactory”/>
</components>

<components>
<component name=”productDatabase” scope=”session”
class=”org.jboss.seam.persistence.ManagedPersistenceContext”>
<property name=”persistenceUnitJndiName”>java:/productEntityManagerFactory</property>
</component>
</components>

It is common to use the auto-create option for infrastructural objects like persistence contexts,
which saves you from having to explicitly specify create=true when you use the @In annotation.

<components xmlns=”http://jboss.com/products/seam/components”
xmlns:persistence=”http://jboss.com/products/seam/persistence”
<persistence:managed-persistence-context name=”productDatabase” auto-create=”true”
persistence-unit-jndi-name=”java:/productEntityManagerFactory”/>
</components>

<components>
<component name=”productDatabase” auto-create=”true”
class=”org.jboss.seam.persistence.ManagedPersistenceContext”>
<property name=”persistenceUnitJndiName”>java:/productEntityManagerFactory</property>
</component>
</components>

The <factory> declaration lets you specify a value or method binding expression that will be
evaluated to initialize the value of a context variable when it is first referenced.
<components>
<factory name=”contact” method=”#{contactManager.loadContact}” scope=”CONVERSATION”/>
</components>

You can create an “alias” (a second name) for a Seam component like so:
<components>
<factory name=”user” value=”#{actor}” scope=”STATELESS”/>
</components>

You can even create an “alias” for a commonly used expression:
<components>
<factory name=”contact” value=”#{contactManager.contact}” scope=”STATELESS”/>
</components>

It is especially common to see the use of auto-create=”true” with the <factory> declaration:
<components>
<factory name=”session” value=”#{entityManager.delegate}” scope=”STATELESS” autocreate=”true”/>
</components>

Sometimes we want to reuse the same components.xml file with minor changes during both deployment and testing. Seam lets you
place wildcards of the form @wildcard@ in the components.xml file which can be replaced either by your Ant build script
(at deployment time) or by providing a file named components.properties in the classpath (at development time).

Using XML Namespaces: Throughout the examples, there have been two competing ways of declaring components: with
and without the use of XML namespaces. The following shows a typical components.xml file without namespaces:

<?xml version=”1.0″ encoding=”UTF-8″?>
<components xmlns=”http://jboss.com/products/seam/components”
xsi:schemaLocation=”http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.1.xsd”>
<component>
<property name=”debug”>true</property>
<property name=”jndiPattern”>@jndiPattern@</property>
</component>
</components>

As you can see, this is somewhat verbose. Even worse, the component and attribute names cannot be validated at development
time.

The namespaced version looks like this:

<?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 debug=”true” jndi-pattern=”@jndiPattern@”/>
</components>

Even though the schema declarations are verbose, the actual XML content is lean and easy to understand. The schemas provide
detailed information about each component and the attributes available, allowing XML editors to offer intelligent
autocomplete. The use of namespaced elements makes generating and maintaining correct components.xml files much simpler.

Now, this works great for the built-in Seam components, but what about user components? There are two options. First, Seam
supports mixing the two models, allowing the use of the generic <component> declarations for user components, along with
namespaced declarations for built-in components. But even better, Seam allows you to quickly declare namespaces for your own
components.

Any Java package can be associated with an XML namespace by annotating the package with the @Namespace annotation.

@Namespace(value=”http://jboss.com/products/seam/examples/seampay”)
package org.jboss.seam.example.seampay;
import org.jboss.seam.annotations.Namespace;

That is all you need to do to use the namespaced style in components.xml! Now we can write:

<components xmlns=”http://jboss.com/products/seam/components”
xmlns:pay=”http://jboss.com/products/seam/examples/seampay” … >
<pay:payment-home new-instance=”#{newPayment}” created-message=”Created a new payment to #{newPayment.payee}” />
<pay:payment name=”newPayment” payee=”Somebody” account=”#{selectedAccount}” payment-date=”#{currentDatetime}”
created-date=”#{currentDatetime}” />
…
</components>

Or:

<components xmlns=”http://jboss.com/products/seam/components”
xmlns:pay=”http://jboss.com/products/seam/examples/seampay” … >
<pay:payment-home>
<pay:new-instance>”#{newPayment}”</pay:new-instance>
<pay:created-message>Created a new payment to #{newPayment.payee}</pay:createdmessage>
</pay:payment-home>
<pay:payment name=”newPayment”>
<pay:payee>Somebody”</pay:payee>
<pay:account>#{selectedAccount}</pay:account>
<pay:payment-date>#{currentDatetime}</pay:payment-date>
<pay:created-date>#{currentDatetime}</pay:created-date>
</pay:payment>
…
</components>

These examples illustrate the two usage models of a namespaced element. In the first declaration, the <pay:payment-home>
references the paymentHome component:

package org.jboss.seam.example.seampay;
…
@Name(“paymentHome”)
public class PaymentController
extends EntityHome<Payment>
{
…
}

In the second declaration, the <pay:payment> element refers to the Payment class in the org.jboss.seam.example.seampay
package. In this case Payment is an entity that is being declared as a Seam component:

package org.jboss.seam.example.seampay;
…
@Entity
public class Payment
implements Serializable
{
…
}

If we want validation and autocompletion to work for user-defined components, we will need a schema. Seam does not yet
provide a mechanism to automatically generate a schema for a set of components, so it is necessary to generate one manually.
The schema definitions for the standard Seam packages can be used for guidance.

The following are the the namespaces used by Seam:
• components — http://jboss.com/products/seam/components
• core — http://jboss.com/products/seam/core
• drools — http://jboss.com/products/seam/drools
• framework — http://jboss.com/products/seam/framework
• jms — http://jboss.com/products/seam/jms
• remoting — http://jboss.com/products/seam/remoting
• theme — http://jboss.com/products/seam/theme
• security — http://jboss.com/products/seam/security
• mail — http://jboss.com/products/seam/mail
• web — http://jboss.com/products/seam/web
• pdf — http://jboss.com/products/seam/pdf
• spring — http://jboss.com/products/seam/spring

Events, interceptors and exception handling: Complementing the contextual component model, there are two further basic
concepts that facilitate the extreme loose-coupling that is the distinctive feature of Seam applications. The first
is a strong event model where events may be mapped to event listeners via JSF-like method binding expressions. The second is
the pervasive use of annotations and interceptors to apply cross-cutting concerns to components which implement business
logic.

Seam events: The Seam component model was developed for use with event-driven applications, specifically to enable the
development of fine-grained, loosely-coupled components in a fine-grained eventing model. Events in Seam come in several
types, most of which we have already seen:

• JSF events
• jBPM transition events
• Seam page actions
• Seam component-driven events
• Seam contextual events

All of these various kinds of events are mapped to Seam components via JSF EL method binding expressions. For a JSF event,
this is defined in the JSF template:

<h:commandButton value=”Click me!” action=”#{helloWorld.sayHello}”/>

For a jBPM transition event, it is specified in the jBPM process definition or pageflow definition:

<start-page name=”hello” view-id=”/hello.jsp”>
<transition to=”hello”>
<action expression=”#{helloWorld.sayHello}”/>
</transition>
</start-page>

Page actions: A Seam page action is an event that occurs just before we render a page. We declare page actions
in WEB-INF/pages.xml. We can define a page action for either a particular JSF view id:

<pages>
<page view-id=”/hello.jsp” action=”#{helloWorld.sayHello}”/>
</pages>

Or we can use a * wildcard as a suffix to the view-id to specify an action that applies to all view
ids that match the pattern:

<pages>
<page view-id=”/hello/*” action=”#{helloWorld.sayHello}”/>
</pages>

If multiple wildcarded page actions match the current view-id, Seam will call all the actions, in
order of least-specific to most-specific.

The page action method can return a JSF outcome. If the outcome is non-null, Seam will use the
defined navigation rules to navigate to a view.

Furthermore, the view id mentioned in the <page> element need not correspond to a real JSP or Facelets page! So, we can
reproduce the functionality of a traditional action-oriented framework like Struts or WebWork using page actions.

For example:
TODO: translate struts action into page action

This is quite useful if you want to do complex things in response to non-faces requests (for example, HTTP GET requests).

Multiple or conditional page actions my be specified using the <action> tag:

<pages>
<page view-id=”/hello.jsp”>
<action execute=”#{helloWorld.sayHello}” if=”#{not validation.failed}”/>
<action execute=”#{hitCount.increment}”/>
</page>
</pages>

Mapping request parameters to the model: Seam lets us provide a value binding that maps a named request parameter to an
attribute of a model object.

<pages>
<page view-id=”/hello.jsp” action=”#{helloWorld.sayHello}”>
<param name=”firstName” value=”#{person.firstName}”/>
<param name=”lastName” value=”#{person.lastName}”/>
</page>
</pages>

The <param> declaration is bidirectional, just like a value binding for a JSF input:

• When a non-faces (GET) request for the view id occurs, Seam sets the value of the named
request parameter onto the model object, after performing appropriate type conversions.
• Any <s:link> or <s:button> transparently includes the request parameter. The value of the
parameter is determined by evaluating the value binding during the render phase (when the
<s:link> is rendered).
• Any navigation rule with a <redirect/> to the view id transparently includes the request
parameter. The value of the parameter is determined by evaluating the value binding at the end
of the invoke application phase.
• The value is transparently propagated with any JSF form submission for the page with the given
view id. This means that view parameters behave like PAGE-scoped context variables for faces
requests.

The essential idea behind all this is that however we get from any other page to /hello.jsp (or from /hello.jsp back to
/hello.jsp), the value of the model attribute referred to in the value binding is “remembered”, without the need for a
conversation (or other server-side state).

Propagating request parameters: If just the name attribute is specified then the request parameter is propagated using the
PAGE context (it isn’t mapped to model property).

<pages>
<page view-id=”/hello.jsp” action=”#{helloWorld.sayHello}”>
<param name=”firstName” />
<param name=”lastName” />
</page>
</pages>

Propagation of page parameters is especially useful if you want to build multi-layer master-detail CRUD pages. You can use
it to “remember” which view you were previously on (e.g. when pressing the Save button), and which entity you were editing.

• Any <s:link> or <s:button> transparently propagates the request parameter if that parameter is listed as a page parameter
for the view.
• The value is transparently propagated with any JSF form submission for the page with the given view id. (This means that
view parameters behave like PAGE-scoped context variables for faces requests.

Conversion and Validation:
You can specify a JSF converter for complex model propreties:

<pages>
<page view-id=”/calculator.jsp” action=”#{calculator.calculate}”>
<param name=”x” value=”#{calculator.lhs}”/>
<param name=”y” value=”#{calculator.rhs}”/>
<param name=”op” converterId=”com.my.calculator.OperatorConverter” value=”#{calculator.op}”/>
</page>
</pages>

Alternatively:

<pages>
<page view-id=”/calculator.jsp” action=”#{calculator.calculate}”>
<param name=”x” value=”#{calculator.lhs}”/>
<param name=”y” value=”#{calculator.rhs}”/>
<param name=”op” converter=”#{operatorConverter}” value=”#{calculator.op}”/>
</page>
</pages>

JSF validators, and required=”true” may also be used:

<pages>
<page view-id=”/blog.xhtml”>
<param name=”date” value=”#{blog.date}”
validatorId=”com.my.blog.PastDate” required=”true”/>
</page>
</pages>

Alternatively:

<pages>
<page view-id=”/blog.xhtml”>
<param name=”date” value=”#{blog.date}”
validator=”#{pastDateValidator}” required=”true”/>
</page>
</pages>

Even better, model-based Hibernate validator annotations are automatically recognized and validated.
When type conversion or validation fails, a global FacesMessage is added to the FacesContext.

Navigation: You can use standard JSF navigation rules defined in faces-config.xml in a Seam application.
However, JSF navigation rules have a number of annoying limitations:

• It is not possible to specify request parameters to be used when redirecting.
• It is not possible to begin or end conversations from a rule.
• Rules work by evaluating the return value of the action method; it is not possible to evaluate an arbitrary EL expression.

A further problem is that “orchestration” logic gets scattered between pages.xml and facesconfig.xml. It’s better to unify
this logic into pages.xml.

This JSF navigation rule:
<navigation-rule>
<from-view-id>/editDocument.xhtml</from-view-id>
<navigation-case>
<from-action>#{documentEditor.update}</from-action>
<from-outcome>success</from-outcome>
<to-view-id>/viewDocument.xhtml</to-view-id>
<redirect/>
</navigation-case>
</navigation-rule>

Can be rewritten as follows:

<page view-id=”/editDocument.xhtml”>
<navigation from-action=”#{documentEditor.update}”>
<rule if-outcome=”success”>
<redirect view-id=”/viewDocument.xhtml”/>
</rule>
</navigation>
</page>

But it would be even nicer if we didn’t have to pollute our DocumentEditor component with stringvalued
return values (the JSF outcomes). So Seam lets us write:

<page view-id=”/editDocument.xhtml”>
<navigation from-action=”#{documentEditor.update}” evaluate=”#{documentEditor.errors.size}”>
<rule if-outcome=”0″>
<redirect view-id=”/viewDocument.xhtml”/>
</rule>
</navigation>
</page>

Or even:

<page view-id=”/editDocument.xhtml”>
<navigation from-action=”#{documentEditor.update}”>
<rule if=”#{documentEditor.errors.empty}”>
<redirect view-id=”/viewDocument.xhtml”/>
</rule>
</navigation>
</page>

The first form evaluates a value binding to determine the outcome value to be used by the subsequent rules. The second
approach ignores the outcome and evaluates a value binding for each possible rule.
Of course, when an update succeeds, we probably want to end the current conversation. We can do that like this:

<page view-id=”/editDocument.xhtml”>
<navigation from-action=”#{documentEditor.update}”>
<rule if=”#{documentEditor.errors.empty}”>
<end-conversation/>
<redirect view-id=”/viewDocument.xhtml”/>
</rule>
</navigation>
</page>

As we’ve ended conversation any subsequent requests won’t know which document we are interested in. We can pass the document
id as a request parameter which also makes the view bookmarkable:

<page view-id=”/editDocument.xhtml”>
<navigation from-action=”#{documentEditor.update}”>
<rule if=”#{documentEditor.errors.empty}”>
<end-conversation/>
<redirect view-id=”/viewDocument.xhtml”>
<param name=”documentId” value=”#{documentEditor.documentId}”/>
</redirect>
</rule>
</navigation>
</page>

Null outcomes are a special case in JSF. The null outcome is interpreted to mean “redisplay the
page”. The following navigation rule matches any non-null outcome, but not the null outcome:

<page view-id=”/editDocument.xhtml”>
<navigation from-action=”#{documentEditor.update}”>
<rule>
<render view-id=”/viewDocument.xhtml”/>
</rule>
</navigation>
</page>

If you want to perform navigation when a null outcome occurs, use the following form instead:

<page view-id=”/editDocument.xhtml”>
<navigation from-action=”#{documentEditor.update}”>
<render view-id=”/viewDocument.xhtml”/>
</navigation>
</page>

The view-id may be given as a JSF EL expression:

<page view-id=”/editDocument.xhtml”>
<navigation>
<rule if-outcome=”success”>
<redirect view-id=”/#{userAgent}/displayDocument.xhtml”/>
</rule>
</navigation>
</page>

Fine-grained files for definition of navigation, page actions and parameters:
If you have a lot of different page actions and page parameters, or even just a lot of navigation rules, you will almost
certainly want to split the declarations up over multiple files. You can define actions and parameters for a page with the
view id /calc/calculator.jsp in a resource named calc/calculator.page.xml. The root element in this case is the <page>
element, and the view id is implied:

<page action=”#{calculator.calculate}”>
<param name=”x” value=”#{calculator.lhs}”/>
<param name=”y” value=”#{calculator.rhs}”/>
<param name=”op” converter=”#{operatorConverter}” value=”#{calculator.op}”/>
</page>

Component-driven events: Seam components can interact by simply calling each others methods. Stateful components may
even implement the observer/observable pattern. But to enable components to interact in a more loosely-coupled fashion than
is possible when the components call each others methods directly, Seam provides component-driven events.
We specify event listeners (observers) in components.xml.

<components>
<event type=”hello”>
<action execute=”#{helloListener.sayHelloBack}”/>
<action execute=”#{logger.logHello}”/>
</event>
</components>

Where the event type is just an arbitrary string.

When an event occurs, the actions registered for that event will be called in the order they appear in components.xml. How
does a component raise an event? Seam provides a built-in component for this.

@Name(“helloWorld”)
public class HelloWorld {
public void sayHello() {
FacesMessages.instance().add(“Hello World!”);
Events.instance().raiseEvent(“hello”);
}
}

Or you can use an annotation.

@Name(“helloWorld”)
public class HelloWorld {
@RaiseEvent(“hello”)
public void sayHello() {
FacesMessages.instance().add(“Hello World!”);
}
}

Notice that this event producer has no dependency upon event consumers. The event listener
may now be implemented with absolutely no dependency upon the producer:

@Name(“helloListener”)
public class HelloListener {
public void sayHelloBack() {
FacesMessages.instance().add(“Hello to you too!”);
}
}

The method binding defined in components.xml above takes care of mapping the event to the
consumer. If you don’t like futzing about in the components.xml file, you can use an annotation instead:

@Name(“helloListener”)
public class HelloListener {
@Observer(“hello”)
public void sayHelloBack() {
FacesMessages.instance().add(“Hello to you too!”);
}
}

You might wonder why I’ve not mentioned anything about event objects in this discussion. In
Seam, there is no need for an event object to propagate state between event producer and listener. State is held in the Seam
contexts, and is shared between components. However, if you really want to pass an event object, you can:

@Name(“helloWorld”)
public class HelloWorld {
private String name;
public void sayHello() {
FacesMessages.instance().add(“Hello World, my name is #0.”, name);
Events.instance().raiseEvent(“hello”, name);
}
}

@Name(“helloListener”)
public class HelloListener {
@Observer(“hello”)
public void sayHelloBack(String name) {
FacesMessages.instance().add(“Hello #0!”, name);
}
}

Contextual events: Seam defines a number of built-in events that the application can use to perform special kinds of
framework integration. The events are:

• org.jboss.seam.validationFailed — called when JSF validation fails
• org.jboss.seam.noConversation — called when there is no long running conversation and a long running conversation is
required
• org.jboss.seam.preSetVariable.<name> — called when the context variable <name> is set
• org.jboss.seam.postSetVariable.<name> — called when the context variable <name> is set
• org.jboss.seam.preRemoveVariable.<name> — called when the context variable <name> is unset
• org.jboss.seam.postRemoveVariable.<name> — called when the context variable <name> is unset
• org.jboss.seam.preDestroyContext.<SCOPE> — called before the <SCOPE> context is destroyed
• org.jboss.seam.postDestroyContext.<SCOPE> — called after the <SCOPE> context is destroyed
• org.jboss.seam.beginConversation — called whenever a long-running conversation begins
• org.jboss.seam.endConversation — called whenever a long-running conversation ends
• org.jboss.seam.conversationTimeout— called when a conversation timeout occurs. The conversation id is passed as a parameter.
• org.jboss.seam.beginPageflow — called when a pageflow begins
• org.jboss.seam.beginPageflow.<name> — called when the pageflow <name> begins
• org.jboss.seam.endPageflow — called when a pageflow ends
• org.jboss.seam.endPageflow.<name> — called when the pageflow <name> ends
• org.jboss.seam.createProcess.<name> — called when the process <name> is created
• org.jboss.seam.endProcess.<name> — called when the process <name> ends
• org.jboss.seam.initProcess.<name> — called when the process <name> is associated with the conversation
• org.jboss.seam.initTask.<name> — called when the task <name> is associated with the conversation
• org.jboss.seam.startTask.<name> — called when the task <name> is started
• org.jboss.seam.endTask.<name> — called when the task <name> is ended
• org.jboss.seam.postCreate.<name> — called when the component <name> is created
• org.jboss.seam.preDestroy.<name> — called when the component <name> is destroyed
• org.jboss.seam.beforePhase — called before the start of a JSF phase
• org.jboss.seam.afterPhase — called after the end of a JSF phase
• org.jboss.seam.postInitialization — called when Seam has initialized and started up all components
• org.jboss.seam.postAuthenticate.<name> — called after a user is authenticated
• org.jboss.seam.preAuthenticate.<name> — called before attempting to authenticate a user
• org.jboss.seam.notLoggedIn — called there is no authenticated user and authentication is required
• org.jboss.seam.rememberMe — occurs when Seam security detects the username in a cookie
• org.jboss.seam.exceptionHandled.<type> — called when an uncaught exception is handled by Seam
• org.jboss.seam.exceptionHandled — called when an uncaught exception is handled by Seam
• org.jboss.seam.exceptionNotHandled — called when there was no handler for an uncaught exception
• org.jboss.seam.afterTransactionSuccess — called when a transaction succeeds in the Seam Application Framework
• org.jboss.seam.afterTransactionSuccess.<name> — called when a transaction succeeds in the Seam Application Framework which
manages an entity called <name>.

Seam components may observe any of these events in just the same way they observe any other component-driven events.

Seam interceptors: EJB 3.0 introduced a standard interceptor model for session bean components. To add an interceptor to a
bean, you need to write a class with a method annotated @AroundInvoke and annotate the bean with an @Interceptors annotation
that specifies the name of the interceptor class. For example, the following interceptor checks that the user is logged in
before allowing invoking an action listener method:

public class LoggedInInterceptor {
@AroundInvoke
public Object checkLoggedIn(InvocationContext invocation) throws Exception {
boolean isLoggedIn = Contexts.getSessionContext().get(“loggedIn”)!=null;
if (isLoggedIn) {
//the user is already logged in
return invocation.proceed();
}
else {
//the user is not logged in, fwd to login page
return “login”;
}
}
}

To apply this interceptor to a session bean which acts as an action listener, we must annotate the session bean
@Interceptors(LoggedInInterceptor.class). This is a somewhat ugly annotation. Seam builds upon the interceptor framework in
EJB3 by allowing you to use @Interceptors as a meta-annotation for class level interceptors (those annotated @Target(TYPE)).
In our example, we would create an @LoggedIn annotation, as follows:

@Target(TYPE)
@Retention(RUNTIME)
@Interceptors(LoggedInInterceptor.class)
public @interface LoggedIn {}

We can now simply annotate our action listener bean with @LoggedIn to apply the interceptor.

@Stateless
@Name(“changePasswordAction”)
@LoggedIn
@Interceptors(SeamInterceptor.class)
public class ChangePasswordAction implements ChangePassword {
…
public String changePassword() { … }
}

If interceptor ordering is important (it usually is), you can add @Interceptor annotations to your
interceptor classes to specify a partial order of interceptors.

@Interceptor(around={BijectionInterceptor.class,
ValidationInterceptor.class,
ConversationInterceptor.class},
within=RemoveInterceptor.class)
public class LoggedInInterceptor
{
…
}

You can even have a “client-side” interceptor, that runs around any of the built-in functionality of EJB3:

@Interceptor(type=CLIENT)
public class LoggedInInterceptor
{
…
}

EJB interceptors are stateful, with a lifecycle that is the same as the component they intercept. For interceptors which do
not need to maintain state, Seam lets you get a performance optimization by specifying @Interceptor(stateless=true).

Much of the functionality of Seam is implemented as a set of built-in Seam interceptors, including
the interceptors named in the previous example. You don’t have to explicitly specify these
interceptors by annotating your components; they exist for all interceptable Seam components.

You can even use Seam interceptors with JavaBean components, not just EJB3 beans!

EJB defines interception not only for business methods (using @AroundInvoke), but also for the lifecycle methods
@PostConstruct, @PreDestroy, @PrePassivate and @PostActive. Seam supports all these lifecycle methods on both component and
interceptor not only for EJB3 beans, but also for JavaBean components (except @PreDestroy which is not meaningful for
JavaBean components).

Managing exceptions: JSF is surprisingly limited when it comes to exception handling. As a partial workaround for this
problem, Seam lets you define how a particular class of exception is to be treated by annotating the exception class, or
declaring the exception class in an XML file. This facility is meant to be combined with the EJB 3.0-standard
@ApplicationException annotation which specifies whether the exception should cause a transaction rollback.

Exceptions and transactions: EJB specifies well-defined rules that let us control whether an exception immediately marks the
current transaction for rollback when it is thrown by a business method of the bean: system exceptions always cause a
transaction rollback, application exceptions do not cause a rollback by default, but they do if
@ApplicationException(rollback=true) is specified. (An application exception is any checked exception, or any unchecked
exception annotated @ApplicationException. A system exception is any unchecked exception without an @ApplicationException
annotation).

Note that there is a difference between marking a transaction for rollback, and actually rolling it back. The exception rules
say that the transaction should be marked rollback only, but it may still be active after the exception is thrown.

Seam applies the EJB 3.0 exception rollback rules also to Seam JavaBean components.

But these rules only apply in the Seam component layer. What about an exception that is uncaught and propagates out of the
Seam component layer, and out of the JSF layer? Well, it is always wrong to leave a dangling transaction open, so Seam rolls
back any active transaction when an exception occurs and is uncaught in the Seam component layer.

Enabling Seam exception handling: To enable Seam’s exception handling, we need to make sure we have the master servlet filter
declared in web.xml:

<filter>
<filter-name>Seam Filter</filter-name>
<filter-class>org.jboss.seam.servlet.SeamFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>Seam Filter</filter-name>
<url-pattern>*.seam</url-pattern>
</filter-mapping>

You may also need to disable Facelets development mode in web.xml and Seam debug mode in components.xml if you want your
exception handlers to fire.

Using annotations for exception handling: The following exception results in a HTTP 404 error whenever it propagates out of
the Seam component layer. It does not roll back the current transaction immediately when thrown, but the transaction will be
rolled back if it the exception is not caught by another Seam component.

@HttpError(errorCode=404)
public class ApplicationException extends Exception { … }

This exception results in a browser redirect whenever it propagates out of the Seam component layer. It also ends the current
conversation. It causes an immediate rollback of the current transaction.

@Redirect(viewId=”/failure.xhtml”, end=true)
@ApplicationException(rollback=true)
public class UnrecoverableApplicationException extends RuntimeException { … }

Note that @Redirect does not work for exceptions which occur during the render phase of the JSF lifecycle.
You can also use EL to specify the viewId to redirect to.

This exception results in a redirect, along with a message to the user, when it propagates out of
the Seam component layer. It also immediately rolls back the current transaction.

@Redirect(viewId=”/error.xhtml”, message=”Unexpected error”)
public class SystemException extends RuntimeException { … }

Using XML for exception handling: Since we can’t add annotations to all the exception classes we are interested in, Seam also
lets us specify this functionality in pages.xml.

<pages>
<exception>
<http-error error-code=”404″/>
</exception>
<exception>
<end-conversation/>
<redirect view-id=”/error.xhtml”>
<message>Database access failed</message>
</redirect>
</exception>
<exception>
<end-conversation/>
<redirect view-id=”/error.xhtml”>
<message>Unexpected failure</message>
</redirect>
</exception>
</pages>

The last <exception> declaration does not specify a class, and is a catch-all for any exception
for which handling is not otherwise specified via annotations or in pages.xml.

You can also use EL to specify the view-id to redirect to.

You can also access the handled exception instance through EL, Seam places it in the conversation context, e.g. to access the
message of the exception:

…
throw new AuthorizationException(“You are not allowed to do this!”);
<pages>
<exception>
<end-conversation/>
<redirect view-id=”/error.xhtml”>
<message severity=”WARN”>#{org.jboss.seam.handledException.message}</message>
</redirect>
</exception>
</pages>

org.jboss.seam.handledException holds the nested exception that was actually handled by an exception handler. The outermost
(wrapper) exception is also available, as org.jboss.seam.exception.

Suppressing exception logging: For the exception handlers defined in pages.xml, it is possible to declare the logging level
at which the exception will be logged, or to even suppress the exception being logged altogether. The attributes log and
logLevel can be used to control exception logging. By setting log=”false” as per the following example, then no log message
will be generated when the specified exception occurs:

<exception log=”false”>
<redirect view-id=”/register.xhtml”>
<message severity=”warn”>You must be a member to use this feature</message>
</redirect>
</exception>

If the log attribute is not specified, then it defaults to true (i.e. the exception will be logged).
Alternatively, you can specify the logLevel to control at which log level the exception will be logged:

<exception logLevel=”info”>
<redirect view-id=”/register.xhtml”>
<message severity=”warn”>You must be a member to use this feature</message>
</redirect>
</exception>

The acceptable values for logLevel are: fatal, error, warn, info, debug or trace. If the logLevel is not specified, or if an
invalid value is configured, then it will default to error.

Some common exceptions:
If you are using JPA:

<exception>
<redirect view-id=”/error.xhtml”>
<message>Not found</message>
</redirect>
</exception>

<exception>
<end-conversation/>
<redirect view-id=”/error.xhtml”>
<message>Another user changed the same data, please try again</message>
</redirect>
</exception>

If you are using the Seam Application Framework:

<exception>
<redirect view-id=”/error.xhtml”>
<message>Not found</message>
</redirect>
</exception>

If you are using Seam Security:

<exception>
<redirect>
<message>You don’t have permission to do this</message>
</redirect>
</exception>

<exception>
<redirect view-id=”/login.xhtml”>
<message>Please log in first</message>
</redirect>
</exception>

And, for JSF:

<exception>
<redirect view-id=”/error.xhtml”>
<message>Your session has timed out, please try again</message>
</redirect>
</exception>

A ViewExpiredException occurs if the user posts back to a page once their session has expired. no-conversation-view-id and
conversation-required give you finer grained control over session expiration if you are inside a conversation.

Conversations and workspace management:
Seam’s conversation model: The examples we have seen so far make use of a very simple conversation model that follows
these rules:

• There is always a conversation context active during the apply request values, process validations, update model values,
invoke application and render response phases of the JSF request lifecycle.
• At the end of the restore view phase of the JSF request lifecycle, Seam attempts to restore any previous long-running
conversation context. If none exists, Seam creates a new temporary conversation context.
• When an @Begin method is encountered, the temporary conversation context is promoted to a long running conversation.
• When an @End method is encountered, any long-running conversation context is demoted to a temporary conversation.
• At the end of the render response phase of the JSF request lifecycle, Seam stores the contents
of a long running conversation context or destroys the contents of a temporary conversation context.
• Any faces request (a JSF postback) will propagate the conversation context. By default, nonfaces requests
(GET requests, for example) do not propagate the conversation context, but see below for more information on this.
• If the JSF request lifecycle is foreshortened by a redirect, Seam transparently stores and restores the current
conversation context—unless the conversation was already ended via @End(beforeRedirect=true).

Seam transparently propagates the conversation context (including the temporary conversation context) across JSF postbacks
and redirects. If you don’t do anything special, a non-faces request (a GET request for example) will not propagate the
conversation context and will be processed in a new temporary conversation. It’s usually the desired behavior.

If you want to propagate a Seam conversation across a non-faces request, you need to explicitly
code the Seam conversation id as a request parameter:

<a href=”main.jsf?conversationId=#{conversation.id}”>Continue</a>

Or, the more JSF-ish:

<h:outputLink value=”main.jsf”>
<f:param name=”conversationId” value=”#{conversation.id}”/>
<h:outputText value=”Continue”/>
</h:outputLink>

If you use the Seam tag library, this is equivalent:

<h:outputLink value=”main.jsf”>
<s:conversationId/>
<h:outputText value=”Continue”/>
</h:outputLink>

If you wish to disable propagation of the conversation context for a postback, a similar trick is used:

<h:commandLink action=”main” value=”Exit”>
<f:param name=”conversationPropagation” value=”none”/>
</h:commandLink>

If you use the Seam tag library, this is equivalent:

<h:commandLink action=”main” value=”Exit”>
<s:conversationPropagation type=”none”/>
</h:commandLink>

Note that disabling conversation context propagation is absolutely not the same thing as ending the conversation.

The conversationPropagation request parameter, or the <s:conversationPropagation> tag
may even be used to begin and end conversation, or begin a nested conversation.

<h:commandLink action=”main” value=”Exit”>
<s:conversationPropagation type=”end”/>
</h:commandLink>
<h:commandLink action=”main” value=”Select Child”>
<s:conversationPropagation type=”nested”/>
</h:commandLink>
<h:commandLink action=”main” value=”Select Hotel”>
<s:conversationPropagation type=”begin”/>
</h:commandLink>
<h:commandLink action=”main” value=”Select Hotel”>
<s:conversationPropagation type=”join”/>
</h:commandLink>

This conversation model makes it easy to build applications which behave correctly with respect
to multi-window operation. For many applications, this is all that is needed. Some complex
applications have either or both of the following additional requirements:

• A conversation spans many smaller units of user interaction, which execute serially or even
concurrently. The smaller nested conversations have their own isolated set of conversation
state, and also have access to the state of the outer conversation.

• The user is able to switch between many conversations within the same browser window. This
feature is called workspace management.

Nested conversations: A nested conversation is created by invoking a method marked @Begin(nested=true) inside the scope of an
existing conversation. A nested conversation has its own conversation context, and also has read-only access to the context
of the outer conversation. (It can read the outer conversation’s context variables, but not write to them.) When an @End is
subsequently encountered, the nested conversation will be destroyed, and the outer conversation will resume, by “popping”
the conversation stack. Conversations may be nested to any arbitrary depth. Certain user activity (workspace management, or
the back button) can cause the outer conversation to be resumed before the inner conversation is ended. In this case it is
possible to have multiple concurrent nested conversations belonging to the same outer conversation.
If the outer conversation ends before a nested conversation ends, Seam destroys all nested conversation contexts along with
the outer context. A conversation may be thought of as a continuable state. Nested conversations allow the application to
capture a consistent continuable state at various points in a user interaction, thus insuring truly correct behavior in the
face of backbuttoning and workspace management. TODO: an example to show how a nested conversation prevents bad stuff
happening when you backbutton. Usually, if a component exists in a parent conversation of the current nested conversation,
the nested conversation will use the same instance. Occasionally, it is useful to have a different instance in each nested
conversation, so that the component instance that exists in the parent conversation is invisible to its child conversations.
You can achieve this behavior by annotating the component @PerNestedConversation.

Starting conversations with GET requests:
JSF does not define any kind of action listener that is triggered when a page is accessed via a non-faces request
(for example, a HTTP GET request). This can occur if the user bookmarks the page, or if we navigate to the page via an
<h:outputLink>. Sometimes we want to begin a conversation immediately the page is accessed. Since there is no JSF action
method, we can’t solve the problem in the usual way, by annotating the action with @Begin. A further problem arises if the
page needs some state to be fetched into a context variable. We’ve already seen two ways to solve this problem. If that
state is held in a Seam component, we can fetch the state in a @Create method. If not, we can define a @Factory method for
the context variable. If none of these options works for you, Seam lets you define a page action in the pages.xml file.

<pages>
<page view-id=”/messageList.jsp” action=”#{messageManager.list}”/>
…
</pages>

This action method is called at the beginning of the render response phase, any time the page is about to be rendered. If a
page action returns a non-null outcome, Seam will process any appropriate JSF and Seam navigation rules, possibly resulting
in a completely different page being rendered.
If all you want to do before rendering the page is begin a conversation, you could use a built-in action method that does
just that:

<pages>
<page view-id=”/messageList.jsp” action=”#{conversation.begin}”/>
…
</pages>
Note that you can also call this built-in action from a JSF control, and, similarly, you can use
#{conversation.end} to end conversations.
If you want more control, to join existing conversations or begin a nested conversion, to begin a
pageflow or an atomic conversation, you should use the <begin-conversation> element.
<pages>
<page view-id=”/messageList.jsp”>
<begin-conversation nested=”true” pageflow=”AddItem”/>
<page>
…
</pages>

There is also an <end-conversation> element.

<pages>
<page view-id=”/home.jsp”>
<end-conversation/>
<page>
…
</pages>

To solve the first problem, we now have five options:
• Annotate the @Create method with @Begin
• Annotate the @Factory method with @Begin
• Annotate the Seam page action method with @Begin
• Use <begin-conversation> in pages.xml.
• Use #{conversation.begin} as the Seam page action method

Using <s:link> and <s:button>:
JSF command links always perform a form submission via JavaScript, which breaks the web browser’s “open in new window” or
“open in new tab” feature. In plain JSF, you need to use an <h:outputLink> if you need this functionality. But there are two
major limitations to <h:outputLink>.
• JSF provides no way to attach an action listener to an <h:outputLink>.
• JSF does not propagate the selected row of a DataModel since there is no actual form submission.

Seam provides the notion of a page action to help solve the first problem, but this does nothing to help us with the second
problem. We could work around this by using the RESTful approach of passing a request parameter and requerying for the
selected object on the server side. In some cases—such as the Seam blog example application—this is indeed the best approach.
The RESTful style supports bookmarking, since it does not require server-side state. In other cases, where we don’t care
about bookmarks, the use of @DataModel and @DataModelSelection is just so convenient and transparent!
To fill in this missing functionality, and to make conversation propagation even simpler to manage, Seam provides the
<s:link> JSF tag. The link may specify just the JSF view id:

<s:link view=”/login.xhtml” value=”Login”/>

Or, it may specify an action method (in which case the action outcome determines the page that results):

<s:link action=”#{login.logout}” value=”Logout”/>

If you specify both a JSF view id and an action method, the ‘view’ will be used unless the action method returns a non-null
outcome:
<s:link view=”/loggedOut.xhtml” action=”#{login.logout}” value=”Logout”/>

The link automatically propagates the selected row of a DataModel using inside <h:dataTable>:

<s:link view=”/hotel.xhtml” action=”#{hotelSearch.selectHotel}” value=”#{hotel.name}”/>

You can leave the scope of an existing conversation:

<s:link view=”/main.xhtml” propagation=”none”/>

You can begin, end, or nest conversations:

<s:link action=”#{issueEditor.viewComment}” propagation=”nest”/>

If the link begins a conversation, you can even specify a pageflow to be used:

<s:link action=”#{documentEditor.getDocument}” propagation=”begin” pageflow=”EditDocument”/>

The taskInstance attribute if for use in jBPM task lists:

<s:link action=”#{documentApproval.approveOrReject}” taskInstance=”#{task}”/>
(See the DVD Store demo application for examples of this.)

Finally, if you need the “link” to be rendered as a button, use <s:button>:

<s:button action=”#{login.logout}” value=”Logout”/>

Success messages: It is quite common to display a message to the user indicating success or failure of an action. It is
convenient to use a JSF FacesMessage for this. Unfortunately, a successful action often requires a browser redirect, and JSF
does not propagate faces messages across redirects. This makes it quite difficult to display success messages in plain JSF.
The built in conversation-scoped Seam component named facesMessages solves this problem.
(You must have the Seam redirect filter installed).

@Name(“editDocumentAction”)
@Stateless
public class EditDocumentBean implements EditDocument {
@In EntityManager em;
@In Document document;
@In FacesMessages facesMessages;
public String update() {
em.merge(document);
facesMessages.add(“Document updated”);
}
}

Any message added to facesMessages is used in the very next render response phase for the current conversation. This even
works when there is no long-running conversation since Seam preserves even temporary conversation contexts across redirects.
You can even include JSF EL expressions in a faces message summary:

facesMessages.add(“Document #{document.title} was updated”);

You may display the messages in the usual way, for example:

<h:messages globalOnly=”true”/>

Natural conversation ids:
When working with conversations that deal with persistent objects, it may be desirable to use the
natural business key of the object instead of the standard, “surrogate” conversation id:
Easy redirect to existing conversation
It can be useful to redirect to an existing conversation if the user requests the same operation
twice. Take this example: “ You are on ebay, half way through paying for an item you just won as
a Christmas present for your parents. Lets say you’re sending it straight to them – you enter your
payment details but you can’t remember their address. You accidentally reuse the same browser
window finding out their address. Now you need to return to the payment for the item. ”
With a natural conversation its really easy to have the user rejoin the existing conversation, and
pick up where they left off – just have them to rejoin the payForItem conversation with the itemId
as the conversation id.

User friendly URLs
For me this consists of a navigable hierarchy (I can navigate by editing the url) and a meaningful
URL (like this Wiki uses – so don’t identify things by random ids). For some applications user
friendly URLs are less important, of course.
With a natural conversations, when you are building your hotel booking system (or,
of course, whatever your app is) you can generate a URL like http://seam-hotels/
book.seam?hotel=BestWesternAntwerpen (of course, whatever parameter hotel maps to on
your domain model must be unique) and with URLRewrite easily transform this to http://seamhotels/
book/BestWesternAntwerpen.

Creating a natural conversation: Natural conversations are defined in pages.xml:

<conversation name=”PlaceBid” parameter-name=”auctionId” parameter-value=”#{auction.auctionId}”/>

The first thing to note from the above definition is that the conversation has a name, in this case
PlaceBid. This name uniquely identifies this particular named conversation, and is used by the
page definition to identify a named conversation to participate in.

The next attribute, parameter-name defines the request parameter that will contain the natural
conversation id, in place of the default conversation id parameter. In this example, the parametername
is auctionId. This means that instead of a conversation parameter like cid=123 appearing
in the URL for your page, it will contain auctionId=765432 instead.

The last attribute in the above configuration, parameter-value, defines an EL expression used
to evaluate the value of the natural business key to use as the conversation id. In this example,
the conversation id will be the primary key value of the auction instance currently in scope.

Next, we define which pages will participate in the named conversation. This is done by specifying
the conversation attribute for a page definition:

<page view-id=”/bid.xhtml” conversation=”PlaceBid” login-required=”true”>
<navigation from-action=”#{bidAction.confirmBid}”>
<rule if-outcome=”success”>
<redirect view-id=”/auction.xhtml”>
<param name=”id” value=”#{bidAction.bid.auction.auctionId}”/>
</redirect>
</rule>
</navigation>
</page>

Redirecting to a natural conversation: When starting, or redirecting to, a natural conversation there are a number of
options for specifying the natural conversation name. Let’s start by looking at the following page definition:

<page view-id=”/auction.xhtml”>
<param name=”id” value=”#{auctionDetail.selectedAuctionId}”/>
<navigation from-action=”#{bidAction.placeBid}”>
<redirect view-id=”/bid.xhtml”/>
</navigation>
</page>

From here, we can see that invoking the action #{bidAction.placeBid} from our auction view (by the way, all these examples
are taken from the seamBay example in Seam), that we will be redirected to /bid.xhtml, which, as we saw previously, is
configured with the natural conversation PlaceBid. The declaration for our action method looks like this:

@Begin(join = true)
public void placeBid()

When named conversations are specified in the <page/> element, redirection to the named conversation occurs as part of
navigation rules, after the action method has already been invoked. This is a problem when redirecting to an existing
conversation, as redirection needs to be occur before the action method is invoked. Therefore it is necessary to specify the
conversation name when the action is invoked. One way of doing this is by using the s:conversationName tag:

<h:commandButton id=”placeBidWithAmount” styleClass=”placeBid” action=”#{bidAction.placeBid}”>
<s:conversationName value=”PlaceBid”/>
</h:commandButton>

Another alternative is to specify the conversationName attribute when using either s:link or s:button:

<s:link value=”Place Bid” action=”#{bidAction.placeBid}” conversationName=”PlaceBid”/>

Workspace management: Workspace management is the ability to “switch” conversations in a single window. Seam makes workspace
management completely transparent at the level of the Java code. To enable workspace management, all you need to do is:

• Provide description text for each view id (when using JSF or Seam navigation rules) or page node (when using jPDL
pageflows). This description text is displayed to the user by the workspace switchers.

• Include one or more of the standard workspace switcher JSP or facelets fragments in your pages. The standard fragments
support workspace management via a drop down menu, a list of conversations, or breadcrumbs.

Workspace management and JSF navigation: When you use JSF or Seam navigation rules, Seam switches to a conversation by
restoring the current view-id for that conversation. The descriptive text for the workspace is defined in
a file called pages.xml that Seam expects to find in the WEB-INF directory, right next to facesconfig.xml:

<pages>
<page view-id=”/main.xhtml”>
<description>Search hotels: #{hotelBooking.searchString}</description>
</page>
<page view-id=”/hotel.xhtml”>
<description>View hotel: #{hotel.name}</description>
</page>
<page view-id=”/book.xhtml”>
<description>Book hotel: #{hotel.name}</description>
</page>
<page view-id=”/confirm.xhtml”>
<description>Confirm: #{booking.description}</description>
</page>
</pages>

Note that if this file is missing, the Seam application will continue to work perfectly! The only
missing functionality will be the ability to switch workspaces.

Workspace management and jPDL pageflow: When you use a jPDL pageflow definition, Seam switches to a conversation by restoring
the current jBPM process state. This is a more flexible model since it allows the same view-id to have
different descriptions depending upon the current <page> node. The description text is defined by the <page> node:

<pageflow-definition name=”shopping”>
<start-state name=”start”>
<transition to=”browse”/>
</start-state>
<page name=”browse” view-id=”/browse.xhtml”>
<description>DVD Search: #{search.searchPattern}</description>
<transition to=”browse”/>
<transition name=”checkout” to=”checkout”/>
</page>
<page name=”checkout” view-id=”/checkout.xhtml”>
<description>Purchase: $#{cart.total}</description>
<transition to=”checkout”/>
<transition name=”complete” to=”complete”/>
</page>
<page name=”complete” view-id=”/complete.xhtml”>
<end-conversation />
</page>
</pageflow-definition>

The conversation switcher: Include the following fragment in your JSP or facelets page to get a drop-down menu that lets you
switch to any current conversation, or to any other page of the application:

<h:selectOneMenu value=”#{switcher.conversationIdOrOutcome}”>
<f:selectItem itemLabel=”Find Issues” itemValue=”findIssue”/>
<f:selectItem itemLabel=”Create Issue” itemValue=”editIssue”/>
<f:selectItems value=”#{switcher.selectItems}”/>
</h:selectOneMenu>
<h:commandButton action=”#{switcher.select}” value=”Switch”/>

In this example, we have a menu that includes an item for each conversation, together with two
additional items that let the user begin a new conversation.
Only conversations with a description (specified in pages.xml) will be included in the drop-down menu.

The conversation list: The conversation list is very similar to the conversation switcher, except that it is displayed as
a table:

<h:dataTable value=”#{conversationList}” var=”entry”
rendered=”#{not empty conversationList}”>
<h:column>
<f:facet name=”header”>Workspace</f:facet>
<h:commandLink action=”#{entry.select}” value=”#{entry.description}”/>
<h:outputText value=”[current]” rendered=”#{entry.current}”/>
</h:column>
<h:column>
<f:facet name=”header”>Activity</f:facet>
<h:outputText value=”#{entry.startDatetime}”>
<f:convertDateTime type=”time” pattern=”hh:mm a”/>
</h:outputText>
<h:outputText value=” – “/>
<h:outputText value=”#{entry.lastDatetime}”>
<f:convertDateTime type=”time” pattern=”hh:mm a”/>
</h:outputText>
</h:column>
<h:column>
<f:facet name=”header”>Action</f:facet>
<h:commandButton action=”#{entry.select}” value=”#{msg.Switch}”/>
<h:commandButton action=”#{entry.destroy}” value=”#{msg.Destroy}”/>
</h:column>
</h:dataTable>

We imagine that you will want to customize this for your own application.

Only conversations with a description will be included in the list. Notice that the conversation list lets the user destroy
workspaces.

Breadcrumbs: Breadcrumbs are useful in applications which use a nested conversation model. The breadcrumbs
are a list of links to conversations in the current conversation stack:

<ui:repeat value=”#{conversationStack}” var=”entry”>
<h:outputText value=” | “/>
<h:commandLink value=”#{entry.description}” action=”#{entry.select}”/>
</ui:repeat>

Conversational components and JSF component bindings: Conversational components have one minor limitation: they cannot be
used to hold bindings to JSF components. (We generally prefer not to use this feature of JSF unless absolutely necessary,
since it creates a hard dependency from application logic to the view.) On a postback request, component bindings are
updated during the Restore View phase, before the Seam conversation context has been restored. To work around this use an
event scoped component to store the component bindings and inject it into the conversation scoped component that requires it.

@Name(“grid”)
@Scope(ScopeType.EVENT)
public class Grid
{
private HtmlPanelGrid htmlPanelGrid;
// getters and setters
…
}

@Name(“gridEditor”)
@Scope(ScopeType.CONVERSATION)
public class GridEditor
{
@In(required=false)
private Grid grid;
…
}

Also, you can’t inject a conversation scoped component into an event scoped component which you bind a JSF control to. This
includes Seam built in components like facesMessages. Alternatively, you can access the JSF component tree through the
implicit uiComponent handle. The following example accesses getRowIndex()of the UIData component which backs the data
table during iteration, it prints the current row number:

<h:dataTable id=”lineItemTable” var=”lineItem” value=”#{orderHome.lineItems}”>
<h:column>
Row: #{uiComponent['lineItemTable'].rowIndex}
</h:column>
…
</h:dataTable>

JSF UI components are available with their client identifier in this map.

Concurrent calls to conversational components: We can encounter concurrency — accessing conversational components from AJAX
requests. We’re going to discuss the options that a Ajax client library should provide to control events originating at the
client — and we’ll look at the options RichFaces gives us.

Conversational components don’t allow real concurrent access therefore Seam queues each request to process them serially.
This allows each request to be executed in a deterministic fashion. However, a simple queue isn’t that great — firstly, if a
method is, for some reason, taking a very long time to complete, running it over and over again whenever the client generates
a request is bad idea (potential for Denial of Service attacks), and, secondly, AJAX is often to used to provide
a quick status update to the user, so continuing to run the action after a long time isn’t useful.
Therefore Seam queues the action event for a period of time (the concurrent request timeout); if
it can’t process the event in time, it creates a temporary conversation and prints out a message
to the user to let them know what’s going on. It’s therefore very important not to flood the server with AJAX events!
We can set a sensible default for the concurrent request timeout (in ms) in components.xml:

<core:manager concurrent-request-timeout=”500″ />

So far we’ve discussed “synchronous” AJAX requests – the client tells the server that an event has
occur, and then rerenders part of the page based on the result. This approach is great when the
AJAX request is lightweight (the methods called are simple e.g. calculating the sum of a column
of numbers). But what if we need to do a complex computation?
For heavy computation we should use a truly asynchronous (poll based) approach — the client
sends an AJAX request to the server, which causes action to be executed asynchronously on
the server (so the the response to the client is immediate); the client then polls the server for
updates. This is useful when you have a long-running action for which it is important that every
action executes (you don’t want some to be dropped as duplicates, or to timeout).

How should we design our conversational AJAX application?
Well first, you need to decide whether you want to use the simpler “synchronous” request or whether you want to add using a
poll-style approach.

If you go for a “synchronous” approach, then you need to make an estimate of how long your
AJAX request will take to complete – is it much shorter than the concurrent request timeout? If not,
you probably want to alter the concurrent request timeout for this method (as discussed above).
Next you probably want a queue on the client side to prevent flooding the server with requests. If the event occurs often
(e.g. a keypress, onblur of input fields) and immediate update of the client is not a priority you should set a request delay
on the client side. When working out your request delay, factor in that the event may also be queued on the server side.

Finally, the client library may provide an option to abort unfinished duplicate requests in favor of the most recent. You
need to be careful with this option as it can lead to flooding of the server with requests if the server is not able to abort
the unfinished request.

Using a poll-style design requires less fine-tuning. You just mark your action method @Asynchronous and decide on a polling
interval:

int total;
// This method is called when an event occurs on the client
// It takes a really long time to execute
@Asynchronous
public void calculateTotal() {
total = someReallyComplicatedCalculation();
}
// This method is called as the result of the poll
// It’s very quick to execute
public int getTotal() {
return total;
}

RichFaces Ajax:
RichFaces Ajax is the AJAX library most commonly used with Seam, and provides all the controls discussed above:

eventsQueue — provide a queue in which events are placed. All events are queued and requests are sent to the server serially.
This is useful if the request to the server can take some time to execute (e.g. heavy computation, retrieving
information from a slow source) as the server isn’t flooded.
• ignoreDupResponses — ignore the response produced by the request if a more recent ‘similar’ request is already in the
queue. ignoreDupResponses=”true” does not cancel the the processing of the request on the server side — just prevents
unnecessary updates on the client side. This option should be used with care with Seam’s conversations as it allows multiple
concurrent requests to be made.
• requestDelay — defines the time (in ms.) that the request will be remain on the queue. If the request has not been
processed by after this time the request will be sent (regardless of whether a response has been received) or discarded (if
there is a more recent similar event on the queue).
This option should be used with care with Seam’s conversations as it allows multiple concurrent requests to be made. You need
to be sure that the delay you set (in combination with the concurrent request timeout) is longer than the action will take
to execute.
• <a:poll reRender=”total” interval=”1000″ /> — Polls the server, and rerenders an area as needed.

Pageflows and business processes: JBoss jBPM is a business process management engine for any Java SE or EE environment. jBPM
lets you represent a business process or user interaction as a graph of nodes representing wait states, decisions, tasks,
web pages, etc. The graph is defined using a simple, very readable, XML dialect called jPDL, and may be edited and visualised
graphically using an eclipse plugin. jPDL is an extensible language, and is suitable for a range of problems, from defining
web application page flow, to traditional workflow management, all the way up to orchestration of services in a SOA
environment.

Seam applications use jBPM for two different problems:

• Defining the pageflow involved in complex user interactions. A jPDL process definition defines
the page flow for a single conversation. A Seam conversation is considered to be a relatively
short-running interaction with a single user.
• Defining the overarching business process. The business process may span multiple
conversations with multiple users. Its state is persistent in the jBPM database, so it is considered
long-running. Coordination of the activities of multiple users is a much more complex problem
than scripting an interaction with a single user, so jBPM offers sophisticated facilities for task
management and dealing with multiple concurrent paths of execution.

Don’t get these two things confused ! They operate at very different levels or granularity. Pageflow, conversation and task
all refer to a single interaction with a single user. A business process spans many tasks. Futhermore, the two applications
of jBPM are totally orthogonal. You can use them together or independently or not at all.
You don’t have to know jDPL to use Seam. If you’re perfectly happy defining pageflow using JSF or Seam navigation rules, and
if your application is more data-driven that process-driven, you probably don’t need jBPM. But we’re finding that thinking of
user interaction in terms of a well-defined graphical representation is helping us build more robust applications.

Pageflow in Seam:
There are two ways to define pageflow in Seam:
• Using JSF or Seam navigation rules – the stateless navigation model
• Using jPDL – the stateful navigation model
Very simple applications will only need the stateless navigation model. Very complex applications
will use both models in different places. Each model has its strengths and weaknesses!

The two navigation models: The stateless model defines a mapping from a set of named, logical outcomes of an event directly
to the resulting page of the view. The navigation rules are entirely oblivious to any state held by the application other
than what page was the source of the event. This means that your action listener methods must sometimes make decisions about
the page flow, since only they have access to the current state of the application.
Here is an example page flow definition using JSF navigation rules:

<navigation-rule>
<from-view-id>/numberGuess.jsp</from-view-id>
<navigation-case>
<from-outcome>guess</from-outcome>
<to-view-id>/numberGuess.jsp</to-view-id>
<redirect/>
</navigation-case>
<navigation-case>
<from-outcome>win</from-outcome>
<to-view-id>/win.jsp</to-view-id>
<redirect/>
</navigation-case>
<navigation-case>
<from-outcome>lose</from-outcome>
<to-view-id>/lose.jsp</to-view-id>
<redirect/>
</navigation-case>
</navigation-rule>

Here is the same example page flow definition using Seam navigation rules:

<page view-id=”/numberGuess.jsp”>
<navigation>
<rule if-outcome=”guess”>
<redirect view-id=”/numberGuess.jsp”/>
</rule>
<rule if-outcome=”win”>
<redirect view-id=”/win.jsp”/>
</rule>
<rule if-outcome=”lose”>
<redirect view-id=”/lose.jsp”/>
</rule>
</navigation>
</page>

If you find navigation rules overly verbose, you can return view ids directly from your action listener methods:

public String guess() {
if (guess==randomNumber) return “/win.jsp”;
if (++guessCount==maxGuesses) return “/lose.jsp”;
return null;
}

Note that this results in a redirect. You can even specify parameters to be used in the redirect:

public String search() {
return “/searchResults.jsp?searchPattern=#{searchAction.searchPattern}”;
}

The stateful model defines a set of transitions between a set of named, logical application states.
In this model, it is possible to express the flow of any user interaction entirely in the jPDL
pageflow definition, and write action listener methods that are completely unaware of the flow of the interaction.
Here is an example page flow definition using jPDL:

<pageflow-definition name=”numberGuess”>
<start-page name=”displayGuess” view-id=”/numberGuess.jsp”>
<redirect/>
<transition name=”guess” to=”evaluateGuess”>
<action expression=”#{numberGuess.guess}” />
</transition>
</start-page>
<decision name=”evaluateGuess” expression=”#{numberGuess.correctGuess}”>
<transition name=”true” to=”win”/>
<transition name=”false” to=”evaluateRemainingGuesses”/>
</decision>
<decision name=”evaluateRemainingGuesses” expression=”#{numberGuess.lastGuess}”>
<transition name=”true” to=”lose”/>
<transition name=”false” to=”displayGuess”/>
</decision>
<page name=”win” view-id=”/win.jsp”>
<redirect/>
<end-conversation />
</page>
<page name=”lose” view-id=”/lose.jsp”>
<redirect/>
<end-conversation />
</page>
</pageflow-definition>

There are two things we notice immediately here:
• The JSF/Seam navigation rules are much simpler. (However, this obscures the fact that the underlying Java code is more
complex.)
• The jPDL makes the user interaction immediately understandable, without us needing to even look at the JSP or Java code.

In addition, the stateful model is more constrained. For each logical state (each step in the page flow), there are a
constrained set of possible transitions to other states. The stateless model is an ad hoc model which is suitable to
relatively unconstrained, freeform navigation where the user decides where he/she wants to go next, not the application.

The biggest contrast between the two models is the back-button behavior.

Seam and the back button: When JSF or Seam navigation rules are used, Seam lets the user freely navigate via the back,
forward and refresh buttons. It is the responsibility of the application to ensure that conversational state remains
internally consistent when this occurs. Experience with the combination of web application frameworks like Struts or
WebWork – that do not support a conversational model – and stateless component models like EJB stateless session beans or
the Spring framework has taught many developers that this is close to impossible to do! However, our experience is that
in the context of Seam, where there is a well-defined conversational model, backed by stateful session beans, it is actually
quite straightforward. Usually it is as simple as combining the use of no-conversation-view-id with null checks at the
beginning of action listener methods. We consider support for freeform navigation to be almost always desirable.
In this case, the no-conversation-view-id declaration goes in pages.xml. It tells Seam to redirect to a different page if a
request originates from a page rendered during a conversation, and that conversation no longer exists:

<page view-id=”/checkout.xhtml”
no-conversation-view-id=”/main.xhtml”/>

On the other hand, in the stateful model, backbuttoning is interpreted as an undefined transition back to a previous state.
Since the stateful model enforces a defined set of transitions from the current state, back buttoning is by default
disallowed in the stateful model! Seam transparently detects the use of the back button, and blocks any attempt to perform
an action from a previous, “stale” page, and simply redirects the user to the “current” page (and displays a faces message).
Whether you consider this a feature or a limitation of the stateful model depends upon your point of view: as an application
developer, it is a feature; as a user, it might be frustrating! You can enable backbutton navigation from a particular page
node by setting back=”enabled”.

<page name=”checkout”
view-id=”/checkout.xhtml”
back=”enabled”>
<redirect/>
<transition to=”checkout”/>
<transition name=”complete” to=”complete”/>
</page>

This allows backbuttoning from the checkout state to any previous state! Of course, we still need to define what happens if a
request originates from a page rendered during a pageflow, and the conversation with the pageflow no longer exists. In this
case, the no-conversation-view-id declaration goes into the pageflow definition:

<page name=”checkout”
view-id=”/checkout.xhtml”
back=”enabled”
no-conversation-view-id=”/main.xhtml”>
<redirect/>
<transition to=”checkout”/>
<transition name=”complete” to=”complete”/>
</page>

In practice, both navigation models have their place, and you’ll quickly learn to recognize when to prefer one model over
the other.

Seam and Object/Relational Mapping: Seam provides extensive support for the two most popular persistence architectures for
Java: Hibernate3, and the Java Persistence API introduced with EJB 3.0. Seam’s unique statemanagement architecture allows
the most sophisticated ORM integration of any web application framework.

Introduction: The state management architecture of Seam was originally designed to solve problems relating to persistence—in
particular problems associated with optimistic transaction processing. Scalable online applications always use optimistic
transactions. Almost all interesting work involves first displaying data to a user, and then, slightly later, updating the
same data. So Hibernate was designed to support the idea of a persistence context which spanned an optimistic transaction.

Unfortunately, the so-called “stateless” architectures that preceded Seam and EJB 3.0 had no construct for representing an
optimistic transaction. So, instead, these architectures provided persistence contexts scoped to the atomic transaction. Of
course, this resulted in many problems for users, and is the cause of the number one user complaint about Hibernate: the
dreaded LazyInitializationException. What we need is a construct for representing an optimistic transaction in the
application tier.

EJB 3.0 recognizes this problem, and introduces the idea of a stateful component (a stateful session bean) with an extended
persistence context scoped to the lifetime of the component. This is a partial solution to the problem however there are
two problems:

• The lifecycle of the stateful session bean must be managed manually via code in the web tier
(it turns out that this is a subtle problem and much more difficult in practice than it sounds).
• Propagation of the persistence context between stateful components in the same optimistic transaction is possible, but
tricky.

Seam solves the first problem by providing conversations, and stateful session bean components scoped to the conversation.
(Most conversations actually represent optimistic transactions in the data layer.) This is sufficient for many simple
applications (such as the Seam booking demo) where persistence context propagation is not needed. For more complex
applications, with many loosly-interacting components in each conversation, propagation of the persistence context across
components becomes an important issue. So Seam extends the persistence context management model of EJB 3.0, to provide
conversation-scoped extended persistence contexts.

Seam managed transactions: EJB session beans feature declarative transaction management. The EJB container is able to start
a transaction transparently when the bean is invoked, and end it when the invocation ends. If we write a session bean method
that acts as a JSF action listener, we can do all the work associated with that action in one transaction, and be sure that
it is committed or rolled back when we finish processing the action. This is a great feature, and all that is needed by some
Seam applications. However, there is a problem with this approach. A Seam application may not perform all data access for a
request from a single method call to a session bean.

• The request might require processing by several loosly-coupled components, each of which is called independently from the
web layer. It is common to see several or even many calls per request from the web layer to EJB components in Seam.
• Rendering of the view might require lazy fetching of associations. The more transactions per request, the more likely we
are to encounter atomicity and isolation problems when our application is processing many concurrent requests. Certainly, all
write operations should occur in the same transaction! Hibernate users developed the “open session in view” pattern to work
around this problem. In the Hibernate community, “open session in view” was historically even more important because
frameworks like Spring use transaction-scoped persistence contexts. So rendering the view would cause
LazyInitializationExceptions when unfetched associations were accessed. This pattern is usually implemented as a single
transaction which spans the entire request. There are several problems with this implementation, the most serious being that
we can never be sure that a transaction is successful until we commit it—but by the time the “open session in view”
transaction is committed, the view is fully rendered, and the rendered response may already have been flushed to the client.
How can we notify the user that their transaction was unsuccessful? Seam solves both the transaction isolation problem and
the association fetching problem, while working around the problems with “open session in view”.
The solution comes in two parts:

• use an extended persistence context that is scoped to the conversation, instead of to the transaction.
• use two transactions per request; the first spans the beginning of the restore view phase (some transaction managers begin
the transaction later at the beginning of the apply request vaues phase) until the end of the invoke application phase; the
second spans the render response phase.

In the next section, we’ll tell you how to set up a conversation-scope persistence context. But first we need to tell you how
to enable Seam transaction management. Note that you can use conversation-scoped persistence contexts without Seam
transaction management, and there are good reasons to use Seam transaction management even when you’re not using
Seam-managed persistence contexts. However, the two facilities were designed to work together, and work best when used
together.

Seam transaction management is useful even if you’re using EJB 3.0 container-managed persistence contexts. But it is
especially useful if you use Seam outside a Java EE 5 environment, or in any other case where you would use a Seam-managed
persistence context.

Disabling Seam-managed transactions:
Seam transaction management is enabled by default for all JSF requests. If you want to disable this feature, you can do it in
components.xml:

<core:init transaction-management-enabled=”false”/>
<transaction:no-transaction />

Configuring a Seam transaction manager: Seam provides a transaction management abstraction for beginning, committing,
rolling back, and synchronizing with a transaction. By default Seam uses a JTA transaction component that integrates with
Container Managed and programmatic EJB transactions. If you are working in a Java EE 5 environment, you should install the
EJB synchronization component in components.xml:

<transaction:ejb-transaction />

However, if you are working in a non EE 5 container, Seam will try auto detect the transaction synchronization mechanism to
use. However, if Seam is unable to detect the correct transaction synchronization to use, you may find you need configure
one of the following:

• JPA RESOURCE_LOCAL transactions with the javax.persistence.EntityTransaction interface. EntityTransaction begins the
transaction at the beginning of the apply request values phase.
• Hibernate managed transactions with the org.hibernate.Transaction interface. HibernateTransaction begins the transaction
at the beginning of the apply request values phase.
• Spring managed transactions with the org.springframework.transaction.PlatformTransactionManager interface. The Spring
PlatformTransactionManagement manager may begin the transaction at the beginning of the apply request values phase if the
userConversationContext attribute is set.
• Explicitly disable Seam managed transactions.

Configure JPA RESOURCE_LOCAL transaction management by adding the following to your components.xml where #{em} is the name
of the persistence:managed-persistence-context component. If your managed persistence context is named entityManager, you can
opt to leave out the entity-manager attribute.

<transaction:entity-transaction entity-manager=”#{em}”/>

To configure Hibernate managed transactions declare the following in your components.xml where #{hibernateSession} is the
name of the project’s persistence:managed-hibernate-session component. If your managed hibernate session is named session,
you can opt to leave out the session attribute.

<transaction:hibernate-transaction session=”#{hibernateSession}”/>

To explicitly disable Seam managed transactions declare the following in your components.xml:

<transaction:no-transaction />

Transaction synchronization: Transaction synchronization provides callbacks for transaction related events such as
beforeCompletion() and afterCompletion(). By default, Seam uses it’s own transaction synchronization component which requires
explicit use of the Seam transaction component when committing a transaction to ensure synchronization callbacks are
correctly executed. If in a Java EE 5 environment the <transaction:ejb-transaction/> component should be be declared in
components.xml to ensure that Seam synchronization callbacks are correctly called if the container commits a transaction
outside of Seam’s knowledge.

Seam-managed persistence contexts: If you’re using Seam outside of a Java EE 5 environment, you can’t rely upon the container
to manage the persistence context lifecycle for you. Even if you are in an EE 5 environment, you might have a complex
application with many loosly coupled components that collaborate together in the scope of a single conversation, and in this
case you might find that propagation of the persistence context between component is tricky and error-prone.
In either case, you’ll need to use a managed persistence context (for JPA) or a managed session (for Hibernate) in your
components. A Seam-managed persistence context is just a built-in Seam component that manages an instance of EntityManager or
Session in the conversation context. You can inject it with @In.
Seam-managed persistence contexts are extremely efficient in a clustered environment. Seam is able to perform an optimization
that EJB 3.0 specification does not allow containers to use for container-managed extended persistence contexts. Seam
supports transparent failover of extended persisence contexts, without the need to replicate any persistence context state
between nodes. (We hope to fix this oversight in the next revision of the EJB spec).

Using a Seam-managed persistence context with JPA:
Configuring a managed persistence context is easy. In components.xml, we can write:

<persistence:managed-persistence-context name=”bookingDatabase” auto-create=”true”
persistence-unit-jndi-name=”java:/EntityManagerFactories/bookingData”/>

This configuration creates a conversation-scoped Seam component named bookingDatabase that manages the lifecycle of
EntityManager instances for the persistence unit (EntityManagerFactory instance) with JNDI name
java:/EntityManagerFactories/bookingData.
Of course, you need to make sure that you have bound the EntityManagerFactory into JNDI. In JBoss, you can do this by adding
the following property setting to persistence.xml.

<property name=”jboss.entity.manager.factory.jndi.name” value=”java:/EntityManagerFactories/bookingData”/>

Now we can have our EntityManager injected using:
@In EntityManager bookingDatabase;

If you are using EJB3 and mark your class or method @TransactionAttribute(REQUIRES_NEW) then the transaction and persistence
context shouldn’t be propagated to method calls on this object. However as the Seam-managed persistence context is
propagated to any component within the conversation, it will be propagated to methods marked REQUIRES_NEW. Therefore,
if you mark a method REQUIRES_NEW then you should access the entity manager using @PersistenceContext.

Using a Seam-managed Hibernate session:
Seam-managed Hibernate sessions are similar. In components.xml:

<persistence:hibernate-session-factory name=”hibernateSessionFactory”/>
<persistence:managed-hibernate-session name=”bookingDatabase” auto-create=”true”
session-factory-jndi-name=”java:/bookingSessionFactory”/>

Where java:/bookingSessionFactory is the name of the session factory specified in hibernate.cfg.xml.

<session-factory name=”java:/bookingSessionFactory”>
<property name=”transaction.flush_before_completion”>true</property>
<property name=”connection.release_mode”>after_statement</property>
<property
property>
<property
property>
<property name=”connection.datasource”>java:/bookingDatasource</property>
…
</session-factory>

Note that Seam does not flush the session, so you should always enable hibernate.transaction.flush_before_completion to
ensure that the session is automatically flushed before the JTA transaction commits.
We can now have a managed Hibernate Session injected into our JavaBean components using the following code:

@In Session bookingDatabase;

Seam-managed persistence contexts and atomic conversations: Persistence contexts scoped to the conversation allows you to
program optimistic transactions that span multiple requests to the server without the need to use the merge() operation ,
without the need to re-load data at the beginning of each request, and without the need to wrestle with the
LazyInitializationException or NonUniqueObjectException. As with any optimistic transaction management, transaction isolation
and consistency can be achieved via use of optimistic locking. Fortunately, both Hibernate and EJB 3.0 make it very easy
to use optimistic locking, by providing the @Version annotation.

By default, the persistence context is flushed (synchronized with the database) at the end of each transaction. This is
sometimes the desired behavior. But very often, we would prefer that all changes are held in memory and only written to the
database when the conversation ends successfully. This allows for truly atomic conversations. As the result of a truly
stupid and shortsighted decision by certain non-JBoss, non-Sun and non-Sybase members of the EJB 3.0 expert group, there is
currently no simple, usable and portable way to implement atomic conversations using EJB 3.0 persistence. However, Hibernate
provides this feature as a vendor extension to the FlushModeTypes defined by the specification, and it is our expectation
that other vendors will soon provide a similar extension.
Seam lets you specify FlushModeType.MANUAL when beginning a conversation. Currently, this works only when Hibernate is the
underlying persistence provider, but we plan to support other equivalent vendor extensions.

@In EntityManager em; //a Seam-managed persistence context
@Begin(flushMode=MANUAL)
public void beginClaimWizard() {
claim = em.find(Claim.class, claimId);
}

Now, the claim object remains managed by the persistence context for the rest ot the conversation. We can make changes to
the claim:

public void addPartyToClaim() {
Party party = ….;
claim.addParty(party);
}

But these changes will not be flushed to the database until we explicitly force the flush to occur:

@End
public void commitClaim() {
em.flush();
}

Of course, you could set the flushMode to MANUAL from pages.xml, for example in a navigation rule:

<begin-conversation flush-mode=”MANUAL” />

Using the JPA “delegate”: The EntityManager interface lets you access a vendor-specific API via the getDelegate()
method. Naturally, the most interesting vendor is Hibernate, and the most powerful delegate interface is
org.hibernate.Session.
But regardless of whether you’re using Hibernate or something else, you’ll almost certainly want to use the delegate in your
Seam components from time to time. One approach would be the following:

@In EntityManager entityManager;
@Create
public void init() {
( (Session) entityManager.getDelegate() ).enableFilter(“currentVersions”);
}

But typecasts are unquestionably the ugliest syntax in the Java language, so most people avoid them whenever possible.
Here’s a different way to get at the delegate. First, add the following line to components.xml:

<factory name=”session” scope=”STATELESS” auto-create=”true” value=”#{entityManager.delegate}”/>

Now we can inject the session directly:

@In Session session;
@Create
public void init() {
session.enableFilter(“currentVersions”);
}

Using EL in EJB-QL/HQL: Seam proxies the EntityManager or Session object whenever you use a Seam-managed persistence context
or inject a container managed persistence context using @PersistenceContext. This lets you use EL expressions in your query
strings, safely and efficiently. For example, this:

User user = em.createQuery(“from User where username=#{user.username}”).getSingleResult();

is equivalent to:

User user = em.createQuery(“from User where username=:username”).setParameter(“username”, user.getUsername())
.getSingleResult();

Of course, you should never, ever write it like this:

User user = em.createQuery(“from User where username=” + user.getUsername()).getSingleResult(); //BAD!
(It is inefficient and vulnerable to SQL injection attacks).

Using Hibernate filters: The coolest, and most unique, feature of Hibernate is filters. Filters let you provide a restricted
view of the data in the database. You can find out more about filters in the Hibernate documentation. But we thought we’d
mention an easy way to incorporate filters into a Seam application, one that works especially well with the Seam Application
Framework.
Seam-managed persistence contexts may have a list of filters defined, which will be enabled whenever an EntityManager or
Hibernate Session is first created. (Of course, they may only be used when Hibernate is the underlying persistence provider).

<persistence:filter name=”regionFilter”>
<persistence:name>region</persistence:name>
<persistence:parameters>
<key>regionCode</key>
<value>#{region.code}</value>
</persistence:parameters>
</persistence:filter>

<persistence:filter name=”currentFilter”>
<persistence:name>current</persistence:name>
<persistence:parameters>
<key>date</key>
<value>#{currentDate}</value>
</persistence:parameters>
</persistence:filter>

<persistence:managed-persistence-context name=”personDatabase”
persistence-unit-jndi-name=”java:/EntityManagerFactories/personDatabase”>
<core:filters>
<value>#{regionFilter}</value>
<value>#{currentFilter}</value>
</core:filters>
</persistence:managed-persistence-context>

JSF form validation in Seam: In plain JSF, validation is defined in the view:

<h:form>
<h:messages/>
<div>
Country:
<h:inputText value=”#{location.country}” required=”true”>
<my:validateCountry/>
</h:inputText>
</div>
<div>
Zip code:
<h:inputText value=”#{location.zip}” required=”true”>
<my:validateZip/>
</h:inputText>
</div>
<h:commandButton/>
</h:form>

In practice, this approach usually violates DRY, since most “validation” actually enforces constraints that are part of the
data model, and exist all the way down to the database schema definition. Seam provides support for model-based constraints
defined using Hibernate Validator.
Let’s start by defining our constraints, on our Location class:

public class Location {
private String country;
private String zip;
@NotNull
@Length(max=30)
public String getCountry() { return country; }
public void setCountry(String c) { country = c; }
@NotNull
@Length(max=6)
@Pattern(“^\d*$”)
public String getZip() { return zip; }
public void setZip(String z) { zip = z; }
}

Well, that’s a decent first cut, but in practice it might be more elegant to use custom constraints
instead of the ones built into Hibernate Validator:

public class Location {
private String country;
private String zip;

@NotNull
@Country
public String getCountry() { return country; }
public void setCountry(String c) { country = c; }

@NotNull
@ZipCode
public String getZip() { return zip; }
public void setZip(String z) { zip = z; }
}

Whichever route we take, we no longer need to specify the type of validation to be used in the JSF page. Instead, we can use
<s:validate> to validate against the constraint defined on the model object.

<h:form>
<h:messages/>
<div>
Country:
<h:inputText value=”#{location.country}” required=”true”>
<s:validate/>
</h:inputText>
</div>
<div>
Zip code:
<h:inputText value=”#{location.zip}” required=”true”>
<s:validate/>
</h:inputText>
</div>
<h:commandButton/>
</h:form>

Note: specifying @NotNull on the model does not eliminate the requirement for required=”true” to appear on the control! This
is due to a limitation of the JSF validation architecture. This approach defines constraints on the model, and presents
constraint violations in the view—a significantly better design.
However, it is not much less verbose than what we started with, so let’s try <s:validateAll>:

<h:form>
<h:messages/>
<s:validateAll>
<div>
Country:
<h:inputText value=”#{location.country}” required=”true”/>
</div>
<div>
Zip code:
<h:inputText value=”#{location.zip}” required=”true”/>
</div>
<h:commandButton/>
</s:validateAll>
</h:form>

This tag simply adds an <s:validate> to every input in the form. For a large form, it can save a lot of typing!

Now we need to do something about displaying feedback to the user when validation fails.
Currently we are displaying all messages at the top of the form. What we would really like to do is
display the message next to the field with the error (this is possible in plain JSF), highlight the field
and label (this is not possible) and, for good measure, display some image next to the field (also
not possible). We also want to display a little colored asterisk next to the label for each required form field.

That’s quite a lot of functionality we need for each field of our form. We wouldn’t want to have to
specify higlighting and the layout of the image, message and input field for every field on the form.
So, instead, we’ll specify the common layout in a facelets template:

<ui:composition xmlns=”http://www.w3.org/1999/xhtml”
xmlns:ui=”http://java.sun.com/jsf/facelets”
xmlns:h=”http://java.sun.com/jsf/html”
xmlns:f=”http://java.sun.com/jsf/core”
xmlns:s=”http://jboss.com/products/seam/taglib”>
<div>
<s:label styleClass=”#{invalid?’error’:”}”>
<ui:insert name=”label”/>
<s:span styleClass=”required” rendered=”#{required}”>*</s:span>
</s:label>
<span>
<h:graphicImage value=”/img/error.gif” rendered=”#{invalid}”/>
<s:validateAll>
<ui:insert/>
</s:validateAll>
</span>
<s:message styleClass=”error”/>
</div>
</ui:composition>

We can include this template for each of our form fields using <s:decorate>.

<h:form>
<h:messages globalOnly=”true”/>
<s:decorate template=”edit.xhtml”>
<ui:define name=”label”>Country:</ui:define>
<h:inputText value=”#{location.country}” required=”true”/>
</s:decorate>
<s:decorate template=”edit.xhtml”>
<ui:define name=”label”>Zip code:</ui:define>
<h:inputText value=”#{location.zip}” required=”true”/>
</s:decorate>
<h:commandButton/>
</h:form>

Finally, we can use RichFaces Ajax to display validation messages as the user is navigating around the form:

<h:form>
<h:messages globalOnly=”true”/>
<s:decorate id=”countryDecoration” template=”edit.xhtml”>
<ui:define name=”label”>Country:</ui:define>
<h:inputText value=”#{location.country}” required=”true”>
<a:support event=”onblur” reRender=”countryDecoration” bypassUpdates=”true”/>
</h:inputText>
</s:decorate>
<s:decorate id=”zipDecoration” template=”edit.xhtml”>
<ui:define name=”label”>Zip code:</ui:define>
<h:inputText value=”#{location.zip}” required=”true”>
<a:support event=”onblur” reRender=”zipDecoration” bypassUpdates=”true”/>
</h:inputText>
</s:decorate>
<h:commandButton/>
</h:form>

It’s better style to define explicit ids for important controls on the page, especially if you want to
do automated testing for the UI, using some toolkit like Selenium. If you don’t provide explicit ids,
JSF will generate them, but the generated values will change if you change anything on the page.

<h:form id=”form”>
<h:messages globalOnly=”true”/>
<s:decorate id=”countryDecoration” template=”edit.xhtml”>
<ui:define name=”label”>Country:</ui:define>
<h:inputText id=”country” value=”#{location.country}” required=”true”>
<a:support event=”onblur” reRender=”countryDecoration” bypassUpdates=”true”/>
</h:inputText>
</s:decorate>
<s:decorate id=”zipDecoration” template=”edit.xhtml”>
<ui:define name=”label”>Zip code:</ui:define>
<h:inputText id=”zip” value=”#{location.zip}” required=”true”>
<a:support event=”onblur” reRender=”zipDecoration” bypassUpdates=”true”/>
</h:inputText>
</s:decorate>
<h:commandButton/>
</h:form>

And what if you want to specify a different message to be displayed when validation fails? You
can use the Seam message bundle (and all it’s goodies like el expressions inside the message,
and per-view message bundles) with the Hibernate Validator:

public class Location {
private String name;
private String zip;
// Getters and setters for name
@NotNull
@Length(max=6)
@ZipCode(message=”#{messages['location.zipCode.invalid']}”)
public String getZip() { return zip; }
public void setZip(String z) { zip = z; }
}

location.zipCode.invalid = The zip code is not valid for #{location.name}

The Seam Application Framework: Seam makes it really easy to create applications by writing plain Java classes with
annotations, which don’t need to extend any special interfaces or superclasses. But we can simplify some common programming
tasks even further, by providing a set of pre-built components which can be re-used either by configuration in components.xml
(for very simple cases) or extension. The Seam Application Framework can reduce the amount of code you need to write when
doing basic database access in a web application, using either Hibernate or JPA. We should emphasize that the framework is
extremely simple, just a handful of simple classes that are easy to understand and extend.

Introduction: The components provided by the Seam application framework may be used in one of two different approaches. The
first way is to install and configure an instance of the component in components.xml, just like we have done with other kinds
of built-in Seam components. For example, the following fragment from components.xml installs a component which can perform
basic CRUD operations for a Person entity:

<framework:entity-home name=”personHome”
entity-class=”eg.Person”
entity-manager=”#{personDatabase}”>
<framework:id>#{param.personId}</framework:id>
</framework:entity-home>

If that looks a bit too much like “programming in XML” for your taste, you can use extension instead:

@Name(“personHome”)
public class PersonHome extends EntityHome<Person> {
@In EntityManager personDatabase;
public EntityManager getEntityManager() {
return personDatabase;
}
}

The second approach has one huge advantage: you can easily add extra functionality, and
override the built-in functionality (the framework classes were carefully designed for extension and customization).

A second advantage is that your classes may be EJB stateful session beans, if you like. (They do not have to be, they can be
plain JavaBean components if you prefer). If you are using JBoss AS, you’ll need 4.2.2.GA or later:

@Stateful
@Name(“personHome”)
public class PersonHome extends EntityHome<Person> implements LocalPersonHome {
}

You can also make your classes stateless session beans. In this case you must use injection to
provide the persistence context, even if it is called entityManager:

@Stateless
@Name(“personHome”)
public class PersonHome extends EntityHome<Person> implements LocalPersonHome {
@In EntityManager entityManager;
public EntityManager getPersistenceContext() {
entityManager;
}
}

At this time, the Seam Application Framework provides four main built-in components:
EntityHome and HibernateEntityHome for CRUD, along with EntityQuery and HibernateEntityQuery for queries.

The Home and Query components are written so that they can function with a scope of session, event or conversation. Which
scope you use depends upon the state model you wish to use in your application.

The Seam Application Framework only works with Seam-managed persistence contexts. By
default, the components will look for a persistence context named entityManager.

Home objects: A Home object provides persistence operations for a particular entity class. Suppose we have our
trusty Person class:

@Entity
public class Person {
@Id private Long id;
private String firstName;
private String lastName;
private Country nationality;
//getters and setters…
}

We can define a personHome component either via configuration:

<framework:entity-home name=”personHome” entity-class=”eg.Person” />

Or via extension:

@Name(“personHome”)
public class PersonHome extends EntityHome<Person> {}

A Home object provides the following operations: persist(), remove(), update() and getInstance(). Before you can call the
remove(), or update() operations, you must first set the identifier of the object you are interested in, using the setId()
method.

We can use a Home directly from a JSF page, for example:

<h1>Create Person</h1>
<h:form>
<div>First name: <h:inputText value=”#{personHome.instance.firstName}”/></div>
<div>Last name: <h:inputText value=”#{personHome.instance.lastName}”/></div>
<div>
<h:commandButton value=”Create Person” action=”#{personHome.persist}”/>
</div>
</h:form>

Usually, it is much nicer to be able to refer to the Person merely as person, so let’s make that possible by adding a line to
components.xml:

<factory name=”person” value=”#{personHome.instance}”/>
<framework:entity-home name=”personHome” entity-class=”eg.Person” />

(If we are using configuration).

Or by adding a @Factory method to PersonHome:

@Name(“personHome”)
public class PersonHome extends EntityHome<Person> {
@Factory(“person”)
public Person initPerson() { return getInstance(); }
}

(If we are using extension).

This change simplifies our JSF page to the following:

<h1>Create Person</h1>
<h:form>
<div>First name: <h:inputText value=”#{person.firstName}”/></div>
<div>Last name: <h:inputText value=”#{person.lastName}”/></div>
<div>
<h:commandButton value=”Create Person” action=”#{personHome.persist}”/>
</div>
</h:form>

Well, that lets us create new Person entries. Yes, that is all the code that is required! Now, if we
want to be able to display, update and delete pre-existing Person entries in the database, we
need to be able to pass the entry identifier to the PersonHome. Page parameters are a great way to do that:

<pages>
<page view-id=”/editPerson.jsp”>
<param name=”personId” value=”#{personHome.id}”/>
</page>
</pages>

Now we can add the extra operations to our JSF page:

<h1>
<h:outputText rendered=”#{!personHome.managed}” value=”Create Person”/>
<h:outputText rendered=”#{personHome.managed}” value=”Edit Person”/>
</h1>
<h:form>
<div>First name: <h:inputText value=”#{person.firstName}”/></div>
<div>Last name: <h:inputText value=”#{person.lastName}”/></div>
<div>
<h:commandButton value=”Create Person” action=”#{personHome.persist}”
rendered=”#{!personHome.managed}”/>
<h:commandButton value=”Update Person” action=”#{personHome.update}”
rendered=”#{personHome.managed}”/>
<h:commandButton value=”Delete Person” action=”#{personHome.remove}”
rendered=”#{personHome.managed}”/>
</div>
</h:form>

When we link to the page with no request parameters, the page will be displayed as a “Create
Person” page. When we provide a value for the personId request parameter, it will be an “Edit
Person” page.
Suppose we need to create Person entries with their nationality initialized. We can do that easily,
via configuration:

<factory name=”person”
value=”#{personHome.instance}”/>
<framework:entity-home name=”personHome”
entity-class=”eg.Person”
new-instance=”#{newPerson}”/>
<component name=”newPerson”
class=”eg.Person”>
<property name=”nationality”>#{country}</property>
</component>

Or by extension:

@Name(“personHome”)
public class PersonHome extends EntityHome<Person> {
@In Country country;
@Factory(“person”)
public Person initPerson() { return getInstance(); }
protected Person createInstance() {
return new Person(country);
}
}

Of course, the Country could be an object managed by another Home object, for example, CountryHome.
To add more sophisticated operations (association management, etc), we can just add methods to PersonHome.

@Name(“personHome”)
public class PersonHome extends EntityHome<Person> {
@In Country country;
@Factory(“person”)
public Person initPerson() { return getInstance(); }
protected Person createInstance() {
return new Person(country);
}
public void migrate()
{
getInstance().setCountry(country);
update();
}
}

The Home object raises an org.jboss.seam.afterTransactionSuccess event when a transaction succeeds (a call to persist(),
update() or remove() succeeds). By observing this event we can refresh our queries when the underlying entities are changed.
If we only want to refresh certain queries when a particular entity is persited, updated or removed we can observe
the org.jboss.seam.afterTransactionSuccess.<name> event (where <name> is the name of the entity).

The Home object automatically displays faces messages when an operation is successful. To customize these messages we can,
again, use configuration:

<factory name=”person”
value=”#{personHome.instance}”/>
<framework:entity-home name=”personHome”
entity-class=”eg.Person”
new-instance=”#{newPerson}”>
<framework:created-message>New person #{person.firstName} #{person.lastName} created</
framework:created-message>
<framework:deleted-message>Person #{person.firstName} #{person.lastName} deleted</
framework:deleted-message>
<framework:updated-message>Person #{person.firstName} #{person.lastName} updated</
framework:updated-message>
</framework:entity-home>
<component name=”newPerson”
class=”eg.Person”>
<property name=”nationality”>#{country}</property>
</component>

Or extension:
@Name(“personHome”)
public class PersonHome extends EntityHome<Person> {
@In Country country;
@Factory(“person”)
public Person initPerson() { return getInstance(); }
protected Person createInstance() {
return new Person(country);
}
protected String getCreatedMessage() { return “New person #{person.firstName}
#{person.lastName} created”; }
protected String getUpdatedMessage() { return “Person #{person.firstName}
#{person.lastName} updated”; }
protected String getDeletedMessage() { return “Person #{person.firstName}
#{person.lastName} deleted”; }
}

But the best way to specify the messages is to put them in a resource bundle known to Seam (the bundle named messages, by
default).

Person_created=New person #{person.firstName} #{person.lastName} created
Person_deleted=Person #{person.firstName} #{person.lastName} deleted
Person_updated=Person #{person.firstName} #{person.lastName} updated

This enables internationalization, and keeps your code and configuration clean of presentation concerns.
The final step is to add validation functionality to the page, using <s:validateAll> and <s:decorate>.

Query objects: If we need a list of all Person instance in the database, we can use a Query object. For example:

<framework:entity-query name=”people” ejbql=”select p from Person p”/>

We can use it from a JSF page:

<h1>List of people</h1>
<h:dataTable value=”#{people.resultList}” var=”person”>
<h:column>
<s:link view=”/editPerson.jsp” value=”#{person.firstName} #{person.lastName}”>
<f:param name=”personId” value=”#{person.id}”/>
</s:link>
</h:column>
</h:dataTable>

We probably need to support pagination:

<framework:entity-query name=”people” ejbql=”select p from Person p” order=”lastName” max-results=”20″/>

We’ll use a page parameter to determine the page to display:

<pages>
<page view-id=”/searchPerson.jsp”>
<param name=”firstResult” value=”#{people.firstResult}”/>
</page>
</pages>

The JSF code for a pagination control is a bit verbose, but manageable:

<h1>Search for people</h1>
<h:dataTable value=”#{people.resultList}” var=”person”>
<h:column>
<s:link view=”/editPerson.jsp” value=”#{person.firstName} #{person.lastName}”>
<f:param name=”personId” value=”#{person.id}”/>
</s:link>
</h:column>
</h:dataTable>
<s:link view=”/search.xhtml” rendered=”#{people.previousExists}” value=”First Page”>
<f:param name=”firstResult” value=”0″/>
</s:link>
<s:link view=”/search.xhtml” rendered=”#{people.previousExists}” value=”Previous Page”>
<f:param name=”firstResult” value=”#{people.previousFirstResult}”/>
</s:link>
<s:link view=”/search.xhtml” rendered=”#{people.nextExists}” value=”Next Page”>
<f:param name=”firstResult” value=”#{people.nextFirstResult}”/>
</s:link>
<s:link view=”/search.xhtml” rendered=”#{people.nextExists}” value=”Last Page”>
<f:param name=”firstResult” value=”#{people.lastFirstResult}”/>
</s:link>

Real search screens let the user enter a bunch of optional search criteria to narrow the list of
results returned. The Query object lets you specify optional “restrictions” to support this important usecase:

<component name=”examplePerson”/>
<framework:entity-query name=”people”
ejbql=”select p from Person p”
order=”lastName”
max-results=”20″>
<framework:restrictions>
<value>lower(firstName) like lower( concat(#{examplePerson.firstName},’%') )</value>
<value>lower(lastName) like lower( concat(#{examplePerson.lastName},’%') )</value>
</framework:restrictions>
</framework:entity-query>

Notice the use of an “example” object.

<h1>Search for people</h1>
<h:form>
<div>First name: <h:inputText value=”#{examplePerson.firstName}”/></div>
<div>Last name: <h:inputText value=”#{examplePerson.lastName}”/></div>
<div><h:commandButton value=”Search” action=”/search.jsp”/></div>
</h:form>
<h:dataTable value=”#{people.resultList}” var=”person”>
<h:column>
<s:link view=”/editPerson.jsp” value=”#{person.firstName} #{person.lastName}”>
<f:param name=”personId” value=”#{person.id}”/>
</s:link>
</h:column>
</h:dataTable>

To refresh the query when the underlying entities change we observe the org.jboss.seam.afterTransactionSuccess event:

<event type=”org.jboss.seam.afterTransactionSuccess”>
<action execute=”#{people.refresh}” />
</event>

Or, to just refresh the query when the person entity is persisted, updated or removed through PersonHome:

<event type=”org.jboss.seam.afterTransactionSuccess.Person”>
<action execute=”#{people.refresh}” />
</event>

Unfortunately Query objects don’t work well with join fetch queries – the use of pagination with these queries is not
recomended, and you’ll have to implement your own method of calculating the total number of results (by overriding
getCountEjbql(). The examples in this section have all shown reuse by configuration. However, reuse by extension
is equally possible for Query objects.

Controller objects: A totally optional part of the Seam Application Framework is the classController and its subclasses
EntityController, HibernateEntityController and BusinessProcessController. These classes provide nothing more than some
convenience methods for access to commonly used built-in components and methods of built-in components.
They help save a few keystrokes (characters can add up!) and provide a great launchpad for new users to explore the rich
functionality built in to Seam.

For example, here is what RegisterAction from the Seam registration example would look like:

@Stateless
@Name(“register”)
public class RegisterAction extends EntityController implements Register
{
@In private User user;
public String register()
{
List existing = createQuery(“select u.username from User u where u.username=:username”)
.setParameter(“username”, user.getUsername())
.getResultList();
if ( existing.size()==0 )
{
persist(user);
info(“Registered new user #{user.username}”);
return “/registered.jspx”;
}
else
{
addFacesMessage(“User #{user.username} already exists”);
return null;
}
}
}
As you can see, its not an earthshattering improvement…

Seam and JBoss Rules: Seam makes it easy to call JBoss Rules (Drools) rulebases from Seam components or jBPM
process definitions.

Security: The Seam Security API is an optional Seam feature that provides authentication and authorization
features for securing both domain and page resources within your Seam project.
Overview:
Seam Security provides two different modes of operation:
• simplified mode – this mode supports authentication services and simple role-based security checks.
• advanced mode – this mode supports all the same features as the simplified mode, plus it offers rule-based security checks
using JBoss Rules.

Which mode is right for my application? That all depends on the requirements of your application. If you have minimal
security requirements, for example if you only wish to restrict certain pages and actions to users who are logged in, or who
belong to a certain role, then the simplified mode will probably be sufficient. The advantages of this is a more simplified
configuration, significantly less libraries to include, and a smaller memory footprint.
If on the other hand, your application requires security checks based on contextual state or
complex business rules, then you will require the features provided by the advanced mode.

Requirements: If using the advanced mode features of Seam Security, the following jar files are required to be configured as
modules in application.xml. If you are using Seam Security in simplified mode, these are not required:

• drools-compiler.jar
• drools-core.jar
• janino.jar
• antlr-runtime.jar
• mvel14.jar

For web-based security, jboss-seam-ui.jar must also be included in the application’s war file.

Disabling Security: In some situations it may be necessary to disable Seam Security, for example during unit tests.
This can be done by calling the static method Identity.setSecurityEnabled(false) to disable security checks. Doing this
prevents any security checks being performed for the following:
• Entity Security
• Hibernate Security Interceptor
• Seam Security Interceptor
• Page restrictions

Authentication: The authentication features provided by Seam Security are built upon JAAS (Java Authentication and
Authorization Service), and as such provide a robust and highly configurable API for handling user authentication. However,
for less complex authentication requirements Seam offers a much more simplified method of authentication that hides the
complexity of JAAS.

Configuration: The simplified authentication method uses a built-in JAAS login module, SeamLoginModule, which delegates
authentication to one of your own Seam components. This login module is already configured inside Seam as part of a default
application policy and as such does not require any additional configuration files. It allows you to write an authentication
method using the entity classes that are provided by your own application. Configuring this simplified form of authentication
requires the identity component to be configured in components.xml:

<components xmlns=”http://jboss.com/products/seam/components”
xmlns:core=”http://jboss.com/products/seam/core”
xmlns:security=”http://jboss.com/products/seam/security”
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xsi:schemaLocation=
“http://jboss.com/products/seam/components http://jboss.com/products/seam/
components-2.1.xsd
http://jboss.com/products/seam/security http://jboss.com/products/seam/security-
2.1.xsd”>
<security:identity authenticate-method=”#{authenticator.authenticate}”/>
</components>

If you wish to use the advanced security features such as rule-based permission checks, all you need to do is include the
Drools (JBoss Rules) jars in your classpath, and add some additional configuration, described later.
The EL expression #{authenticator.authenticate} is a method binding indicating that the
authenticate method of the authenticator component will be used to authenticate the user.

Writing an authentication method: The authenticate-method property specified for identity in components.xml specifies
which method will be used by SeamLoginModule to authenticate users. This method takes no parameters, and is expected to
return a boolean indicating whether authentication is successful or not. The user’s username and password can be obtained
from Identity.instance().getUsername() and Identity.instance().getPassword(), respectively. Any roles that the user is a
member of should be assigned using Identity.instance().addRole(). Here’s a complete example of an authentication method
inside a JavaBean component:

@Name(“authenticator”)
public class Authenticator {
@In EntityManager entityManager;
public boolean authenticate() {
try
{
User user = (User) entityManager.createQuery(
“from User where username = :username and password = :password”)
.setParameter(“username”, Identity.instance().getUsername())
.setParameter(“password”, Identity.instance().getPassword())
.getSingleResult();
if (user.getRoles() != null)
{
for (UserRole mr : user.getRoles())
Identity.instance().addRole(mr.getName());
}
return true;
}
catch (NoResultException ex)
{
return false;
}
}
}

In the above example, both User and UserRole are application-specific entity beans. The roles parameter is populated with
the roles that the user is a member of, which should be added to the Set as literal string values, e.g. “admin”, “user”. In
this case, if the user record is not found and a NoResultException thrown, the authentication method returns false to
indicate the authentication failed.

Identity.addRole(): The Identity.addRole() method behaves differently depending on whether the current session is
authenticated or not. If the session is not authenticated, then addRole() should only be called during the authentication
process. When called here, the role name is placed into a temporary list of pre-authenticated roles. Once authentication is
successful, the pre-authenticated roles then become “real” roles, and calling Identity.hasRole() for those roles will then
return true. The following sequence diagram represents the list of pre-authenticated roles as a first class object to
show more clearly how it fits in to the authentication process.

Special Considerations: When writing an authenticator method, it is important that it is kept minimal and free from any
side-effects. This is because there is no guarantee as to how many times the authenticator method will be called by the
security API, and as such it may be invoked multiple times during a single request. Because of this, any special code that
should execute upon a successful or failed authentication should be written by implementing an event observer. See the
section on Security Events for more information about which events are raised by Seam Security.

To give an example, let’s say that upon a successful login that some user statistics must be updated. We would do this by
writing an event observer for the org.jboss.seam.security.loginSuccessful event, like this:

@In UserStats userStats;
@Observer(“org.jboss.seam.security.loginSuccessful”)
public void updateUserStats()
{
userStats.setLastLoginDate(new Date());
userStats.incrementLoginCount();
}

Writing a login form: The Identity component provides both username and password properties, catering for the most
common authentication scenario. These properties can be bound directly to the username and password fields on a login form.
Once these properties are set, calling the identity.login() method will authenticate the user using the provided credentials.
Here’s an example of a simple login form:

<div>
<h:outputLabel for=”name” value=”Username”/>
<h:inputText id=”name” value=”#{identity.username}”/>
</div>
<div>
<h:outputLabel for=”password” value=”Password”/>
<h:inputSecret id=”password” value=”#{identity.password}”/>
</div>
<div>
<h:commandButton value=”Login” action=”#{identity.login}”/>
</div>

Similarly, logging out the user is done by calling #{identity.logout}. Calling this action will
clear the security state of the currently authenticated user.

Handling Security Exceptions: To prevent users from receiving the default error page in response to a security error, it’s
recommended that pages.xml is configured to redirect security errors to a more “pretty” page. The two main types of
exceptions thrown by the security API are:

• NotLoggedInException – This exception is thrown if the user attempts to access a restricted
action or page when they are not logged in.

• AuthorizationException – This exception is only thrown if the user is already logged in, and
they have attempted to access a restricted action or page for which they do not have the necessary privileges.

In the case of a NotLoggedInException, it is recommended that the user is redirected to either a login or registration page
so that they can log in. For an AuthorizationException, it may be useful to redirect the user to an error page. Here’s an
example of a pages.xml file that redirects both of these security exceptions:

<pages>
…
<exception>
<redirect view-id=”/login.xhtml”>
<message>You must be logged in to perform this action</message>
</redirect>
</exception>

<exception>
<end-conversation/>
<redirect view-id=”/security_error.xhtml”>
<message>You do not have the necessary security privileges to perform this action.</message>
</redirect>
</exception>
</pages>

Most web applications require even more sophisticated handling of login redirection, so Seam
includes some special functionality for handling this problem.

Login Redirection: You can ask Seam to redirect the user to a login screen when an unauthenticated user tries to
access a particular view (or wildcarded view id) as follows:

<pages login-view-id=”/login.xhtml”>
<page view-id=”/members/*” login-required=”true”/>
…
</pages>

(This is less of a blunt instrument than the exception handler shown above, but should probably
be used in conjunction with it).

After the user logs in, we want to automatically send them back where they came from, so they can retry the action that
required logging in. If you add the following event listeners to components.xml, attempts to access a restricted view while
not logged in will be remembered, so that upon the user successfully logging in they will be redirected to the originally
requested view, with any page parameters that existed in the original request.

<event type=”org.jboss.seam.security.notLoggedIn”>
<action execute=”#{redirect.captureCurrentView}”/>
</event>
<event type=”org.jboss.seam.security.postAuthenticate”>
<action execute=”#{redirect.returnToCapturedView}”/>
</event>

Note that login redirection is implemented as a conversation-scoped mechanism, so don’t end the conversation in your
authenticate() method.

HTTP Authentication: Although not recommended for use unless absolutely necessary, Seam provides means for authenticating
using either HTTP Basic or HTTP Digest (RFC 2617) methods. To use either form of authentication, the authentication-filter
component must be enabled in components.xml:

<web:authentication-filter url-pattern=”*.seam” auth-type=”basic”/>

To enable the filter for basic authentication, set auth-type to basic, or for digest authentication,
set it to digest. If using digest authentication, the key and realm must also be set:

<web:authentication-filter url-pattern=”*.seam” auth-type=”digest” key=”AA3JK34aSDlkj” realm=”My App”/>

The key can be any String value. The realm is the name of the authentication realm that is presented to the user when they
authenticate.

Writing a Digest Authenticator: If using digest authentication, your authenticator class should extend the abstract class
org.jboss.seam.security.digest.DigestAuthenticator, and use the validatePassword()
method to validate the user’s plain text password against the digest request. Here is an example:

public boolean authenticate()
{
try
{
User user = (User) entityManager.createQuery(
“from User where username = :username”)
.setParameter(“username”, identity.getUsername())
.getSingleResult();
return validatePassword(user.getPassword());
}
catch (NoResultException ex)
{
return false;
}
}

Advanced Authentication Features:
This section explores some of the advanced features provided by the security API for addressing more complex security
requirements.

Using your container’s JAAS configuration: If you would rather not use the simplified JAAS configuration provided by the Seam
Security API, you may instead delegate to the default system JAAS configuration by providing a jaas-configname
property in components.xml. For example, if you are using JBoss AS and wish to use the other policy (which uses the
UsersRolesLoginModule login module provided by JBoss AS), then the entry in components.xml would look like this:

<security:identity jaas-config-name=”other”/>

Please keep in mind that doing this does not mean that your user will be authenticated in whichever container your Seam
application is deployed in. It merely instructs Seam Security to authenticate itself using the configured JAAS security
policy.

Error Messages: The security API produces a number of default faces messages for various security-related events.
The following table lists the message keys that can be used to override these messages by specifying them in a
message.properties resource file. To suppress the message, just put the key with an empty value in the resource file.

Security Message Keys:

Message Key                                              Description
————-                                          —————–
org.jboss.seam.loginSuccessful                This message is produced when a user successfully logs in via the security API.

org.jboss.seam.loginFailed                    This message is produced when the login process fails,either because the user
provided an incorrect username or password, or because authentication failed in
some other way.

org.jboss.seam.NotLoggedIn                    This message is produced when a user attempts to perform an action or access a
page that requires a security check, and the user is not currently
authenticated.

org.jboss.seam.AlreadyLoggedIn                This message is produced when a user that is already authenticated attempts to
log in again.

Authorization:

SSL Security:
Seam includes basic support for serving sensitive pages via the HTTPS protocol. This is easily configured by specifying a
scheme for the page in pages.xml. The following example shows how the view /login.xhtml is configured to use HTTPS:

<page view-id=”/login.xhtml” scheme=”https”/>

This configuration is automatically extended to both s:link and s:button JSF controls, which (when specifying the view) will
also render the link using the correct protocol. Based on the previous example, the following link will use the HTTPS
protocol because /login.xhtml is configured to use it:

<s:link view=”/login.xhtml” value=”Login”/>

Browsing directly to a view when using the incorrect protocol will cause a redirect to the same
view using the correct protocol. For example, browsing to a page that has scheme=”https” using
HTTP will cause a redirect to the same page using HTTPS.

It is also possible to configure a default scheme for all pages. This is useful if you wish to use HTTPS for a only few
pages. If no default scheme is specified then the normal behavior is to continue use the current scheme. So once the user
accessed a page that required HTTPS, then HTTPS would continue to be used after the user navigated away to other non-HTTPS
pages. (While this is good for security, it is not so great for performance!). To define HTTP as the default scheme, add
this line to pages.xml:

<page view-id=”*” scheme=”http” />

Of course, if none of the pages in your application use HTTPS then it is not required to specify a default scheme.

You may configure Seam to automatically invalidate the current HTTP session each time the
scheme changes. Just add this line to components.xml:

<core:servlet-session invalidate-on-scheme-change=”true”/>

This option helps make your system less vulnerable to sniffing of the session id or leakage of
sensitive data from pages using HTTPS to other pages using HTTP.

CAPTCHA: Though strictly not part of the security API, Seam provides a built-in CAPTCHA (Completely
Automated Public Turing test to tell Computers and Humans Apart) algorithm to prevent
automated processes from interacting with your application.

Configuring the CAPTCHA Servlet: To get up and running, it is necessary to configure the Seam Resource Servlet, which will
provide the Captcha challenge images to your pages. This requires the following entry in web.xml:

<servlet>
<servlet-name>Seam Resource Servlet</servlet-name>
<servlet-class>org.jboss.seam.servlet.SeamResourceServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Seam Resource Servlet</servlet-name>
<url-pattern>/seam/resource/*</url-pattern>
</servlet-mapping>

Adding a CAPTCHA to a form: Adding a CAPTCHA challenge to a form is extremely easy. Here’s an example:

<h:graphicImage value=”/seam/resource/captcha”/>
<h:inputText id=”verifyCaptcha” value=”#{captcha.response}” required=”true”>
<s:validate />
</h:inputText>
<h:message for=”verifyCaptcha”/>

That’s all there is to it. The graphicImage control displays the CAPTCHA challenge, and the inputText receives the user’s
response. The response is automatically validated against the CAPTCHA when the form is submitted.

Customising the CAPTCHA algorithm:
You may customize the CAPTCHA algorithm by overriding the built-in component:

@Name(“org.jboss.seam.captcha”)
@Scope(SESSION)
public class HitchhikersCaptcha extends Captcha
{
@Override @Create
public void init()
{
setChallenge(“What is the answer to life, the universe and everything?”);
setCorrectResponse(“42″);
}
@Override
public BufferedImage renderChallenge()
{
BufferedImage img = super.renderChallenge();
img.getGraphics().drawOval(5, 3, 60, 14); //add an obscuring decoration
return img;
}
}

Security Events:
Event Key                                                Description
——————–                                   ——————
org.jboss.seam.security.loginSuccessful            Raised when a login attempt issuccessful.

org.jboss.seam.security.loginFailed                Raised when a login attempt fails.

org.jboss.seam.security.alreadyLoggedIn            Raised when a user that is already authenticated attempts to log in
again.
org.jboss.seam.security.notLoggedIn                Raised when a security check fails when the user is not logged in.

org.jboss.seam.security.notAuthorized              Raised when a security check fails when the user is logged in however
doesn’t have sufficient privileges.

org.jboss.seam.security.preAuthenticate            Raised just prior to user authentication.

org.jboss.seam.security.postAuthenticate           Raised just after user authentication.

org.jboss.seam.security.loggedOut                  Raised after the user has logged out.

org.jboss.seam.security.credentialsUpdated         Raised when the user’s credentials have been changed.

org.jboss.seam.security.rememberMe                 Raised when the Identity’s rememberMe property is changed.

Run As: Sometimes it may be necessary to perform certain operations with elevated privileges, such
as creating a new user account as an unauthenticated user. Seam Security supports such a
mechanism via the RunAsOperation class. This class allows either the Principal or Subject,
or the user’s roles to be overridden for a single set of operations.
The following code example demonstrates how RunAsOperation is used, by overriding its
getRoles() method to specify a set of roles to masquerade as for the duration of the operation.
The execute() method contains the code that will be executed with the elevated privileges.

new RunAsOperation() {
@Override
public String[] getRoles() {
return new String[] { “admin” };
}
public void execute() {
executePrivilegedOperation();
}
}.run();

In a similar way, the getPrincipal() or getSubject() methods can also be overriden to specify
the Principal and Subject instances to use for the duration of the operation. Finally, the run()
method is used to carry out the RunAsOperation.

Extending the Identity component: Sometimes it might be necessary to extend the Identity component if your application has
special security requirements. For example, users might be required to authenticate using a Company or Department ID, along
with their usual username and password. If permission-based security is required then RuleBasedIdentity should be extended,
otherwise Identity should be extended.
The following example shows an extended Identity component with an additional companyCode field. The install precendence of
APPLICATION ensures that this extended Identity gets installed in preference to the built-in Identity.

@Name(“org.jboss.seam.security.identity”)
@Scope(SESSION)
@Install(precedence = APPLICATION)
@BypassInterceptors
@Startup
public class CustomIdentity extends Identity
{
private static final LogProvider log = Logging.getLogProvider(CustomIdentity.class);
private String companyCode;
public String getCompanyCode()
{

return companyCode;
}
public void setCompanyCode(String companyCode)
{
this.companyCode = companyCode;
}
@Override
public String login()
{
log.info(“###### CUSTOM LOGIN CALLED ######”);
return super.login();
}
}

Internationalization, localization and themes: Seam makes it easy to build internationalized applications. First, let’s walk
through all the stages needed to internationalize and localize your app. Then we’ll take a look at the components Seam
bundles.

Asynchronicity and messaging: Seam makes it very easy to perform work asynchronously from a web request. When most people
think of asynchronicity in Java EE, they think of using JMS. This is certainly one way to approach the problem in Seam, and
is the right way when you have strict and well-defined quality of service requirements. Seam makes it easy to send and
recieve JMS messages using Seam components. But for many usecases, JMS is overkill. Seam layers a simple asynchronous method
and event facility over your choice of dispatchers:

• java.util.concurrent.ScheduledThreadPoolExecutor (by default)
• the EJB timer service (for EJB 3.0 environments)
• Quartz

Asynchronicity: Asynchronous events and method calls have the same quality of service expectations as the underlying
dispatcher mechanism. The default dispatcher, based upon a ScheduledThreadPoolExecutor performs efficiently but provides no
support for persistent asynchronous tasks, and hence no guarantee that a task will ever actually be executed. If you’re
working in an environment that supports EJB 3.0, and add the following line to components.xml:

<async:timer-service-dispatcher/>

then your asynchronous tasks will be processed by the container’s EJB timer service. If you’re not familiar with the Timer
service, don’t worry, you don’t need to interact with it directly if you want to use asynchronous methods in Seam. The
important thing to know is that any good EJB 3.0 implementation will have the option of using persistent timers, which gives
some guarantee that the tasks will eventually be processed.
Another alternative is to use the open source Quartz library to manage asynchronous method. You need to bundle the Quartz
library JAR (found in the lib directory) in your EAR and declare it as a Java module in application.xml. In addition, you
need to add the following line to components.xml to install the Quartz dispatcher.

<async:quartz-dispatcher/>

The Seam API for the default ScheduledThreadPoolExecutor, the EJB3 Timer, and the Quartz Scheduler are largely the same. They
can just “plug and play” by adding a line to components.xml.

Asynchronous methods: In simplest form, an asynchronous call just lets a method call be processed asynchronously (in a
different thread) from the caller. We usually use an asynchronous call when we want to return an immediate response to the
client, and let some expensive work be processed in the background.
This pattern works very well in applications which use AJAX, where the client can automatically poll the server for the
result of the work.
For EJB components, we annotate the local interface to specify that a method is processed asynchronously.

@Local
public interface PaymentHandler
{
@Asynchronous
public void processPayment(Payment payment);
}

(For JavaBean components we can annotate the component implementation class if we like).

The use of asynchronicity is transparent to the bean class:

@Stateless
@Name(“paymentHandler”)
public class PaymentHandlerBean implements PaymentHandler
{
public void processPayment(Payment payment)
{
//do some work!
}
}

And also transparent to the client:

@Stateful
@Name(“paymentAction”)
public class CreatePaymentAction
{
@In(create=true) PaymentHandler paymentHandler;
@In Bill bill;
public String pay()
{
paymentHandler.processPayment( new Payment(bill) );
return “success”;
}
}

The asynchronous method is processed in a completely new event context and does not have access to the session or
conversation context state of the caller. However, the business process context is propagated. Asynchronous method calls may
be scheduled for later execution using the @Duration, @Expiration and @IntervalDuration annotations.

@Local
public interface PaymentHandler
{
@Asynchronous
public void processScheduledPayment(Payment payment, @Expiration Date date);
@Asynchronous
public void processRecurringPayment(Payment payment,
@Expiration Date date,
@IntervalDuration Long interval)’
}

@Stateful
@Name(“paymentAction”)
public class CreatePaymentAction
{
@In(create=true) PaymentHandler paymentHandler;
@In Bill bill;
public String schedulePayment()
{
paymentHandler.processScheduledPayment( new Payment(bill), bill.getDueDate());
return “success”;
}
public String scheduleRecurringPayment()
{
paymentHandler.processRecurringPayment( new Payment(bill), bill.getDueDate(),ONE_MONTH);
return “success”;
}
}

Both client and server may access the Timer object associated with the invocation. The Timer object shown below is the EJB3
timer when you use the EJB3 dispatcher. For the default ScheduledThreadPoolExecutor, the returned object is Future from the
JDK. For the Quartz dispatcher, it returns QuartzTriggerHandle.

@Local
public interface PaymentHandler
{
@Asynchronous
public Timer processScheduledPayment(Payment payment, @Expiration Date date);
}

@Stateless
@Name(“paymentHandler”)
public class PaymentHandlerBean implements PaymentHandler
{
@In Timer timer;
public Timer processScheduledPayment(Payment payment, @Expiration Date date)
{
//do some work!
return timer; //note that return value is completely ignored
}
}

@Stateful
@Name(“paymentAction”)
public class CreatePaymentAction
{
@In(create=true) PaymentHandler paymentHandler;
@In Bill bill;
public String schedulePayment()
{
Timer timer = paymentHandler.processScheduledPayment( new Payment(bill),
bill.getDueDate() );
return “success”;
}
}

Asynchronous methods cannot return any other value to the caller.

Asynchronous methods with the Quartz Dispatcher: The Quartz dispatcher allows you to use the @Asynchronous, @Duration,
@Expiration, and @IntervalDuration annotations as above. But it has some powerful additional features. The Quartz dispatcher
supports three new annotations. The @FinalExpiration annotation specifies an end date for the recurring task.

// Defines the method in the “processor” component
@Asynchronous
public QuartzTriggerHandle schedulePayment(@Expiration Date when,
@IntervalDuration Long interval,
@FinalExpiration Date endDate,
Payment payment)
{
// do the repeating or long running task until endDate
}

… …

// Schedule the task in the business logic processing code
// Starts now, repeats every hour, and ends on May 10th, 2010
Calendar cal = Calendar.getInstance ();
cal.set (2010, Calendar.MAY, 10);
processor.schedulePayment(new Date(), 60*60*1000, cal.getTime(), payment);

Note that the method returns the QuartzTriggerHandle object, which you can use later to stop, pause, and resume the
scheduler. The QuartzTriggerHandle object is serializable, so you can save it into the database if you need to keep it
around for extended period of time.

QuartzTriggerHandle handle = processor.schedulePayment(payment.getPaymentDate(), payment.getPaymentCron(), payment);
payment.setQuartzTriggerHandle( handle );
// Save payment to DB
// later …
// Retrieve payment from DB
// Cancel the remaining scheduled tasks
payment.getQuartzTriggerHandle().cancel();

The @IntervalCron annotation supports Unix cron job syntax for task scheduling. For instance, the following asynchronous
method runs at 2:10pm and at 2:44pm every Wednesday in the month of March.

// Define the method
@Asynchronous
public QuartzTriggerHandle schedulePayment(@Expiration Date when,
@IntervalCron String cron,
Payment payment)
{
// do the repeating or long running task
}
… …
// Schedule the task in the business logic processing code
QuartzTriggerHandle handle =
processor.schedulePayment(new Date(), “0 10,44 14 ? 3 WED”, payment);

The @IntervalBusinessDay annotation supports invocation on the “nth Business Day” scenario.
For instance, the following asynchronous method runs at 14:00 on the 2nd business day of each
month. By default, it excludes all weekends and US federal holidays until 2010 from the business days.

// Define the method
@Asynchronous
public QuartzTriggerHandle schedulePayment(@Expiration Date when,
@IntervalBusinessDay NthBusinessDay nth,
Payment payment)
{
// do the repeating or long running task
}
… …
// Schedule the task in the business logic processing code
QuartzTriggerHandle handle =
processor.schedulePayment(new Date(),
new NthBusinessDay(2, “14:00″, WEEKLY), payment);

The NthBusinessDay object contains the configuration of the invocation trigger. You can specify
more holidays (e.g., company holidays, non-US holidays etc.) via the additionalHolidays property.

public class NthBusinessDay implements Serializable
{
int n;
String fireAtTime;
List <Date> additionalHolidays;
BusinessDayIntervalType interval;
boolean excludeWeekends;
boolean excludeUsFederalHolidays;
public enum BusinessDayIntervalType { WEEKLY, MONTHLY, YEARLY }
public NthBusinessDay ()
{
n = 1;
fireAtTime = “12:00″;
additionalHolidays = new ArrayList <Date> ();
interval = BusinessDayIntervalType.WEEKLY;
excludeWeekends = true;
excludeUsFederalHolidays = true;
}
… …
}

The @IntervalDuration, @IntervalCron, and @IntervalNthBusinessDay annotations are
mutually exclusive. If they are used in the same method, a RuntimeException will be thrown.

Asynchronous events: Component-driven events may also be asynchronous. To raise an event for asynchronous processing, simply
call the raiseAsynchronousEvent() method of the Events class. To schedule a timed event, call the raiseTimedEvent() method,
passing a schedule object (for the default dispatcher or timer service dispatcher, use TimerSchedule). Components may
observe asynchronous events in the usual way, but remember that only the business process context is propagated to the
asynchronous thread.

Messaging in Seam:
Seam makes it easy to send and receive JMS messages to and from Seam components.

Configuration: To configure Seam’s infrastructure for sending JMS messages, you need to tell Seam about any topics and
queues you want to send messages to, and also tell Seam where to find the QueueConnectionFactory and/or
TopicConnectionFactory. Seam defaults to using UIL2ConnectionFactory which is the usual connection factory for use with
JBossMQ. If you are using some other JMS provider, you need to set one or both of
queueConnection.queueConnectionFactoryJndiName and topicConnection.topicConnectionFactoryJndiName in seam.properties,
web.xml or components.xml.
You also need to list topics and queues in components.xml to install Seam managed TopicPublishers and QueueSenders:

<jms:managed-topic-publisher name=”stockTickerPublisher” auto-create=”true” topic-jndi-name=”topic/stockTickerTopic”/>
<jms:managed-queue-sender name=”paymentQueueSender” auto-create=”true” queue-jndi-name=”queue/paymentQueue”/>

Sending messages:
Now, you can inject a JMS TopicPublisher and TopicSession into any component:

@In
private TopicPublisher stockTickerPublisher;
@In
private TopicSession topicSession;
public void publish(StockPrice price) {
try
{
stockTickerPublisher.publish( topicSession.createObjectMessage(price) );
}
catch (Exception ex)
{
throw new RuntimeException(ex);
}
}

Or, for working with a queue:

@In
private QueueSender paymentQueueSender;
@In
private QueueSession queueSession;
public void publish(Payment payment) {
try
{
paymentQueueSender.send( queueSession.createObjectMessage(payment) );
}
catch (Exception ex)
{
throw new RuntimeException(ex);
}
}

Receiving messages using a message-driven bean: You can process messages using any EJB3 message driven bean. Message-driven
beans may even be Seam components, in which case it is possible to inject other event and application scoped Seam components.

Receiving messages in the client: Seam Remoting lets you subscribe to a JMS topic from client-side JavaScript.
This is described in the Remoting section.

Caching: A well designed Seam application will feature a rich, multi-layered caching strategy that impacts every layer of
the application:

• The database, of course, has its own cache. This is super-important, but can’t scale like a cache in the application tier.
• Your ORM solution (Hibernate, or some other JPA implementation) has a second-level cache of data from the database. This is
a very powerful capability, but is often misused. In a clustered environment, keeping the data in the cache transactionally
consistent across the whole cluster, and with the database, is quite expensive. It makes most sense for data which is shared
between many users, and is updated rarely. In traditional stateless architectures, people often try to use the second-level
cache for conversational state. This is always bad, and is especially wrong in Seam.

• The Seam conversation context is a cache of conversational state. Components you put into the conversation context can hold
and cache state relating to the current user interaction.

• In particular, the Seam-managed persistence context (or an extended EJB container-managed persistence context associated
with a conversation-scoped stateful session bean) acts as a cache of data that has been read in the current conversation.
This cache tends to have a pretty high hitrate! Seam optimizes the replication of Seam-managed persistence contexts in a
clustered environment, and there is no requirement for transactional consistency with the database (optimistic locking is
sufficient) so you don’t need to worry too much about the performance implications of this cache, unless you read thousands
of objects into a single persistence context.

• The application can cache non-transactional state in the Seam application context. State kept in the application context
is of course not visible to other nodes in the cluster.

• The application can cache transactional state using the Seam pojoCache component, which integrates JBossCache into the
Seam environment. This state will be visible to other nodes if you run JBoss cache in a clustered mode.

• Finally, Seam lets you cache rendered fragments of a JSF page. Unlike the ORM second-level cache, this cache is not
automatically invalidated when data changes, so you need to write application code to perform explicit invalidation, or set
appropriate expiration policies.

For more information about the second-level cache, you’ll need to refer to the documentation of your ORM solution, since
this is an extremely complex topic. In this section we’ll discuss the use of JBossCache directly, via the pojoCache
component, or as the page fragment cache, via the <s:cache> control.

Using JBossCache in Seam: The built-in pojoCache component manages an instance of org.jboss.cache.aop.PojoCache.
You can safely put any immutable Java object in the cache, and it will be replicated across the cluster (assuming that
replication is enabled). If you want to keep mutable objects in the cache, you’ll need to run the JBossCache bytecode
preprocessor to ensure that changes to the objects will be automatically detected and replicated.
To use pojoCache, all you need to do is put the JBossCache jars in the classpath, and provide a resource named treecache.xml
with an appropriate cache configuration. JBossCache has many scary and confusing configuration settings, so we won’t discuss
them here. Please refer to the JBossCache documentation for more information.

You can find a sample treecache.xml in examples/blog/resources/treecache.xml. For an EAR depoyment of Seam, we recommend
that the JBossCache jars and configuration go directly into the EAR. Make sure you place both jboss-cache.jar and
jgroups.jar in your EAR’s lib folder. Now you can inject the cache into any Seam component:

@Name(“chatroom”)
public class Chatroom {
@In PojoCache pojoCache;
public void join(String username) {
try
{
Set<String> userList = (Set<String>) pojoCache.get(“chatroom”, “userList”);
if (userList==null)
{
userList = new HashSet<String>();
pojoCache.put(“chatroom”, “userList”, userList);
}
userList.put(username);
}
catch (CacheException ce)
{
throw new RuntimeException(ce);
}
}
}

If you want to have multiple JBossCache configurations in your application, use components.xml:

<core:pojo-cache name=”myCache” cfg-resource-name=”myown/cache.xml”/>

Page fragment caching: The most interesting user of JBossCache is the <s:cache> tag, Seam’s solution to the problem
of page fragment caching in JSF. <s:cache> uses pojoCache internally, so you need to follow the steps listed above before
you can use it. (Put the jars in the EAR, wade through the scary configuration options, etc).

<s:cache> is used for caching some rendered content which changes rarely. For example, the welcome page of our blog displays
the recent blog entries:

<s:cache key=”recentEntries-#{blog.id}” region=”welcomePageFragments”>
<h:dataTable value=”#{blog.recentEntries}” var=”blogEntry”>
<h:column>
<h3>#{blogEntry.title}</h3>
<div>
<s:formattedText value=”#{blogEntry.body}”/>
</div>
</h:column>
</h:dataTable>
</s:cache>

The key let’s you have multiple cached versions of each page fragment. In this case, there is one cached version per blog.
The region determines the JBossCache node that all version will be stored in. Different nodes may have different expiry
policies. (That’s the stuff you set up using the aforementioned scary configuration options).

Of course, the big problem with <s:cache> is that it is too stupid to know when the underlying data changes (for example,
when the blogger posts a new entry). So you need to evict the cached fragment manually:

public void post() {
…
entityManager.persist(blogEntry);
pojoCache.remove(“welcomePageFragments”, “recentEntries-” + blog.getId() );
}

Alternatively, if it is not critical that changes are immediately visible to the user, you could set a short expiry time on
the JbossCache node.

Web Services: Seam integrates with JBossWS to allow standard JEE web services to take full advantage of
Seam’s contextual framework, including support for conversational web services. This chapter
walks through the steps required to allow web services to run within a Seam environment.

Configuration and Packaging: To allow Seam to intercept web service requests so that the necessary Seam
contexts can be created for the request, a special SOAP handler must be configured;
org.jboss.seam.webservice.SOAPRequestHandler is a SOAPHandler implementation that
does the work of managing Seam’s lifecycle during the scope of a web service request.

A special configuration file, standard-jaxws-endpoint-config.xml should be placed into the
META-INF directory of the jar file that contains the web service classes. This file contains the
following SOAP handler configuration:

<jaxws-config xmlns=”urn:jboss:jaxws-config:2.0″
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xmlns:javaee=”http://java.sun.com/xml/ns/javaee”
xsi:schemaLocation=”urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd”>
<endpoint-config>
<config-name>Seam WebService Endpoint</config-name>
<pre-handler-chains>
<javaee:handler-chain>
<javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
<javaee:handler>
<javaee:handler-name>SOAP Request Handler</javaee:handler-name>
<javaee:handler-class>org.jboss.seam.webservice.SOAPRequestHandler</
javaee:handler-class>
</javaee:handler>
</javaee:handler-chain>
</pre-handler-chains>
</endpoint-config>
</jaxws-config>

Conversational Web Services: So how are conversations propagated between web service requests? Seam uses a SOAP header
element present in both the SOAP request and response messages to carry the conversation ID
from the consumer to the service, and back again. Here’s an example of a web service request
that contains a conversation ID:

<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”
xmlns:seam=”http://seambay.example.seam.jboss.org/”>
<soapenv:Header>
<seam:conversationId xmlns:seam=’http://www.jboss.org/seam/webservice’>2</
seam:conversationId>
</soapenv:Header>
<soapenv:Body>
<seam:confirmAuction/>
</soapenv:Body>
</soapenv:Envelope>

As you can see in the above SOAP message, there is a conversationId element within the
SOAP header that contains the conversation ID for the request, in this case 2. Unfortunately,
because web services may be consumed by a variety of web service clients written in a variety of
languages, it is up to the developer to implement conversation ID propagation between individual
web services that are intended to be used within the scope of a single conversation.

An important thing to note is that the conversationId header element must be qualified with a
namespace of http://www.jboss.org/seam/webservice, otherwise Seam will not be able to
read the conversation ID from the request. Here’s an example of a response to the above request
message:

<env:Envelope xmlns:env=’http://schemas.xmlsoap.org/soap/envelope/’>
<env:Header>
<seam:conversationId xmlns:seam=’http://www.jboss.org/seam/webservice’>2</
seam:conversationId>
</env:Header>
<env:Body>
<confirmAuctionResponse xmlns=”http://seambay.example.seam.jboss.org/”/>
</env:Body>
</env:Envelope>

As you can see, the response message contains the same conversationId element as the request.

A Recommended Strategy: As web services must be implemented as either a stateless session bean or POJO, it is recommended
that for conversational web services, the web service acts as a facade to a conversational Seam component.

If the web service is written as a stateless session bean, then it is also possible to make it a Seam
component by giving it a @Name. Doing this allows Seam’s bijection (and other) features to be used
in the web service class itself.

An example web service: Let’s walk through an example web service. The code in this section all comes from the seamBay
example application in Seam’s /examples directory, and follows the recommended strategy as
described in the previous section. Let’s first take a look at the web service class and one of its
web service methods:

@Stateless
@WebService(name = “AuctionService”, serviceName = “AuctionService”)
public class AuctionService implements AuctionServiceRemote
{
@WebMethod
public boolean login(String username, String password)
{
Identity.instance().setUsername(username);
Identity.instance().setPassword(password);
Identity.instance().login();
return Identity.instance().isLoggedIn();
}
// snip
}

As you can see, our web service is a stateless session bean, and is annotated using the JWS
annotations from the javax.jws package, as defined by JSR-181. The @WebService annotation
tells the container that this class implements a web service, and the @WebMethod annotation on
the login() method identifies the method as a web service method. The name and serviceName
attributes in the @WebService annotation are optional.
As is required by the specification, each method that is to be exposed as a web service method
must also be declared in the remote interface of the web service class (when the web service
is a stateless session bean). In the above example, the AuctionServiceRemote interface must
declare the login() method as it is annotated as a @WebMethod.
As you can see in the above code, the web service implements a login() method that delegates
to Seam’s built-in Identity component. In keeping with our recommended strategy, the web
service is written as a simple facade, passing off the real work to a Seam component. This allows
for the greatest reuse of business logic between web services and other clients.
Let’s look at another example. This web service method begins a new conversation by delegating
to the AuctionAction.createAuction() method:

@WebMethod
public void createAuction(String title, String description, int categoryId)
{
AuctionAction action = (AuctionAction) Component.getInstance(AuctionAction.class, true);
action.createAuction();
action.setDetails(title, description, categoryId);
}

And here’s the code from AuctionAction:

@Begin
public void createAuction()
{
auction = new Auction();
auction.setAccount(authenticatedAccount);
auction.setStatus(Auction.STATUS_UNLISTED);
durationDays = DEFAULT_AUCTION_DURATION;
}

From this we can see how web services can participate in long running conversations, by acting
as a facade and delegating the real work to a conversational Seam component.

Remoting: Seam provides a convenient method of remotely accessing components from a web page, using
AJAX (Asynchronous Javascript and XML). The framework for this functionality is provided with
almost no up-front development effort – your components only require simple annotating to
become accessible via AJAX. This chapter describes the steps required to build an AJAX-enabled
web page, then goes on to explain the features of the Seam Remoting framework in more detail.

Configuration: To use remoting, the Seam Resource servlet must first be configured in your web.xml file:

<servlet>
<servlet-name>Seam Resource Servlet</servlet-name>
<servlet-class>org.jboss.seam.servlet.SeamResourceServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Seam Resource Servlet</servlet-name>
<url-pattern>/seam/resource/*</url-pattern>
</servlet-mapping>

The next step is to import the necessary Javascript into your web page. There are a minimum of two scripts that must be
imported. The first one contains all the client-side framework code that enables remoting functionality:

<script type=”text/javascript” src=”seam/resource/remoting/resource/remote.js”></script>

The second script contains the stubs and type definitions for the components you wish to call.
It is generated dynamically based on the local interface of your components, and includes type
definitions for all of the classes that can be used to call the remotable methods of the interface.
The name of the script reflects the name of your component. For example, if you have a stateless
session bean annotated with @Name(“customerAction”), then your script tag should look like this:

<script type=”text/javascript”
src=”seam/resource/remoting/interface.js?customerAction”></script>

If you wish to access more than one component from the same page, then include them all as
parameters of your script tag:

<script type=”text/javascript”
src=”seam/resource/remoting/interface.js?customerAction&accountAction”></script>

Alternatively, you may use the s:remote tag to import the required Javascript. Separate each
component or class name you wish to import with a comma:

<s:remote include=”customerAction,accountAction”/>

The “Seam” object: Client-side interaction with your components is all performed via the Seam Javascript object.
This object is defined in remote.js, and you’ll be using it to make asynchronous calls against
your component. It is split into two areas of functionality; Seam.Component contains methods for
working with components and Seam.Remoting contains methods for executing remote requests.
The easiest way to become familiar with this object is to start with a simple example.
A Hello World example:
Let’s step through a simple example to see how the Seam object works. First of all, let’s create a
new Seam component called helloAction.

@Stateless
@Name(“helloAction”)
public class HelloAction implements HelloLocal {
public String sayHello(String name) {
return “Hello, ” + name;
}
}
You also need to create a local interface for our new component – take special note of the
@WebRemote annotation, as it’s required to make our method accessible via remoting:
@Local
public interface HelloLocal {
@WebRemote
public String sayHello(String name);
}

That’s all the server-side code we need to write. Now for our web page – create a new page and
import the helloAction component:

<s:remote include=”helloAction”/>

To make this a fully interactive user experience, let’s add a button to our page:
<button onclick=”javascript:sayHello()”>Say Hello</button>
We’ll also need to add some more script to make our button actually do something when it’s clicked:

<script type=”text/javascript”>
//<![CDATA[
function sayHello() {
var name = prompt("What is your name?");
Seam.Component.getInstance("helloAction").sayHello(name, sayHelloCallback);
}
function sayHelloCallback(result) {
alert(result);
}
// ]]>
</script>

We’re done! Deploy your application and browse to your page. Click the button, and enter a
name when prompted. A message box will display the hello message confirming that the call was
successful. If you want to save some time, you’ll find the full source code for this Hello World
example in Seam’s /examples/remoting/helloworld directory.
So what does the code of our script actually do? Let’s break it down into smaller pieces. To start
with, you can see from the Javascript code listing that we have implemented two methods – the first
method is responsible for prompting the user for their name and then making a remote request.
Take a look at the following line:
Seam.Component.getInstance(“helloAction”).sayHello(name, sayHelloCallback);
The first section of this line, Seam.Component.getInstance(“helloAction”) returns a proxy,
or “stub” for our helloAction component. We can invoke the methods of our component against this stub, which is exactly what
happens with the remainder of the line: sayHello(name, sayHelloCallback);.
What this line of code in its completeness does, is invoke the sayHello method of our component,
passing in name as a parameter. The second parameter, sayHelloCallback isn’t a parameter
of our component’s sayHello method, instead it tells the Seam Remoting framework that once
it receives the response to our request, it should pass it to the sayHelloCallback Javascript
method. This callback parameter is entirely optional, so feel free to leave it out if you’re calling a
method with a void return type or if you don’t care about the result.
The sayHelloCallback method, once receiving the response to our remote request then pops
up an alert message displaying the result of our method call.

Seam.Component: The Seam.Component Javascript object provides a number of client-side methods for working
with your Seam components. The two main methods, newInstance() and getInstance() are
documented in the following sections however their main difference is that newInstance() will
always create a new instance of a component type, and getInstance() will return a singleton
instance.
Seam.Component.newInstance():
Use this method to create a new instance of an entity or Javabean component. The object
returned by this method will have the same getter/setter methods as its server-side counterpart,
or alternatively if you wish you can access its fields directly. Take the following Seam entity
component for example:

@Name(“customer”)
@Entity
public class Customer implements Serializable
{
private Integer customerId;
private String firstName;
private String lastName;
@Column public Integer getCustomerId() {
return customerId;
}
public void setCustomerId(Integer customerId} {
this.customerId = customerId;
}
@Column public String getFirstName() {
return firstName;
}
public void setFirstName(String firstName) {
this.firstName = firstName;
}
@Column public String getLastName() {
return lastName;
}
public void setLastName(String lastName) {
this.lastName = lastName;
}
}

To create a client-side Customer you would write the following code:

var customer = Seam.Component.newInstance(“customer”);

Then from here you can set the fields of the customer object:

customer.setFirstName(“John”);
// Or you can set the fields directly
customer.lastName = “Smith”;

Seam.Component.getInstance(): The getInstance() method is used to get a reference to a Seam session bean component stub,
which can then be used to remotely execute methods against your component. This method
returns a singleton for the specified component, so calling it twice in a row with the same
component name will return the same instance of the component.
To continue our example from before, if we have created a new customer and we now wish to
save it, we would pass it to the saveCustomer() method of our customerAction component:

Seam.Component.getInstance(“customerAction”).saveCustomer(customer);

Seam.Component.getComponentName(): Passing an object into this method will return its component name if it is a component,
or null if it is not.

if (Seam.Component.getComponentName(instance) == “customer”)
alert(“Customer”);
else if (Seam.Component.getComponentName(instance) == “staff”)
alert(“Staff member”);

Seam.Remoting:
Most of the client side functionality for Seam Remoting is contained within the Seam.Remoting
object. While you shouldn’t need to directly call most of its methods, there are a couple of important
ones worth mentioning.
Seam.Remoting.createType():
If your application contains or uses Javabean classes that aren’t Seam components, you may
need to create these types on the client side to pass as parameters into your component method.
Use the createType() method to create an instance of your type. Pass in the fully qualified Java
class name as a parameter:

var widget = Seam.Remoting.createType(“com.acme.widgets.MyWidget”);

Seam.Remoting.getTypeName():
This method is the equivalent of Seam.Component.getComponentName() but for non-component
types. It will return the name of the type for an object instance, or null if the type is not known.
The name is the fully qualified name of the type’s Java class.

Evaluating EL Expressions:
Seam Remoting also supports the evaluation of EL expressions, which provides another
convenient method for retrieving data from the server. Using the Seam.Remoting.eval() function,
an EL expression can be remotely evaluated on the server and the resulting value returned
to a client-side callback method. This function accepts two parameters, the first being the EL
expression to evaluate, and the second being the callback method to invoke with the value of the
expression. Here’s an example:

function customersCallback(customers) {
for (var i = 0; i < customers.length; i++) {
alert(“Got customer: ” + customers[i].getName());
}
}
Seam.Remoting.eval(“#{customers}”, customersCallback);

In this example, the expression #{customers} is evaluated by Seam, and the value of the
expression (in this case a list of Customer objects) is returned to the customersCallback()
method. It is important to remember that the objects returned this way must have their types
imported (via s:remote) to be able to work with them in Javascript. So to work with a list of
customer objects, it is required to import the customer type:

<s:remote include=”customer”/>

Client Interfaces: In the configuration section above, the interface, or “stub” for our component is imported into our
page either via seam/resource/remoting/interface.js: or using the s:remote tag:

<script type=”text/javascript”
src=”seam/resource/remoting/interface.js?customerAction”></script>
<s:remote include=”customerAction”/>

By including this script in our page, the interface definitions for our component, plus any other
components or types that are required to execute the methods of our component are generated
and made available for the remoting framework to use.
There are two types of client stub that can be generated, “executable” stubs and “type” stubs.
Executable stubs are behavioural, and are used to execute methods against your session bean
components, while type stubs contain state and represent the types that can be passed in as
parameters or returned as a result.
The type of client stub that is generated depends on the type of your Seam component. If the
component is a session bean, then an executable stub will be generated, otherwise if it’s an
entity or JavaBean, then a type stub will be generated. There is one exception to this rule; if your
component is a JavaBean (ie it is not a session bean nor an entity bean) and any of its methods
are annotated with @WebRemote, then an executable stub will be generated for it instead of a
type stub. This allows you to use remoting to call methods of your JavaBean components in a
non-EJB environment where you don’t have access to session beans.

The Context:
The Seam Remoting Context contains additional information which is sent and received as part
of a remoting request/response cycle. At this stage it only contains the conversation ID but may
be expanded in the future.

Setting and reading the Conversation ID:
If you intend on using remote calls within the scope of a conversation then
you need to be able to read or set the conversation ID in the Seam
Remoting Context. To read the conversation ID after making a remote request call
Seam.Remoting.getContext().getConversationId(). To set the conversation ID before
making a request, call Seam.Remoting.getContext().setConversationId().
If the conversation ID hasn’t been explicitly set with
Seam.Remoting.getContext().setConversationId(), then it will be automatically assigned
the first valid conversation ID that is returned by any remoting call. If you are working with multiple
conversations within your page, then you may need to explicitly set the conversation ID before
each call. If you are working with just a single conversation, then you don’t need to do anything
special.

Remote calls within the current conversation scope:
In some circumstances it may be required to make a remote call within the scope of the current
view’s conversation. To do this, you must explicitly set the conversation ID to that of the view
before making the remote call. This small snippet of JavaScript will set the conversation ID that
is used for remoting calls to the current view’s conversation ID:
Seam.Remoting.getContext().setConversationId( #{conversation.id} );

Batch Requests:
Seam Remoting allows multiple component calls to be executed within a single request. It is
recommended that this feature is used wherever it is appropriate to reduce network traffic.
The method Seam.Remoting.startBatch() will start a new batch, and any component calls
executed after starting a batch are queued, rather than being sent immediately. When all the
desired component calls have been added to the batch, the Seam.Remoting.executeBatch()
method will send a single request containing all of the queued calls to the server, where they will
be executed in order. After the calls have been executed, a single response containining all return
values will be returned to the client and the callback functions (if provided) triggered in the same
order as execution.
If you start a new batch via the startBatch() method but then decide you don’t want to send
it, the Seam.Remoting.cancelBatch() method will discard any calls that were queued and exit
the batch mode.
To see an example of a batch being used, take a look at /examples/remoting/chatroom.

Working with Data types: Primitives / Basic Types:
This section describes the support for basic data types. On the server side these values are
generally compatible with either their primitive type or their corresponding wrapper class.
String:
Simply use Javascript String objects when setting String parameter values.
Number:
There is support for all number types supported by Java. On the client side, number values are
always serialized as their String representation and then on the server side they are converted
to the correct destination type. Conversion into either a primitive or wrapper type is supported for
Byte, Double, Float, Integer, Long and Short types.
Boolean:
Booleans are represented client side by Javascript Boolean values, and server side by a Java
boolean.
JavaBeans:
In general these will be either Seam entity or JavaBean components, or some other noncomponent
class. Use the appropriate method (either Seam.Component.newInstance() for Seam
components or Seam.Remoting.createType() for everything else) to create a new instance of
the object.
It is important to note that only objects that are created by either of these two methods should
be used as parameter values, where the parameter is not one of the other valid types mentioned
anywhere else in this section. In some situations you may have a component method where the
exact parameter type cannot be determined, such as:
@Name(“myAction”)
public class MyAction implements MyActionLocal {
public void doSomethingWithObject(Object obj) {
// code
}
}

In this case you might want to pass in an instance of your myWidget component, however the
interface for myAction won’t include myWidget as it is not directly referenced by any of its methods.
To get around this, MyWidget needs to be explicitly imported:

<s:remote include=”myAction,myWidget”/>

This will then allow a myWidget object to be created with
Seam.Component.newInstance(“myWidget”), which can then be passed to myAction.doSomethingWithObject().

Dates and Times:
Date values are serialized into a String representation that is accurate to the millisecond. On the
client side, use a Javascript Date object to work with date values. On the server side, use any
java.util.Date (or descendent, such as java.sql.Date or java.sql.Timestamp class.
Enums:
On the client side, enums are treated the same as Strings. When setting the value for an enum
parameter, simply use the String representation of the enum. Take the following component as
an example:

@Name(“paintAction”)
public class paintAction implements paintLocal {
public enum Color {red, green, blue, yellow, orange, purple};
public void paint(Color color) {
// code
}
}

To call the paint() method with the color red, pass the parameter value as a String literal:
Seam.Component.getInstance(“paintAction”).paint(“red”);
The inverse is also true – that is, if a component method returns an enum parameter (or contains
an enum field anywhere in the returned object graph) then on the client-side it will be represented as a String.

Collections:
Bags:
Bags cover all collection types including arrays, collections, lists, sets, (but excluding Maps – see
the next section for those), and are implemented client-side as a Javascript array. When calling a
component method that accepts one of these types as a parameter, your parameter should be a
Javascript array. If a component method returns one of these types, then the return value will also
be a Javascript array. The remoting framework is clever enough on the server side to convert the
bag to an appropriate type for the component method call.
Maps:
As there is no native support for Maps within Javascript, a simple Map implementation is provided
with the Seam Remoting framework. To create a Map which can be used as a parameter to a
remote call, create a new Seam.Remoting.Map object:

var map = new Seam.Remoting.Map();

This Javascript implementation provides basic methods for working with Maps: size(),
isEmpty(), keySet(), values(), get(key), put(key, value), remove(key) and
contains(key). Each of these methods are equivalent to their Java counterpart. Where the
method returns a collection, such as keySet() and values(), a Javascript Array object will be
returned that contains the key or value objects (respectively).
Debugging:
To aid in tracking down bugs, it is possible to enable a debug mode which will display the contents
of all the packets send back and forth between the client and server in a popup window. To enable
debug mode, either execute the setDebug() method in Javascript:

Seam.Remoting.setDebug(true);

Or configure it via components.xml:

<remoting:remoting debug=”true”/>

To turn off debugging, call setDebug(false). If you want to write your own messages to the
debug log, call Seam.Remoting.log(message).

The Loading Message:
The default loading message that appears in the top right corner of the screen can be modified,
its rendering customised or even turned off completely.
Changing the message:
To change the message from the default “Please Wait…” to something different, set the value of
Seam.Remoting.loadingMessage:
Seam.Remoting.loadingMessage = “Loading…”;
Hiding the loading message:
To completely suppress the display of the loading message, override the implementation of
displayLoadingMessage() and hideLoadingMessage() with functions that instead do nothing:
// don’t display the loading indicator
Seam.Remoting.displayLoadingMessage = function() {};
Seam.Remoting.hideLoadingMessage = function() {};
A Custom Loading Indicator:
It is also possible to override the loading indicator to display an animated icon, or anything else
that you want. To do this override the displayLoadingMessage() and hideLoadingMessage()
messages with your own implementation:
Seam.Remoting.displayLoadingMessage = function() {
// Write code here to display the indicator
};
Seam.Remoting.hideLoadingMessage = function() {
// Write code here to hide the indicator
};

Controlling what data is returned:
When a remote method is executed, the result is serialized into an XML response that is returned
to the client. This response is then unmarshaled by the client into a Javascript object. For
complex types (i.e. Javabeans) that include references to other objects, all of these referenced
objects are also serialized as part of the response. These objects may reference other objects,
which may reference other objects, and so forth. If left unchecked, this object “graph” could
potentially be enormous, depending on what relationships exist between your objects. And as
a side issue (besides the potential verbosity of the response), you might also wish to prevent
sensitive information from being exposed to the client.
Seam Remoting provides a simple means to “constrain” the object graph, by specifying the
exclude field of the remote method’s @WebRemote annotation. This field accepts a String array
containing one or more paths specified using dot notation. When invoking a remote method, the
objects in the result’s object graph that match these paths are excluded from the serialized result packet.
For all our examples, we’ll use the following Widget class:

@Name(“widget”)
public class Widget
{
private String value;
private String secret;
private Widget child;
private Map<String,Widget> widgetMap;
private List<Widget> widgetList;
// getters and setters for all fields
}

Constraining normal fields: If your remote method returns an instance of Widget, but you don’t want to expose the secret
field because it contains sensitive information, you would constrain it like this:

@WebRemote(exclude = {“secret”})
public Widget getWidget();

The value “secret” refers to the secret field of the returned object. Now, suppose that we don’t
care about exposing this particular field to the client. Instead, notice that the Widget value that
is returned has a field child that is also a Widget. What if we want to hide the child’s secret
value instead? We can do this by using dot notation to specify this field’s path within the result’s
object graph:

@WebRemote(exclude = {“child.secret”})
public Widget getWidget();

Constraining Maps and Collections
The other place that objects can exist within an object graph are within a Map or some kind of
collection (List, Set, Array, etc). Collections are easy, and are treated like any other field. For
example, if our Widget contained a list of other Widgets in its widgetList field, to constrain the
secret field of the Widgets in this list the annotation would look like this:

@WebRemote(exclude = {“widgetList.secret”})
public Widget getWidget();

To constrain a Map’s key or value, the notation is slightly different. Appending [key] after the Map’s
field name will constrain the Map’s key object values, while [value] will constrain the value object
values. The following example demonstrates how the values of the widgetMap field have their
secret field constrained:

@WebRemote(exclude = {“widgetMap[value].secret”})
public Widget getWidget();

Constraining objects of a specific type:
There is one last notation that can be used to constrain the fields of a type of object no matter
where in the result’s object graph it appears. This notation uses either the name of the component
(if the object is a Seam component) or the fully qualified class name (only if the object is not a
Seam component) and is expressed using square brackets:

@WebRemote(exclude = {“[widget].secret”})
public Widget getWidget();

Combining Constraints:
Constraints can also be combined, to filter objects from multiple paths within the object graph:

@WebRemote(exclude = {“widgetList.secret”, “widgetMap[value].secret”})

public Widget getWidget();

JMS Messaging:
Seam Remoting provides experimental support for JMS Messaging. This section describes the
JMS support that is currently implemented, but please note that this may change in the future. It
is currently not recommended that this feature is used within a production environment.
Configuration:
Before you can subscribe to a JMS topic, you must first configure a list
of the topics that can be subscribed to by Seam Remoting. List the topics
under org.jboss.seam.remoting.messaging.subscriptionRegistry.allowedTopics in
seam.properties, web.xml or components.xml.

<remoting:remoting poll-timeout=”5″ poll-interval=”1″/>

Subscribing to a JMS Topic:
The following example demonstrates how to subscribe to a JMS Topic:

function subscriptionCallback(message)
{
if (message instanceof Seam.Remoting.TextMessage)
alert(“Received message: ” + message.getText());
}
Seam.Remoting.subscribe(“topicName”, subscriptionCallback);

The Seam.Remoting.subscribe() method accepts two parameters, the first being the name of
the JMS Topic to subscribe to, the second being the callback function to invoke when a message is received.
There are two types of messages supported, Text messages and Object messages. If you
need to test for the type of message that is passed to your callback function you can use
the instanceof operator to test whether the message is a Seam.Remoting.TextMessage or
Seam.Remoting.ObjectMessage. A TextMessage contains the text value in its text field (or
alternatively call getText() on it), while an ObjectMessage contains its object value in its value
field (or call its getValue() method).

Unsubscribing from a Topic
To unsubscribe from a topic, call Seam.Remoting.unsubscribe() and pass in the topic name:

Seam.Remoting.unsubscribe(“topicName”);

Tuning the Polling Process:
There are two parameters which you can modify to control how polling occurs. The first one is
Seam.Remoting.pollInterval, which controls how long to wait between subsequent polls for
new messages. This parameter is expressed in seconds, and its default setting is 10.
The second parameter is Seam.Remoting.pollTimeout, and is also expressed as seconds. It
controls how long a request to the server should wait for a new message before timing out and
sending an empty response. Its default is 0 seconds, which means that when the server is polled,
if there are no messages ready for delivery then an empty response will be immediately returned.
Caution should be used when setting a high pollTimeout value; each request that has to wait for
a message means that a server thread is tied up until a message is received, or until the request
times out. If many such requests are being served simultaneously, it could mean a large number
of threads become tied up because of this reason.
It is recommended that you set these options via components.xml, however they can be overridden
via Javascript if desired. The following example demonstrates how to configure the polling to occur
much more aggressively. You should set these parameters to suitable values for your application:
Via components.xml:

<remoting:remoting poll-timeout=”5″ poll-interval=”1″/>

Via JavaScript:

// Only wait 1 second between receiving a poll response and sending the next poll request.
Seam.Remoting.pollInterval = 1;

// Wait up to 5 seconds on the server for new messages
Seam.Remoting.pollTimeout = 5;

Seam and the Google Web Toolkit: To use GWT in our applications, we need to install Seam resource servlet.

Spring Framework integration:

Hibernate Search:
Configuration:
Hibernate Search is configured either in the META-INF/persistence.xml or hibernate.cfg.xml
file. Hibernate Search configuration has sensible defaults for most configuration parameters. Here is
a minimal persistence unit configuration to get started.

<persistence-unit name=”sample”>
<jta-data-source>java:/DefaultDS</jta-data-source>
<properties>
[...]
<!– use a file system based index –>
<property name=”hibernate.search.default.directory_provider”
value=”org.hibernate.search.store.FSDirectoryProvider”/>
<!– directory where the indexes will be stored –>
<property name=”hibernate.search.default.indexBase”
value=”/Users/prod/apps/dvdstore/dvdindexes”/>
</properties>
</persistence-unit>

If you plan to target Hibernate Annotations or EntityManager 3.2.x (embedded into JBoss AS 4.2.GA), you also need to
configure the appropriate event listeners.

<persistence-unit name=”sample”>
<jta-data-source>java:/DefaultDS</jta-data-source>
<properties>
[...]
<!– use a file system based index –>
<property name=”hibernate.search.default.directory_provider”
value=”org.hibernate.search.store.FSDirectoryProvider”/>
<!– directory where the indexes will be stored –>
<property name=”hibernate.search.default.indexBase”
value=”/Users/prod/apps/dvdstore/dvdindexes”/>
<property name=”hibernate.ejb.event.post-insert”
value=”org.hibernate.search.event.FullTextIndexEventListener”/>
<property name=”hibernate.ejb.event.post-update”
value=”org.hibernate.search.event.FullTextIndexEventListener”/>
<property name=”hibernate.ejb.event.post-delete”
value=”org.hibernate.search.event.FullTextIndexEventListener”/>
</properties>
</persistence-unit>

This step is no longer necessary if Hibernate Annotation or EntityManager 3.3.x are used.

In addition to the configuration file, the following jars have to be deployed:
• hibernate-search.jar
• hibernate-commons-annotations.jar
• lucene-core.jar

If you deploy those in a EAR, don’t forget to update application.xml.

Usage
Hibernate Search uses annotations to map entities to a Lucene index, check the reference
documentation [http://www.hibernate.org/hib_docs/search/reference/en/html_single/] for more
informations.
Hibernate Search is fully integrated with the API and semantic of JPA / Hibernate. Switching from
a HQL or Criteria based query requires just a few lines of code. The main API the application
interacts with is the FullTextSession API (subclass of Hibernate’s Session).
When Hibernate Search is present, JBoss Seam injects a FullTextSession.

@Stateful
@Name(“search”)
public class FullTextSearchAction implements FullTextSearch, Serializable {
@In FullTextSession session;
public void search(String searchString) {
org.apache.lucene.query.Query luceneQuery = getLuceneQuery();
org.hibernate.Query query session.createFullTextQuery(luceneQuery, Product.class);
searchResults = query
.setMaxResults(pageSize + 1)
.setFirstResult(pageSize * currentPage)
.list();
}
[...]
}

FullTextSession extends org.hibernate.Session so that it can be used as a regular Hibernate Session.

If the Java Persistence API is used, a smoother integration is proposed.

@Stateful
@Name(“search”)
public class FullTextSearchAction implements FullTextSearch, Serializable {
@In FullTextEntityManager em;
public void search(String searchString) {
org.apache.lucene.query.Query luceneQuery = getLuceneQuery();
javax.persistence.Query query = em.createFullTextQuery(luceneQuery, Product.class);
searchResults = query
.setMaxResults(pageSize + 1)
.setFirstResult(pageSize * currentPage)
.getResultList();
}
[...]
}

When Hibernate Search is present, a FulltextEntityManager is injected.
FullTextEntityManager extends EntityManager with search specific methods, the same way
FullTextSession extends Session.
When an EJB 3.0 Session or Message Driven Bean injection is used (i.e. via the
@PersistenceContext annotation), it is not possible to replace the EntityManager interface by
the FullTextEntityManager interface in the declaration statement. However, the implementation
injected will be a FullTextEntityManager implementation: downcasting is then possible.

@Stateful
@Name(“search”)
public class FullTextSearchAction implements FullTextSearch, Serializable {
@PersistenceContext EntityManager em;
public void search(String searchString) {
org.apache.lucene.query.Query luceneQuery = getLuceneQuery();
FullTextEntityManager ftEm = (FullTextEntityManager) em;
javax.persistence.Query query = ftEm.createFullTextQuery(luceneQuery, Product.class);
searchResults = query
.setMaxResults(pageSize + 1)
.setFirstResult(pageSize * currentPage)
.getResultList();
}
[...]
}

For people accustomed to Hibernate Search out of Seam, note that using Search.createFullTextSession is not necessary.

Check the DVDStore or the blog examples of the JBoss Seam distribution for a concrete use of Hibernate Search.

Configuring Seam and packaging Seam applications:
Basic Seam configuration:
First, let’s look at the basic configuration that is needed whenever we use Seam with JSF.

Integrating Seam with JSF and your servlet container:
Of course, you need a faces servlet!

<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>

In addition, Seam requires the following entry in your web.xml file:

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

This listener is responsible for bootstrapping Seam, and for destroying session and application contexts.
Some JSF implementations have a broken implementation of server-side state saving that interferes with Seam’s conversation
propagation. If you have problems with conversation propagation during form submissions, try switching to client-side state
saving. You’ll need this in web.xml:

<context-param>
<param-name>javax.faces.STATE_SAVING_METHOD</param-name>
<param-value>client</param-value>
</context-param>

Using facelets:

If you want follow our advice and use facelets instead of JSP, add the following lines to facesconfig.xml:

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

And the following lines to web.xml:

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

Seam Resource Servlet: The Seam Resource Servlet provides resources used by Seam Remoting, captchas (see the
security chapter) and some JSF UI controls. Configuring the Seam Resource Servlet requires the following entry in web.xml:

<servlet>
<servlet-name>Seam Resource Servlet</servlet-name>
<servlet-class>org.jboss.seam.servlet.SeamResourceServlet</servlet-class>
</servlet>

<servlet-mapping>
<servlet-name>Seam Resource Servlet</servlet-name>
<url-pattern>/seam/resource/*</url-pattern>
</servlet-mapping>

Seam servlet filters:
Seam doesn’t need any servlet filters for basic operation. However, there are several features
which depend upon the use of filters. To make things easier, Seam lets you add and configure
servlet filters just like you would configure other built-in Seam components. To take advantage of
this feature, we must first install a master filter in web.xml:

<filter>
<filter-name>Seam Filter</filter-name>
<filter-class>org.jboss.seam.servlet.SeamFilter</filter-class>
</filter>

<filter-mapping>
<filter-name>Seam Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

The Seam master filter must be the first filter specified in web.xml. This ensures it is run first.

The Seam filters share a number of common attributes, you can set these in components.xml in
addition to any parameters discussed below:
• url-pattern — Used to specify which requests are filtered, the default is all requests. urlpattern
is a Tomcat style pattern which allows a wildcard suffix.
• regex-url-pattern — Used to specify which requests are filtered, the default is all requests.
regex-url-pattern is a true regular expression match for request path. It’s worth noting when
composing the regular expression that the request path does not contain the server or request
context path.
• disabled — Used to disable a built in filter.
Adding the master filter enables the following built-in filters.

Exception handling:
This filter provides the exception mapping functionality in pages.xml (almost all applications will
need this). It also takes care of rolling back uncommitted transactions when uncaught exceptions
occur. (According to the Java EE specification, the web container should do this automatically, but
we’ve found that this behavior cannot be relied upon in all application servers. And it is certainly
not required of plain servlet engines like Tomcat.)
By default, the exception handling filter will process all requests, however this behavior may
be adjusted by adding a <web:exception-filter> entry to components.xml, as shown in this
example:

<components xmlns=”http://jboss.com/products/seam/components”
xmlns:web=”http://jboss.com/products/seam/web”>
<web:exception-filter url-pattern=”*.seam”/>
</components>

Conversation propagation with redirects:
This filter allows Seam to propagate the conversation context across browser redirects. It
intercepts any browser redirects and adds a request parameter that specifies the Seam
conversation identifier.
The redirect filter will process all requests by default, but this behavior can also be adjusted in components.xml:

<web:redirect-filter url-pattern=”*.seam”/>

Multipart form submissions:
This feature is necessary when using the Seam file upload JSF control. It detects multipart form
requests and processes them according to the multipart/form-data specification (RFC-2388). To
override the default settings, add the following entry to components.xml:
<web:multipart-filter create-temp-files=”true”
max-request-size=”1000000″
url-pattern=”*.seam”/>
• create-temp-files — If set to true, uploaded files are written to a temporary file (instead of
held in memory). This may be an important consideration if large file uploads are expected. The
default setting is false.
• max-request-size — If the size of a file upload request (determined by reading the Content-
Length header in the request) exceeds this value, the request will be aborted. The default
setting is 0 (no size limit).

Character encoding
Sets the character encoding of submitted form data.
This filter is not installed by default and requires an entry in components.xml to enable it:

<web:character-encoding-filter encoding=”UTF-16″
override-client=”true”
url-pattern=”*.seam”/>
• encoding — The encoding to use.
• override-client — If this is set to true, the request encoding will be set to whatever is
specified by encoding no matter whether the request already specifies an encoding or not. If
set to false, the request encoding will only be set if the request doesn’t already specify an
encoding. The default setting is false.

RichFaces:
If RichFaces is used in your project, Seam will install the RichFaces Ajax filter for you, making
sure to install it before all other built-in filters. You don’t need to install the RichFaces Ajax filter
in web.xml yourself.
The RichFaces Ajax filter is only installed if the RichFaces jars are present in your project.
To override the default settings, add the following entry to components.xml. The options are the
same as those specified in the RichFaces Developer Guide:

<web:ajax4jsf-filter force-parser=”true”
enable-cache=”true”
log4j-init-file=”custom-log4j.xml”
url-pattern=”*.seam”/>

• force-parser — forces all JSF pages to be validated by Richfaces’s XML syntax checker. If
false, only AJAX responses are validated and converted to well-formed XML. Setting forceparser
to false improves performance, but can provide visual artifacts on AJAX updates.
• enable-cache — enables caching of framework-generated resources (e.g. javascript, CSS,
images, etc). When developing custom javascript or CSS, setting to true prevents the browser
from caching the resource.
• log4j-init-file — is used to setup per-application logging. A path, relative to web application
context, to the log4j.xml configuration file should be provided.

Identity Logging:
This filter adds the authenticated user name to the log4j mapped diagnostic context so that it can
be included in formatted log output if desired, by adding %X{username} to the pattern. By default, the logging filter will
process all requests, however this behavior may be adjusted by adding a <web:logging-filter> entry to components.xml, as
shown in this example:

<components xmlns=”http://jboss.com/products/seam/components”
xmlns:web=”http://jboss.com/products/seam/web”>
<web:logging-filter url-pattern=”*.seam”/>
</components>

Context management for custom servlets:
Requests sent direct to some servlet other than the JSF servlet are not processed through the
JSF lifecycle, so Seam provides a servlet filter that can be applied to any other servlet that needs
access to Seam components.
This filter allows custom servlets to interact with the Seam contexts. It sets up the Seam contexts
at the beginning of each request, and tears them down at the end of the request. You should make
sure that this filter is never applied to the JSF FacesServlet. Seam uses the phase listener for
context management in a JSF request.
This filter is not installed by default and requires an entry in components.xml to enable it:

<web:context-filter url-pattern=”/media/*”/>

The context filter expects to find the conversation id of any conversation context in a request
parameter named conversationId. You are responsible for ensuring that it gets sent in the
request.
You are also responsible for ensuring propagation of any new conversation id back to the client.
Seam exposes the conversation id as a property of the built in component conversation.

Adding custom filters:
Seam can install your filters for you, allowing you to specify where in the chain your filter is
placed (the servlet specification doesn’t provide a well defined order if you specify your filters in
a web.xml). Just add the @Filter annotation to your Seam component (which must implement
javax.servlet.Filter):

@Startup
@Scope(APPLICATION)
@Name(“org.jboss.seam.web.multipartFilter”)
@BypassInterceptors
@Filter(within=”org.jboss.seam.web.ajax4jsfFilter”)
public class MultipartFilter extends AbstractFilter {

Adding the @Startup annotation means thar the component is available during Seam startup;
bijection isn’t available here (@BypassInterceptors); and the filter should be further down the
chain than the RichFaces filter (@Filter(within=”org.jboss.seam.web.ajax4jsfFilter”)).

Integrating Seam with your EJB container:
We need to apply the SeamInterceptor to our Seam components. The simplest way to do this
across an entire application is to add the following interceptor configuration in ejb-jar.xml:

<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>

Seam needs to know where to go to find session beans in JNDI. One way to do this is specify
the @JndiName annotation on every session bean Seam component. However, this is quite
tedious. A better approach is to specify a pattern that Seam can use to calculate the JNDI
name from the EJB name. Unfortunately, there is no standard mapping to global JNDI defined
in the EJB3 specification, so this mapping is vendor-specific. We usually specify this option in components.xml.

For JBoss AS, the following pattern is correct:

<core:init jndi-name=”myEarName/#{ejbName}/local” />

Where myEarName is the name of the EAR in which the bean is deployed.
Outside the context of an EAR (when using the JBoss Embeddable EJB3 container), the following
pattern is the one to use:

<core:init jndi-name=”#{ejbName}/local” />

Don’t forget!: There is one final item you need to know about. You must place a seam.properties, METAINF/
seam.properties or META-INF/components.xml file in any archive in which your Seam
components are deployed (even an empty properties file will do). At startup, Seam will scan any
archives with seam.properties files for seam components.
In a web archive (WAR) file, you must place a seam.properties file in the WEB-INF/classes
directory if you have any Seam components included here.
That’s why all the Seam examples have an empty seam.properties file. You can’t just delete
this file and expect everything to still work!
You might think this is silly and what kind of idiot framework designers would make an empty file
affect the behavior of their software?? Well, this is a workaround for a limitation of the JVM—if
we didn’t use this mechanism, our next best option would be to force you to list every component
explicitly in components.xml, just like some other competing frameworks do!

Packaging: Once you’ve packaged all this stuff together into an EAR, the archive structure will look something
like this:

my-application.ear/
jboss-seam.jar
lib/
jboss-el.jar
META-INF/
MANIFEST.MF
application.xml
my-application.war/
META-INF/
MANIFEST.MF
WEB-INF/
web.xml
components.xml
faces-config.xml
lib/
jsf-facelets.jar
jboss-seam-ui.jar
login.jsp
register.jsp
…
my-application.jar/
META-INF/
MANIFEST.MF
persistence.xml
seam.properties
org/
jboss/
myapplication/
User.class
Login.class
LoginBean.class
Register.class
RegisterBean.class
…

You should declare jboss-seam.jar as an ejb module in META-INF/application.xml; jbossel.
jar should be placed in the EAR’s lib directory (putting it in the EAR classpath.
If you want to use jBPM or Drools, you must include the needed jars in the EAR’s lib directory.
If you want to use facelets (our recommendation), you must include jsf-facelets.jar in the
WEB-INF/lib directory of the WAR.

If you want to use the Seam tag library (most Seam applications do), you must include jbossseam-
ui.jar in the WEB-INF/lib directory of the WAR. If you want to use the PDF or email tag
libraries, you need to put jboss-seam-pdf.jar or jboss-seam-mail.jar in WEB-INF/lib.
If you want to use the Seam debug page (only works for applications using facelets), you must
include jboss-seam-debug.jar in the WEB-INF/lib directory of the WAR.
Seam ships with several example applications that are deployable in any Java EE container that
supports EJB 3.0.

Boostrapping Hibernate in Seam: Seam will bootstrap a Hibernate SessionFactory from your hibernate.cfg.xml file if you
install a built-in component:

<persistence:hibernate-session-factory name=”hibernateSessionFactory”/>
You will also need to configure a managed session if you want a Seam managed Hibernate
Session to be available via injection.
<persistence:managed-hibernate-session name=”hibernateSession”
session-factory=”#{hibernateSessionFactory}”/>

Boostrapping JPA in Seam:
Seam will bootstrap a JPA EntityManagerFactory from your persistence.xml file if you install
this built-in component:

<persistence:entity-manager-factory name=”entityManagerFactory”/>
You will also need to configure a managed persistence context if you want a Seam managed JPA
EntityManager to be available via injection.
<persistence:managed-persistence-context name=”entityManager”
entity-manager-factory=”#{entityManagerFactory}”/>

Packaging:
We can package our application as a WAR, in the following structure:

my-application.war/
META-INF/
MANIFEST.MF
WEB-INF/
web.xml
components.xml
faces-config.xml
lib/
jboss-seam.jar
jboss-seam-ui.jar
jboss-el.jar
jsf-facelets.jar
hibernate3.jar
hibernate-annotations.jar
hibernate-validator.jar
…
my-application.jar/
META-INF/
MANIFEST.MF
seam.properties
hibernate.cfg.xml
org/
jboss/
myapplication/
User.class
Login.class
Register.class
…
login.jsp
register.jsp
…

If we want to deploy Hibernate in a non-EE environment like Tomcat or TestNG, we need to do
a little bit more work.

Configuring SFSB and Session Timeouts in JBoss AS: It is very important that the timeout for Stateful Session Beans is set
higher than the timeout for HTTP Sessions, otherwise SFSB’s may time out before the user’s HTTP session has ended.
JBoss Application Server has a default session bean timeout of 30 minutes, which is configured
in server/default/conf/standardjboss.xml (replace default with your own configuration).
The default SFSB timeout can be adjusted by modifying the value of max-bean-life in the
LRUStatefulContextCachePolicy cache configuration:

<container-cache-conf>
<cache-policy>org.jboss.ejb.plugins.LRUStatefulContextCachePolicy</cache-policy>
<cache-policy-conf>
<min-capacity>50</min-capacity>
<max-capacity>1000000</max-capacity>
<remover-period>1800</remover-period>
<!– SFSB timeout in seconds; 1800 seconds == 30 minutes –>
<max-bean-life>1800</max-bean-life>
<overager-period>300</overager-period>
<max-bean-age>600</max-bean-age>
<resizer-period>400</resizer-period>
<max-cache-miss-period>60</max-cache-miss-period>
<min-cache-miss-period>1</min-cache-miss-period>
<cache-load-factor>0.75</cache-load-factor>
</cache-policy-conf>
</container-cache-conf>

The default HTTP session timeout can be modified in server/default/deploy/jbosswebtomcat55.
sar/conf/web.xml for JBoss 4.0.x, or in server/default/deploy/jbossweb.
deployer/conf/web.xml for JBoss 4.2.x. The following entry in this file controls the default
session timeout for all web applications:

<session-config>
<!– HTTP Session timeout, in minutes –>
<session-timeout>30</session-timeout>
</session-config>

To override this value for your own application, simply include this entry in your application’s own web.xml.

Running Seam in a Portlet:
If you want to run your Seam application in a portlet, take a look at the JBoss Portlet Bridge,
an implementation of JSR-301 that supports JSF within a portlet, with extensions for Seam and RichFaces.

Seam annotations: When you write a Seam application, you’ll use a lot of annotations. Seam lets you use annotations
to achieve a declarative style of programming. Most of the annotations you’ll use are defined by the
EJB 3.0 specification. The annotations for data validation are defined by the Hibernate Validator
package. Finally, Seam defines its own set of annotations.
All of these annotations are defined in the package org.jboss.seam.annotations.

Annotations for component definition: The first group of annotations lets you define a Seam component. These annotations
appear on the component class.

@Name
@Name(“componentName”)
Defines the Seam component name for a class. This annotation is required for all Seam
components.
@Scope
@Scope(ScopeType.CONVERSATION)

Defines the default context of the component. The possible values are defined by the ScopeType enumeration: EVENT, PAGE,
CONVERSATION, SESSION, BUSINESS_PROCESS, APPLICATION, STATELESS.

When no scope is explicitly specified, the default depends upon the component type. For
stateless session beans, the default is STATELESS. For entity beans and stateful session
beans, the default is CONVERSATION. For JavaBeans, the default is EVENT.

@Role
@Role(name=”roleName”, scope=ScopeType.SESSION)

Allows a Seam component to be bound to multiple contexts variables. The @Name/@Scope
annotations define a “default role”. Each @Role annotation defines an additional role.
• name — the context variable name.

• scope — the context variable scope. When no scope is explicitly specified, the default depends upon the component type, as
above.

@Roles
@Roles({
@Role(name=”user”, scope=ScopeType.CONVERSATION),
@Role(name=”currentUser”, scope=ScopeType.SESSION)
})

Allows specification of multiple additional roles.

@BypassInterceptors
Disables Seam all interceptors on a particular component or method of a component.

@JndiName
@JndiName(“my/jndi/name”)
Specifies the JNDI name that Seam will use to look up the EJB component. If
no JNDI name is explicitly specified, Seam will use the JNDI pattern specified by
org.jboss.seam.core.init.jndiPattern.

@Conversational
Specifies that a conversation scope component is conversational, meaning that no method of
the component may be called unless a long-running conversation is active.

@PerNestedConversation
Limits the scope of a CONVERSATION-scoped component to just the parent conversation
in which it was instantiated. The component instance will not be visible to nested child
conversations, which will get their own instance.
Warning: this is ill-defined, since it implies that a component will be visible for some part of a
request cycle, and invisible after that. It is not recommended that applications use this feature!

@Startup

@Scope(APPLICATION) @Startup(depends=”org.jboss.seam.bpm.jbpm”)

Specifies that an application scope component is started immediately at initialization time.
This is mainly used for certain built-in components that bootstrap critical infrastructure such
as JNDI, datasources, etc.

@Scope(SESSION) @Startup
Specifies that a session scope component is started immediately at session creation time.
• depends — specifies that the named components must be started first, if they are installed.

@Install(false)
Specifies whether or not a component should be installed by default. The lack of an @Install
annotation indicates a component should be installed.

@Install(dependencies=”org.jboss.seam.bpm.jbpm”)
Specifies that a component should only be stalled if the components listed as dependencies are also installed.

@Install(genericDependencies=ManagedQueueSender.class)
Specifies that a component should only be installed if a component that is implemented by a
certain class is installed. This is useful when the dependency doesn’t have a single well-known
name.
@Install(classDependencies=”org.hibernate.Session”)
Specifies that a component should only be installed if the named class is in the classpath.

@Install(precedence=BUILT_IN)
Specifies the precedence of the component. If multiple components with the same name exist,
the one with the higher precedence will be installed. The defined precendence values are (in
ascending order):
• BUILT_IN — Precedence of all built-in Seam components
• FRAMEWORK — Precedence to use for components of frameworks which extend Seam
• APPLICATION — Predence of application components (the default precedence)
• DEPLOYMENT — Precedence to use for components which override application components
in a particular deployment
• MOCK — Precedence for mock objects used in testing
@Synchronized
@Synchronized(timeout=1000)
Specifies that a component is accessed concurrently by multiple clients, and that Seam should
serialize requests. If a request is not able to obtain its lock on the component in the given
timeout period, an exception will be raised.

@ReadOnly
Specifies that a JavaBean component or component method does not require state replication
at the end of the invocation.

@AutoCreate
Specifies that a component will be automatically created, even if the client does not specify
create=true.

Annotations for bijection:
The next two annotations control bijection. These attributes occur on component instance
variables or property accessor methods.

@In
Specifies that a component attribute is to be injected from a context variable at the beginning
of each component invocation. If the context variable is null, an exception will be thrown.
@In(required=false)
Specifies that a component attribute is to be injected from a context variable at the beginning
of each component invocation. The context variable may be null.
@In(create=true)
Specifies that a component attribute is to be injected from a context variable at the beginning
of each component invocation. If the context variable is null, an instance of the component
is instantiated by Seam.

@In(value=”contextVariableName”)
Specifies the name of the context variable explicitly, instead of using the annotated instance
variable name.
@In(value=”#{customer.addresses['shipping']}”)
Specifies that a component attribute is to be injected by evaluating a JSF EL expression at
the beginning of each component invocation.
• value — specifies the name of the context variable. Default to the name of the component
attribute. Alternatively, specifies a JSF EL expression, surrounded by #{…}.
• create — specifies that Seam should instantiate the component with the same name as
the context variable if the context variable is undefined (null) in all contexts. Default to false.
• required — specifies Seam should throw an exception if the context variable is undefined
in all contexts.
@Out
Specifies that a component attribute that is a Seam component is to be outjected to its context
variable at the end of the invocation. If the attribute is null, an exception is thrown.
@Out(required=false)
Specifies that a component attribute that is a Seam component is to be outjected to its context
variable at the end of the invocation. The attribute may be null.
@Out(scope=ScopeType.SESSION)
Specifies that a component attribute that is not a Seam component type is to be outjected to
a specific scope at the end of the invocation.
Alternatively, if no scope is explicitly specified, the scope of the component with the @Out
attribute is used (or the EVENT scope if the component is stateless).
@Out(value=”contextVariableName”)
Specifies the name of the context variable explicitly, instead of using the annotated instance
variable name.
• value — specifies the name of the context variable. Default to the name of the component
attribute.
• required — specifies Seam should throw an exception if the component attribute is null
during outjection.
Note that it is quite common for these annotations to occur together, for example:
@In(create=true) @Out private User currentUser;
The next annotation supports the manager component pattern, where a Seam component that
manages the lifecycle of an instance of some other class that is to be injected. It appears on a
component getter method.
@Unwrap
Specifies that the object returned by the annotated getter method is the thing that is injected
instead of the component instance itself.
The next annotation supports the factory component pattern, where a Seam component is
responsible for initializing the value of a context variable. This is especially useful for initializing
any state needed for rendering the response to a non-faces request. It appears on a component
method.
@Factory
@Factory(“processInstance”) public void createProcessInstance() { … }
Specifies that the method of the component is used to initialize the value of the named context
variable, when the context variable has no value. This style is used with methods that return
void.
@Factory(“processInstance”, scope=CONVERSATION) public ProcessInstance
createProcessInstance() { … }
Specifies that the method returns a value that Seam should use to initialize the value of
the named context variable, when the context variable has no value. This style is used with
methods that return a value. If no scope is explicitly specified, the scope of the component with
the @Factory method is used (unless the component is stateless, in which case the EVENT
context is used).
• value — specifies the name of the context variable. If the method is a getter method, default
to the JavaBeans property name.
• scope — specifies the scope that Seam should bind the returned value to. Only meaningful
for factory methods which return a value.
• autoCreate — specifies that this factory method should be automatically called whenever
the variable is asked for, even if @In does not specify create=true.
This annotation lets you inject a Log:
@Logger(“categoryName”)
Specifies that a component field is to be injected with an instance of
org.jboss.seam.log.Log. For entity beans, the field must be declared as static.
• value — specifies the name of the log category. Default to the name of the component
class.
The last annotation lets you inject a request parameter value:
@RequestParameter
@RequestParameter(“parameterName”)
Specifies that a component attribute is to be injected with the value of a request parameter.
Basic type conversions are performed automatically.
• value — specifies the name of the request parameter. Default to the name of the
component attribute.

Annotations for component lifecycle methods:
These annotations allow a component to react to its own lifecycle events. They occur on methods
of the component. There may be only one of each per component class.
@Create
@Create
Specifies that the method should be called when an instance of the component is instantiated
by Seam. Note that create methods are only supported for JavaBeans and stateful session
beans.

@Destroy
Specifies that the method should be called when the context ends and its context variables are
destroyed. Note that destroy methods are only supported for JavaBeans and stateful session
beans.
Destroy methods should be used only for cleanup. Seam catches, logs and swallows any
exception that propagates out of a destroy method.
@Observer
@Observer(“somethingChanged”)
Specifies that the method should be called when a component-driven event of the specified
type occurs.
@Observer(value=”somethingChanged”,create=false)
Specifies that the method should be called when an event of the specified type occurs but
that an instance should not be created if one doesn’t exist. If an instance does not exist and
create is false, the event will not be observed. The default value for create is true.

Annotations for context demarcation:
These annotations provide declarative conversation demarcation. They appear on methods of
Seam components, usually action listener methods.
Every web request has a conversation context associated with it. Most of these conversations
end at the end of the request. If you want a conversation that span multiple requests, you must
“promote” the current conversation to a long-running conversation by calling a method marked
with @Begin.

@Begin
Specifies that a long-running conversation begins when this method returns a non-null
outcome without exception.
@Begin(join=true)
Specifies that if a long-running conversation is already in progress, the conversation context
is simply propagated.
@Begin(nested=true)
Specifies that if a long-running conversation is already in progress, a new nested conversation
context begins. The nested conversation will end when the next @End is encountered, and the
outer conversation will resume. It is perfectly legal for multiple nested conversations to exist
concurrently in the same outer conversation.
@Begin(pageflow=”process definition name”)
Specifies a jBPM process definition name that defines the pageflow for this conversation.
@Begin(flushMode=FlushModeType.MANUAL)
Specify the flush mode of any Seam-managed persistence contexts.
flushMode=FlushModeType.MANUAL supports the use of atomic conversations where all write
operations are queued in the conversation context until an explicit call to flush() (which
usually occurs at the end of the conversation).
• join — determines the behavior when a long-running conversation is already in progress.
If true, the context is propagated. If false, an exception is thrown. Default to false. This
setting is ignored when nested=true is specified.
• nested — specifies that a nested conversation should be started if a long-running
conversation is already in progress.
• flushMode — set the flush mode of any Seam-managed Hibernate sessions or JPA
persistence contexts that are created during this conversation.
• pageflow — a process definition name of a jBPM process definition deployed via
org.jboss.seam.bpm.jbpm.pageflowDefinitions.
@End
@End
Specifies that a long-running conversation ends when this method returns a non-null outcome
without exception.
• beforeRedirect — by default, the conversation will not actually be destroyed until after
any redirect has occurred. Setting beforeRedirect=true specifies that the conversation
should be destroyed at the end of the current request, and that the redirect will be processed
in a new temporary conversation context.
@StartTask
“Starts” a jBPM task. Specifies that a long-running conversation begins when this method
returns a non-null outcome without exception. This conversation is associated with the jBPM
task specified in the named request parameter. Within the context of this conversation, a
business process context is also defined, for the business process instance of the task
instance.
• The jBPM TaskInstance will be available in a request context variable named
taskInstance. The jPBM ProcessInstance will be available in a request context variable
named processInstance. (Of course, these objects are available for injection via @In.)
• taskIdParameter — the name of a request parameter which holds the id of the task. Default
to “taskId”, which is also the default used by the Seam taskList JSF component.
• flushMode — set the flush mode of any Seam-managed Hibernate sessions or JPA
persistence contexts that are created during this conversation.
@BeginTask
Resumes work on an incomplete jBPM task. Specifies that a long-running conversation
begins when this method returns a non-null outcome without exception. This conversation is
associated with the jBPM task specified in the named request parameter. Within the context
of this conversation, a business process context is also defined, for the business process
instance of the task instance.
• The jBPM org.jbpm.taskmgmt.exe.TaskInstance will be available in a request context
variable named taskInstance. The jPBM org.jbpm.graph.exe.ProcessInstance will be
available in a request context variable named processInstance.
• taskIdParameter — the name of a request parameter which holds the id of the task. Default
to “taskId”, which is also the default used by the Seam taskList JSF component.
• flushMode — set the flush mode of any Seam-managed Hibernate sessions or JPA
persistence contexts that are created during this conversation.
@EndTask
“Ends” a jBPM task. Specifies that a long-running conversation ends when this method
returns a non-null outcome, and that the current task is complete. Triggers a jBPM transition.
The actual transition triggered will be the default transition unless the application has called
Transition.setName() on the built-in component named transition.
@EndTask(transition=”transitionName”)
Triggers the given jBPM transition.
• transition — the name of the jBPM transition to be triggered when ending the task.
Defaults to the default transition.
• beforeRedirect — by default, the conversation will not actually be destroyed until after
any redirect has occurred. Setting beforeRedirect=true specifies that the conversation
should be destroyed at the end of the current request, and that the redirect will be processed
in a new temporary conversation context.
@CreateProcess
@CreateProcess(definition=”process definition name”)
Creates a new jBPM process instance when the method returns a non-null outcome without
exception. The ProcessInstance object will be available in a context variable named
processInstance.
• definition — the name of the jBPM process definition deployed via
org.jboss.seam.bpm.jbpm.processDefinitions.
@ResumeProcess
@ResumeProcess(processIdParameter=”processId”)
Re-enters the scope of an existing jBPM process instance when the method returns a nonnull
outcome without exception. The ProcessInstance object will be available in a context
variable named processInstance.
• processIdParameter — the name a request parameter holding the process id. Default to
“processId”.
@Transition
@Transition(“cancel”)
Marks a method as signalling a transition in the current jBPM process instance whenever the
method returns a non-null result.

Annotations for use with Seam JavaBean components in a J2EE environment: Seam provides an annotation that lets you force a
rollback of the JTA transaction for certain action listener outcomes.

@Transactional
Specifies that a JavaBean component should have a similar transactional behavior to the
default behavior of a session bean component. ie. method invocations should take place in
a transaction, and if no transaction exists when the method is called, a transaction will be
started just for that method. This annotation may be applied at either class or method level.
Do not use this annotation on EJB 3.0 components, use @TransactionAttribute!

@ApplicationException
Synonym for javax.ejb.ApplicationException, for use in a pre Java EE 5 environment. Applied
to an exception to denote that it is an application exception and should be reported to the
client directly(i.e., unwrapped).
Do not use this annotation on EJB 3.0 components, use
@javax.ejb.ApplicationException instead.
• rollback — by default false, if true this exception should set the transaction to rollback
only
• end — by default false, if true this exception should end the current long-running
conversation

@Interceptors
@Interceptors({DVDInterceptor, CDInterceptor})
Synonym for javax.interceptors.Interceptors, for use in a pre Java EE 5 environment. Note
that this may only be used as a meta-annotation. Declares an ordered list of interceptors for
a class or method.
Do not use this annotations on EJB 3.0 components, use
@javax.interceptor.Interceptors instead.
These annotations are mostly useful for JavaBean Seam components. If you use EJB 3.0
components, you should use the standard Java EE5 annotation.

Annotations for exceptions: These annotations let you specify how Seam should handle an exception that propagates out of
a Seam component.
@Redirect
@Redirect(viewId=”error.jsp”)
Specifies that the annotated exception causes a browser redirect to a specified view id.
• viewId — specifies the JSF view id to redirect to. You can use EL here.
• message — a message to be displayed, default to the exception message.
• end — specifies that the long-running conversation should end, default to false.
@HttpError
@HttpError(errorCode=404)
Specifies that the annotated exception causes a HTTP error to be sent.
• errorCode — the HTTP error code, default to 500.
• message — a message to be sent with the HTTP error, default to the exception message.
• end — specifies that the long-running conversation should end, default to false.

Annotations for Seam Remoting:
Seam Remoting requires that the local interface of a session bean be annotated with the following annotation:
@WebRemote
@WebRemote(exclude=”path.to.exclude”)
Indicates that the annotated method may be called from client-side JavaScript. The exclude
property is optional and allows objects to be excluded from the result’s object graph (see the
Remoting chapter for more details).

Annotations for Seam interceptors:
The following annotations appear on Seam interceptor classes.
Please refer to the documentation for the EJB 3.0 specification for information about the
annotations required for EJB interceptor definition.
@Interceptor
@Interceptor(stateless=true)
Specifies that this interceptor is stateless and Seam may optimize replication.
@Interceptor(type=CLIENT)
Specifies that this interceptor is a “client-side” interceptor that is called before the EJB
container.
@Interceptor(around={SomeInterceptor.class, OtherInterceptor.class})
Specifies that this interceptor is positioned higher in the stack than the given interceptors.
@Interceptor(within={SomeInterceptor.class, OtherInterceptor.class})
Specifies that this interceptor is positioned deeper in the stack than the given interceptors.
Annotations for asynchronicity:
The following annotations are used to declare an asynchronous method, for example:
@Asynchronous public void scheduleAlert(Alert alert, @Expiration Date date) { … }
@Asynchronous public Timer scheduleAlerts(Alert alert,
@Expiration Date date,
@IntervalDuration long interval) { … }
@Asynchronous
@Asynchronous
Specifies that the method call is processed asynchronously.
@Duration
@Duration
Specifies that a parameter of the asynchronous call is the duration before the call is processed
(or first processed for recurring calls).
@Expiration
@Expiration
Specifies that a parameter of the asynchronous call is the datetime at which the call is
processed (or first processed for recurring calls).
@IntervalDuration
@IntervalDuration
Specifies that an asynchronous method call recurs, and that the annotationed parameter is
duration between recurrences.

Annotations for use with JSF:
The following annotations make working with JSF easier.
@Converter
Allows a Seam component to act as a JSF converter. The annotated class must be a Seam
component, and must implement javax.faces.convert.Converter.
• id — the JSF converter id. Defaults to the component name.
• forClass — if specified, register this component as the default converter for a type.
@Validator
Allows a Seam component to act as a JSF validator. The annotated class must be a Seam
component, and must implement javax.faces.validator.Validator.
• id — the JSF validator id. Defaults to the component name.
27.10.1. Annotations for use with dataTable
The following annotations make it easy to implement clickable lists backed by a stateful session
bean. They appear on attributes.
@DataModel
@DataModel(“variableName”)
Outjects a property of type List, Map, Set or Object[] as a JSF DataModel into the scope
of the owning component (or the EVENT scope if the owning component is STATELESS). In the
case of Map, each row of the DataModel is a Map.Entry.
• value — name of the conversation context variable. Default to the attribute name.
• scope — if scope=ScopeType.PAGE is explicitly specified, the DataModel will be kept in the
PAGE context.
@DataModelSelection
@DataModelSelection
Injects the selected value from the JSF DataModel (this is the element of the underlying
collection, or the map value). If only one @DataModel attribute is defined for a component, the
selected value from that DataModel will be injected. Otherwise, the component name of each
@DataModel must be specified in the value attribute for each @DataModelSelection.
If PAGE scope is specified on the associated @DataModel, then, in addition to the DataModel
Selection being injected, the associated DataModel will also be injected. In this case, if the
property annotated with @DataModel is a getter method, then a setter method for the property
must also be part of the Business API of the containing Seam Component.
• value — name of the conversation context variable. Not needed if there is exactly one
@DataModel in the component.
@DataModelSelectionIndex
@DataModelSelectionIndex
Exposes the selection index of the JSF DataModel as an attribute of the component (this is the
row number of the underlying collection, or the map key). If only one @DataModel attribute is
defined for a component, the selected value from that DataModel will be injected. Otherwise,
the component name of each @DataModel must be specified in the value attribute for each
@DataModelSelectionIndex.
• value — name of the conversation context variable. Not needed if there is exactly one
@DataModel in the component.
Meta-annotations for databinding
These meta-annotations make it possible to implement similar functionality to @DataModel and
@DataModelSelection for other datastructures apart from lists.
@DataBinderClass
@DataBinderClass(DataModelBinder.class)
Specifies that an annotation is a databinding annotation.
@DataSelectorClass
@DataSelectorClass(DataModelSelector.class)
Specifies that an annotation is a dataselection annotation.

Annotations for packaging:
This annotation provides a mechanism for declaring information about a set of components that
are packaged together. It can be applied to any Java package.
@Namespace
@Namespace(value=”http://jboss.com/products/seam/example/seampay”)
Specifies that components in the current package are associated with the given namespace.
The declared namespace can be used as an XML namespace in a components.xml file to
simplify application configuration.
@Namespace(value=”http://jboss.com/products/seam/core”, prefix=”org.jboss.seam.core”)
Specifies a namespace to associate with a given package. Additionally, it specifies a
component name prefix to be applied to component names specified in the XML file. For
example, an XML element named init that is associated with this namespace would be
understood to actually refer to a component named org.jboss.seam.core.init.

Annotations for integrating with the servlet container:
These annotations allow you to integrate your Seam components with the servlet container.
@Filter
Use the Seam component (which implements javax.servlet.Filter) annotated with
@Filter as a servlet filter. It will be executed by Seam’s master filter.
•
@Filter(around={“seamComponent”, “otherSeamComponent”})
Specifies that this filter is positioned higher in the stack than the given filters.
•
@Filter(within={“seamComponent”, “otherSeamComponent”})
Specifies that this filter is positioned deeper in the stack than the given filters.

Seam JSF controls: Seam includes a number of JSF controls that are useful for working with Seam. These are
intended to complement the built-in JSF controls, and controls from other third-party libraries. We
recommend JBoss RichFaces, and Apache MyFaces Trinidad tag libraries for use with Seam. We
do not recommend the use of the Tomahawk tag library.
29.1. Tags
To use these tags, define the “s” namespace in your page as follows (facelets only):
<html xmlns=”http://www.w3.org/1999/xhtml”
xmlns:s=”http://jboss.com/products/seam/taglib”>
The ui example demonstrates the use of a number of these tags.
29.1.1. Navigation Controls
29.1.1.1. <s:button>
Description
A button that supports invocation of an action with control over conversation propagation. Does
not submit the form.
Attributes
• value — the label.
• action — a method binding that specified the action listener.
• view — the JSF view id to link to.
• fragment — the fragment identifier to link to.
• disabled — is the link disabled?
• propagation — determines the conversation propagation style: begin, join, nest, none or
end.
• pageflow — a pageflow definition to begin. (This is only useful when propagation=”begin”
or propagation=”join” is used).
Usage
<s:button id=”cancel”
Chapter 29. Seam JSF controls
408
value=”Cancel”
action=”#{hotelBooking.cancel}”/>
You can specify both view and action on <s:link />. In this case, the action wil be called once
the redirect to the specified view has occured.
29.1.1.2. <s:conversationId>
Description
Add the conversation id to JSF link or button (e.g. <h:commandLink /> , <s:button />).
Attributes
None
29.1.1.3. <s:taskId>
Description
Add the task id to an output link (or similar JSF control), when the task is available via #{task}.
Attributes
None.
29.1.1.4. <s:link>
Description
A link that supports invocation of an action with control over conversation propagation. Does not
submit the form.
Attributes
• value — the label.
• action — a method binding that specified the action listener.
• view — the JSF view id to link to.
• fragment — the fragment identifier to link to.
• disabled — is the link disabled?
• propagation — determines the conversation propagation style: begin, join, nest, none or
end.
• pageflow — a pageflow definition to begin. (This is only useful when using
propagation=”begin” or propagation=”join”.)
Navigation Controls
409
Usage
<s:link id=”register” view=”/register.xhtml”
value=”Register New User”/>
You can specify both view and action on <s:link />. In this case, the action will be called once
the redirect to the specified view has occured.
29.1.1.5. <s:conversationPropagation>
Description
Customize the conversation propagation for a command link or button (or similar JSF control).
Facelets only.
Attributes
• type — determines the conversation propagation style: begin, join, nest, none or end.
• pageflow — a pageflow definition to begin. (This is only useful when using
propagation=”begin” or propagation=”join”.)
Usage
<h:commandButton value=”Apply” action=”#{personHome.update}”>
<s:conversationPropagation type=”join” />
</h:commandButton>
29.1.1.6. <s:defaultAction>
Description
Specify the default action to run when the form is submitted using the enter key.
Currently you can only nest it inside buttons (e.g. <h:commandButton />, <a:commandButton />
or <tr:commandButton />).
You must specify an id on the action source. You can only have one default action per form.
Attributes
None.
Usage
<h:commandButton id=”foo” value=”Foo” action=”#{manager.foo}”>
Chapter 29. Seam JSF controls
410
<s:defaultAction />
</h:commandButton>
29.1.2. Converters and Validators
29.1.2.1. <s:convertDateTime>
Description
Perform date or time conversions in the Seam timezone.
Attributes
None.
Usage
<h:outputText value=”#{item.orderDate}”>
<s:convertDateTime type=”both” dateStyle=”full”/>
</h:outputText>
29.1.2.2. <s:convertEntity>
Description
Assigns an entity converter to the current component. This is primarily useful for radio button and
dropdown controls.
The converter works with any managed entity which has an @Id annotation – either simple or
composite.
Attributes
None.
Configuration
You must use Seam managed transactions (see Section 9.2, “Seam managed transactions”) with
<s:convertEntity />.
If your Managed Persistence Context isn’t called entityManager, then you need to set it in
components.xml:
<component name=”org.jboss.seam.ui.EntityConverter”>
<property name=”entityManager”>#{em}</property>
Converters and Validators
411
</component>
If you are using a Managed Hibernate Session then you need to set it in components.xml:
<component name=”org.jboss.seam.ui.EntityConverter”>
<property name=”session”>#{hibernateSession}</property>
</component>
If you want to use more than one entity manager with the entity converter, you can create a copy
of the entity converter for each entity manager in components.xml:
<component name=”myEntityConverter”>
<property name=”entityManager”>#{em}</property>
</component>
<h:selectOneMenu value=”#{person.continent}”>
<s:selectItems value=”#{continents.resultList}” var=”continent”
label=”#{continent.name}” />
<f:converter converterId=”myEntityConverter” />
</h:selectOneMenu>
Usage
<h:selectOneMenu value=”#{person.continent}” required=”true”>
<s:selectItems value=”#{continents.resultList}” var=”continent”
label=”#{continent.name}”
noSelectionLabel=”Please Select…”/>
<s:convertEntity />
</h:selectOneMenu>
29.1.2.3. <s:convertEnum>
Description
Assigns an enum converter to the current component. This is primarily useful for radio button and
dropdown controls.
Attributes
None.
Chapter 29. Seam JSF controls
412
Usage
<h:selectOneMenu value=”#{person.honorific}”>
<s:selectItems value=”#{honorifics}” var=”honorific”
label=”#{honorific.label}”
noSelectionLabel=”Please select” />
<s:convertEnum />
</h:selectOneMenu>
29.1.2.4. <s:validate>
Description
A non-visual control, validates a JSF input field against the bound property using Hibernate
Validator.
Attributes
None.
Usage
<h:inputText id=”userName” required=”true”
value=”#{customer.userName}”>
<s:validate />
</h:inputText>
<h:message for=”userName” styleClass=”error” />
29.1.2.5. <s:validateAll>
Description
A non-visual control, validates all child JSF input fields against their bound properties using
Hibernate Validator.
Attributes
None.
Usage
<s:validateAll>
<div>
<h:outputLabel for=”username”>Username:</h:outputLabel>
Formatting
413
<h:inputText id=”username” value=”#{user.username}”
required=”true”/>
<h:message for=”username” styleClass=”error” />
</div>
<div>
<h:outputLabel for=”password”>Password:</h:outputLabel>
<h:inputSecret id=”password” value=”#{user.password}”
required=”true”/>
<h:message for=”password” styleClass=”error” />
</div>
<div>
<h:outputLabel for=”verify”>Verify Password:</h:outputLabel>
<h:inputSecret id=”verify” value=”#{register.verify}”
required=”true”/>
<h:message for=”verify” styleClass=”error” />
</div>
</s:validateAll>
29.1.3. Formatting
29.1.3.1. <s:decorate>
Description
“Decorate” a JSF input field when validation fails or when required=”true” is set.
Attributes
• template — the facelets template to use to decorate the component
#{invalid} and #{required} are available inside s:decorate; #{required} evaluates to true
if you have set the input component being decorated as required, and #{invalid} evaluates to
true if a validation error occurs.
Usage
<s:decorate template=”edit.xhtml”>
<ui:define name=”label”>Country:</ui:define>
<h:inputText value=”#{location.country}” required=”true”/>
</s:decorate>
<ui:composition xmlns=”http://www.w3.org/1999/xhtml”
xmlns:ui=”http://java.sun.com/jsf/facelets”
Chapter 29. Seam JSF controls
414
xmlns:h=”http://java.sun.com/jsf/html”
xmlns:f=”http://java.sun.com/jsf/core”
xmlns:s=”http://jboss.com/products/seam/taglib”>
<div>
<s:label styleClass=”#{invalid?’error’:”}”>
<ui:insert name=”label”/>
<s:span styleClass=”required” rendered=”#{required}”>*</s:span>
</s:label>
<span>
<s:validateAll>
<ui:insert/>
</s:validateAll>
</span>
<s:message styleClass=”error”/>
</div>
</ui:composition>
29.1.3.2. <s:div>
Description
Render a HTML <div>.
Attributes
None.
Usage
<s:div rendered=”#{selectedMember == null}”>
Sorry, but this member does not exist.
</s:div>
29.1.3.3. <s:span>
Description
Render a HTML <span>.
Formatting
415
Attributes
None.
Usage
<s:span styleClass=”required” rendered=”#{required}”>*</s:span>
29.1.3.4. <s:fragment>
Description
A non-rendering component useful for enabling/disabling rendering of it’s children.
Attributes
None.
Usage
<s:fragment rendered=”#{auction.highBidder ne null}”>
Current bid:
</s:fragment>
29.1.3.5. <s:label>
Description
“Decorate” a JSF input field with the label. The label is placed inside the HTML <label> tag, and
is associated with the nearest JSF input component. It is often used with <s:decorate>.
Attributes
• style — The control’s style
• styleClass — The control’s style class
Usage
<s:label styleClass=”label”>
Country:
</s:label>
<h:inputText value=”#{location.country}” required=”true”/>
Chapter 29. Seam JSF controls
416
29.1.3.6. <s:message>
Description
“Decorate” a JSF input field with the validation error message.
Attributes
None.
Usage
<f:facet name=”afterInvalidField”>
<s:span>
 Error: 
<s:message/>
</s:span>
</f:facet>
29.1.4. Seam Text
29.1.4.1. <s:validateFormattedText>
Description
Checks that the submitted value is valid Seam Text
Attributes
None.
29.1.4.2. <s:formattedText>
Description
Outputs Seam Text, a rich text markup useful for blogs, wikis and other applications that might
use rich text. See the Seam Text chapter for full usage.
Attributes
• value — an EL expression specifying the rich text markup to render.
Usage
<s:formattedText value=”#{blog.text}”/>

Dropdowns
29.1.5.1. <s:enumItem>
Description
Creates a SelectItem from an enum value.
Attributes
• enumValue — the string representation of the enum value.
• label — the label to be used when rendering the SelectItem.
Usage
<h:selectOneRadio id=”radioList”
layout=”lineDirection”
value=”#{newPayment.paymentFrequency}”>
<s:convertEnum />
Chapter 29. Seam JSF controls
418
<s:enumItem enumValue=”ONCE” label=”Only Once” />
<s:enumItem enumValue=”EVERY_MINUTE” label=”Every Minute” />
<s:enumItem enumValue=”HOURLY” label=”Every Hour” />
<s:enumItem enumValue=”DAILY” label=”Every Day” />
<s:enumItem enumValue=”WEEKLY” label=”Every Week” />
</h:selectOneRadio>
29.1.5.2. <s:selectItems>
Description
Creates a List<SelectItem> from a List, Set, DataModel or Array.
Attributes
• value — an EL expression specifying the data that backs the List<SelectItem>
• var— defines the name of the local variable that holds the current object during iteration
• label — the label to be used when rendering the SelectItem. Can reference the var variable.
• itemValue — Value to return to the server if this option is selected. Optional, by default the var
object is used. Can reference the var variable.
• disabled — if true the SelectItem will be rendered disabled. Can reference the var variable.
• noSelectionLabel — specifies the (optional) label to place at the top of list (if
required=”true” is also specified then selecting this value will cause a validation error).
• hideNoSelectionLabel — if true, the noSelectionLabel will be hidden when a value is
selected
Usage
<h:selectOneMenu value=”#{person.age}”
converter=”ageConverter”>
<s:selectItems value=”#{ages}” var=”age” label=”#{age}” />
</h:selectOneMenu>
29.1.6. Other
29.1.6.1. <s:cache>
Description
Cache the rendered page fragment using JBoss Cache. Note that <s:cache> actually uses the
instance of JBoss Cache managed by the built-in pojoCache component.
Other
419
Attributes
• key — the key to cache rendered content, often a value expression. For example, if we
were caching a page fragment that displays a document, we might use key=”Document-
#{document.id}”.
• enabled — a value expression that determines if the cache should be used.
• region — a JBoss Cache node to use (different nodes can have different expiry policies).
Usage
<s:cache key=”entry-#{blogEntry.id}” region=”pageFragments”>
<div>
<h3>#{blogEntry.title}</h3>
<div>
<s:formattedText value=”#{blogEntry.body}”/>
</div>
<p>
[Posted on 
<h:outputText value="#{blogEntry.date}">
<f:convertDateTime timezone="#{blog.timeZone}" locale="#{blog.locale}"
type="both"/>
</h:outputText>]
</p>
</div>
</s:cache>
29.1.6.2. <s:fileUpload>
Description
Renders a file upload control. This control must be used within a form with an encoding type of
multipart/form-data, i.e:
<h:form enctype=”multipart/form-data”>
For multipart requests, the Seam Multipart servlet filter must also be configured in web.xml:
<filter>
<filter-name>Seam Filter</filter-name>
<filter-class>org.jboss.seam.servlet.SeamFilter</filter-class>
</filter>
Chapter 29. Seam JSF controls
420
<filter-mapping>
<filter-name>Seam Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
Configuration
The following configuration options for multipart requests may be configured in components.xml:
• createTempFiles — if this option is set to true, uploaded files are streamed to a temporary
file instead of in memory.
• maxRequestSize — the maximum size of a file upload request, in bytes.
Here’s an example:
<component>
<property name=”createTempFiles”>true</property>
<property name=”maxRequestSize”>1000000</property>
</component>
Attributes
• data — this value binding receives the binary file data. The receiving field should be declared
as a byte[] or InputStream (required).
• contentType — this value binding receives the file’s content type (optional).
• fileName — this value binding receives the filename (optional).
• fileSize — this value binding receives the file size (optional).
• accept — a comma-separated list of content types to accept, may not be supported by the
browser. E.g. “images/png,images/jpg”, “images/*”.
• style — The control’s style
• styleClass — The control’s style class
Usage
<s:fileUpload id=”picture” data=”#{register.picture}”
accept=”image/png”
Other
421
contentType=”#{register.pictureContentType}” />
29.1.6.3. <s:graphicImage>
Description
An extended <h:graphicImage> that allows the image to be created in a Seam Component;
further transforms can be applied to the image.
All attributes for <h:graphicImage> are supported, as well as:
Attributes
• value — image to display. Can be a path String (loaded from the classpath), a byte[],
a java.io.File, a java.io.InputStream or a java.net.URL. Currently supported image
formats are image/png, image/jpeg and image/gif.
• fileName — if not specified the served image will have a generated file name. If you want to
name your file, you should specify it here. This name should be unique
Transformations
To apply a transform to the image, you would nest a tag specifying the transform to apply. Seam
currently supports these transforms:
<s:transformImageSize>
• width — new width of the image
• height — new height of the image
• maintainRatio — if true, and one of width/height are specified, the image will be resized
with the dimension not specified being calculated to maintain the aspect ratio.
• factor — scale the image by the given factor
<s:transformImageBlur>
• radius — perform a convolution blur with the given radius
<s:transformImageType>
• contentType — alter the type of the image to either image/jpeg or image/png
It’s easy to create your own transform – create a UIComponent which implements
org.jboss.seam.ui.graphicImage.ImageTransform. Inside the applyTransform()method
use image.getBufferedImage() to get the original image and image.setBufferedImage() to
set your transformed image. Transforms are applied in the order specified in the view.
Chapter 29. Seam JSF controls
422
Usage
<s:graphicImage rendered=”#{auction.image ne null}”
value=”#{auction.image.data}”>
<s:transformImageSize width=”200″ maintainRatio=”true”/>
</s:graphicImage>
29.1.6.4. <s:remote>
Description
Generates the Javascript stubs required to use Seam Remoting.
Attributes
• include — a comma-separated list of the component names (or fully qualified class names)for
which to generate Seam Remoting Javascript stubs. See Chapter 22, Remoting for more details.
Usage
<s:remote include=”customerAction,accountAction,com.acme.MyBean”/>
29.2. Annotations
Seam also provides annotations to allow you to use Seam components as JSF converters and
validators:
@Converter
@Name(“itemConverter”)
@BypassInterceptors
@Converter
public class ItemConverter implements Converter {
@Transactional
public Object getAsObject(FacesContext context, UIComponent cmp, String value) {
EntityManager entityManager = (EntityManager)
Component.getInstance(“entityManager”);
entityManager.joinTransaction();
// Do the conversion
}
Annotations
423
public String getAsString(FacesContext context, UIComponent cmp, Object value) {
// Do the conversion
}
}
<h:inputText value=”#{shop.item}” converter=”itemConverter” />
Registers the Seam component as a JSF converter. Shown here is a converter which is able
to access the JPA EntityManager inside a JTA transaction, when converting the value back
to it’s object representation.
@Validator
@Name(“itemValidator”)
@BypassInterceptors
@Validator
public class ItemValidator implements Validator {
public void validate(FacesContext context, UIComponent cmp, Object value)
throws ValidatorException {
ItemController ItemController = (ItemController) Component.getInstance(“itemController”);
return itemController.validate(value);
}
}
<h:inputText value=”#{shop.item}” validator=”itemValidator” />
Registers the Seam component as a JSF validator. Shown here is a validator which injects
another Seam component; the injected component is used to validate the value.

JBoss EL: Seam uses JBoss EL which provides an extension to the standard Unified Expression Language
(EL). JBoss EL provides a number of enhancements that increase the expressiveness and power of EL expressions.

Parameterized Expressions: Standard EL does not allow you to use a method with user defined parameters — of course, JSF
listener methods (e.g. a valueChangeListener) take parameters provided by JSF.
JBoss EL removes this restriction. For example:

<h:commandButton action=”#{hotelBooking.bookHotel(hotel)}” value=”Book Hotel”/>
@Name(“hotelBooking”)
public class HotelBooking {
public String bookHotel(Hotel hotel) {
// Book the hotel
}
}

Usage: Just as in calls to method from Java, parameters are surrounded by parentheses, and separated by commas:

<h:commandButton action=”#{hotelBooking.bookHotel(hotel, user)}” value=”Book Hotel”/>

The parameters hotel and user will be evaluated as value expressions and passed to the
bookHotel() method of the component.
Any value expression may be used as a parameter:

<h:commandButton action=”#{hotelBooking.bookHotel(hotel.id, user.username)}” value=”Book Hotel”/>

It’s important to fully understand how this extension to EL works. When the page is rendered, the
parameter names are stored (for example, hotel.id and user.username), and evaluated (as value expressions) when the page is
submitted. You can’t pass objects as parameters!
You must ensure that the parameters are available not only when the page is rendered, but also when it is submittedIf the
arguments can not be resolved when the page is submitted the action method will be called with null arguments!
You can also pass literal strings using single quotes:

<h:commandLink action=”#{printer.println(‘Hello world!’)}” value=”Hello”/>

Unified EL also supports value expressions, used to bind a field to a backing bean. Value
expressions use JavaBean naming conventions and expect a getter/setter pair. Often JSF expects
a value expression where only retrieval (get) is needed (e.g. the rendered attribute). Many objects,
however, don’t have appropriately named property accessors or require parameters.
JBoss EL removes this restriction by allowing values to be retrieved using the method syntax.
For example:

<h:outputText value=”#{person.name}” rendered=”#{person.name.length() > 5}” />

You can access the size of a collection in a similar manner:

#{searchResults.size()}

In general any expression of the form #{obj.property} would be identical to the expression

#{obj.getProperty()}.

Parameters are also allowed. The following example calls the productsByColorMethod with a literal string argument:

#{controller.productsByColor(‘blue’)}

Limitations and Hints: When using JBoss EL you should keep the following points in mind:
• Incompatibility with JSP 2.1 — JBoss EL can’t currently be used with JSP 2.1 as the compiler
rejects expressions with parameters in. So, if you want to use this extension with JSF 1.2, you
will need to use Facelets. The extension works correctly with JSP 2.0.

• Use inside iterative components — Components like <c:forEach /> and <ui:repeat />iterate
over a List or array, exposing each item in the list to nested components. This works great if
you are selecting a row using a <h:commandButton /> or <h:commandLink />:

@Factory(“items”)
public List<Item> getItems() {
return entityManager.createQuery(“select …”).getResultList();
}
<h:dataTable value=”#{items}” var=”item”>
<h:column>
<h:commandLink value=”Select #{item.name}” action=”#{itemSelector.select(item})” />
</h:column>
</h:dataTable>

However if you want to use <s:link /> or <s:button /> you must expose the items
as a DataModel, and use a <dataTable /> (or equivalent from a component set like
<rich:dataTable /> ). Neither <s:link /> or <s:button /> submit the form (and therefore
produce a bookmarkable link) so a “magic” parameter is needed to recreate the item when the
action method is called. This magic parameter can only be added when a data table backed by a DataModel is used.

• Calling a MethodExpression from Java code — Normally, when a MethodExpression is
created, the parameter types are passed in by JSF. In the case of a method binding, JSF
assumes that there are no parameters to pass. With this extension, we can’t know the parameter
types until after the expression has been evaluated. This has two minor consequences:
• When you invoke a MethodExpression in Java code, parameters you pass may be ignored.
Parameters defined in the expression will take precedence.
• Ordinarily, it is safe to call methodExpression.getMethodInfo().getParamTypes() at any
time. For an expression with parameters, you must first invoke the MethodExpression before
calling getParamTypes().
Both of these cases are exceedingly rare and only apply when you want to invoke the
MethodExpression by hand in Java code.

Projection: JBoss EL supports a limited projection syntax. A projection expression maps a sub-expression
across a multi-valued (list, set, etc…) expression. For instance, the expression:

#{company.departments}
might return a list of departments. If you only need a list of department names, your only option is
to iterate over the list to retrieve the values. JBoss EL allows this with a projection expression:
#{company.departments.{d|d.name}}
The subexpression is enclosed in braces. In this example, the expression d.name is evaluated
for each department, using d as an alias to the department object. The result of this expression
will be a list of String values.
Any valid expression can be used in an expression, so it would be perfectly valid to write the
following, assuming you had a use for the lengths of all the department names in a company:
#{company.departments.{d|d.size()}}
Projections can be nested. The following expression returns the last names of every employee
in every department:
#{company.departments.{d|d.employees.{emp|emp.lastName}}}
Nested projections can be slightly tricky, however. The following expression looks like it returns
a list of all the employees in all the departments:
#{company.departments.{d|d.employees}}
However, it actually returns a list containing a list of the employees for each individual department.
To combine the values, it is necessary to use a slightly longer expression:
#{company.departments.{d|d.employees.{e|e}}}
It is important to note that this syntax cannot be parsed by Facelets or JSP and thus cannot be
used in xhtml or JSP files. We anticipate that the projection syntax will change in future versions
of JBoss EL.

2) Hibernate (mapping, filter, listener, HQL)

3) Oracle 10g -> PL/SQL

4) Design Pattern -> Singleton, Service Locator, Delegate, Facade, DAO/DTO, Command, Decorator.

5) Struts(1.2,2.0), Spring, Spring-MVC.

6) Web Services -> REST, WSDL

7) JQuery, AJAX, JSON

8) Core Java (Collection, Thread(Synchronization), File Operation(Serialization), Exception Handling).

9) Spring (IOC, DI{ How to achieve DI without spring}, Transaction Management{Isolation Level}).

Ease of use
Thanks to the unwavering focus on ease of use, EJB 3 is probably the simplest server-side development platform around. The features that shine the brightest are POJO programming, annotations in favor of verbose XML, heavy use of sensible defaults, and JPA, all of which you will be learning about in this book.Although the number of EJB services is significant, you’ll find them very intuitive.For the most part, EJB 3 has a practical outlook and doesn’t demand that you understand the theoretical intricacies. 

Integrated solution stack
EJB 3 offers a complete stack of server solutions, including persistence, messaging,lightweight scheduling, remoting, web services, dependency injection (DI) and interceptors. This means that you won’t have to spend a lot of time looking for third-party tools to integrate into your application.In addition, EJB 3 provides seamless integration with other Java EE technologies, such as JDBC, JavaMail,Java Transaction API JTA (JTA), Java Messaging Service (JMS), Java Authentication and Authorization Service (JAAS), Java Naming and Directory Interface (JNDI),Java Remote Method Invocation (RMI) and so on.EJB is also guaranteed to seamlessly integrate with presentation-tier technologies like JavaServer Pages (JSP),servlets, JavaServer Faces (JSF) and Swing.

Open Java EE standard
EJB is a critical part of the Java EE standard. This is an extremely important concept to grasp if you are to adopt EJB 3. EJB 3 has an open, public API specification,which organizations are encouraged to use to create a container or persistence provider implementation. The EJB 3 standard is developed by the Java Community Process JCP) consisting of a nonexclusive group of individuals driving the Java standard.The open standard leads to broader vendor support for EJB 3, which means you don’t have to depend on a proprietary solution.

Broad vendor support
EJB is supported by a large and diverse variety of independent organizations.This includes the technology world’s largest, most respected, and most financially strong names, such as Oracle and IBM as well as passionate and energetic open source groups like JBoss and Geronimo.

Stable, high-quality code base
Although EJB 3 is a groundbreaking step, most application server implementations will still benefit from a relatively stable code base that has lived through some of the most demanding enterprise environments over a prolonged period of time.

Clustering, load balancing, and failover
Features historically added by most application server vendors are robust support for clustering, load balancing, and failover. EJB application servers have a proven track record of supporting some of the largest high-performance computing (HPC)-enabled server farm environments. More importantly, you can leverage such support with no changes to code, no third-party tool integration, and relatively simple configuration (beyond the inherent work in setting up a hardware cluster). This means that you can rely on hardware clustering to scale up your application with EJB 3 if you need to.

Understanding EJB types
EJB classifies beans into three types, based on what they are used for:
■ Session beans
■ Message-driven beans
■ Entities

Getting inside EJB
When you build a simple Java class, you need a Java Virtual Machine (JVM) to execute it. In a similar way (as you learned in the previous section) to execute session beans and MDBs you need an EJB container, and to run your entities you need a persistence provider.

Accessing EJB services: the EJB container
the container transparently provides EJB component services such as transactions, security management,remoting, and web services support. As a matter of fact, you might even think of the container as a JVM on steroids, whose purpose is to execute EJBs. In EJB 3, the container provides services applicable to session beans and MDBs only. The task of putting an EJB 3 component inside a container is called
deployment.

Accessing JPA services: the persistence provider
Instead of following the JVM-like container model, JPA follows a model similar to APIs, like JDBC. JPA provides persistence services such as retrieving, adding, modifying, and deleting JPA entities when you explicitly ask for them by invoking EntityManager API methods.
The “provider” terminology comes from APIs such as JDBC and JNDI too. you know that a “provider” is essentially the vendor implementation that the JDBC API uses under the covers.Similarly Products that provide JPA implementation are called persistence providers or persistence engines.JBoss Hibernate and Oracle TopLink are two popular JPA providers.
Since JPA is completely pluggable and separable, the persistence provider and container in an EJB 3 solution need not come from the same vendor.For example,you could use Hibernate inside a BEA WebLogic container if it suits you better,instead of the Kodo implementation WebLogic ships with.

Gaining functionality with EJB services

Integration -> Session beans and MDBs ->
Helps glue together components, ideally through simple configuration instead of code. In EJB 3, this is done through dependency injection (DI) as well as lookup.
Pooling -> Stateless session beans, MDBs ->
For each EJB component, the EJB platform creates a pool of component instances that are shared by clients. At any point in time, each pooled instance is only allowed to be used by a single client. As soon as an instance is finished servicing a client,it is returned to the pool for reuse instead of being frivolously discarded for the garbage collector to reclaim.
Thread-safety -> Session beans and MDBs ->
EJB makes all components thread-safe and highly performant in ways that are completely invisible. This means that you can write your server components as if you were developing a single-threaded desktop
application. It doesn’t matter how complex the component itself is;
EJB will make sure it is thread-safe.
State management -> Stateful session beans ->
The EJB container manages state transparently for stateful components
instead of having you write verbose and error-prone code for state management.This means that you can maintain state in instance variables as if you were developing a desktop application. EJB takes care of all the details of session maintenance behind the scenes.
Messaging -> MDBs ->
EJB 3 allows you to write messaging-aware components without having
to deal with a lot of the mechanical details of the Java Messaging
Service (JMS) API.
Transactions -> Session beans and MDB ->
EJB supports declarative transaction management that helps you add transactional behavior to components using simple configuration instead of code.In effect, you can designate any component method to be transactional.If the method completes normally, EJB commits the transaction and makes the data changes made by the method permanent.Otherwise the transaction is rolled back.
Security -> Session beans ->
EJB supports integration with the Java Authentication and Authorization Service (JAAS) API, so it is very easy to completely externalize security and secure an application using simple configuration instead of cluttering up your application with security code.
Interceptors -> Session beans and MDBs ->
EJB 3 introduces AOP in a very lightweight, accessible manner using interceptors. This allows you to easily separate out crosscutting concerns such as logging, auditing, and so on in a configurable way.
Remote access -> Session beans ->
In EJB 3, you can make components remotely accessible without writing
any code. In addition, EJB 3 enables client code to access remote components as if they were local components using DI.
Web services -> Stateless session beans ->
EJB 3 can transparently turn business components into robust web services with minimal code change.
Persistence -> Entities ->
Providing standards-based, 100 percent configurable automated persistence as an alternative to verbose and error-prone JDBC/SQL code is a principal goal of the EJB 3 platform.
Caching and performance -> Entities ->
In addition to automating persistence, JPA transparently provides a number of services geared toward data caching, performance optimization and application tuning. These services are invaluable in supporting medium to large-scale systems.

New features: simplifying EJB
There are three primary sources of complexities in EJB 2:the heavyweight programming model, direct use of the Java Naming Directory Interface (JNDI) and a verbose XML deployment descriptor.
Three primary techniques in EJB 3 eliminate these sources of complexity: metadata annotations, minimal deployment descriptors and dependency injection.

Replacing deployment descriptors with annotations
annotations simplify the EJB programming model, remove the need for detailed deployment descriptors and act as an effective delivery mechanism for dependency injection.
Java metadata annotations: a brief primer
Annotations essentially allow us to “attach” additional information (officially called attributes) to a Java class, interface, method, or variable.The additional information conveyed by annotations can be used by a development environment like Eclipse, the Java compiler, a deployment tool, a persistence provider like Hibernate or a runtime environment like the Java EE container.Another way to think about annotations is that they are “custom” Java modifiers (in addition to private,public, static, final, and so on) that can be used by anything handling Java source or byte code.This is how annotations look:

import mypackage.Author;
@Author(“Debu Panda, Reza Rahman and Derek Lane”)
public class EJB3InAction implements ManningBook

Note that, just like anything else, annotations and attribute-oriented programming have a few weaknesses.Specifically, it isn’t always a good idea to mix and match configuration with source code such as annotations.This means that you would have to change source code each time you made a configuration change to something like a database connection resource or deployment environment entry.EJB 3 solves this problem by allowing you to override annotations with XML
deployment descriptors where appropriate.

Know your deployment descriptor
A deployment descriptor is simply an XML file that contains application configuration information.Every deployment unit in Java EE can have a deployment descriptor that describes its contents and environment. Some typical examples of deployment units are the Enterprise Archive (EAR), Web Application Archive (WAR), and the EJB (ejb-jar) module.
We know in EJB 2, how verbose the XML (ejb-jar.xml) descriptor was.
Most elements were required even if they were trivial. Ex:

HelloUserBean
ejb3inaction.example.Hello
ejb3inaction.example.HelloUserBean
Stateless
Container

The EJB 3 makes deployment descriptors completely optional.

Mixing annotations and deployment descriptors