<s:link>
and <s:button>
Seam is an application framework for Enterprise Java. It is inspired by the following principles:
Seam defines a uniform component model for all business logic in your application. A Seam component may be stateful, with the state associated with any one of several well-defined contexts, including the long-running, persistent, business process context and the conversation context, which is preserved across multiple web requests in a user interaction.
There is no distinction between presentation tier components and business logic components in Seam. You can layer your application according to whatever architecture you devise, rather than being forced to shoehorn your application logic into an unnatural layering scheme forced upon you by whatever combination of stovepipe frameworks you're using today.
Unlike plain Java EE or J2EE components, Seam components may simultaneously access state associated with the web request and state held in transactional resources (without the need to propagate web request state manually via method parameters). You might object that the application layering imposed upon you by the old J2EE platform was a Good Thing. Well, nothing stops you creating an equivalent layered architecture using Seam — the difference is that you get to architect your own application and decide what the layers are and how they work together.
JSF and EJB 3.0 are two of the best new features of Java EE 5. EJB3 is a brand new component model for server side business and persistence logic. Meanwhile, JSF is a great component model for the presentation tier. Unfortunately, neither component model is able to solve all problems in computing by itself. Indeed, JSF and EJB3 work best used together. But the Java EE 5 specification provides no standard way to integrate the two component models. Fortunately, the creators of both models foresaw this situation and provided standard extension points to allow extension and integration with other frameworks.
Seam unifies the component models of JSF and EJB3, eliminating glue code, and letting the developer think about the business problem.
It is possible to write Seam applications where "everything" is an EJB. This may come as a surprise if you're used to thinking of EJBs as coarse-grained, so-called "heavyweight" objects. However, version 3.0 has completely changed the nature of EJB from the point of view of the developer. An EJB is a fine-grained object — nothing more complex than an annotated JavaBean. Seam even encourages you to use session beans as JSF action listeners!
On the other hand, if you prefer not to adopt EJB 3.0 at this time, you don't have to. Virtually any Java class may be a Seam component, and Seam provides all the functionality that you expect from a "lightweight" container, and more, for any component, EJB or otherwise.
Seam supports the best open source JSF-based AJAX solutions: JBoss RichFaces and ICEfaces. These solutions let you add AJAX capability to your user interface without the need to write any JavaScript code.
Alternatively, Seam provides a built-in JavaScript remoting layer that lets you call components asynchronously from client-side JavaScript without the need for an intermediate action layer. You can even subscribe to server-side JMS topics and receive messages via AJAX push.
Neither of these approaches would work well, were it not for Seam's built-in concurrency and state management, which ensures that many concurrent fine-grained, asynchronous AJAX requests are handled safely and efficiently on the server side.
Optionally, Seam provides transparent business process management via jBPM. You won't believe how easy it is to implement complex workflows, collaboration and and task management using jBPM and Seam.
Seam even allows you to define presentation tier pageflow using the same language (jPDL) that jBPM uses for business process definition.
JSF provides an incredibly rich event model for the presentation tier. Seam enhances this model by exposing jBPM's business process related events via exactly the same event handling mechanism, providing a uniform event model for Seam's uniform component model.
We're all used to the concept of declarative transaction management and declarative security from the early days of EJB. EJB 3.0 even introduces declarative persistence context management. These are three examples of a broader problem of managing state that is associated with a particular context, while ensuring that all needed cleanup occurs when the context ends. Seam takes the concept of declarative state management much further and applies it to application state. Traditionally, J2EE applications implement state management manually, by getting and setting servlet session and request attributes. This approach to state management is the source of many bugs and memory leaks when applications fail to clean up session attributes, or when session data associated with different workflows collides in a multi-window application. Seam has the potential to almost entirely eliminate this class of bugs.
Declarative application state management is made possible by the richness of the context model defined by Seam. Seam extends the context model defined by the servlet spec — request, session, application — with two new contexts — conversation and business process — that are more meaningful from the point of view of the business logic.
You'll be amazed at how many things become easier once you start using conversations.
Have you ever suffered pain dealing with lazy association fetching in an ORM solution
like Hibernate or JPA? Seam's conversation-scoped persistence contexts mean you'll
rarely have to see a LazyInitializationException
. Have you ever
had problems with the refresh button? The 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.
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.
Seam applications let the user freely switch between multiple browser tabs, each associated with a different, safely isolated, conversation. Applications may even take advantage of workspace management, allowing the user to switch between conversations (workspaces) in a single browser tab. Seam provides not only correct multi-window operation, but also multi-window-like operation in a single window!
Traditionally, the Java community has been in a state of deep confusion about precisely what kinds of meta-information counts as configuration. J2EE and popular "lightweight" containers have provided XML-based deployment descriptors both for things which are truly configurable between different deployments of the system, and for any other kinds or declaration which can not easily be expressed in Java. Java 5 annotations changed all this.
EJB 3.0 embraces annotations and "configuration by exception" as the easiest way to provide information to the container in a declarative form. Unfortunately, JSF is still heavily dependent on verbose XML configuration files. Seam extends the annotations provided by EJB 3.0 with a set of annotations for declarative state management and declarative context demarcation. This lets you eliminate the noisy JSF managed bean declarations and reduce the required XML to just that information which truly belongs in XML (the JSF navigation rules).
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.
We think the latest incarnation of Java EE is great. But we know it's never going to be perfect. Where there are holes in the specifications (for example, limitations in the JSF lifecycle for GET requests), Seam fixes them. And the authors of Seam are working with the JCP expert groups to make sure those fixes make their way back into the next revision of the standards.
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.
Seam works in any Java EE application server, and even works in Tomcat. If your environment supports EJB 3.0, great! If it doesn't, no problem, you can use Seam's built-in transaction management with JPA or Hibernate3 for persistence. Or, you can deploy JBoss Embedded in Tomcat, and get full support for EJB 3.0.
It turns out that the combination of Seam, JSF and EJB3 is the simplest way to write a complex web application in Java. You won't believe how little code is required!
Visit SeamFramework.org to find out how to contribute to Seam!
Seam provides a number of example applications demonstrating how to use the various features
of Seam. This tutorial will guide you through a few of those examples to help you get started
learning Seam. The Seam examples are located in the examples
subdirectory
of the Seam distribution. The registration example, which will be the first example we look at,
is in the examples/registration
directory.
Each example has the same directory structure:
The view
directory contains view-related files such as
web page templates, images and stylesheets.
The resources
directory contains deployment descriptors and
other configuration files.
The src
directory contains the application source code.
The example applications run both on JBoss AS and Tomcat with no additional configuration.
The following sections will explain the procedure in both cases. Note that all the examples
are built and run from the Ant build.xml
, so you'll need a recent version
of Ant installed before you get started.
The examples are configured for use on JBoss AS 4.2 or 5.0. You'll need to set jboss.home
,
in the shared build.properties
file in the root folder of your Seam
installation, to the location of your JBoss AS installation.
Once you've set the location of JBoss AS and started the application server, you can build and deploy
any example by typing ant explode
in the the directory for that example. Any example
that is packaged as an EAR deploys to a URL like
/seam-
, where example
example
is
the name of the example folder, with one exception. If the example folder begins with seam, the prefix
"seam" is ommitted. For instance, if JBoss AS is running on port 8080, the URL for the registration
example is
http://localhost:8080/seam-registration/
, whereas the URL for the seamspace
example is
http://localhost:8080/seam-space/
.
If, on the other hand, the example gets packaged as a WAR, then it deploys to a URL like
/jboss-seam-
. Most of the examples can be deployed as a WAR
to Tomcat with Embedded JBoss by typing example
ant tomcat.deploy
. Several of the examples
can only be deployed as a WAR. Those examples are groovybooking, hibernate, jpa, and spring.
The examples are also configured for use on Tomcat 6.0. You will need to follow the instructions in Section 30.6.1, “Installing Embedded JBoss” for installing JBoss Embedded on Tomcat 6.0. JBoss Embedded is only required to run the Seam demos that use EJB3 components on Tomcat. There are also examples of non-EJB3 applications that can be run on Tomcat without the use of JBoss Embedded.
You'll need to
set tomcat.home
, in the shared build.properties
file in
the root folder of your Seam installation, to the location of your Tomcat installation.
make sure you set the location of your Tomcat.
You'll need to use a different Ant target when using Tomcat. Use
ant tomcat.deploy
in example subdirectory to build and deploy
any example for Tomcat.
On Tomcat, the examples deploy to URLs like
/jboss-seam-
, so for the registration
example the URL would be
example
http://localhost:8080/jboss-seam-registration/
. The same is true
for examples that deploy as a WAR, as mentioned in the previous section.
Most of the examples come with a suite of TestNG integration tests. The easiest way to run the tests is
to run ant test
. It is also possible to run the tests inside your IDE using the
TestNG plugin. Consult the readme.txt in the examples directory of the Seam distribution for more
information.
The registration example is a simple application that lets a new user store his username, real name and password in the database. The example isn't intended to show off all of the cool functionality of Seam. However, it demonstrates the use of an EJB3 session bean as a JSF action listener, and basic configuration of Seam.
We'll go slowly, since we realize you might not yet be familiar with EJB 3.0.
The start page displays a very basic form with three input fields. Try filling them in and then submitting the form. This will save a user object in the database.
The example is implemented with two Facelets templates, one entity bean and one stateless session bean. Let's take a look at the code, starting from the "bottom".
We need an EJB entity bean for user data. This class defines persistence and validation declaratively, via annotations. It also needs some extra annotations that define the class as a Seam component.
Example 1.1. User.java
@Entity
@Name("user")
@Scope(SESSION)
@Table(name="users")
public class User implements Serializable
{
private static final long serialVersionUID = 1881413500711441951L;
private String username;
private String password;
private String name;
public User(String name, String password, String username)
{
this.name = name;
this.password = password;
this.username = username;
}
public User() {}
@NotNull @Length(min=5, max=15)
public String getPassword()
{
return password;
}
public void setPassword(String password)
{
this.password = password;
}
@NotNull
public String getName()
{
return name;
}
public void setName(String name)
{
this.name = name;
}
@Id @NotNull @Length(min=5, max=15)
public String getUsername()
{
return username;
}
public void setUsername(String username)
{
this.username = username;
}
}
![]() | The EJB3 standard |
![]() | A Seam component needs a component name specified by the
|
![]() | Whenever Seam instantiates a component, it binds the new instance to a context
variable in the component's default context. The default
context is specified using the
|
![]() | The EJB standard |
![]() |
|
![]() | An empty constructor is both required by both the EJB specification and by Seam. |
![]() | The |
![]() | The EJB standard |
The most important things to notice in this example are the @Name
and
@Scope
annotations. These annotations establish that this class is a Seam component.
We'll see below that the properties of our User
class are bound
directly to JSF components and are populated by JSF during the update model values phase. We
don't need any tedious glue code to copy data back and forth between the JSP pages and the
entity bean domain model.
However, entity beans shouldn't do transaction management or database access. So we can't use this component as a JSF action listener. For that we need a session bean.
Most Seam application use session beans as JSF action listeners (you can use JavaBeans instead if you like).
We have exactly one JSF action in our application, and one session bean method attached to it. In
this case, we'll use a stateless session bean, since all the state associated with our action is
held by the User
bean.
This is the only really interesting code in the example!
Example 1.2. RegisterAction.java
@Stateless@Name("register") public class RegisterAction implements Register { @In private Use
r user; @PersistenceContext private Ent
ityManager em; @Logger private Log
log; public String register() {
List existing = em.createQuery( "select username from User where username = #{user.username}") .getR
esultList(); if (existing.size()==0) { em.persist(user); log.info("Registered new user #{user.username}"); retur
n "/registered.xhtml"; }
else { FacesMessages.instance().add("User #{user.username} already exists"); retur
n null; } } }
![]() | The EJB |
![]() | The
|
![]() | The EJB standard |
![]() | The Seam |
![]() | The action listener method uses the standard EJB3
|
![]() | Notice that Seam lets you use a JSF EL expression inside EJB-QL. Under the
covers, this results in an ordinary JPA |
![]() | The |
![]() | JSF action listener methods return a string-valued outcome that determines what page will be displayed next. A null outcome (or a void action listener method) redisplays the previous page. In plain JSF, it is normal to always use a JSF navigation rule to determine the JSF view id from the outcome. For complex application this indirection is useful and a good practice. However, for very simple examples like this one, Seam lets you use the JSF view id as the outcome, eliminating the requirement for a navigation rule. Note that when you use a view id as an outcome, Seam always performs a browser redirect. |
![]() | Seam provides a number of built-in components to help solve
common problems. The |
Note that we did not explicitly specify a @Scope
this time. Each Seam
component type has a default scope if not explicitly specified. For stateless session beans, the
default scope is the stateless context, which is the only sensible value.
Our session bean action listener performs the business and persistence logic for our mini-application. In more complex applications, we might need require a separate service layer. This is easy to achieve with Seam, but it's overkill for most web applications. Seam does not force you into any particular strategy for application layering, allowing your application to be as simple, or as complex, as you want.
Note that in this simple application, we've actually made it far more complex than it needs to be. If we had used the Seam application framework controllers, we would have eliminated all of our application code. However, then we wouldn't have had much of an application to explain.
Naturally, our session bean needs a local interface.
That's the end of the Java code. Now we'll look at the view.
The view pages for a Seam application could be implemented using any technology that supports JSF. In this example we use Facelets, because we think it's better than JSP.
Example 1.4. register.xhtml
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:s="http://jboss.com/products/seam/taglib"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:f="http://java.sun.com/jsf/core">
<head>
<title>Register New User</title>
</head>
<body>
<f:view>
<h:form>
<s:validateAll>
<h:panelGrid columns="2">
Username: <h:inputText value="#{user.username}" required="true"/>
Real Name: <h:inputText value="#{user.name}" required="true"/>
Password: <h:inputSecret value="#{user.password}" required="true"/>
</h:panelGrid>
</s:validateAll>
<h:messages/>
<h:commandButton value="Register" action="#{register.register}"/>
</h:form>
</f:view>
</body>
</html>
The only thing here that is specific to Seam is the
<s:validateAll>
tag. This JSF component tells JSF to validate all
the contained input fields against the Hibernate Validator annotations specified on the entity bean.
Example 1.5. registered.xhtml
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:f="http://java.sun.com/jsf/core">
<head>
<title>Successfully Registered New User</title>
</head>
<body>
<f:view>
Welcome, #{user.name}, you are successfully registered as #{user.username}.
</f:view>
</body>
</html>
This is a simple Facelets page using some inline EL. There's nothing specific to Seam here.
Since this is the first Seam app we've seen, we'll take a look at the deployment descriptors. Before we get into them, it is worth noting that Seam strongly values minimal configuration. These configuration files will be created for you when you create a Seam application. You'll never need to touch most of these files. We're presenting them now only to help you understand what all the pieces in the example are doing.
If you've used many Java frameworks before, you'll be used to having to declare all your component classes in some kind of XML file that gradually grows more and more unmanageable as your project matures. You'll be relieved to know that Seam does not require that application components be accompanied by XML. Most Seam applications require a very small amount of XML that does not grow very much as the project gets bigger.
Nevertheless, it is often useful to be able to provide for some external
configuration of some components (particularly the components built in to
Seam). You have a couple of options here, but the most flexible option is to provide this
configuration in a file called components.xml
, located in the
WEB-INF
directory. We'll use the components.xml
file to tell
Seam how to find our EJB components in JNDI:
Example 1.6. components.xml
<?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.2.xsd
http://jboss.com/products/seam/components
http://jboss.com/products/seam/components-2.2.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,
which it reads from the components.properties file. You learn more about how this process works in
Section 5.2, “Configuring components via components.xml
”.
The presentation layer for our mini-application will be deployed in a WAR. So we'll need a web deployment descriptor.
Example 1.7. web.xml
<?xml version="1.0" encoding="UTF-8"?>
<web-app 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"
version="2.5">
<listener>
<listener-class>org.jboss.seam.servlet.SeamListener</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.
Most Seam applications use JSF views as the presentation layer. So usually we'll need
faces-config.xml
. In our case, we are going to use Facelets for
defining our views, so we need to tell JSF to use Facelets as its templating engine.
Example 1.8. faces-config.xml
<?xml version="1.0" encoding="UTF-8"?>
<faces-config 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"
version="1.2">
<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. Here, we are simply
using it to enable Facelets as the view handler instead of JSP.
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's stand is that process flow and configuration data are the only things that truly belong in XML.
In this simple example, we don't even need a navigation rule, since we decided to embed the view id in our action code.
The ejb-jar.xml
file integrates Seam with EJB3, by attaching the
SeamInterceptor
to all session beans in the archive.
<?xml version="1.0" encoding="UTF-8"?>
<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>
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>
Finally, since our application is deployed as an EAR, we need a deployment descriptor there, too.
Example 1.9. registration application
<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/application_5.xsd"
version="5">
<display-name>Seam Registration</display-name>
<module>
<web>
<web-uri>jboss-seam-registration.war</web-uri>
<context-root>/seam-registration</context-root>
</web>
</module>
<module>
<ejb>jboss-seam-registration.jar</ejb>
</module>
<module>
<ejb>jboss-seam.jar</ejb>
</module>
<module>
<java>jboss-el.jar</java>
</module>
</application>
This deployment descriptor links modules in the enterprise archive and binds the web application
to the context root /seam-registration
.
We've now seen all the files in the entire application!
When the form is submitted, JSF asks Seam to resolve the variable named user
.
Since there is no value already bound to that name (in any Seam context), Seam instantiates the
user
component, and returns the resulting User
entity bean
instance to JSF after storing it in the Seam session context.
The form input values are now validated against the Hibernate Validator constraints specified on the
User
entity. If the constraints are violated, JSF redisplays the page. Otherwise,
JSF binds the form input values to properties of the User
entity bean.
Next, JSF asks Seam to resolve the variable named register
. Seam uses the JNDI
pattern mentioned earlier to locate the stateless session bean, wraps it as a Seam component, and
returns it. Seam then presents this component to JSF and JSF invokes the register()
action listener method.
But Seam is not done yet. Seam intercepts the method call and injects the User
entity from the Seam session context, before allowing the invocation to continue.
The register()
method checks if a user with the entered username already exists.
If so, an error message is queued with the FacesMessages
component, and a null
outcome is returned, causing a page redisplay. The FacesMessages
component
interpolates the JSF expression embedded in the message string and adds a JSF
FacesMessage
to the view.
If no user with that username exists, the "/registered.xhtml"
outcome triggers a
browser redirect to the registered.xhtml
page. When JSF comes to render the page, it
asks Seam to resolve the variable named user
and uses property values of the returned
User
entity from Seam's session scope.
Clickable lists of database search results are such an important part of any online application that Seam
provides special functionality on top of JSF to make it easier to query data using EJB-QL or HQL and display
it as a clickable list using a JSF <h:dataTable>
. The messages example
demonstrates this functionality.
The message list example has one entity bean, Message
, one session bean,
MessageListBean
and one JSP.
The Message
entity defines the title, text, date and time of a message, and a
flag indicating whether the message has been read:
Example 1.10. Message.java
@Entity
@Name("message")
@Scope(EVENT)
public class Message implements Serializable
{
private Long id;
private String title;
private String text;
private boolean read;
private Date datetime;
@Id @GeneratedValue
public Long getId()
{
return id;
}
public void setId(Long id)
{
this.id = id;
}
@NotNull @Length(max=100)
public String getTitle()
{
return title;
}
public void setTitle(String title)
{
this.title = title;
}
@NotNull @Lob
public String getText()
{
return text;
}
public void setText(String text)
{
this.text = text;
}
@NotNull
public boolean isRead()
{
return read;
}
public void setRead(boolean read)
{
this.read = read;
}
@NotNull
@Basic @Temporal(TemporalType.TIMESTAMP)
public Date getDatetime()
{
return datetime;
}
public void setDatetime(Date datetime)
{
this.datetime = datetime;
}
}
Just like in the previous example, we have a session bean, MessageManagerBean
,
which defines the action listener methods for the two buttons on our form. One of the buttons
selects a message from the list, and displays that message. The other button deletes a message. So
far, this is not so different to the previous example.
But MessageManagerBean
is also responsible for fetching the list of messages
the first time we navigate to the message list page. There are various ways the user could navigate
to the page, and not all of them are preceded by a JSF action — the user might have
bookmarked the page, for example. So the job of fetching the message list takes place in a Seam
factory method, instead of in an action listener method.
We want to cache the list of messages in memory between server requests, so we will make this a stateful session bean.
Example 1.11. MessageManagerBean.java
@Stateful @Scope(SESSION) @Name("messageManager") public class MessageManagerBean implements Serializable, MessageManager { @DataModel private List<Message> messageList; @DataModelSelection @Out(requir
ed=false) private Mes
sage message; @PersistenceContext(type=EXTENDED) private Ent
ityManager em; @Factory("messageList") public void
findMessages() { messageList = em.createQuery("select msg from Message msg order by msg.datetime desc") .getResultList(); } public void select() {
message.setRead(true); } public void delete() {
messageList.remove(message); em.remove(message); message=null; } @Remove public void
destroy() {} }
![]() | The |
![]() | The |
![]() | The |
![]() | This stateful bean has an EJB3 extended persistence context.
The messages retrieved in the query remain in the managed state as long as the bean
exists, so any subsequent method calls to the stateful bean can update them without
needing to make any explicit call to the |
![]() | The first time we navigate to the JSP page, there will be no value in the
|
![]() | The |
![]() | The |
![]() | All stateful session bean Seam components must have a method
with no parameters marked |
Note that this is a session-scoped Seam component. It is associated with the user login session, and all requests from a login session share the same instance of the component. (In Seam applications, we usually use session-scoped components sparingly.)
All session beans have a business interface, of course.
Example 1.12. MessageManager.java
@Local
public interface MessageManager
{
public void findMessages();
public void select();
public void delete();
public void destroy();
}
From now on, we won't show local interfaces in our code examples.
Let's skip over components.xml
, persistence.xml
,
web.xml
, ejb-jar.xml
, faces-config.xml
and application.xml
since they are much the same as the previous example, and go
straight to the JSP.
The JSP page is a straightforward use of the JSF <h:dataTable>
component. Again, nothing specific to Seam.
Example 1.13. messages.jsp
<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<html>
<head>
<title>Messages</title>
</head>
<body>
<f:view>
<h:form>
<h2>Message List</h2>
<h:outputText value="No messages to display"
rendered="#{messageList.rowCount==0}"/>
<h:dataTable var="msg" value="#{messageList}"
rendered="#{messageList.rowCount>0}">
<h:column>
<f:facet name="header">
<h:outputText value="Read"/>
</f:facet>
<h:selectBooleanCheckbox value="#{msg.read}" disabled="true"/>
</h:column>
<h:column>
<f:facet name="header">
<h:outputText value="Title"/>
</f:facet>
<h:commandLink value="#{msg.title}" action="#{messageManager.select}"/>
</h:column>
<h:column>
<f:facet name="header">
<h:outputText value="Date/Time"/>
</f:facet>
<h:outputText value="#{msg.datetime}">
<f:convertDateTime type="both" dateStyle="medium" timeStyle="short"/>
</h:outputText>
</h:column>
<h:column>
<h:commandButton value="Delete" action="#{messageManager.delete}"/>
</h:column>
</h:dataTable>
<h3><h:outputText value="#{message.title}"/></h3>
<div><h:outputText value="#{message.text}"/></div>
</h:form>
</f:view>
</body>
</html>
The first time we navigate to the messages.jsp
page, the page will try to resolve the
messageList
context variable. Since this context variable is not initialized,
Seam will call the factory method findMessages()
, which performs a query against the
database and results in a DataModel
being outjected. This
DataModel
provides the row data needed for rendering the
<h:dataTable>
.
When the user clicks the <h:commandLink>
, JSF calls the
select()
action listener. Seam intercepts this call and injects the selected row
data into the message
attribute of the messageManager
component.
The action listener fires, marking the selected Message
as read. At the end of the
call, Seam outjects the selected Message
to the context variable named
message
. Next, the EJB container commits the transaction, and the change to the
Message
is flushed to the database. Finally, the page is re-rendered,
redisplaying the message list, and displaying the selected message below it.
If the user clicks the <h:commandButton>
, JSF calls the
delete()
action listener. Seam intercepts this call and injects the selected row
data into the message
attribute of the messageList
component. The
action listener fires, removing the selected Message
from the list, and also calling
remove()
on the EntityManager
. At the end of the call, Seam
refreshes the messageList
context variable and clears the context variable named
message
. The EJB container commits the transaction, and deletes the
Message
from the database. Finally, the page is re-rendered, redisplaying the
message list.
jBPM provides sophisticated functionality for workflow and task management. To get a small taste of how jBPM integrates with Seam, we'll show you a simple "todo list" application. Since managing lists of tasks is such core functionality for jBPM, there is hardly any Java code at all in this example.
The center of this example is the jBPM process definition. There are also two JSPs and two trivial JavaBeans (There was no reason to use session beans, since they do not access the database, or have any other transactional behavior). Let's start with the process definition:
Example 1.14. todo.jpdl.xml
<process-definition name="todo"> <start-state name="start"> <transition to="todo"/> </start-state> <task-node
name="todo"> <task na
me="todo" description="#{todoList.description}"> <assi
gnment actor-id="#{actor.id}"/> </task> <transition to="done"/> </task-node> <end-state
name="done"/> </process-definition>
![]() | The |
![]() | The |
![]() | The |
![]() | Tasks need to be assigned to a user or group of users when they are created. In this
case, the task is assigned to the current user, which we get from a built-in Seam
component named |
![]() | The |
If we view this process definition using the process definition editor provided by JBossIDE, this is what it looks like:
This document defines our business process as a graph of nodes. This is the most trivial possible business process: there is one task to be performed, and when that task is complete, the business process ends.
The first JavaBean handles the login screen login.jsp
. Its job is just to
initialize the jBPM actor id using the actor
component. In a real application, it
would also need to authenticate the user.
Example 1.15. Login.java
@Name("login")
public class Login
{
@In
private Actor actor;
private String user;
public String getUser()
{
return user;
}
public void setUser(String user)
{
this.user = user;
}
public String login()
{
actor.setId(user);
return "/todo.jsp";
}
}
Here we see the use of @In
to inject the built-in Actor
component.
The JSP itself is trivial:
Example 1.16. login.jsp
<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<html>
<head>
<title>Login</title>
</head>
<body>
<h1>Login</h1>
<f:view>
<h:form>
<div>
<h:inputText value="#{login.user}"/>
<h:commandButton value="Login" action="#{login.login}"/>
</div>
</h:form>
</f:view>
</body>
</html>
The second JavaBean is responsible for starting business process instances, and ending tasks.
Example 1.17. TodoList.java
@Name("todoList") public class TodoList { private String description; public String getDescription() { return description; } public void setDescription(String description) { this.description = description; }
@CreateProcess(definition="todo") public void createTodo() {}
@StartTask @EndTask public void done() {} }
![]() | The description property accepts user input from the JSP page, and exposes it to the process definition, allowing the task description to be set. |
![]() | The Seam |
![]() | The Seam |
In a more realistic example, @StartTask
and @EndTask
would not
appear on the same method, because there is usually work to be done using the application in order to
complete the task.
Finally, the core of the application is in todo.jsp
:
Example 1.18. todo.jsp
<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<%@ taglib uri="http://jboss.com/products/seam/taglib" prefix="s" %>
<html>
<head>
<title>Todo List</title>
</head>
<body>
<h1>Todo List</h1>
<f:view>
<h:form id="list">
<div>
<h:outputText value="There are no todo items."
rendered="#{empty taskInstanceList}"/>
<h:dataTable value="#{taskInstanceList}" var="task"
rendered="#{not empty taskInstanceList}">
<h:column>
<f:facet name="header">
<h:outputText value="Description"/>
</f:facet>
<h:inputText value="#{task.description}"/>
</h:column>
<h:column>
<f:facet name="header">
<h:outputText value="Created"/>
</f:facet>
<h:outputText value="#{task.taskMgmtInstance.processInstance.start}">
<f:convertDateTime type="date"/>
</h:outputText>
</h:column>
<h:column>
<f:facet name="header">
<h:outputText value="Priority"/>
</f:facet>
<h:inputText value="#{task.priority}" style="width: 30"/>
</h:column>
<h:column>
<f:facet name="header">
<h:outputText value="Due Date"/>
</f:facet>
<h:inputText value="#{task.dueDate}" style="width: 100">
<f:convertDateTime type="date" dateStyle="short"/>
</h:inputText>
</h:column>
<h:column>
<s:button value="Done" action="#{todoList.done}" taskInstance="#{task}"/>
</h:column>
</h:dataTable>
</div>
<div>
<h:messages/>
</div>
<div>
<h:commandButton value="Update Items" action="update"/>
</div>
</h:form>
<h:form id="new">
<div>
<h:inputText value="#{todoList.description}"/>
<h:commandButton value="Create New Item" action="#{todoList.createTodo}"/>
</div>
</h:form>
</f:view>
</body>
</html>
Let's take this one piece at a time.
The page renders a list of tasks, which it gets from a built-in Seam component named
taskInstanceList
. The list is defined inside a JSF form.
Example 1.19. todo.jsp
<h:form id="list">
<div>
<h:outputText value="There are no todo items." rendered="#{empty taskInstanceList}"/>
<h:dataTable value="#{taskInstanceList}" var="task"
rendered="#{not empty taskInstanceList}">
...
</h:dataTable>
</div>
</h:form>
Each element of the list is an instance of the jBPM class TaskInstance
. The
following code simply displays the interesting properties of each task in the list. For the description,
priority and due date, we use input controls, to allow the user to update these values.
<h:column>
<f:facet name="header">
<h:outputText value="Description"/>
</f:facet>
<h:inputText value="#{task.description}"/>
</h:column>
<h:column>
<f:facet name="header">
<h:outputText value="Created"/>
</f:facet>
<h:outputText value="#{task.taskMgmtInstance.processInstance.start}">
<f:convertDateTime type="date"/>
</h:outputText>
</h:column>
<h:column>
<f:facet name="header">
<h:outputText value="Priority"/>
</f:facet>
<h:inputText value="#{task.priority}" style="width: 30"/>
</h:column>
<h:column>
<f:facet name="header">
<h:outputText value="Due Date"/>
</f:facet>
<h:inputText value="#{task.dueDate}" style="width: 100">
<f:convertDateTime type="date" dateStyle="short"/>
</h:inputText>
</h:column>
#{task.dueDate}
. This button ends the task by calling the action method annotated @StartTask
@EndTask
. It passes the task id to Seam as a request parameter:
<h:column>
<s:button value="Done" action="#{todoList.done}" taskInstance="#{task}"/>
</h:column>
Note that this is using a Seam <s:button>
JSF control from the
seam-ui.jar
package. This button is used to update the properties of the
tasks. When the form is submitted, Seam and jBPM will make any changes to the tasks persistent.
There is no need for any action listener method:
<h:commandButton value="Update Items" action="update"/>
A second form on the page is used to create new items, by calling the action method annotated
@CreateProcess
.
<h:form id="new">
<div>
<h:inputText value="#{todoList.description}"/>
<h:commandButton value="Create New Item" action="#{todoList.createTodo}"/>
</div>
</h:form>
After logging in, todo.jsp uses the taskInstanceList
component to display a table
of outstanding todo items for a the current user. Initially there are none. It
also presents a form to enter a new entry. When the user types the todo item and
hits the "Create New Item" button, #{todoList.createTodo}
is called. This starts
the todo process, as defined in todo.jpdl.xml
.
The process instance is created, starting in the start state and immediately transition to
the todo
state, where a new task is created. The task description is set
based on the user's
input, which was saved to #{todoList.description}
. Then, the task is
assigned to
the current user, which was stored in the seam actor component. Note that in
this example, the process has no extra process state. All the state in this example
is stored in the task definition. The process and task information is stored in the database
at the end of the request.
When todo.jsp
is redisplayed, taskInstanceList
now finds
the task that was just created.
The task is shown in an h:dataTable
. The internal state of the task is
displayed in
each column: #{task.description}
, #{task.priority}
,
#{task.dueDate}
, etc... These fields
can all be edited and saved back to the database.
Each todo item also has "Done" button, which calls #{todoList.done}
. The
todoList
component
knows which task the button is for because each s:button specificies
taskInstance="#{task}"
, referring
to the task for that particular line of of the table. The @StartTast
and
@EndTask
annotations
cause seam to make the task active and immediately complete the task. The original process then
transitions into the done
state, according to the process definition, where it ends.
The state of the task and process are both updated in the database.
When todo.jsp
is displayed again, the now-completed task is no longer
displayed in the
taskInstanceList
, since that component only display active tasks for the user.
For Seam applications with relatively freeform (ad hoc) navigation, JSF/Seam navigation rules are a perfectly good way to define the page flow. For applications with a more constrained style of navigation, especially for user interfaces which are more stateful, navigation rules make it difficult to really understand the flow of the system. To understand the flow, you need to piece it together from the view pages, the actions and the navigation rules.
Seam allows you to use a jPDL process definition to define pageflow. The simple number guessing example shows how this is done.
The example is implemented using one JavaBean, three JSP pages and a jPDL pageflow definition. Let's begin with the pageflow:
Example 1.20. pageflow.jpdl.xml
<pageflow-definition xmlns="http://jboss.com/products/seam/pageflow" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://jboss.com/products/seam/pageflow http://jboss.com/products/seam/pageflow-2.2.xsd" name="numberGuess"> <start-pagename="displayGuess" view-id="/numberGuess.jspx"> <redirect/> <transit
ion name="guess" to="evaluateGuess"> <acti
on expression="#{numberGuess.guess}"/> </transition> <transition name="giveup" to="giveup"/> <transition name="cheat" to="cheat"/> </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="giveup" view-id="/giveup.jspx"> <redirect/> <transition name="yes" to="lose"/> <transition name="no" to="displayGuess"/> </page> <process-state name="cheat"> <sub-process name="cheat"/> <transition to="displayGuess"/> </process-state> <page name="win" view-id="/win.jspx"> <redirect/> <end-conversation/> </page> <page name="lose" view-id="/lose.jspx"> <redirect/> <end-conversation/> </page> </pageflow-definition>
![]() | The |
![]() | The |
![]() | A transition |
![]() | A |
Here is what the pageflow looks like in the JBoss Developer Studio pageflow editor:
Now that we have seen the pageflow, it is very, very easy to understand the rest of the application!
Here is the main page of the application, numberGuess.jspx
:
Example 1.21. numberGuess.jspx
<<?xml version="1.0"?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:s="http://jboss.com/products/seam/taglib"
xmlns="http://www.w3.org/1999/xhtml"
version="2.0">
<jsp:output doctype-root-element="html"
doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN"
doctype-system="http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"/>
<jsp:directive.page contentType="text/html"/>
<html>
<head>
<title>Guess a number...</title>
<link href="niceforms.css" rel="stylesheet" type="text/css" />
<script language="javascript" type="text/javascript" src="niceforms.js" />
</head>
<body>
<h1>Guess a number...</h1>
<f:view>
<h:form styleClass="niceform">
<div>
<h:messages globalOnly="true"/>
<h:outputText value="Higher!"
rendered="#{numberGuess.randomNumber gt numberGuess.currentGuess}"/>
<h:outputText value="Lower!"
rendered="#{numberGuess.randomNumber lt numberGuess.currentGuess}"/>
</div>
<div>
I'm thinking of a number between
<h:outputText value="#{numberGuess.smallest}"/> and
<h:outputText value="#{numberGuess.biggest}"/>. You have
<h:outputText value="#{numberGuess.remainingGuesses}"/> guesses.
</div>
<div>
Your guess:
<h:inputText value="#{numberGuess.currentGuess}" id="inputGuess"
required="true" size="3"
rendered="#{(numberGuess.biggest-numberGuess.smallest) gt 20}">
<f:validateLongRange maximum="#{numberGuess.biggest}"
minimum="#{numberGuess.smallest}"/>
</h:inputText>
<h:selectOneMenu value="#{numberGuess.currentGuess}"
id="selectGuessMenu" required="true"
rendered="#{(numberGuess.biggest-numberGuess.smallest) le 20 and
(numberGuess.biggest-numberGuess.smallest) gt 4}">
<s:selectItems value="#{numberGuess.possibilities}" var="i" label="#{i}"/>
</h:selectOneMenu>
<h:selectOneRadio value="#{numberGuess.currentGuess}" id="selectGuessRadio"
required="true"
rendered="#{(numberGuess.biggest-numberGuess.smallest) le 4}">
<s:selectItems value="#{numberGuess.possibilities}" var="i" label="#{i}"/>
</h:selectOneRadio>
<h:commandButton value="Guess" action="guess"/>
<s:button value="Cheat" view="/confirm.jspx"/>
<s:button value="Give up" action="giveup"/>
</div>
<div>
<h:message for="inputGuess" style="color: red"/>
</div>
</h:form>
</f:view>
</body>
</html>
</jsp:root>
Notice how the command button names the guess
transition instead of calling an
action directly.
The win.jspx
page is predictable:
Example 1.22. win.jspx
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core" xmlns="http://www.w3.org/1999/xhtml" version="2.0"> <jsp:output doctype-root-element="html" doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN" doctype-system="http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"/> <jsp:directive.page contentType="text/html"/> <html> <head> <title>You won!</title> <link href="niceforms.css" rel="stylesheet" type="text/css" /> </head> <body> <h1>You won!</h1> <f:view> Yes, the answer was <h:outputText value="#{numberGuess.currentGuess}" />. It took you <h:outputText value="#{numberGuess.guessCount}" /> guesses. <h:outputText value="But you cheated, so it doesn't count!" rendered="#{numberGuess.cheat}"/> Would you like to <a href="numberGuess.seam">play again</a>? </f:view> </body> </html> </jsp:root>
The lose.jspx
looks roughly the same, so we'll skip over it.
Finally, we'll look at the actual application code:
Example 1.23. NumberGuess.java
@Name("numberGuess")
@Scope(ScopeType.CONVERSATION)
public class NumberGuess implements Serializable {
private int randomNumber;
private Integer currentGuess;
private int biggest;
private int smallest;
private int guessCount;
private int maxGuesses;
private boolean cheated;
@Create
public void begin()
{
randomNumber = new Random().nextInt(100);
guessCount = 0;
biggest = 100;
smallest = 1;
}
public void setCurrentGuess(Integer guess)
{
this.currentGuess = guess;
}
public Integer getCurrentGuess()
{
return currentGuess;
}
public void guess()
{
if (currentGuess>randomNumber)
{
biggest = currentGuess - 1;
}
if (currentGuess<randomNumber)
{
smallest = currentGuess + 1;
}
guessCount ++;
}
public boolean isCorrectGuess()
{
return currentGuess==randomNumber;
}
public int getBiggest()
{
return biggest;
}
public int getSmallest()
{
return smallest;
}
public int getGuessCount()
{
return guessCount;
}
public boolean isLastGuess()
{
return guessCount==maxGuesses;
}
public int getRemainingGuesses() {
return maxGuesses-guessCount;
}
public void setMaxGuesses(int maxGuesses) {
this.maxGuesses = maxGuesses;
}
public int getMaxGuesses() {
return maxGuesses;
}
public int getRandomNumber() {
return randomNumber;
}
public void cheated()
{
cheated = true;
}
public boolean isCheat() {
return cheated;
}
public List<Integer> getPossibilities()
{
List<Integer> result = new ArrayList<Integer>();
for(int i=smallest; i<=biggest; i++) result.add(i);
return result;
}
}
![]() | The first time a JSP page asks for a |
The pages.xml
file starts a Seam
conversation (much more about that later), and specifies the
pageflow definition to use for the conversation's page flow.
Example 1.24. pages.xml
<?xml version="1.0" encoding="UTF-8"?>
<pages xmlns="http://jboss.com/products/seam/pages"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://jboss.com/products/seam/pages http://jboss.com/products/seam/pages-2.2.xsd">
<page view-id="/numberGuess.jspx">
<begin-conversation join="true" pageflow="numberGuess"/>
</page>
</pages>
As you can see, this Seam component is pure business logic! It doesn't need to know anything at all about the user interaction flow. This makes the component potentially more reuseable.
We'll step through basic flow of the application. The game starts with the
numberGuess.jspx
view. When the page is first displayed, the
pages.xml
configuration causes conversation to begin and associates
the numberGuess
pageflow
with that conversation. The pageflow starts with a start-page
tag,
which is a wait state, so the numberGuess.xhtml
is rendered.
The view references the numberGuess
component, causing a new
instance to be created and stored in the conversation. The @Create
method
is called, initializing the state of the game. The view displays an h:form
that allows the user to edit #{numberGuess.currentGuess}
.
The "Guess" button triggers the guess
action. Seam defers to the pageflow
to handle the action, which says that the pageflow should transition to the evaluateGuess
state, first invoking #{numberGuess.guess}
, which updates the guess count
and highest/lowest suggestions in the numberGuess
component.
The evaluateGuess
state checks the value of #{numberGuess.correctGuess}
and transitions either to the win
or evaluatingRemainingGuesses
state. We'll assume the number was incorrect, in which case the pageflow transitions to
evaluatingRemainingGuesses
. That is also a decision state, which
tests the #{numberGuess.lastGuess}
state to determine whether or not the user has
more guesses. If there are more guesses (lastGuess
is false
),
we transition back to the original displayGuess
state. Finally we've
reached a page state, so the associated page /numberGuess.jspx
is displayed.
Since the page has a redirect element, Seam sends a redirect to the the user's browser,
starting the process over.
We won't follow the state any more except to note that if on a future request either the
win
or the lose
transition were taken, the user would
be taken to either the /win.jspx
or /lose.jspx
.
Both states specify that Seam should end the conversation, tossing away all the game state and
pageflow state, before redirecting the user to the
final page.
The numberguess example also contains Giveup and Cheat buttons. You should be able to
trace the pageflow state for both actions relatively easily. Pay particular attention
to the cheat
transition, which loads a sub-process to handle that flow.
Although it's
overkill for this application, it does demonstrate how complex pageflows can be broken down into
smaller parts to make them easier to understand.
The booking application is a complete hotel room reservation system incorporating the following features:
User registration
Login
Logout
Set password
Hotel search
Hotel selection
Room reservation
Reservation confirmation
Existing reservation list
The booking application uses JSF, EJB 3.0 and Seam, together with Facelets for the view. There is also a port of this application to JSF, Facelets, Seam, JavaBeans and Hibernate3.
One of the things you'll notice if you play with this application for long enough is that it is extremely robust. You can play with back buttons and browser refresh and opening multiple windows and entering nonsensical data as much as you like and you will find it very difficult to make the application crash. You might think that we spent weeks testing and fixing bugs to achive this. Actually, this is not the case. Seam was designed to make it very straightforward to build robust web applications and a lot of robustness that you are probably used to having to code yourself comes naturally and automatically with Seam.
As you browse the sourcecode of the example application, and learn how the application works, observe how the declarative state management and integrated validation has been used to achieve this robustness.
The project structure is identical to the previous one, to install and deploy this application,
please refer to Section 1.1, “Using the Seam examples”. Once you've successfully started the application, you
can access it by pointing your browser to
http://localhost:8080/seam-booking/
The application uses six session beans for to implement the business logic for the listed features.
AuthenticatorAction
provides the login authentication logic.
BookingListAction
retrieves existing bookings for the currently logged in user.
ChangePasswordAction
updates the password of the currently logged in user.
HotelBookingAction
implements booking and confirmation
functionality. This functionality is implemented as a
conversation, so this is one of the most interesting classes in the
application.
HotelSearchingAction
implements the hotel search functionality.
RegisterAction
registers a new system user.
Three entity beans implement the application's persistent domain model.
Hotel
is an entity bean that represent a hotel
Booking
is an entity bean that represents an existing booking
User
is an entity bean to represents a user who can make hotel bookings
We encourage you browse the sourcecode at your pleasure. In this tutorial we'll concentrate upon one particular piece of functionality: hotel search, selection, booking and confirmation. From the point of view of the user, everything from selecting a hotel to confirming a booking is one continuous unit of work, a conversation. Searching, however, is not part of the conversation. The user can select multiple hotels from the same search results page, in different browser tabs.
Most web application architectures have no first class construct to represent a conversation. This
causes enormous problems managing conversational state. Usually, Java web applications
use a combination of several techniques. Some state can be transfered in the URL.
What can't is either thrown into the
HttpSession
or flushed to the database after every
request, and reconstructed from the database at the beginning of each new request.
Since the database is the least scalable tier, this often results in an utterly unacceptable lack of scalability. Added latency is also a problem, due to the extra traffic to and from the database on every request. To reduce this redundant traffic, Java applications often introduce a data (second-level) cache that keeps commonly accessed data between requests. This cache is necessarily inefficient, because invalidation is based upon an LRU policy instead of being based upon when the user has finished working with the data. Furthermore, because the cache is shared between many concurrent transactions, we've introduced a whole raft of problem's associated with keeping the cached state consistent with the database.
Now consider the state held in the HttpSession
. The HttpSession is great
place for true session data, data that is common to all requests that the user has with the application.
However, it's a bad place to store data related to individual series of requests. Using the session of
conversational quickly breaks down when dealing with the back button and multiple windows.
On top of that, without careful
programming, data in the HTTP Session can grow quite large, making the HTTP session difficult
to cluster. Developing mechanisms to isolate session state associated with different concurrent
conversations, and incorporating failsafes to ensure that conversation state is destroyed when
the user aborts one of the
conversations by closing a browser window or tab is not for the faint hearted. Fortunately, with Seam,
you don't have to worry about that.
Seam introduces the conversation context as a first class construct. You can safely keep conversational state in this context, and be assured that it will have a well-defined lifecycle. Even better, you won't need to be continually pushing data back and forth between the application server and the database, since the conversation context is a natural cache of data that the user is currently working with.
In this application, we'll use the conversation context to store stateful session beans.
There is an ancient canard in the Java
community that stateful session beans are a scalability killer. This may have been true in the
early days of enterprise Java, but it is no longer true today. Modern application servers have
extremely
sophisticated mechanisms for stateful session bean state replication. JBoss AS, for example, performs
fine-grained replication, replicating only those bean attribute values which actually
changed. Note that all the traditional technical arguments for why stateful beans are inefficient apply
equally to the HttpSession
, so the practice of shifting state from business tier
stateful session bean components to the web session to try and improve performance is unbelievably
misguided. It is certainly possible to write unscalable applications using stateful session beans, by
using stateful beans incorrectly, or by using them for the wrong thing. But that doesn't mean you should
never use them.
If you remain unconvinced, Seam allows the use of POJOs instead of stateful session beans.
With Seam, the choice is yours.
The booking example application shows how stateful components with different scopes can collaborate together to achieve complex behaviors. The main page of the booking application allows the user to search for hotels. The search results are kept in the Seam session scope. When the user navigates to one of these hotels, a conversation begins, and a conversation scoped component calls back to the session scoped component to retrieve the selected hotel.
The booking example also demonstrates the use of RichFaces Ajax to implement rich client behavior without the use of handwritten JavaScript.
The search functionality is implemented using a session-scope stateful session bean, similar to the one we saw in the message list example.
Example 1.25. HotelSearchingAction.java
@Stateful@Name("hotelSearch") @Scope(ScopeType.SESSION) @Restrict("#{i
dentity.loggedIn}") public class HotelSearchingAction implements HotelSearching { @PersistenceContext private EntityManager em; private String searchString; private int pageSize = 10; private int page; @DataModel
private List<Hotel> hotels; public void find() { page = 0; queryHotels(); } public void nextPage() { page++; queryHotels(); } private void queryHotels() { hotels = em.createQuery("select h from Hotel h where lower(h.name) like #{pattern} " + "or lower(h.city) like #{pattern} " + "or lower(h.zip) like #{pattern} " + "or lower(h.address) like #{pattern}") .setMaxResults(pageSize) .setFirstResult( page * pageSize ) .getResultList(); } public boolean isNextPageAvailable() { return hotels!=null && hotels.size()==pageSize; } public int getPageSize() { return pageSize; } public void setPageSize(int pageSize) { this.pageSize = pageSize; } @Factory(value="pattern", scope=ScopeType.EVENT) public String getSearchPattern() { return searchString==null ? "%" : '%' + searchString.toLowerCase().replace('*', '%') + '%'; } public String getSearchString() { return searchString; } public void setSearchString(String searchString) { this.searchString = searchString; }
@Remove public void destroy() {} }
![]() | The EJB standard |
![]() | The |
![]() | The
|
![]() | The EJB standard |
The main page of the application is a Facelets page. Let's look at the fragment which relates to searching for hotels:
Example 1.26. main.xhtml
<div class="section"> <span class="errors"> <h:messages globalOnly="true"/> </span> <h1>Search Hotels</h1> <h:form id="searchCriteria"> <fieldset> <h:inputText id="searchString" value="#{hotelSearch.searchString}" style="width: 165px;"> <a:support event="onkeyup" actionListener="#{hotelSearch.find}"reRender="searchResults" /> </h:inputText>   <a:commandButton id="findHotels" value="Find Hotels" action="#{hotelSearch.find}" reRender="searchResults"/>   <a:stat
us> <f:facet name="start"> <h:graphicImage value="/img/spinner.gif"/> </f:facet> </a:status> <br/> <h:outputLabel for="pageSize">Maximum results:</h:outputLabel>  <h:selectOneMenu value="#{hotelSearch.pageSize}" id="pageSize"> <f:selectItem itemLabel="5" itemValue="5"/> <f:selectItem itemLabel="10" itemValue="10"/> <f:selectItem itemLabel="20" itemValue="20"/> </h:selectOneMenu> </fieldset> </h:form> </div> <a:outputPanel
id="searchResults"> <div class="section"> <h:outputText value="No Hotels Found" rendered="#{hotels != null and hotels.rowCount==0}"/> <h:dataTable id="hotels" value="#{hotels}" var="hot" rendered="#{hotels.rowCount>0}"> <h:column> <f:facet name="header">Name</f:facet> #{hot.name} </h:column> <h:column> <f:facet name="header">Address</f:facet> #{hot.address} </h:column> <h:column> <f:facet name="header">City, State</f:facet> #{hot.city}, #{hot.state}, #{hot.country} </h:column> <h:column> <f:facet name="header">Zip</f:facet> #{hot.zip} </h:column> <h:column> <f:facet name="header">Action</f:facet> <s
:link id="viewHotel" value="View Hotel" action="#{hotelBooking.selectHotel(hot)}"/> </h:column> </h:dataTable> <s:link value="More results" action="#{hotelSearch.nextPage}" rendered="#{hotelSearch.nextPageAvailable}"/> </div> </a:outputPanel>
![]() | The RichFaces Ajax |
![]() | The RichFaces Ajax |
![]() | The RichFaces Ajax |
![]() | The Seam If you're wondering how navigation occurs,
you can find all the rules in |
This page displays the search results dynamically as we type, and lets us choose a hotel and pass it
to the selectHotel()
method of the HotelBookingAction
, which is
where the really interesting stuff is going to happen.
Now let's see how the booking example application uses a conversation-scoped stateful session bean to achieve a natural cache of persistent data related to the conversation. The following code example is pretty long. But if you think of it as a list of scripted actions that implement the various steps of the conversation, it's understandable. Read the class from top to bottom, as if it were a story.
Example 1.27. HotelBookingAction.java
@Stateful @Name("hotelBooking") @Restrict("#{identity.loggedIn}") public class HotelBookingAction implements HotelBooking { @PersistenceContext(type=EXTENDED) private EntityManager em; @In private User user; @In(required=false) @Out private Hotel hotel; @In(required=false) @Out(requir
ed=false) private Booking booking; @In private FacesMessages facesMessages; @In private Events events; @Logger private Log log; private boolean bookingValid; @Begin
public void selectHotel(Hotel selectedHotel) { hotel = em.merge(selectedHotel); } public void bookHotel() { booking = new Booking(hotel, user); Calendar calendar = Calendar.getInstance(); booking.setCheckinDate( calendar.getTime() ); calendar.add(Calendar.DAY_OF_MONTH, 1); booking.setCheckoutDate( calendar.getTime() ); } public void setBookingDetails() { Calendar calendar = Calendar.getInstance(); calendar.add(Calendar.DAY_OF_MONTH, -1); if ( booking.getCheckinDate().before( calendar.getTime() ) ) { facesMessages.addToControl("checkinDate", "Check in date must be a future date"); bookingValid=false; } else if ( !booking.getCheckinDate().before( booking.getCheckoutDate() ) ) { facesMessages.addToControl("checkoutDate", "Check out date must be later than check in date"); bookingValid=false; } else { bookingValid=true; } } public boolean isBookingValid() { return bookingValid; } @End
public void confirm() { em.persist(booking); facesMessages.add("Thank you, #{user.name}, your confimation number " + " for #{hotel.name} is #{booki g.id}"); log.info("New booking: #{booking.id} for #{user.username}"); events.raiseTransactionSuccessEvent("bookingConfirmed"); } @End public void cancel() {} @Remove
public void destroy() {}
![]() | This bean uses an EJB3 extended persistence context, so that any entity instances remain managed for the whole lifecycle of the stateful session bean. |
![]() | The
|
![]() | The
|
![]() | The
|
![]() | This EJB remove method will be called when Seam destroys the conversation context. Don't forget to define this method! |
HotelBookingAction
contains all the action listener methods that implement selection,
booking and booking confirmation, and holds state related to this work in its instance variables. We
think you'll agree that this code is much cleaner and simpler than getting and setting
HttpSession
attributes.
Even better, a user can have multiple isolated conversations per login session. Try it! Log in, run a search, and navigate to different hotel pages in multiple browser tabs. You'll be able to work on creating two different hotel reservations at the same time. If you leave any one conversation inactive for long enough, Seam will eventually time out that conversation and destroy its state. If, after ending a conversation, you backbutton to a page of that conversation and try to perform an action, Seam will detect that the conversation was already ended, and redirect you to the search page.
The WAR also includes seam-debug.jar
. The Seam debug page will be available
if this jar is deployed in
WEB-INF/lib
, along with the Facelets, and if you set the debug property
of the init
component:
<core:init jndi-pattern="@jndiPattern@" debug="true"/>
This page lets you browse and inspect the Seam components
in any of the Seam contexts associated with your current login session. Just point your browser at
http://localhost:8080/seam-booking/debug.seam
.
Long-running conversations make it simple to maintain consistency of state in an application even in the face of multi-window operation and back-buttoning. Unfortunately, simply beginning and ending a long-running conversation is not always enough. Depending on the requirements of the application, inconsistencies between what the user's expectations and the reality of the application’s state can still result.
The nested booking application extends the features of the hotel booking application to incorporate the selection of rooms. Each hotel has available rooms with descriptions for a user to select from. This requires the addition of a room selection page in the hotel reservation flow.
The user now has the option to select any available room to be included in the booking. As with the
hotel booking application we saw previously, this can lead to issues with state consistency. As with storing state
in the HTTPSession
, if a conversation variable changes it affects all windows operating within
the same conversation context.
To demonstrate this, let’s suppose the user clones the room selection screen in a new window. The user then selects the Wonderful Room and proceeds to the confirmation screen. To see just how much it would cost to live the high-life, the user returns to the original window, selects the Fantastic Suite for booking, and again proceeds to confirmation. After reviewing the total cost, the user decides that practicality wins out and returns to the window showing Wonderful Room to confirm.
In this scenario, if we simply store all state in the conversation, we are not protected from multi-window operation within the same conversation. Nested conversations allow us to achieve correct behavior even when context can vary within the same conversation.
Now let's see how the nested booking example extends the behavior of the hotel booking application through use of nested conversations. Again, we can read the class from top to bottom, as if it were a story.
Example 1.28. RoomPreferenceAction.java
@Stateful @Name("roomPreference") @Restrict("#{identity.loggedIn}") public class RoomPreferenceAction implements RoomPreference { @Logger private Log log; @In private Hotel hotel; @In private Booking booking; @DataModel(value="availableRooms") private List<Room> availableRooms; @DataModelSelection(value="availableRooms") private Room roomSelection; @In(required=false, value="roomSelection") @Out(required=false, value="roomSelection") private Room room; @Factory("availableRooms") public voidloadAvailableRooms() { availableRooms = hotel.getAvailableRooms(booking.getCheckinDate(), booking.getCheckoutDate()); log.info("Retrieved #0 available rooms", availableRooms.size()); } public BigDecimal getExpectedPrice() { log.info("Retrieving price for room #0", roomSelection.getName()); return booking.getTotal(roomSelection); } @Begin(nest
ed=true) public String selectPreference() { log.info("Room selected"); this.roo
m = this.roomSelection; return "payment"; } public String requestConfirmation() { // all validations are performed through the s:validateAll, so checks are already // performed log.info("Request confirmation from user"); return "confirm"; } @End(beforeRedirect=true) public Stri
ng cancel() { log.info("ending conversation"); return "cancel"; } @Destroy @Remove public void destroy() {} }
![]() | The |
![]() | When
|
![]() | The |
![]() | The
|
When we begin a nested conversation it is pushed onto the conversation stack. In the nestedbooking
example, the conversation stack consists of the outer long-running conversation (the booking) and each of the nested conversations (room
selections).
Example 1.29. rooms.xhtml
<div class="section"> <h1>Room Preference</h1> </div> <div class="section"> <h:form id="room_selections_form"> <div class="section"> <h:outputText styleClass="output" value="No rooms available for the dates selected: " rendered="#{availableRooms != null and availableRooms.rowCount == 0}"/> <h:outputText styleClass="output" value="Rooms available for the dates selected: " rendered="#{availableRooms != null and availableRooms.rowCount > 0}"/> <h:outputText styleClass="output" value="#{booking.checkinDate}"/> - <h:outputText styleClass="output" value="#{booking.checkoutDate}"/> <br/><br/><h:dataTable value="#{availableRooms}" var="room" rendered="#{availableRooms.rowCount > 0}"> <h:column> <f:facet name="header">Name</f:facet> #{room.name} </h:column> <h:column> <f:facet name="header">Description</f:facet> #{room.description} </h:column> <h:column> <f:facet name="header">Per Night</f:facet> <h:outputText value="#{room.price}"> <f:convertNumber type="currency" currencySymbol="$"/> </h:outputText> </h:column>
<h:column> <f:facet name="header">Action</f:facet> <h:commandLink id="selectRoomPreference" action="#{roomPreference.selectPreference}">Select</h:commandLink> </h:column> </h:dataTable> </div> <div class="entry"> <div class="label"> </div> <d
iv class="input"> <s:button id="cancel" value="Revise Dates" view="/book.xhtml"/> </div> </div> </h:form> </div>
![]() | When requested from EL, the |
![]() | Invoking the |
![]() | Revising the dates simply returns to the |
Now that we have seen how to nest a conversation, let's see how we can confirm the booking once a room has been selected. This
can be achieved by simply extending the behavior of the HotelBookingAction
.
Example 1.30. HotelBookingAction.java
@Stateful @Name("hotelBooking") @Restrict("#{identity.loggedIn}") public class HotelBookingAction implements HotelBooking { @PersistenceContext(type=EXTENDED) private EntityManager em; @In private User user; @In(required=false) @Out private Hotel hotel; @In(required=false) @Out(required=false) private Booking booking; @In(required=false) private Room roomSelection; @In private FacesMessages facesMessages; @In private Events events; @Logger private Log log; @Begin public void selectHotel(Hotel selectedHotel) { log.info("Selected hotel #0", selectedHotel.getName()); hotel = em.merge(selectedHotel); } public String setBookingDates() { // the result will indicate whether or not to begin the nested conversation // as well as the navigation. if a null result is returned, the nested // conversation will not begin, and the user will be returned to the current // page to fix validation issues String result = null; Calendar calendar = Calendar.getInstance(); calendar.add(Calendar.DAY_OF_MONTH, -1); // validate what we have received from the user so far if ( booking.getCheckinDate().before( calendar.getTime() ) ) { facesMessages.addToControl("checkinDate", "Check in date must be a future date"); } else if ( !booking.getCheckinDate().before( booking.getCheckoutDate() ) ) { facesMessages.addToControl("checkoutDate", "Check out date must be later than check in date"); } else { result = "rooms"; } return result; } public void bookHotel() { booking = new Booking(hotel, user); Calendar calendar = Calendar.getInstance(); booking.setCheckinDate( calendar.getTime() ); calendar.add(Calendar.DAY_OF_MONTH, 1); booking.setCheckoutDate( calendar.getTime() ); } @End(root=true) public voidconfirm() { // on confirmation we set the room preference in the booking. the room preference // will be injected based on the nested conversation we are in. booking.setRoomPreference(roomSelection);
em.persist(booking); facesMessages.add("Thank you, #{user.name}, your confimation number for #{hotel.name} is #{booking.id}"); log.info("New booking: #{booking.id} for #{user.username}"); events.raiseTransactionSuccessEvent("bookingConfirmed"); } @End(root=t
rue, beforeRedirect=true) public void cancel() {} @Destroy @Remove public void destroy() {} }
![]() | Annotating an action with
|
![]() | The |
![]() | By simply annotating the cancellation action with
|
Feel free to deploy the application, open many windows or tabs and attempt combinations of various hotels with various room preferences. Confirming a booking always results in the correct hotel and room preference thanks to the nested conversation model.
The DVD Store demo application shows the practical usage of jBPM for both task management and pageflow.
The user screens take advantage of a jPDL pageflow to implement searching and shopping cart functionality.
The administration screens take use jBPM to manage the approval and shipping cycle for orders. The business process may even be changed dynamically, by selecting a different process definition!
The Seam DVD Store demo can be run from dvdstore
directory,
just like the other demo applications.
Seam makes it very easy to implement applications which keep state on the server-side. However, server-side state is not always appropriate, especially in for functionality that serves up content. For this kind of problem we often want to keep application state in the URL so that any page can be accessed at any time through a bookmark. The blog example shows how to a implement an application that supports bookmarking throughout, even on the search results page. This example demonstrates how Seam can manage application state in the URL as well as how Seam can rewrite those URLs to be even
The Blog example demonstrates the use of "pull"-style MVC, where instead of using action listener methods to retrieve data and prepare the data for the view, the view pulls data from components as it is being rendered.
This snippet from the index.xhtml
facelets page displays a list of recent blog
entries:
Example 1.31.
<h:dataTable value="#{blog.recentBlogEntries}" var="blogEntry" rows="3">
<h:column>
<div class="blogEntry">
<h3>#{blogEntry.title}</h3>
<div>
<s:formattedText value="#{blogEntry.excerpt==null ? blogEntry.body : blogEntry.excerpt}"/>
</div>
<p>
<s:link view="/entry.xhtml" rendered="#{blogEntry.excerpt!=null}" propagation="none"
value="Read more...">
<f:param name="blogEntryId" value="#{blogEntry.id}"/>
</s:link>
</p>
<p>
[Posted on 
<h:outputText value="#{blogEntry.date}">
<f:convertDateTime timeZone="#{blog.timeZone}" locale="#{blog.locale}" type="both"/>
</h:outputText>]
 
<s:link view="/entry.xhtml" propagation="none" value="[Link]">
<f:param name="blogEntryId" value="#{blogEntry.id}"/>
</s:link>
</p>
</div>
</h:column>
</h:dataTable>
If we navigate to this page from a bookmark, how does the #{blog.recentBlogEntries}
data used by the <h:dataTable>
actually get initialized?
The Blog
is retrieved lazily — "pulled" — when needed, by a Seam
component named blog
. This is the opposite flow of control to what is used in
traditional action-based web frameworks like Struts.
Example 1.32.
@Name("blog") @Scope(ScopeType.STATELESS) @AutoCreate public class BlogService { @In EntityManager entityManager; @Unwrap
public Blog getBlog() { return (Blog) entityManager.createQuery("select distinct b from Blog b left join fetch b.blogEntries") .setHint("org.hibernate.cacheable", true) .getSingleResult(); } }
![]() | This component uses a seam-managed persistence context. Unlike the other examples we've seen, this persistence context is managed by Seam, instead of by the EJB3 container. The persistence context spans the entire web request, allowing us to avoid any exceptions that occur when accessing unfetched associations in the view. |
![]() | The |
This is good so far, but what about bookmarking the result of form submissions, such as a search results page?
The blog example has a tiny form in the top right of each page that allows the user to search for
blog entries. This is defined in a file, menu.xhtml
, included by the facelets
template, template.xhtml
:
Example 1.33.
<div id="search">
<h:form>
<h:inputText value="#{searchAction.searchPattern}"/>
<h:commandButton value="Search" action="/search.xhtml"/>
</h:form>
</div>
To implement a bookmarkable search results page, we need to perform a browser redirect after processing the search form submission. Because we used the JSF view id as the action outcome, Seam automatically redirects to the view id when the form is submitted. Alternatively, we could have defined a navigation rule like this:
<navigation-rule>
<navigation-case>
<from-outcome>searchResults</from-outcome>
<to-view-id>/search.xhtml</to-view-id>
<redirect/>
</navigation-case>
</navigation-rule>
Then the form would have looked like this:
<div id="search">
<h:form>
<h:inputText value="#{searchAction.searchPattern}"/>
<h:commandButton value="Search" action="searchResults"/>
</h:form>
</div>
But when we redirect, we need to include the values submitted with the form
in the URL to get a bookmarkable URL like
http://localhost:8080/seam-blog/search/
. JSF does not provide
an easy way to do this, but Seam does. We use two Seam features
to accomplish this: page parameters and URL rewriting.
Both are defined in WEB-INF/pages.xml
:
Example 1.34.
<pages>
<page view-id="/search.xhtml">
<rewrite pattern="/search/{searchPattern}"/>
<rewrite pattern="/search"/>
<param name="searchPattern" value="#{searchService.searchPattern}"/>
</page>
...
</pages>
The page parameter instructs Seam to link the request parameter named searchPattern
to the value of #{searchService.searchPattern}
, both whenever a request for
the Search page comes in and whenever a link to the search page is generated. Seam
takes responsibility for maintaining the link between URL state and application state, and you,
the developer, don't have to worry about it.
Without URL rewriting, the URL for a search on the term book
would be http://localhost:8080/seam-blog/seam/search.xhtml?searchPattern=book
.
This is nice, but Seam can make the URL even simpler using a rewrite rule. The first
rewrite rule, for the pattern /search/{searchPattern}
, says that
any time we have a URL for search.xhtml with a searchPattern request parameter, we can
fold that URL into the simpler URL. So,the URL we saw earlier,
http://localhost:8080/seam-blog/seam/search.xhtml?searchPattern=book
can be written instead as http://localhost:8080/seam-blog/search/book
.
Just like with page parameters, URL rewriting is bi-directional. That means that Seam
forwards requests for the simpler URL to the the right view, and it also automatically generates
the simpler view for you. You never need to worry about constructing URLs. It's
all handled transparently behind the scenes. The only requirement is that to use URL rewriting,
the rewrite filter needs to be enabled in components.xml
.
<web:rewrite-filter view-mapping="/seam/*" />
The redirect takes us to the search.xhtml
page:
<h:dataTable value="#{searchResults}" var="blogEntry">
<h:column>
<div>
<s:link view="/entry.xhtml" propagation="none" value="#{blogEntry.title}">
<f:param name="blogEntryId" value="#{blogEntry.id}"/>
</s:link>
posted on
<h:outputText value="#{blogEntry.date}">
<f:convertDateTime timeZone="#{blog.timeZone}" locale="#{blog.locale}" type="both"/>
</h:outputText>
</div>
</h:column>
</h:dataTable>
Which again uses "pull"-style MVC to retrieve the actual search results using Hibernate Search.
@Name("searchService")
public class SearchService
{
@In
private FullTextEntityManager entityManager;
private String searchPattern;
@Factory("searchResults")
public List<BlogEntry> getSearchResults()
{
if (searchPattern==null || "".equals(searchPattern) ) {
searchPattern = null;
return entityManager.createQuery("select be from BlogEntry be order by date desc").getResultList();
}
else
{
Map<String,Float> boostPerField = new HashMap<String,Float>();
boostPerField.put( "title", 4f );
boostPerField.put( "body", 1f );
String[] productFields = {"title", "body"};
QueryParser parser = new MultiFieldQueryParser(productFields, new StandardAnalyzer(), boostPerField);
parser.setAllowLeadingWildcard(true);
org.apache.lucene.search.Query luceneQuery;
try
{
luceneQuery = parser.parse(searchPattern);
}
catch (ParseException e)
{
return null;
}
return entityManager.createFullTextQuery(luceneQuery, BlogEntry.class)
.setMaxResults(100)
.getResultList();
}
}
public String getSearchPattern()
{
return searchPattern;
}
public void setSearchPattern(String searchPattern)
{
this.searchPattern = searchPattern;
}
}
Very occasionally, it makes more sense to use push-style MVC for processing RESTful pages, and so
Seam provides the notion of a page action. The Blog example uses a page action for
the blog entry page, entry.xhtml
. Note that this is a little bit contrived, it would
have been easier to use pull-style MVC here as well.
The entryAction
component works much like an action class in a traditional
push-MVC action-oriented framework like Struts:
@Name("entryAction")
@Scope(STATELESS)
public class EntryAction
{
@In Blog blog;
@Out BlogEntry blogEntry;
public void loadBlogEntry(String id) throws EntryNotFoundException
{
blogEntry = blog.getBlogEntry(id);
if (blogEntry==null) throw new EntryNotFoundException(id);
}
}
Page actions are also declared in pages.xml
:
<pages>
...
<page view-id="/entry.xhtml">
<rewrite pattern="/entry/{blogEntryId}" />
<rewrite pattern="/entry" />
<param name="blogEntryId"
value="#{blogEntry.id}"/>
<action execute="#{entryAction.loadBlogEntry(blogEntry.id)}"/>
</page>
<page view-id="/post.xhtml" login-required="true">
<rewrite pattern="/post" />
<action execute="#{postAction.post}"
if="#{validation.succeeded}"/>
<action execute="#{postAction.invalid}"
if="#{validation.failed}"/>
<navigation from-action="#{postAction.post}">
<redirect view-id="/index.xhtml"/>
</navigation>
</page>
<page view-id="*">
<action execute="#{blog.hitCount.hit}"/>
</page>
</pages>
Notice that the example is using page actions for post validation and the pageview counter. Also notice the use of a parameter in the page action method binding. This is not a standard feature of JSF EL, but Seam lets you use it, not just for page actions but also in JSF method bindings.
When the entry.xhtml
page is requested, Seam first binds the page parameter
blogEntryId
to the model. Keep in mind that because of the URL rewriting,
the blogEntryId parameter name won't show up in the URL. Seam then runs the page action, which retrieves
the needed
data — the blogEntry
— and places it in the Seam event context.
Finally, the following is rendered:
<div class="blogEntry">
<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>
If the blog entry is not found in the database, the EntryNotFoundException
exception is thrown. We want this exception to result in a 404 error, not a 505, so we annotate the
exception class:
@ApplicationException(rollback=true)
@HttpError(errorCode=HttpServletResponse.SC_NOT_FOUND)
public class EntryNotFoundException extends Exception
{
EntryNotFoundException(String id)
{
super("entry not found: " + id);
}
}
An alternative implementation of the example does not use the parameter in the method binding:
@Name("entryAction")
@Scope(STATELESS)
public class EntryAction
{
@In(create=true)
private Blog blog;
@In @Out
private BlogEntry blogEntry;
public void loadBlogEntry() throws EntryNotFoundException
{
blogEntry = blog.getBlogEntry( blogEntry.getId() );
if (blogEntry==null) throw new EntryNotFoundException(id);
}
}
<pages>
...
<page view-id="/entry.xhtml" action="#{entryAction.loadBlogEntry}">
<param name="blogEntryId" value="#{blogEntry.id}"/>
</page>
...
</pages>
It is a matter of taste which implementation you prefer.
The blog demo also demonstrates very simple password authentication, posting to the blog, page fragment caching and atom feed generation.
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.
This is the easy way to get your feet wet with Seam, and gives you some ammunition for next time you find yourself trapped in an elevator with one of those tedious Ruby guys ranting about how great and wonderful his new toy is for building totally trivial applications that put things in databases.
In this release, seam-gen works best for people with JBoss AS. You can use the generated project with other J2EE or Java EE 5 application servers by making a few manual changes to the project configuration.
You can use seam-gen without Eclipse, but in this tutorial, we want to show you how to use it in conjunction with Eclipse for debugging and integration testing. If you don't want to install Eclipse, you can still follow along with this tutorial—all steps can be performed from the command line.
seam-gen is basically just an intricate Ant script wrapped around Hibernate Tools, together with some templates. That makes it easy to customize if you need to.
Make sure you have JDK 5 or JDK 6 (see Section 42.1, “JDK Dependencies” for details), JBoss AS 4.2 or 5.0 and Ant 1.7.0, 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=512m
If you don't have so much memory available, the following is our minimum recommendation:
-Xms256m -Xmx512m -XX:PermSize=128m -XX:MaxPermSize=256m
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
.
The first thing we need to do is configure seam-gen for your environment: JBoss AS installation directory, project workspace, and database connection. It's easy, just type:
cd jboss-seam-2.2.x seam setup
And you will be prompted for the needed information:
~/workspace/jboss-seam$ ./seam setup Buildfile: build.xml init: setup: [echo] Welcome to seam-gen :-) [input] Enter your project workspace (the directory that contains your Seam projects) [C:/Projects] [C:/Projects] /Users/pmuir/workspace [input] Enter your JBoss home directory [C:/Program Files/jboss-4.2.3.GA] [C:/Program Files/jboss-4.2.3.GA] /Applications/jboss-4.2.3.GA [input] Enter the project name [myproject] [myproject] helloworld [echo] Accepted project name as: helloworld [input] Select a RichFaces skin (not applicable if using ICEFaces) [blueSky] ([blueSky], classic, ruby, wine, deepMarine, emeraldTown, sakura, DEFAULT) [input] Is this project deployed as an EAR (with EJB components) or a WAR (with no EJB support) [ear] ([ear], war, ) [input] Enter the Java package name for your session beans [com.mydomain.helloworld] [com.mydomain.helloworld] org.jboss.helloworld [input] Enter the Java package name for your entity beans [org.jboss.helloworld] [org.jboss.helloworld] [input] Enter the Java package name for your test cases [org.jboss.helloworld.test] [org.jboss.helloworld.test] [input] What kind of database are you using? [hsql] ([hsql], mysql, oracle, postgres, mssql, db2, sybase, enterprisedb, h2) mysql [input] Enter the Hibernate dialect for your database [org.hibernate.dialect.MySQLDialect] [org.hibernate.dialect.MySQLDialect] [input] Enter the filesystem path to the JDBC driver jar [lib/hsqldb.jar] [lib/hsqldb.jar] /Users/pmuir/java/mysql.jar [input] Enter JDBC driver class for your database [com.mysql.jdbc.Driver] [com.mysql.jdbc.Driver] [input] Enter the JDBC URL for your database [jdbc:mysql:///test] [jdbc:mysql:///test] jdbc:mysql:///helloworld [input] Enter database username [sa] [sa] pmuir [input] Enter database password [] [] [input] skipping input as property hibernate.default_schema.new has already been set. [input] Enter the database catalog name (it is OK to leave this blank) [] [] [input] Are you working with tables that already exist in the database? [n] (y, [n], ) y [input] Do you want to drop and recreate the database tables and data in import.sql each time you deploy? [n] (y, [n], ) n [input] Enter your ICEfaces home directory (leave blank to omit ICEfaces) [] [] [propertyfile] Creating new property file: /Users/pmuir/workspace/jboss-seam/seam-gen/build.properties [echo] Installing JDBC driver jar to JBoss server [echo] Type 'seam create-project' to create the new project BUILD SUCCESSFUL Total time: 1 minute 32 seconds ~/workspace/jboss-seam $
The tool provides sensible defaults, which you can accept by just pressing enter at the prompt.
The most important choice you need to make is between EAR deployment and WAR deployment of your project.
EAR projects support EJB 3.0 and require Java EE 5. WAR projects do not support EJB 3.0, but may be deployed
to a J2EE environment. The packaging of a WAR is also simpler to understand. If you installed an EJB3-ready
application server like JBoss, choose ear
. Otherwise, choose war
.
We'll assume that you've chosen an EAR deployment for the rest of the tutorial, but you can follow exactly
the same steps for a WAR deployment.
If you are working with an existing data model, make sure you tell seam-gen that the tables already exist in the database.
The settings are stored in seam-gen/build.properties
, but you 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
C:\Projects\jboss-seam>seam new-project Buildfile: build.xml ... new-project: [echo] A new Seam project named 'helloworld' was created in the C:\Projects directory [echo] Type 'seam explode' and go to http://localhost:8080/helloworld [echo] Eclipse Users: Add the project into Eclipse using File > New > Project and select General > Project (not Java Project) [echo] NetBeans Users: Open the project in NetBeans BUILD SUCCESSFUL Total time: 7 seconds C:\Projects\jboss-seam>
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.
If your default JDK in Eclipse is not a Java SE 5 or Java SE 6 JDK, you will need to select a Java SE 5
compliant JDK using Project -> Properties -> Java Compiler
.
Alternatively, you can deploy the project from outside Eclipse by typing seam explode
.
Go to http://localhost:8080/helloworld
to see a welcome page. This is a facelets page,
view/home.xhtml
, using the template view/layout/template.xhtml
.
You can edit this page, or the template, in Eclipse, and see the results immediately,
by clicking refresh in your browser.
Don't get scared by the XML configuration documents that were generated into the project directory. They are mostly standard Java EE stuff, the stuff you need to create once and then never look at again, and they are 90% the same between all Seam projects. (They are so easy to write that even seam-gen can do it.)
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.xml
and
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.
If you're used to traditional action-style web frameworks, you're probably wondering how you can create a simple web page with a stateless action method in Java. If you type:
seam new-action
Seam will prompt for some information, and generate a new facelets page and Seam component for your project.
C:\Projects\jboss-seam>seam new-action Buildfile: build.xml validate-workspace: validate-project: action-input: [input] Enter the Seam component name ping [input] Enter the local interface name [Ping] [input] Enter the bean class name [PingBean] [input] Enter the action method name [ping] [input] Enter the page name [ping] setup-filters: new-action: [echo] Creating a new stateless session bean component with an action method [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld\test [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld\test [copy] Copying 1 file to C:\Projects\helloworld\view [echo] Type 'seam restart' and go to http://localhost:8080/helloworld/ping.seam BUILD SUCCESSFUL Total time: 13 seconds C:\Projects\jboss-seam>
Because we've added a new Seam component, we need to restart the exploded directory deployment. You can do
this by typing seam restart
, or by running the restart
target in the
generated project build.xml
file from inside Eclipse. Another way to force a restart is
to edit the file resources/META-INF/application.xml
in Eclipse. Note that you
do not need to restart JBoss each time you change the application.
Now go to http://localhost:8080/helloworld/ping.seam
and click the button. You can see
the code behind this action by looking in the project src
directory. Put a breakpoint in
the ping()
method, and click the button again.
Finally, locate the PingTest.xml
file in the test package and run the integration tests
using the TestNG plugin for Eclipse. Alternatively, run the tests using seam test
or the
test
target of the generated build.
The next step is to create a form. Type:
seam new-form
C:\Projects\jboss-seam>seam new-form Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml validate-workspace: validate-project: action-input: [input] Enter the Seam component name hello [input] Enter the local interface name [Hello] [input] Enter the bean class name [HelloBean] [input] Enter the action method name [hello] [input] Enter the page name [hello] setup-filters: new-form: [echo] Creating a new stateful session bean component with an action method [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello\test [copy] Copying 1 file to C:\Projects\hello\view [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello\test [echo] Type 'seam restart' and go to http://localhost:8080/hello/hello.seam BUILD SUCCESSFUL Total time: 5 seconds C:\Projects\jboss-seam>
Restart the application again, and go to http://localhost:8080/helloworld/hello.seam
.
Then take a look at the generated code. Run the test. Try adding some new fields to the form and Seam
component (remember to restart the deployment each time you change the Java code).
Manually create some tables in your database. (If you need to switch to a different database, just run
seam setup
again.) Now type:
seam generate-entities
Restart the deployment, and go to http://localhost:8080/helloworld
. You can browse the
database, edit existing objects, and create new objects. If you look at the generated code, you'll probably
be amazed how simple it is! Seam was designed so that data access code is easy to write by hand, even for
people who don't want to cheat by using seam-gen.
Place your existing, valid entity classes inside the src/main
. Now type
seam generate-ui
Restart the deployment, and go to http://localhost:8080/helloworld
.
Finally, we want to be able to deploy the application using standard Java EE 5 packaging. First, we need
to remove the exploded directory by running seam unexplode
. To deploy the EAR, we can
type seam deploy
at the command prompt, or run the deploy
target of
the generated project build script. You can undeploy using seam undeploy
or the
undeploy
target.
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
.
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-deployed
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/hot
source directory. However, seam-gen does not support
incremental hot deployment for EAR projects.
Seam 2 was developed for JavaServer Faces 1.2. When using JBoss AS, we recommend using JBoss 4.2 or JBoss 5.0, both of which bundle the JSF 1.2 reference implementation. However, it is still possible to use Seam 2 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 applications can be deployed to 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://www.jboss.org/jbossas/downloads.
The web configuration for JBoss 4.0 can be found in the
server/default/deploy/jbossweb-tomcat55.sar
. You'll need to delete
myfaces-api.jar
any myfaces-impl.jar
from the
jsf-libs
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
.
JBoss Tools is a collection of Eclipse plugins. JBoss Tools a project creation wizard for Seam, Content Assist for the Unified Expression Language (EL) in both facelets and Java code, a graphical editor for jPDL, a graphical editor for Seam configuration files, support for running Seam integration tests from within Eclipse, and much more.
In short, if you are an Eclipse user, then you'll want JBoss Tools!
JBoss Tools, as with seam-gen, works best with JBoss AS, but it's possible with a few tweaks to get your app running on other application servers. The changes are much like those described for seam-gen later in this reference manual.
Make sure you have JDK 5, JBoss AS 4.2 or 5.0, Eclipse 3.3, the JBoss Tools plugins (at least Seam Tools, the Visual Page Editor, jBPM Tools and JBoss AS Tools) and the TestNG plugin for Eclipse correctly installed before starting.
Please see the official JBoss Tools installation page for the quickest way to get JBoss Tools setup in Eclipse. You can also check out the Installing JBoss Tools page on the JBoss community wiki for the gory details and a set of alternative installation approaches.
Start up Eclipse and select the Seam perspective.
Go to File -> New -> Seam Web Project.
First, enter a name for your new project. For this tutorial, we're
going to use
helloworld
.
Now, we need to tell JBoss Tools about JBoss AS. In this example we are using JBoss AS 4.2, though you can certainly use JBoss AS 5.0 as well. Selecting JBoss AS is a two step process. First we need to define a runtime. Again, we'll choose JBoss AS 4.2 in this case:
Enter a name for the runtime, and locate it on your hard drive:
Next, we need to define a server JBoss Tools can deploy the project to. Make sure to again select JBoss AS 4.2, and also the runtime you just defined:
On the next screen give the server a name, and hit Finish:
Make sure the runtime and server you just created are selected, select Dynamic Web Project with Seam 2.0 (technology preview) and hit Next:
The next 3 screens allow you to further customize your new project, but for us the defaults are fine. So just hit Next until you reach the final screen.
The first step here is to tell JBoss Tools about the Seam download you want to use. Add a new Seam Runtime - make sure to give it a name, and select 2.0 as the version:
The most important choice you need to make is between EAR deployment and WAR deployment of your project. EAR projects support EJB 3.0 and require Java EE 5. WAR projects do not support EJB 3.0, but may be deployed to a J2EE environment. The packaging of a WAR is also simpler to understand. If you installed an EJB3-ready application server like JBoss, choose EAR. Otherwise, choose WAR. We'll assume that you've chosen a WAR deployment for the rest of the tutorial, but you can follow exactly the same steps for a EAR deployment.
Next, select your database type. We'll assume you have MySQL installed, with an existing schema. You'll need to tell JBoss Tools about the database, select MySQL as the database, and create a new connection profile. Select Generic JDBC Connection:
Give it a name:
JBoss Tools doesn't come with drivers for any databases, so you need to tell JBoss Tools where the MySQL JDBC driver is. Tell it about the driver by clicking ....
Locate MySQL 5, and hit Add...:
Choose the MySQL JDBC Driver template:
Locate the jar on your computer by choosing Edit Jar/Zip:
Review the username and password used to connect, and if correct, hit Ok.
Finally, choose the newly created driver:
If you are working with an existing data model, make sure you tell JBoss Tools that the tables already exist in the database.
Review the username and password used to connect, test the connection using the Test Connection button, and if it works, hit Finish:
Finally, review the package names for your generated beans, and if you are happy, click Finish:
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. 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
Locate the server in the JBoss Server View, right click on the server and select Edit Launch Configuration:
Then, alter the VM arguements:
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
.
To start JBoss, and deploy the project, just right click on the server you created, and click Start, (or Debug to start in debug mode):
Don't get scared by the XML configuration documents that were generated into the project directory. They are mostly standard Java EE stuff, the stuff you need to create once and then never look at again, and they are 90% the same between all Seam projects.
If you're used to traditional action-style web frameworks, you're probably wondering how you can create a simple web page with a stateless action method in Java.
First, select New -> Seam Action:
Now, enter the name of the Seam component. JBoss Tools selects sensible defaults for other fields:
Finally, hit Finish.
Now go to http://localhost:8080/helloworld/ping.seam
and click the button. You can see the code behind this action by
looking in the project src
directory. Put a
breakpoint in the ping()
method, and click the
button again.
Finally, open the helloworld-test
project, locate
PingTest
class, right click on it, and choose
Run As -> TestNG Test:
The first step is to create a form. Select New -> Seam Form:
Now, enter the name of the Seam component. JBoss Tools selects sensible defaults for other fields:
Go to http://localhost:8080/helloworld/hello.seam
.
Then take a look at the generated code. Run the test. Try adding some
new fields to the form and Seam component (note, you don't need to
restart the app server each time you change the code in
src/action
as Seam hot reloads the component for
you Section 3.6, “Seam and incremental hot deployment with JBoss Tools”).
Manually create some tables in your database. (If you need to switch to a different database, create a new project, and select the correct database). Then, select New -> Seam Generate Entities:
JBoss Tools gives you the option to either reverse engineer entities, components and views from a database schema or to reverse engineer components and views from existing JPA entities. We're going to do Reverse engieneer from database.
Restart the deployment:
Then go to http://localhost:8080/helloworld
. You can
browse the database, edit existing objects, and create new objects. If
you look at the generated code, you'll probably be amazed how simple it
is! Seam was designed so that data access code is easy to write by
hand, even for people who don't want to cheat by using reverse
engineering.
JBoss Tools supports incremental hot deployment of:
any facelets page
any pages.xml
file
out of the box.
But if we want to change any Java code, we still need to do a full restart of the application by doing a Full Publish.
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 JBoss Tools, incremental hot deployment
is available out of the box for classes in the
src/action
source directory. However, JBoss Tools
does not support incremental hot deployment for EAR projects.
The two core concepts in Seam are the notion of a context and the notion of a component. Components are stateful objects, usually EJBs, and an instance of a component is associated with a context, and given a name in that context. Bijection provides a mechanism for aliasing internal component names (instance variables) to contextual names, allowing component trees to be dynamically assembled, and reassembled by Seam.
Let's start by describing the contexts built in to Seam.
Seam contexts are created and destroyed by the framework. The application does not control context demarcation via explicit Java API calls. Context are usually implicit. In some cases, however, contexts are demarcated via annotations.
The basic Seam contexts are:
Stateless context
Event (i.e., request) context
Page context
Conversation context
Session context
Business process context
Application context
You will recognize some of these contexts from servlet and related specifications. However, two of them might be new to you: conversation context, and business process context. One reason state management in web applications is so fragile and error-prone is that the three built-in contexts (request, session and application) are not especially meaningful from the point of view of the business logic. A user login session, for example, is a fairly arbitrary construct in terms of the actual application work flow. Therefore, most Seam components are scoped to the conversation or business process contexts, since they are the contexts which are most meaningful in terms of the application.
Let's look at each context in turn.
Components which are truly stateless (stateless session beans, primarily) always live in the stateless context (which is basically the absense of a context since the instance Seam resolves is not stored). Stateless components are not very interesting, and are arguably not very object-oriented. Nevertheless, they do get developed and used and are thus an important part of any Seam application.
The event context is the "narrowest" stateful context, and is a generalization of the notion of the web request context to cover other kinds of events. Nevertheless, the event context associated with the lifecycle of a JSF request is the most important example of an event context, and the one you will work with most often. Components associated with the event context are destroyed at the end of the request, but their state is available and well-defined for at least the lifecycle of the request.
When you invoke a Seam component via RMI, or Seam Remoting, the event context is created and destroyed just for the invocation.
The page context allows you to associate state with a particular instance of a rendered page. You can initialize state in your event listener, or while actually rendering the page, and then have access to it from any event that originates from that page. This is especially useful for functionality like clickable lists, where the list is backed by changing data on the server side. The state is actually serialized to the client, so this construct is extremely robust with respect to multi-window operation and the back button.
The conversation context is a truly central concept in Seam. A conversation is a unit of work from the point of view of the user. It might span several interactions with the user, several requests, and several database transactions. But to the user, a conversation solves a single problem. For example, "book hotel", "approve contract", "create order" are all conversations. You might like to think of a conversation implementing a single "use case" or "user story", but the relationship is not necessarily quite exact.
A conversation holds state associated with "what the user is doing now, in this window". A single user may have multiple conversations in progress at any point in time, usually in multiple windows. The conversation context allows us to ensure that state from the different conversations does not collide and cause bugs.
It might take you some time to get used to thinking of applications in terms of conversations. But once you get used to it, we think you'll love the notion, and never be able to not think in terms of conversations again!
Some conversations last for just a single request. Conversations that span multiple requests must be demarcated using annotations provided by Seam.
Some conversations are also tasks. A task is a conversation that is significant in terms of a long-running business process, and has the potential to trigger a business process state transition when it is successfully completed. Seam provides a special set of annotations for task demarcation.
Conversations may be nested, with one conversation taking place "inside" a wider conversation. This is an advanced feature.
Usually, conversation state is actually held by Seam in the servlet session between requests. Seam implements configurable conversation timeout, automatically destroying inactive conversations, and thus ensuring that the state held by a single user login session does not grow without bound if the user abandons conversations.
Seam serializes processing of concurrent requests that take place in the same long-running conversation context, in the same process.
Alternatively, Seam may be configured to keep conversational state in the client browser.
A session context holds state associated with the user login session. While there are some cases where it is useful to share state between several conversations, we generally frown on the use of session context for holding components other than global information about the logged in user.
In a JSR-168 portal environment, the session context represents the portlet session.
The business process context holds state associated with the long running business process. This state is managed and made persistent by the BPM engine (JBoss jBPM). The business process spans multiple interactions with multiple users, so this state is shared between multiple users, but in a well-defined manner. The current task determines the current business process instance, and the lifecycle of the business process is defined externally using a process definition language, so there are no special annotations for business process demarcation.
The application context is the familiar servlet context from the servlet spec. Application context is mainly useful for holding static information such as configuration data, reference data or metamodels. For example, Seam stores its own configuration and metamodel in the application context.
A context defines a namespace, a set of context variables. These work much the same as session or request attributes in the servlet spec. You may bind any value you like to a context variable, but usually we bind Seam component instances to context variables.
So, within a context, a component instance is identified by the context variable name (this is
usually, but not always, the same as the component name). You may programatically access a named
component instance in a particular scope via the Contexts
class, which provides
access to several thread-bound instances of the Context
interface:
User user = (User) Contexts.getSessionContext().get("user");
You may also set or change the value associated with a name:
Contexts.getSessionContext().set("user", user);
Usually, however, we obtain components from a context via injection, and put component instances into a context via outjection.
Sometimes, as above, component instances are obtained from a particular known scope. Other times, all stateful scopes are searched, in priority order. The order is as follows:
Event context
Page context
Conversation context
Session context
Business process context
Application context
You can perform a priority search by calling Contexts.lookupInStatefulContexts()
.
Whenever you access a component by name from a JSF page, a priority search occurs.
Neither the servlet nor EJB specifications define any facilities for managing concurrent requests originating from the same client. The servlet container simply lets all threads run concurrently and leaves enforcing threadsafeness to application code. The EJB container allows stateless components to be accessed concurrently, and throws an exception if multiple threads access a stateful session bean.
This behavior might have been okay in old-style web applications which were based around fine-grained, synchronous requests. But for modern applications which make heavy use of many fine-grained, asynchronous (AJAX) requests, concurrency is a fact of life, and must be supported by the programming model. Seam weaves a concurrency management layer into its context model.
The Seam session and application contexts are multithreaded. Seam will allow concurrent requests in a context to be processed concurrently. The event and page contexts are by nature single threaded. The business process context is strictly speaking multi-threaded, but in practice concurrency is sufficiently rare that this fact may be disregarded most of the time. Finally, Seam enforces a single thread per conversation per process model for the conversation context by serializing concurrent requests in the same long-running conversation context.
Since the session context is multithreaded, and often contains volatile state, session scope
components are always protected by Seam from concurrent access so long as the Seam interceptors
are not disabled for that component. If interceptors are disabled, then any thread-safety that is
required must be implemented by the component itself. Seam serializes requests to session
scope session beans and JavaBeans by default (and detects and breaks any deadlocks that occur). This is
not the default behaviour for application scoped components however, since application scoped components
do not usually hold volatile state and because synchronization at the global level is
extremely expensive. However, you can force a serialized threading model on any
session bean or JavaBean component by adding the @Synchronized
annotation.
This concurrency model means that AJAX clients can safely use volatile session and conversational state, without the need for any special work on the part of the developer.
Seam components are POJOs (Plain Old Java Objects). In particular, they are JavaBeans or EJB 3.0 enterprise beans. While Seam does not require that components be EJBs and can even be used without an EJB 3.0 compliant container, Seam was designed with EJB 3.0 in mind and includes deep integration with EJB 3.0. Seam supports the following component types.
EJB 3.0 stateless session beans
EJB 3.0 stateful session beans
EJB 3.0 entity beans (i.e., JPA entity classes)
JavaBeans
EJB 3.0 message-driven beans
Spring beans (see Chapter 27, Spring Framework integration)
Stateless session bean components are not able to hold state across multiple invocations. Therefore, they usually work by operating upon the state of other components in the various Seam contexts. They may be used as JSF action listeners, but cannot provide properties to JSF components for display.
Stateless session beans always live in the stateless context.
Stateless session beans can be accessed concurrently as a new instance is used for each request. Assigning the instance to the request is the responsibility of the EJB3 container (normally instances will be allocated from a reusable pool meaning that you may find any instance variables contain data from previous uses of the bean).
Stateless session beans are the least interesting kind of Seam component.
Seam stateless session bean components may be instantiated using Component.getInstance()
or @In(create=true)
. They should not be directly instantiated via JNDI lookup
or the new
operator.
Stateful session bean components are able to hold state not only across multiple invocations of the
bean, but also across multiple requests. Application state that does not belong in the database should
usually be held by stateful session beans. This is a major difference between Seam and many other web
application frameworks. Instead of sticking information about the current conversation directly in the
HttpSession
, you should keep it in instance variables of a stateful session bean
that is bound to the conversation context. This allows Seam to manage the lifecycle of this state for
you, and ensure that there are no collisions between state relating to different concurrent
conversations.
Stateful session beans are often used as JSF action listener, and as backing beans that provide properties to JSF components for display or form submission.
By default, stateful session beans are bound to the conversation context. They may never be bound to the page or stateless contexts.
Concurrent requests to session-scoped stateful session beans are always serialized by Seam as long as the Seam interceptors are not disabled for the bean.
Seam stateful session bean components may be instantiated using Component.getInstance()
or @In(create=true)
. They should not be directly instantiated via JNDI lookup
or the new
operator.
Entity beans may be bound to a context variable and function as a seam component. Because entities have a persistent identity in addition to their contextual identity, entity instances are usually bound explicitly in Java code, rather than being instantiated implicitly by Seam.
Entity bean components do not support bijection or context demarcation. Nor does invocation of an entity bean trigger validation.
Entity beans are not usually used as JSF action listeners, but do often function as backing beans that provide properties to JSF components for display or form submission. In particular, it is common to use an entity as a backing bean, together with a stateless session bean action listener to implement create/update/delete type functionality.
By default, entity beans are bound to the conversation context. They may never be bound to the stateless context.
Note that it in a clustered environment is somewhat less efficient to bind an entity bean directly to a conversation or session scoped Seam context variable than it would be to hold a reference to the entity bean in a stateful session bean. For this reason, not all Seam applications define entity beans to be Seam components.
Seam entity bean components may be instantiated using Component.getInstance()
,
@In(create=true)
or directly using the new
operator.
Javabeans may be used just like a stateless or stateful session bean. However, they do not provide the functionality of a session bean (declarative transaction demarcation, declarative security, efficient clustered state replication, EJB 3.0 persistence, timeout methods, etc).
In a later chapter, we show you how to use Seam and Hibernate without an EJB container. In this use case, components are JavaBeans instead of session beans. Note, however, that in many application servers it is somewhat less efficient to cluster conversation or session scoped Seam JavaBean components than it is to cluster stateful session bean components.
By default, JavaBeans are bound to the event context.
Concurrent requests to session-scoped JavaBeans are always serialized by Seam.
Seam JavaBean components may be instantiated using Component.getInstance()
or @In(create=true)
. They should not be directly instantiated using the
new
operator.
Message-driven beans may function as a seam component. However, message-driven beans are called quite differently to other Seam components - instead of invoking them via the context variable, they listen for messages sent to a JMS queue or topic.
Message-driven beans may not be bound to a Seam context. Nor do they have access to the session or conversation state of their "caller". However, they do support bijection and some other Seam functionality.
Message-driven beans are never instantiated by the application. They are instantiated by the EJB container when a message is received.
In order to perform its magic (bijection, context demarcation, validation, etc), Seam must intercept component invocations. For JavaBeans, Seam is in full control of instantiation of the component, and no special configuration is needed. For entity beans, interception is not required since bijection and context demarcation are not defined. For session beans, we must register an EJB interceptor for the session bean component. We could use an annotation, as follows:
@Stateless
@Interceptors(SeamInterceptor.class)
public class LoginAction implements Login {
...
}
But a much better way is to define the interceptor 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>
All seam components need a name. We can assign a name to a component using the
@Name
annotation:
@Name("loginAction")
@Stateless
public class LoginAction implements Login {
...
}
This name is the seam component name and is not related to any other name defined by the EJB specification. However, seam component names work just like JSF managed bean names and you can think of the two concepts as identical.
@Name
is not the only way to define a component name, but we always need
to specify the name somewhere. If we don't, then none of the other
Seam annotations will function.
Whenever Seam instantiates a component, it binds the new instance to a variable in the scope configured
for the component that matches the component name. This behavior is identical to how JSF managed beans
work, except that Seam allows you to configure this mapping using annotations rather than XML. You can
also programmatically bind a component to a context variable. This is useful if a particular component
serves more than one role in the system. For example, the currently logged in User
might be bound to the currentUser
session context variable, while a
User
that is the subject of some administration functionality might be bound to the
user
conversation context variable. Be careful, though, because through a
programmatic assignment, it's possible to overwrite a context variable that has a reference to a Seam
component, potentially confusing matters.
For very large applications, and for built-in seam components, qualified component names are often used to avoid naming conflicts.
@Name("com.jboss.myapp.loginAction")
@Stateless
public class LoginAction implements Login {
...
}
We may use the qualified component name both in Java code and in JSF's expression language:
<h:commandButton type="submit" value="Login"
action="#{com.jboss.myapp.loginAction.login}"/>
Since this is noisy, Seam also provides a means of aliasing a qualified name to a simple name. Add a
line like this to the components.xml
file:
<factory name="loginAction" scope="STATELESS" value="#{com.jboss.myapp.loginAction}"/>
All of the built-in Seam components have qualified names but can be accessed through
their unqualified names due to the namespace import feature of Seam.
The components.xml
file included in the Seam JAR defines the following
namespaces.
<components xmlns="http://jboss.com/products/seam/components"> <import>org.jboss.seam.core</import> <import>org.jboss.seam.cache</import> <import>org.jboss.seam.transaction</import> <import>org.jboss.seam.framework</import> <import>org.jboss.seam.web</import> <import>org.jboss.seam.faces</import> <import>org.jboss.seam.international</import> <import>org.jboss.seam.theme</import> <import>org.jboss.seam.pageflow</import> <import>org.jboss.seam.bpm</import> <import>org.jboss.seam.jms</import> <import>org.jboss.seam.mail</import> <import>org.jboss.seam.security</import> <import>org.jboss.seam.security.management</import> <import>org.jboss.seam.security.permission</import> <import>org.jboss.seam.captcha</import> <import>org.jboss.seam.excel.exporter</import> <!-- ... ---> </components>
When attempting to resolve an unqualified name, Seam will check each of those namespaces, in order.
You can include additional namespaces in your application's components.xml
file
for application-specific namespaces.
We can override the default scope (context) of a component using the @Scope
annotation. This lets us define what context a component instance is bound to, when it is instantiated
by Seam.
@Name("user")
@Entity
@Scope(SESSION)
public class User {
...
}
org.jboss.seam.ScopeType
defines an enumeration of possible scopes.
Some Seam component classes can fulfill more than one role in the system. For example, we often have
a User
class which is usually used as a session-scoped component representing the
current user but is used in user administration screens as a conversation-scoped component. The
@Role
annotation lets us define an additional named role for a component, with a
different scope — it lets us bind the same component class to different context variables. (Any
Seam component instance may be bound to multiple context variables, but this lets
us do it at the class level, and take advantage of auto-instantiation.)
@Name("user")
@Entity
@Scope(CONVERSATION)
@Role(name="currentUser", scope=SESSION)
public class User {
...
}
The @Roles
annotation lets us specify as many additional roles as we like.
@Name("user")
@Entity
@Scope(CONVERSATION)
@Roles({@Role(name="currentUser", scope=SESSION),
@Role(name="tempUser", scope=EVENT)})
public class User {
...
}
Like many good frameworks, Seam eats its own dogfood and is implemented mostly as a set of built-in
Seam interceptors (see later) and Seam components. This makes it easy for applications to interact with
built-in components at runtime or even customize the basic functionality of Seam by replacing the
built-in components with custom implementations. The built-in components are defined in the Seam
namespace org.jboss.seam.core
and the Java package of the same name.
The built-in components may be injected, just like any Seam components, but they also provide
convenient static instance()
methods:
FacesMessages.instance().add("Welcome back, #{user.name}!");
Dependency injection or inversion of control is by now a familiar concept to most Java developers. Dependency injection allows a component to obtain a reference to another component by having the container "inject" the other component to a setter method or instance variable. In all dependency injection implementations that we have seen, injection occurs when the component is constructed, and the reference does not subsequently change for the lifetime of the component instance. For stateless components, this is reasonable. From the point of view of a client, all instances of a particular stateless component are interchangeable. On the other hand, Seam emphasizes the use of stateful components. So traditional dependency injection is no longer a very useful construct. Seam introduces the notion of bijection as a generalization of injection. In contrast to injection, bijection is:
contextual - bijection is used to assemble stateful components from various different contexts (a component from a "wider" context may even have a reference to a component from a "narrower" context)
bidirectional - values are injected from context variables into attributes of the component being invoked, and also outjected from the component attributes back out to the context, allowing the component being invoked to manipulate the values of contextual variables simply by setting its own instance variables
dynamic - since the value of contextual variables changes over time, and since Seam components are stateful, bijection takes place every time a component is invoked
In essence, bijection lets you alias a context variable to a component instance variable, by specifying that the value of the instance variable is injected, outjected, or both. Of course, we use annotations to enable bijection.
The @In
annotation specifies that a value should be injected, either into an instance
variable:
@Name("loginAction")
@Stateless
public class LoginAction implements Login {
@In User user;
...
}
or into a setter method:
@Name("loginAction")
@Stateless
public class LoginAction implements Login {
User user;
@In
public void setUser(User user) {
this.user=user;
}
...
}
By default, Seam will do a priority search of all contexts, using the name of the property or instance
variable that is being injected. You may wish to specify the context variable name explicitly, using, for
example, @In("currentUser")
.
If you want Seam to create an instance of the component when there is no existing component instance
bound to the named context variable, you should specify @In(create=true)
. If the value is
optional (it can be null), specify @In(required=false)
.
For some components, it can be repetitive to have to specify @In(create=true)
everywhere
they are used. In such cases, you can annotate the component @AutoCreate
, and then it
will always be created, whenever needed, even without the explicit use of create=true
.
You can even inject the value of an expression:
@Name("loginAction")
@Stateless
public class LoginAction implements Login {
@In("#{user.username}") String username;
...
}
Injected values are disinjected (i.e., set to null
) immediately after method
completion and outjection.
(There is much more information about component lifecycle and injection in the next chapter.)
The @Out
annotation specifies that an attribute should be outjected, either from an
instance variable:
@Name("loginAction")
@Stateless
public class LoginAction implements Login {
@Out User user;
...
}
or from a getter method:
@Name("loginAction")
@Stateless
public class LoginAction implements Login {
User user;
@Out
public User getUser() {
return user;
}
...
}
An attribute may be both injected and outjected:
@Name("loginAction")
@Stateless
public class LoginAction implements Login {
@In @Out User user;
...
}
or:
@Name("loginAction")
@Stateless
public class LoginAction implements Login {
User user;
@In
public void setUser(User user) {
this.user=user;
}
@Out
public User getUser() {
return user;
}
...
}
Session bean and entity bean Seam components support all the usual EJB 3.0 lifecycle callback
(@PostConstruct
, @PreDestroy
, etc). But Seam also supports
the use of any of these callbacks with JavaBean components. However, since these annotations are
not available in a J2EE environment, Seam defines two additional component lifecycle callbacks,
equivalent to @PostConstruct
and @PreDestroy
.
The @Create
method is called after Seam instantiates a component.
Components may define only one @Create
method.
The @Destroy
method is called when the context that the Seam component is bound to
ends. Components may define only one @Destroy
method.
In addition, stateful session bean components must define a method with no parameters
annotated @Remove
. This method is called by Seam when the context ends.
Finally, a related annotation is the @Startup
annotation, which may be applied to any
application or session scoped component. The @Startup
annotation tells Seam to
instantiate the component immediately, when the context begins, instead of waiting until it is first
referenced by a client. It is possible to control the order of instantiation of startup components by
specifying @Startup(depends={....})
.
The @Install
annotation lets you control conditional installation of components that
are required in some deployment scenarios and not in others. This is useful if:
You want to mock out some infrastructural component in tests.
You want change the implementation of a component in certain deployment scenarios.
You want to install some components only if their dependencies are available (useful for framework authors).
@Install
works by letting you specify precedence
and dependencies.
The precedence of a component is a number that Seam uses to decide which component to install when there are multiple classes with the same component name in the classpath. Seam will choose the component with the higher precendence. There are some predefined precedence values (in ascending order):
BUILT_IN
— the lowest precedece components are
the components built in to Seam.
FRAMEWORK
— components defined by third-party
frameworks may override built-in components, but are overridden by
application components.
APPLICATION
— the default precedence. This is
appropriate for most application components.
DEPLOYMENT
— for application components which
are deployment-specific.
MOCK
— for mock objects used in testing.
Suppose we have a component named messageSender
that talks to
a JMS queue.
@Name("messageSender")
public class MessageSender {
public void sendMessage() {
//do something with JMS
}
}
In our unit tests, we don't have a JMS queue available, so we would like to stub out this method. We'll create a mock component that exists in the classpath when unit tests are running, but is never deployed with the application:
@Name("messageSender")
@Install(precedence=MOCK)
public class MockMessageSender extends MessageSender {
public void sendMessage() {
//do nothing!
}
}
The precedence
helps Seam decide which version to use when it finds
both components in the classpath.
This is nice if we are able to control exactly which classes are in the classpath. But
if I'm writing a reusable framework with many dependecies, I don't want to have to
break that framework across many jars. I want to be able to decide which components
to install depending upon what other components are installed, and upon what classes
are available in the classpath. The @Install
annotation also
controls this functionality. Seam uses this mechanism internally to enable conditional
installation of many of the built-in components. However, you probably won't need to
use it in your application.
Who is not totally fed up with seeing noisy code like this?
private static final Log log = LogFactory.getLog(CreateOrderAction.class);
public Order createOrder(User user, Product product, int quantity) {
if ( log.isDebugEnabled() ) {
log.debug("Creating new order for user: " + user.username() +
" product: " + product.name()
+ " quantity: " + quantity);
}
return new Order(user, product, quantity);
}
It is difficult to imagine how the code for a simple log message could possibly be more verbose. There is more lines of code tied up in logging than in the actual business logic! I remain totally astonished that the Java community has not come up with anything better in 10 years.
Seam provides a logging API that simplifies this code significantly:
@Logger private Log log;
public Order createOrder(User user, Product product, int quantity) {
log.debug("Creating new order for user: #0 product: #1 quantity: #2", user.username(), product.name(), quantity);
return new Order(user, product, quantity);
}
It doesn't matter if you declare the log
variable static or not — it will work
either way, except for entity bean components which require the log
variable to be
static.
Note that we don't need the noisy if ( log.isDebugEnabled() )
guard, since string
concatenation happens inside the debug()
method. Note also that we
don't usually need to specify the log category explicitly, since Seam knows what component it is injecting
the Log
into.
If User
and Product
are Seam components available in the current
contexts, it gets even better:
@Logger private Log log;
public Order createOrder(User user, Product product, int quantity) {
log.debug("Creating new order for user: #{user.username} product: #{product.name} quantity: #0", quantity);
return new Order(user, product, quantity);
}
Seam logging automagically chooses whether to send output to log4j or JDK logging. If log4j is in the classpath, Seam with use it. If it is not, Seam will use JDK logging.
Many application servers feature an amazingly broken implementation of HttpSession
clustering, where changes to the state of mutable objects bound to the session are only replicated when the
application calls setAttribute()
explicitly. This is a source of bugs that can not
effectively be tested for at development time, since they will only manifest when failover occurs.
Furthermore, the actual replication message contains the entire serialized object graph bound to the session
attribute, which is inefficient.
Of course, EJB stateful session beans must perform automatic dirty checking and replication of mutable state and a sophisticated EJB container can introduce optimizations such as attribute-level replication. Unfortunately, not all Seam users have the good fortune to be working in an environment that supports EJB 3.0. So, for session and conversation scoped JavaBean and entity bean components, Seam provides an extra layer of cluster-safe state management over the top of the web container session clustering.
For session or conversation scoped JavaBean components, Seam automatically forces replication to occur by
calling setAttribute()
once in every request that the component was invoked by the
application. Of course, this strategy is inefficient for read-mostly components. You can control this
behavior by implementing the org.jboss.seam.core.Mutable
interface, or by extending
org.jboss.seam.core.AbstractMutable
, and writing your own dirty-checking logic inside
the component. For example,
@Name("account")
public class Account extends AbstractMutable
{
private BigDecimal balance;
public void setBalance(BigDecimal balance)
{
setDirty(this.balance, balance);
this.balance = balance;
}
public BigDecimal getBalance()
{
return balance;
}
...
}
Or, you can use the @ReadOnly
annotation to achieve a similar effect:
@Name("account")
public class Account
{
private BigDecimal balance;
public void setBalance(BigDecimal balance)
{
this.balance = balance;
}
@ReadOnly
public BigDecimal getBalance()
{
return balance;
}
...
}
For session or conversation scoped entity bean components, Seam automatically forces replication to occur
by calling setAttribute()
once in every request, unless the (conversation-scoped)
entity is currently associated with a Seam-managed persistence context, in which case no replication is
needed. This strategy is not necessarily efficient, so session or conversation scope entity beans
should be used with care. You can always write a stateful session bean or JavaBean component to "manage" the
entity bean instance. For example,
@Stateful
@Name("account")
public class AccountManager extends AbstractMutable
{
private Account account; // an entity bean
@Unwrap
public Account getAccount()
{
return account;
}
...
}
Note that the EntityHome
class in the Seam Application Framework provides a great example
of managing an entity bean instance using a Seam component.
We often need to work with objects that are not Seam components. But we still want to be able to inject
them into our components using @In
and use them in value and method binding expressions,
etc. Sometimes, we even need to tie them into the Seam context lifecycle (@Destroy
, for
example). So the Seam contexts can contain objects which are not Seam components, and Seam provides a couple
of nice features that make it easier to work with non-component objects bound to contexts.
The factory component pattern lets a Seam component act as the instantiator for a
non-component object. A factory method will be called when a context variable is
referenced but has no value bound to it. We define factory methods using the @Factory
annotation. The factory method binds a value to the context variable, and determines the scope of the bound
value. There are two styles of factory method. The first style returns a value, which is bound to the
context by Seam:
@Factory(scope=CONVERSATION)
public List<Customer> getCustomerList() {
return ... ;
}
The second style is a method of type void
which binds the value to the context
variable itself:
@DataModel List<Customer> customerList;
@Factory("customerList")
public void initCustomerList() {
customerList = ... ;
}
In both cases, the factory method is called when we reference the customerList
context
variable and its value is null, and then has no further part to play in the lifecycle of the value. An even
more powerful pattern is the manager component pattern. In this case, we have a Seam
component that is bound to a context variable, that manages the value of the context variable, while
remaining invisible to clients.
A manager component is any component with an @Unwrap
method. This method returns the
value that will be visable to clients, and is called every time a context variable is
referenced.
@Name("customerList")
@Scope(CONVERSATION)
public class CustomerListManager
{
...
@Unwrap
public List<Customer> getCustomerList() {
return ... ;
}
}
The manager component pattern is especially useful if we have an object where you need more control over the
lifecycle of the component. For example, if you have a heavyweight object that needs a cleanup operation when
the context ends you could @Unwrap
the object, and perform cleanup in the
@Destroy
method of the manager component.
@Name("hens")
@Scope(APPLICATION)
public class HenHouse
{
Set<Hen> hens;
@In(required=false) Hen hen;
@Unwrap
public List<Hen> getHens()
{
if (hens == null)
{
// Setup our hens
}
return hens;
}
@Observer({"chickBorn", "chickenBoughtAtMarket"})
public addHen()
{
hens.add(hen);
}
@Observer("chickenSoldAtMarket")
public removeHen()
{
hens.remove(hen);
}
@Observer("foxGetsIn")
public removeAllHens()
{
hens.clear();
}
...
}
Here the managed component observes many events which change the underlying object. The component manages these actions itself, and because the object is unwrapped on every access, a consistent view is provided.
The philosophy of minimizing XML-based configuration is extremely strong in Seam. Nevertheless,
there are various reasons why we might want to configure a Seam component using XML: to isolate
deployment-specific information from the Java code, to enable the creation of re-usable frameworks,
to configure Seam's built-in functionality, etc.
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
.
Seam components may be provided with configuration properties either via servlet context parameters, via
system properties, 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, a system
property named org.jboss.seam.properties.com.jboss.myapp.settings.locale
via -D at startup, or
as a servlet context parameter, and Seam will set the value of the locale
attribute
whenever it instantiates the component.
The same mechanism is used to configure Seam itself. For example, to set the conversation timeout, we
provide a value for org.jboss.seam.core.manager.conversationTimeout
in
web.xml
, seam.properties
, or via a system property prefixed with
org.jboss.seam.properties
. (There is a built-in Seam
component named org.jboss.seam.core.manager
with a setter method named
setConversationTimeout()
.)
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 class="org.jboss.seam.bpm.Jbpm"/>
</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"
class="org.jboss.seam.persistence.ManagedPersistenceContext">
<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" auto-create="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). You'll see this approach used in the Seam examples.
If you have a large number of components that need to be configured in XML, it makes much more sense
to split up the information in components.xml
into many small files. Seam lets
you put configuration for a class named, for example, com.helloworld.Hello
in a
resource named com/helloworld/Hello.component.xml
. (You might be familiar with this
pattern, since it is the same one we use in Hibernate.) The root element of the file may be either a
<components>
or <component>
element.
The first option lets you define multiple components in the file:
<components>
<component class="com.helloworld.Hello" name="hello">
<property name="name">#{user.name}</property>
</component>
<factory name="message" value="#{hello.message}"/>
</components>
The second option only lets you define or configure one component, but is less noisy:
<component name="hello">
<property name="name">#{user.name}</property>
</component>
In the second option, the class name is implied by the file in which the component definition appears.
Alternatively, you may put configuration for all classes in the com.helloworld
package in com/helloworld/components.xml
.
Properties of string, primitive or primitive wrapper type may be configured just as you would expect:
org.jboss.seam.core.manager.conversationTimeout 60000
<core:manager conversation-timeout="60000"/>
<component name="org.jboss.seam.core.manager">
<property name="conversationTimeout">60000</property>
</component>
Arrays, sets and lists of strings or primitives are also supported:
org.jboss.seam.bpm.jbpm.processDefinitions order.jpdl.xml, return.jpdl.xml, inventory.jpdl.xml
<bpm:jbpm>
<bpm:process-definitions>
<value>order.jpdl.xml</value>
<value>return.jpdl.xml</value>
<value>inventory.jpdl.xml</value>
</bpm:process-definitions>
</bpm:jbpm>
<component name="org.jboss.seam.bpm.jbpm">
<property name="processDefinitions">
<value>order.jpdl.xml</value>
<value>return.jpdl.xml</value>
<value>inventory.jpdl.xml</value>
</property>
</component>
Even maps with String-valued keys and string or primitive values are supported:
<component name="issueEditor">
<property name="issueStatuses">
<key>open</key> <value>open issue</value>
<key>resolved</key> <value>issue resolved by developer</value>
<key>closed</key> <value>resolution accepted by user</value>
</property>
</component>
When configuring multi-valued properties, by default, Seam will preserve the order in which you place the attributes
in components.xml
(unless you use a SortedSet
/SortedMap
then Seam will use TreeMap
/TreeSet
). If the property has a concrete type (for
example LinkedList
) Seam will use that type.
You can also override the type by specifying a fully qualified class name:
<component name="issueEditor">
<property name="issueStatusOptions" type="java.util.LinkedHashMap">
<key>open</key> <value>open issue</value>
<key>resolved</key> <value>issue resolved by developer</value>
<key>closed</key> <value>resolution accepted by user</value>
</property>
</component>
Finally, you may wire together components using a value-binding expression. Note that this is quite
different to injection using @In
, since it happens at component instantiation time
instead of invocation time. It is therefore much more similar to the dependency injection facilities
offered by traditional IoC containers like JSF or Spring.
<drools:managed-working-memory name="policyPricingWorkingMemory"
rule-base="#{policyPricingRules}"/>
<component name="policyPricingWorkingMemory"
class="org.jboss.seam.drools.ManagedWorkingMemory">
<property name="ruleBase">#{policyPricingRules}</property>
</component>
Seam also resolves an EL expression string prior to assigning the initial value to the bean property of the component. So you can inject some contextual data into your components.
<component name="greeter" class="com.example.action.Greeter">
<property name="message">Nice to see you, #{identity.username}!</property>
</component>
However, there is one important exception. If the type of the property to which the initial value is
being assigned is either a Seam ValueExpression
or
MethodExpression
, then the evaluation of the EL is deferred. Instead, the appropriate
expression wrapper is created and assigned to the property. The message templates on the Home component
from the Seam Application Framework serve as an example.
<framework:entity-home name="myEntityHome"
class="com.example.action.MyEntityHome" entity-class="com.example.model.MyEntity"
created-message="'#{myEntityHome.instance.name}' has been successfully added."/>
Inside the component, you can access the expression string by calling
getExpressionString()
on the ValueExpression
or
MethodExpression
. If the property is a ValueExpression
, you can
resolve the value using getValue()
and if the property is a
MethodExpression
, you can invoke the method using invoke(Object
args...)
. Obviously, to assign a value to a MethodExpression
property, the
entire initial value must be a single EL expression.
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.2.xsd">
<component class="org.jboss.seam.core.init">
<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.2.xsd
http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.2.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. (Package-level annotations are declared in a file named
package-info.java
in the package directory.) Here is an example from the seampay demo:
@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:created-message>
</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>
{
...
}
The element name is the hyphenated form of the component name. The attributes of the element are the hyphenated form of the property names.
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
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.
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>
You can find out more information about JSF events and jBPM events elsewhere. Let's concentrate for now upon the two additional kinds of events defined by Seam.
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>
Keep in mind that if the <page>
element is defined in
a fine-grained page descriptor, the view-id
attribute
can be left off since it is implied.
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. 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>
Page actions are executed on both an initial (non-faces) request and a postback (faces) request. If you are using the page action to load data, this operation may conflict with the standard JSF action(s) being executed on a postback. One way to disable the page action is to setup a condition that resolves to true only on an initial request.
<pages>
<page view-id="/dashboard.xhtml">
<action execute="#{dashboard.loadData}"
if="#{not facesContext.renderKit.responseStateManager.isPostback(facesContext)}"/>
</page>
</pages>
This condition consults the ResponseStateManager#isPostback(FacesContext)
to
determine if the request is a postback. The ResponseStateManager is accessed using
FacesContext.getCurrentInstance().getRenderKit().getResponseStateManager()
.
To save you from the verbosity of JSF's API, Seam offers a built-in condition that allows you to
accomplish the same result with a heck of a lot less typing. You can disable a page action on postback
by simply setting the on-postback
to false
:
<pages>
<page view-id="/dashboard.xhtml">
<action execute="#{dashboard.loadData}" on-postback="false"/>
</page>
</pages>
For backwards compatibility reasons, the default value of the on-postback
attribute
is true, though likely you will end up using the opposite setting more often.
A JSF faces request (a form submission) encapsulates both an "action" (a method binding) and "parameters" (input value bindings). A page action might also needs parameters!
Since GET requests are bookmarkable, page parameters are passed as human-readable request parameters. (Unlike JSF form inputs, which are anything but!)
You can use page parameters with or without an action method.
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).
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.
This all sounds pretty complex, and you're probably wondering if such an exotic construct is really worth the effort. Actually, the idea is very natural once you "get it". It is definitely worth taking the time to understand this stuff. Page parameters are the most elegant way to propagate state across a non-faces request. They are especially cool for problems like search screens with bookmarkable results pages, where we would like to be able to write our application code to handle both POST and GET requests with the same code. Page parameters eliminate repetitive listing of request parameters in the view definition and make redirects much easier to code.
Rewriting occurs based on rewrite patterns found for views in pages.xml
.
Seam URL rewriting does both incoming and outgoing URL rewriting based on the same pattern.
Here's a simple pattern:
<page view-id="/home.xhtml">
<rewrite pattern="/home" />
</page>
In this case, any incoming request for /home
will be sent to
/home.xhtml
. More interestingly,
any link generated that would normally point to /home.seam
will
instead be rewritten as /home
. Rewrite patterns only match the portion of the URL
before the query parameters. So, /home.seam?conversationId=13
and
/home.seam?color=red
will both be matched by this rewrite rule.
Rewrite rules can take these query paramters into consideration, as shown with the following rules.
<page view-id="/home.xhtml">
<rewrite pattern="/home/{color}" />
<rewrite pattern="/home" />
</page>
In this case, an incoming request for /home/red
will be served as
if it were a request
for /home.seam?color=red
. Similarly, if color is a page parameter an outgoing
URL that would normally show as /home.seam?color=blue
would instead
be output as
/home/blue
. Rules are processed in order, so it is important to list
more specific rules before more general rules.
Default Seam query parameters can also be mapped using URL rewriting, allowing for another
option for hiding Seam's fingerprints.
In the following example, /search.seam?conversationId=13
would
be written as /search-13
.
<page view-id="/search.xhtml">
<rewrite pattern="/search-{conversationId}" />
<rewrite pattern="/search" />
</page>
Seam URL rewriting provides simple, bidirectional rewriting on a per-view basis. For more
complex rewriting rules that cover non-seam components, Seam applications can continue to
use the org.tuckey URLRewriteFilter
or apply rewriting rules at the web server.
URL rewriting requires the Seam rewrite filter to be enable. Rewrite filter configuration is discussed in Section 30.1.4.3, “URL rewriting”.
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. Seam also provides a default date converter to convert a string parameter value to a date and back.
When type conversion or validation fails, a global FacesMessage
is added to the FacesContext
.
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 faces-config.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 string-valued 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>
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>
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);
}
}
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.postReInitialization
— called when Seam has re-initialized and started up all components after a redeploy
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>
org.jboss.seam.security.loggedOut
— called when a user logs out
org.jboss.seam.security.loginFailed
— called when a user authentication attempt fails
org.jboss.seam.security.loginSuccessful
— called when a user is successfully authenticated
org.jboss.seam.security.notAuthorized
— called when an authorization check fails
org.jboss.seam.security.notLoggedIn
— called there is no authenticated user and authentication is required
org.jboss.seam.security.postAuthenticate.
— called after a user is authenticated
org.jboss.seam.security.preAuthenticate
— called before attempting to authenticate a user
Seam components may observe any of these events in just the same way they observe any other component-driven events.
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).
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.
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.
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 need to disable Facelets development mode in web.xml
and
Seam debug mode in components.xml
if you want your exception handlers
to fire.
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 { ... }
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 { ... }
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 class="javax.persistence.EntityNotFoundException">
<http-error error-code="404"/>
</exception>
<exception class="javax.persistence.PersistenceException">
<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 class="org.jboss.seam.security.AuthorizationException">
<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.caughtException
.
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 log-level
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 class="org.jboss.seam.security.NotLoggedInException" 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 log-level
to control at which log level the exception will be logged:
<exception class="org.jboss.seam.security.NotLoggedInException" log-level="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 log-level
are: fatal, error, warn, info, debug
or trace
. If the log-level
is not specified, or if an invalid value is
configured, then it will default to error
.
If you are using JPA:
<exception class="javax.persistence.EntityNotFoundException">
<redirect view-id="/error.xhtml">
<message>Not found</message>
</redirect>
</exception>
<exception class="javax.persistence.OptimisticLockException">
<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 class="org.jboss.seam.framework.EntityNotFoundException">
<redirect view-id="/error.xhtml">
<message>Not found</message>
</redirect>
</exception>
If you are using Seam Security:
<exception class="org.jboss.seam.security.AuthorizationException">
<redirect>
<message>You don't have permission to do this</message>
</redirect>
</exception>
<exception class="org.jboss.seam.security.NotLoggedInException">
<redirect view-id="/login.xhtml">
<message>Please log in first</message>
</redirect>
</exception>
And, for JSF:
<exception class="javax.faces.application.ViewExpiredException">
<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. The conversation-required
and no-conversation-view-id
settings in the Seam page descriptor, discussed in Section 7.4, “Requiring a long-running conversation”, give you
finer-grained control over session expiration if you are accessing a page used within a conversation.
<s:link>
and <s:button>
It's time to understand Seam's conversation model in more detail.
Historically, the notion of a Seam "conversation" came about as a merger of three different ideas:
The idea of a workspace, which I encountered in a project for the Victorian government in 2002. In this project I was forced to implement workspace management on top of Struts, an experience I pray never to repeat.
The idea of an application transaction
with optimistic semantics, and the realization that existing
frameworks based around a stateless architecture could not
provide effective management of extended persistence contexts.
(The Hibernate team is truly fed up with copping the blame for
LazyInitializationException
s, which are
not really Hibernate's fault, but rather the fault of the
extremely limiting persistence context model supported by
stateless architectures such as the Spring framework or the
traditional stateless session facade
(anti)pattern in J2EE.)
The idea of a workflow task.
By unifying these ideas and providing deep support in the framework, we have a powerful construct that lets us build richer and more efficient applications with less code than before.
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, non-faces 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. This is usually - but not always - 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?#{manager.conversationIdParameter}=#{conversation.id}">Continue</a>
Or, the more JSF-ish:
<h:outputLink value="main.jsf">
<f:param name="#{manager.conversationIdParameter}" 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 a conversation, end the current conversation,
destroy the entire conversation stack, or begin a nested conversation.
<h:commandLink action="main" value="Exit">
<s:conversationPropagation type="end"/>
</h:commandLink>
<h:commandLink action="main" value="Exit">
<s:conversationPropagation type="endRoot"/>
</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.
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, but can read values from the outer
conversation's context. The outer conversation's context is
read-only within a nested conversation, but because objects
are obtained by reference, changes to the objects themselves
will be reflected in the outer context.
Nesting a conversation through initializes a context that is stacked on the context of the original, or outer, conversation. The outer conversation is considered the parent.
Any values outjected or directly set into the nested conversation’s context do not affect the objects accessible in the parent conversation’s context.
Injection or a context lookup from the conversation context will first lookup the value in the current conversation context and, if no value is found, will proceed down the conversation stack if the conversation is nested. As you will see in moment, this behavior can be overriden.
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.
The conversation at the bottom of the conversation stack is the root
conversation. Destroying this conversation always destroy all of its
descendents. You can achieve this declaratively by specifying
@End(root=true)
.
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 ensuring truly correct behavior in the face of backbuttoning and workspace management.
As mentioned previously, 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
.
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
Certain pages are only relevant in the context of a long-running conversation. One way to "protect" such a page is to require a long-running conversation as a prerequisite to rendering the page. Fortunately, Seam has a built-in mechanism for enforcing this requirement.
In the Seam page descriptor, you can indicate that the current conversation must be long-running (or nested)
in order for a page to be rendered using the conversation-required
attribute as follows:
<page view-id="/book.xhtml" conversation-required="true"/>
The only downside is there's no built-in way to indicate which long-running conversation is required. You can build on this basic authorization by dually checking if a specific value is present in the conversation within a page action.
When Seam determines that this page is requested outside of a long-running conversation, the following actions are taken:
A contextual event named org.jboss.seam.noConversation
is raised
A warning status message is registered using the bundle key org.jboss.seam.NoConversation
The user is redirected to an alternate page, if defined
The alternate page is defined in the no-conversation-view-id
attribute on a
<pages>
element in the Seam page descriptor as follows:
<pages no-conversation-view-id="/main.xhtml"/>
At the moment, you can only define one such page for the entire application.
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="nested"/>
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 is 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"/>
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"/>
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 it's 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 conversation, 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://seam-hotels/book/BestWesternAntwerpen.
Much better!
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 parameter-name
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>
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 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.
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 faces-config.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.
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>
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 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 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 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.
A general discussion of concurrent calls to Seam components can be found in Section 4.1.10, “Concurrency model”. Here we will discuss the most common situation in which you will 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 you.
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, when you are working inside a long running conversation, 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" />
We can also fine tune the concurrent request timeout on a page-by-page basis:
<page view-id="/book.xhtml"
conversation-required="true"
login-required="true"
concurrent-request-timeout="2000" />
So far we've discussed AJAX requests which appear serial to the user - 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 thats going to take a minute?
For heavy computation we should use a poll based approach — the client sends an AJAX request to the server, which causes action to be executed asynchronously on the server (the response to the client is immediate) and the client then polls the server for updates. This is good approach when you have a long-running action for which it is important that every action executes (you don't want some to timeout).
Well first, you need to decide whether you want to use the simpler "serial" request or whether you want to use a polling approach.
If you go for a "serial" requests, then you need to estimate how long your 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 page (as discussed above). 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.
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;
}
However carefully you design your application to queue concurrent
requests to your conversational component, there is a risk that the
server will become overloaded and be unable to process all the
requests before the request will have to wait longer than the
concurrent-request-timeout
. In this case Seam will
throw a ConcurrentRequestTimeoutException
which can
be handled in pages.xml
. We recommend sending an
HTTP 503 error:
<exception class="org.jboss.seam.ConcurrentRequestTimeoutException" log-level="trace">
<http-error error-code="503" />
</exception>
The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay.
Alternatively you could redirect to an error page:
<exception class="org.jboss.seam.ConcurrentRequestTimeoutException" log-level="trace">
<end-conversation/>
<redirect view-id="/error.xhtml">
<message>The server is too busy to process your request, please try again later</message>
</redirect>
</exception>
ICEfaces, RichFaces Ajax and Seam Remoting can all handle HTTP error codes. Seam Remoting will pop up a dialog box showing the HTTP error. ICEfaces will indicate the error in its connection status component. RichFaces provides the most complete support for handling HTTP errors by providing a user definable callback. For example, to show the error message to the user:
<script type="text/javascript"> A4J.AJAX.onError = function(req,status,message) { alert("An error occurred"); }; </script>
If instead of an error code, the server reports that the view has expired, perhaps because the session timed out, you use a separate callback function in RichFaces to handle this scenario.
<script type="text/javascript"> A4J.AJAX.onExpired = function(loc,message) { alert("View expired"); }; </script>
Alternatively, you can allow RichFaces handle the error, in which case the user will be presented with a prompt that reads "View state could't be restored - reload page?" You can customize this message globally by setting the following message key in an application resource bundle.
AJAX_VIEW_EXPIRED=View expired. Please reload the page.
RichFaces (Ajax4jsf) is the Ajax library most commonly used with Seam, and provides all the controls discussed above:
eventsQueue
— provides 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
— ignores the response
produced by the request if a more recent 'similar' request is
already in the queue. ignoreDupResponses="true" does not
cancel 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
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.
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 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 stateful/stateless navigation distinction is quite similar to the traditional view of modal/modeless interaction. Now, Seam applications are not usually modal in the simple sense of the word - indeed, avoiding application modal behavior is one of the main reasons for having conversations! However, Seam applications can be, and often are, modal at the level of a particular conversation. It is well-known that modal behavior is something to avoid as much as possible; it is very difficult to predict the order in which your users are going to want to do things! However, there is no doubt that the stateful model has its place.
The biggest contrast between the two models is the back-button behavior.
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, using the back button 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, the back button is not permitted by default
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 navigation via the back button 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.
We need to install the Seam jBPM-related components, and place the
pageflow definitions (using the standard .jpdl.xml
extension) inside a Seam archive (an archive which
contains a seam.properties
file):
<bpm:jbpm />
We can also explicitly tell Seam where to find our pageflow
definition. We specify this in components.xml
:
<bpm:jbpm>
<bpm:pageflow-definitions>
<value>pageflow.jpdl.xml</value>
</bpm:pageflow-definitions>
</bpm:jbpm>
We "start" a jPDL-based pageflow by specifying the name of the
process definition using a @Begin
,
@BeginTask
or @StartTask
annotation:
@Begin(pageflow="numberguess")
public void begin() { ... }
Alternatively we can start a pageflow using pages.xml:
<page>
<begin-conversation pageflow="numberguess"/>
</page>
If we are beginning the pageflow during the RENDER_RESPONSE
phase — during a @Factory
or @Create
method, for example — we consider ourselves to be already at the page being
rendered, and use a <start-page>
node as the first node
in the pageflow, as in the example above.
But if the pageflow is begun as the result of an action listener invocation,
the outcome of the action listener determines which is the first page to be
rendered. In this case, we use a <start-state>
as
the first node in the pageflow, and declare a transition for each possible
outcome:
<pageflow-definition name="viewEditDocument">
<start-state name="start">
<transition name="documentFound" to="displayDocument"/>
<transition name="documentNotFound" to="notFound"/>
</start-state>
<page name="displayDocument" view-id="/document.jsp">
<transition name="edit" to="editDocument"/>
<transition name="done" to="main"/>
</page>
...
<page name="notFound" view-id="/404.jsp">
<end-conversation/>
</page>
</pageflow-definition>
Each <page>
node represents a state where
the system is waiting for user input:
<page name="displayGuess" view-id="/numberGuess.jsp">
<redirect/>
<transition name="guess" to="evaluateGuess">
<action expression="#{numberGuess.guess}" />
</transition>
</page>
The view-id
is the JSF view id. The <redirect/>
element has the same effect as <redirect/>
in a
JSF navigation rule: namely, a post-then-redirect behavior, to overcome problems
with the browser's refresh button. (Note that Seam propagates conversation contexts
over these browser redirects. So there is no need for a Ruby on Rails style "flash"
construct in Seam!)
The transition name is the name of a JSF outcome triggered by clicking
a command button or command link in numberGuess.jsp
.
<h:commandButton type="submit" value="Guess" action="guess"/>
When the transition is triggered by clicking this button, jBPM will activate the
transition action by calling the guess()
method of the
numberGuess
component. Notice that the syntax used for
specifying actions in the jPDL is just a familiar JSF EL expression, and that
the transition action handler is just a method of a Seam component in the
current Seam contexts. So we have exactly the same event model for jBPM events
that we already have for JSF events! (The One Kind of Stuff
principle.)
In the case of a null outcome (for example, a command button with no
action
defined), Seam will signal the transition with no
name if one exists, or else simply redisplay the page if all transitions
have names. So we could slightly simplify our example pageflow and this button:
<h:commandButton type="submit" value="Guess"/>
Would fire the following un-named transition:
<page name="displayGuess" view-id="/numberGuess.jsp">
<redirect/>
<transition to="evaluateGuess">
<action expression="#{numberGuess.guess}" />
</transition>
</page>
It is even possible to have the button call an action method, in which case the action outcome will determine the transition to be taken:
<h:commandButton type="submit" value="Guess" action="#{numberGuess.guess}"/>
<page name="displayGuess" view-id="/numberGuess.jsp">
<transition name="correctGuess" to="win"/>
<transition name="incorrectGuess" to="evaluateGuess"/>
</page>
However, this is considered an inferior style, since it moves responsibility for controlling the flow out of the pageflow definition and back into the other components. It is much better to centralize this concern in the pageflow itself.
Usually, we don't need the more powerful features of jPDL when defining pageflows.
We do need the <decision>
node, however:
<decision name="evaluateGuess" expression="#{numberGuess.correctGuess}">
<transition name="true" to="win"/>
<transition name="false" to="evaluateRemainingGuesses"/>
</decision>
A decision is made by evaluating a JSF EL expression in the Seam contexts.
We end the conversation using <end-conversation>
or @End
. (In fact, for readability, use of
both is encouraged.)
<page name="win" view-id="/win.jsp">
<redirect/>
<end-conversation/>
</page>
Optionally, we can end a task, specify a jBPM transition
name. In this case, Seam will signal the end of the current task in the
overarching business process.
<page name="win" view-id="/win.jsp">
<redirect/>
<end-task transition="success"/>
</page>
It is possible to compose pageflows and have one pageflow pause
pause while another pageflow executes. The <process-state>
node pauses the outer pageflow, and begins execution of a named
pageflow:
<process-state name="cheat">
<sub-process name="cheat"/>
<transition to="displayGuess"/>
</process-state>
The inner flow begins executing at a <start-state>
node. When it reaches an <end-state>
node,
execution of the inner flow ends, and execution of the outer flow
resumes with the transition defined by the <process-state>
element.