Seam - Contextual Components

Components which are truly stateless (stateless session beans, primarily) always live in the stateless context (this is really a non-context). Stateless components are not very interesting, and are arguably not very object-oriented. Nevertheless, they are important and often useful.

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 distroyed 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", 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.

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:

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.

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 are the least interesting kind of Seam component.

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.

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.

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, automatic 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.

By default, JavaBeans are bound to the conversation context.

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 any Seam contexts apart from the EVENT and APPLICATION contexts. However, they do support bijection and some other Seam functionality.

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.

Almost all seam components need a name. We 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.

Just like in JSF, a seam component instance is usually bound to a context variable with the same name as the component name. So, for example, we would access the LoginAction using Contexts.getStatelessContext().get("loginAction"). In particular, whenever Seam itself instantiates a component, it binds the new instance to a variable with the component name. However, again like JSF, it is possible for the application to bind a component to some other context variable by programmatic API call. This is only 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.

For very large applications, and for built-in seam components, qualified names are often used.

@Name("com.jboss.myapp.loginAction")
@Stateless
@Interceptors(SeamInterceptor.class)
public class LoginAction implements Login { 
    ... 
}

Unfortunately, JSF's expression language interprets a period as a property dereference. So, inside a JSF expression, we use $ to indicate a qualified component name:

<h:commandButton type="submit" value="Login"
                 action="#{com$jboss$myapp$loginAction.login}"/>

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}!");

Seam was designed to integrate tightly in a Java EE 5 environment. However, we understand that there are many projects which are not running in a full EE environment. We also realize the critical importance of easy unit and integration testing using frameworks such as TestNG and JUnit. So, we've made it easy to run Seam in Java SE environments by allowing you to boostrap certain critical infrastructure normally only found in EE environments by installing built-in Seam components.

For example, you can run your EJB3 components in Tomcat or an integration test suite just by installing the built-in component org.jboss.seam.core.ejb, which automatically bootstraps the JBoss Embeddable EJB3 container and deploys your EJB components.

Or, if you're not quite ready for the Brave New World of EJB 3.0, you can write a Seam application that uses only JavaBean components, together with Hibernate3 for persistence, by installing the built-in component org.jboss.seam.core.hibernate. When using Hibernate outside of a J2EE environment, you will also probably need a JTA transaction manager and JNDI server, which are available via the built-in component org.jboss.seam.core.microcontainer. This lets you use the bulletproof JTA/JCA pooling datasource from JBoss application server in an SE environment like Tomcat!

Seam components may be provided with configuration properties either via servlet context parameters, or via a properties file named seam.properties in the root of the classpath.

The configurable Seam component must expose a JavaBeans-style property setter methods for the configurable attributes. If a seam component named com.jboss.myapp.settings has a setter method named setLocale(), we can provide a property named com.jboss.myapp.settings.locale in the seam.properties file or as a servlet context parameter, and Seam will set the value of the locale attribute whenever it instantiates the component.

Note that it is not possible to configure stateless session beans or entity beans.

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 or seam.properties. (There is a built-in Seam component named org.jboss.seam.core.manager with a setter method named setConversationTimeout().)

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

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. The components.xml file lets us handle special cases where that is not the case.

For example, the following components.xml file installs the JBoss Embeddable EJB3 container:

<components>
    <component class="org.jboss.seam.core.Ejb"/>
</components>

This one installs and configures two different Seam-managed persistence contexts:

<components>

    <component name="customerDatabase" 
              class="org.jboss.seam.core.ManagedPersistenceContext">
        <property name="persistenceUnitJndiName">java:/customerEntityManagerFactory</property>
    </component>
    
    <component name="accountingDatabase"
              class="org.jboss.seam.core.ManagedPersistenceContext">
        <property name="persistenceUnitJndiName">java:/accountingEntityManagerFactory</property>
    </component>

</components>

Sometimes we want to reuse the same components.xml file with minor changes during both deployment and testing. Seam let's 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.

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 to specify an action that applies to all view ids that match the pattern:

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

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

The page action method can return a JSF outcome. If the outcome is non-null, Seam will delegate to the defined JSF navigation rules and a different view may end up being rendered.

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

TODO: translate struts action into page action

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

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 WEB-INF/events.xml.

<events>
    <event type="hello">
        <action expression="#{helloListener.sayHelloBack}"/>
        <action expression="#{logger.logHello}"/>
    </event>
<events>

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 events.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");
    }
}

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!");
    }
}

If you don't like the events.xml file, we 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. All state is held in the Seam contexts, and is shared between components.

Let's step through a simple example to see how the Seam object works. First of all, let's create a new Seam component called helloAction.

          
  @Stateless
  @Name("helloAction")
  @Scope(SESSION)
  public class HelloAction implements HelloLocal {
    public String sayHello(String name) {
      return "Hello, " + name;
    }
  }
          
        

You also need to create a local interface for our new component - take special note of the @WebRemote annotation, as it's required to make our method accessible via remoting:

          
  @Local
  public interface HelloLocal {
    @WebRemote
    public String sayHello(String name);
  }
          
        

That's all the server-side code we need to write. Now for our web page - create a new page and import the following scripts:

          
  <script type="text/javascript" src="seam/remoting/resource/remote.js">
    <!--
    // This space intentionally left blank
    //-->
  </script>

  <script type="text/javascript" src="seam/remoting/interface.js?helloAction">
    <!--
    // This space intentionally left blank
    //-->
  </script>
          
        

To make this a fully interactive user experience, let's add a button to our page:

          
  <button onclick="javascript:sayHello()">Say Hello</button>
          
        

We'll also need to add some more script to make our button actually do something when it's clicked:

          
  <script type="text/javascript">
    //<![CDATA[

    function sayHello() {
      var name = prompt("What is your name?");
      Seam.Component.getInstance("helloAction").sayHello(name, sayHelloCallback);
    }

    function sayHelloCallback(result) {
      alert(result);
    }

    // ]]>
  </script>
          
        

We're done! Deploy your application and browse to your page. Click the button, and enter a name when prompted. A message box will display the hello message confirming that the call was successful. If you want to save some time, you'll find the full source code for this Hello World example in Seam's /examples/remoting/helloworld directory.

So what does the code of our script actually do? Let's break it down into smaller pieces. To start with, you can see from the Javascript code listing that we have implemented two methods - the first method is responsible for prompting the user for their name and then making a remote request. Take a look at the following line:

  Seam.Component.getInstance("helloAction").sayHello(name, sayHelloCallback);
        

The first section of this line, Seam.Component.getInstance("helloAction") returns a proxy, or "stub" for our helloAction component. We can invoke the methods of our component against this stub, which is exactly what happens with the remainder of the line: sayHello(name, sayHelloCallback);.

What this line of code in its completeness does, is invoke the sayHello method of our component, passing in name as a parameter. The second parameter, sayHelloCallback isn't a parameter of our component's sayHello method, instead it tells the Seam Remoting framework that once it receives the response to our request, it should pass it to the sayHelloCallback Javascript method. This callback parameter is entirely optional, so feel free to leave it out if you're calling a method with a void return type or if you don't care about the result.

The sayHelloCallback method, once receiving the response to our remote request then pops up an alert message displaying the result of our method call.

The Seam.Component Javascript object provides a number of client-side methods for working with your Seam components. The two main methods, newInstance() and getInstance() are documented in the following sections however their main difference is that newInstance() will always create a new instance of a component type, and getInstance() will return a singleton instance.

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

  var customer = Seam.Component.newInstance("customer");
          

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

  Seam.Component.getInstance("customerAction").saveCustomer(customer);          
          

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

Most of the client side functionality for Seam Remoting is contained within the Seam.Remoting object. While you shouldn't need to directly call most of its methods, there are a couple of important ones worth mentioning.

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

This section describes the support for basic data types. On the server side these values are generally compatible with either their primitive type or their corresponding wrapper class.

In general these will be either Seam entity or JavaBean components, or some other non-component class. Use the appropriate method (either Seam.Component.newInstance() for Seam components or Seam.Remoting.createType() for everything else) to create a new instance of the object.

It is important to note that only objects that are created by either of these two methods should be used as parameter values, where the parameter is not one of the other valid types mentioned anywhere else in this section. In some situations you may have a component method where the exact parameter type cannot be determined, such as:

  @Name("myAction")
  public class MyAction implements MyActionLocal {
    public void doSomethingWithObject(Object obj) {
      // code
    }
  }
        

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

                  
  <script type="text/javascript" src="seam/remoting/interface.js?myAction&myWidget">
    <!--
    // This space intentionally left blank
    //-->
  </script>        
          
        

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

Date values are serialized into a String representation that is accurate to the millisecond. On the client side, use a Javascript Date object to work with date values. On the server side, use any java.util.Date (or descendent, such as java.sql.Date or java.sql.Timestamp class.

On the client side, enums are treated the same as Strings. When setting the value for an enum parameter, simply use the String representation of the enum. Take the following component as an example:

  @Name("paintAction")
  public class paintAction implements paintLocal {
    public enum Color {red, green, blue, yellow, orange, purple};

    public void paint(Color color) {
      // code
    }    
  }            
        

To call the paint() method with the color red, pass the parameter value as a String literal:

  Seam.Component.getInstance("paintAction").paint("red");
        

The inverse is also true - that is, if a component method returns an enum parameter (or contains an enum field anywhere in the returned object graph) then on the client-side it will be represented as a String.

To change the message from the default "Please Wait..." to something different, set the value of Seam.Remoting.loadingMessage:

  Seam.Remoting.loadingMessage = "Loading...";        
        

To completely suppress the display of the loading message, override the implementation of displayLoadingMessage() and hideLoadingMessage() with functions that instead do nothing:

  // don't display the loading indicator
  Seam.Remoting.displayLoadingMessage = function() {};
  Seam.Remoting.hideLoadingMessage = function() {};        
        

It is also possible to override the loading indicator to display an animated icon, or anything else that you want. To do this override the displayLoadingMessage() and hideLoadingMessage() messages with your own implementation:

  Seam.Remoting.displayLoadingMessage = function() {
    // Write code here to display the indicator
  };
  
  Seam.Remoting.hideLoadingMessage = function() {
    // Write code here to hide the indicator
  };
        

Before you can subscribe to a JMS topic, you must first configure a list of the topics that can be subscribed to by Seam Remoting. List the topics under org.jboss.seam.remoting.messaging.subscriptionRegistry.allowedTopics in seam.properties, web.xml or components.xml.

<component name="org.jboss.seam.remoting.messaging.subscriptionRegistry">
    <property name="allowedTopics">chatroomTopic, stockTickerTopic</property>
</component>

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

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

The Seam.Remoting.subscribe() method accepts two parameters, the first being the name of the JMS Topic to subscribe to, the second being the callback function to invoke when a message is received.

There are two types of messages supported, Text messages and Object messages. If you need to test for the type of message that is passed to your callback function you can use the instanceof operator to test whether the message is a Seam.Remoting.TextMessage or Seam.Remoting.ObjectMessage. A TextMessage contains the text value in its text field (or alternatively call getText() on it), while an ObjectMessage contains its object value in its object field (or call its getObject() method).

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

  Seam.Remoting.unsubscribe("topicName");        
        

There are two parameters which you can modify to control how polling occurs. The first one is Seam.Remoting.pollInterval, which controls how long to wait between subsequent polls for new messages. This parameter is expressed in seconds, and its default setting is 10.

The second parameter is Seam.Remoting.pollTimeout, and is also expressed as seconds. It controls how long a request to the server should wait for a new message before timing out and sending an empty response. Its default is 0 seconds, which means that when the server is polled, if there are no messages ready for delivery then an empty response will be immediately returned.

The following example demonstrates how to configure the polling to occur much more aggressively. You should set these parameters to suitable values for your application:

  // Only wait 1 second between receiving a poll response and sending the next poll request.
  Seam.Remoting.pollInterval = 1;
  
  // Wait up to 5 seconds on the server for new messages
  Seam.Remoting.pollTimeout = 5;   
        

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

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

This listener is responsible for bootstrapping Seam, and for destroying session and application contexts.

If you are using Seam in Apache MyFaces (and possibly some other JSF implementations), you must use client-side state saving. So you'll also need this in web.xml:

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

To integrate with the JSF request lifecycle, we also need a JSF PhaseListener registered in in the faces-config.xml file:

<lifecycle>
    <phase-listener>org.jboss.seam.jsf.SeamPhaseListener</phase-listener>
</lifecycle>

The actual listener class here varies depending upon how you want to manage transaction demarcation (more on this below).

We need to apply the SeamInterceptor to our Seam components. The simplest way to do this is to add the following interceptor binding to the <assembly-descriptor> in ejb-jar.xml:

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

Seam needs to know where to go to find session beans in JNDI. One way to do this is specify the @JndiName annotation on every session bean Seam component. However, this is quite tedious. A better approach is to specify a pattern that Seam can use to calculate the JNDI name from the EJB name. Unfortunately, there is no standard mapping to global JNDI defined in the EJB3 specification, so this mapping is vendor-specific. We must specify a pattern using the configuration property named org.jboss.seam.core.init.jndiPattern. We may specify this using components.xml, web.xml or even seam.properties.

For JBoss AS, the following pattern is correct:

<component name="org.jboss.seam.core.init">
    <property name="jndiPattern">myEarName/#{ejbName}/local</property>
</component>

Or:

<context-param>
    <param-name>org.jboss.seam.core.init.jndiPattern</param-name>
    <param-value>myEarName/#{ejbName}/local</param-value>
</context-param>

Where myEarName is the name of the EAR in which the bean is deployed.

Outside the context of an EAR (when using the JBoss Embeddable EJB3 container), the following pattern is the one to use:

<component name="org.jboss.seam.core.init">
    <property name="jndiPattern">#{ejbName}/local</property>
</component>

Or:

<context-param>
    <param-name>org.jboss.seam.core.init.jndiPattern</param-name>
    <param-value>#{ejbName}/local</param-value>
</context-param>

If you want to use post-then-redirect in JSF, and you want Seam to propagate the conversation context across the browser redirects, you need to register a servlet filter:

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

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

This filter intercepts any browser redirects and adds a request parameter that specifies the Seam conversation id.

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

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

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

Seam ships with several example applications that are deployable in any Java EE container that supports EJB 3.0.

Seam ships with a build of the Embeddable EJB3 container in the embedded-ejb directory. To use the Embeddable EJB3 container with Seam, add the embedded-ejb/conf directory, and all jars in the lib and embedded-ejb/lib directories to your classpath. Then, add the following line to components.xml:

<component class="org.jboss.seam.core.Ejb"/>

This setting installs the built-in component named org.jboss.seam.core.ejb. This component is responsible for bootstrapping the EJB container when Seam is started, and shutting it down when the web application is undeployed.

You should refer to the Embeddable EJB3 container documentation for more information about configuring the container. You'll probably at least need to set up your own datasource. Embeddable EJB3 is implemented using the JBoss Microcontainer, so it's very easy to add new services to the minimal set of services provided by default. For example, I can add a new datasource by putting this jboss-beans.xml file in my classpath:

<?xml version="1.0" encoding="UTF-8"?>

<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="urn:jboss:bean-deployer bean-deployer_1_0.xsd"
            xmlns="urn:jboss:bean-deployer">

   <bean name="bookingDatasourceBootstrap"
        class="org.jboss.resource.adapter.jdbc.local.LocalTxDataSource">
      <property name="driverClass">org.hsqldb.jdbcDriver</property>
      <property name="connectionURL">jdbc:hsqldb:.</property>
      <property name="userName">sa</property>
      <property name="jndiName">java:/bookingDatasource</property>
      <property name="minSize">0</property>
      <property name="maxSize">10</property>
      <property name="blockingTimeout">1000</property>
      <property name="idleTimeout">100000</property>
      <property name="transactionManager">
        <inject bean="TransactionManager"/>
      </property>
      <property name="cachedConnectionManager">
        <inject bean="CachedConnectionManager"/>
      </property>
      <property name="initialContextProperties">
        <inject bean="InitialContextProperties"/>
      </property>
   </bean>

   <bean name="bookingDatasource" class="java.lang.Object">
      <constructor factoryMethod="getDatasource">
         <factory bean="bookingDatasourceBootstrap"/>
      </constructor>
   </bean>

</deployment>

The archive structure of a WAR-based deployment on an servlet engine like Tomcat will look something like this:

my-application.war/
    META-INF/
        MANIFEST.MF
    WEB-INF/
        web.xml
        components.xml
        faces-config.xml
        lib/
            jboss-seam.jar
            myfaces-api.jar
            myfaces-impl.jar
            jboss-ejb3.jar
            jboss-jca.jar
            jboss-j2ee.jar
            ...
            mc-conf.jar/
                ejb3-interceptors-aop.xml
                embedded-jboss-beans.xml
                default.persistence.properties
                jndi.properties
                login-config.xml
                security-beans.xml
                log4j.xml
            my-application.jar/
                META-INF/
                    MANIFEST.MF
                    persistence.xml
                    jboss-beans.xml
                log4j.xml
                seam.properties
                org/
                    jboss/
                        myapplication/
                            User.class
                            Login.class
                            LoginBean.class
                            Register.class
                            RegisterBean.class
                            ...
    login.jsp
    register.jsp
    ...

The mc-conf.jar just contains the standard JBoss Microcontainer configuration files for Embeddable EJB3. You won't usually need to edit these files yourself.

Most of the Seam example applications may be deployed to Tomcat by running ant deploy.tomcat.

To make use of Seam managed transactions, you need to use SeamExtendedManagedPersistencePhaseListener in place of SeamPhaseListener.

<lifecycle>
     <phase-listener>
        org.jboss.seam.jsf.SeamExtendedManagedPersistencePhaseListener
    </phase-listener>
</lifecycle>

It's also a good idea to add a servlet filter to rollback uncommitted transactions when uncaught exceptions occur.

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

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

You'll need to use a managed persistence context (for EJB3) or managed session (for Hibernate) in your components. We'll see how to use a managed session later. Configuring a managed persistence context is easy. In components.xml, we can write:

<component name="bookingDatabase"
          class="org.jboss.seam.core.ManagedPersistenceContext">
    <property name="persistenceUnitJndiName">java:/EntityManagerFactories/bookingData</property>
</component>

This configuration creates a conversation-scoped Seam component named bookingDatabase that manages the lifecycle of EntityManager instances for the persistence unit (EntityManagerFactory instance) with JNDI name java:/EntityManagerFactories/bookingData.

Of course, you need to make sure that you have bound the EntityManagerFactory into JNDI. In JBoss, you can do this by adding the following property setting to persistence.xml.

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

Now we can have our EntityManager injected using:

@In(create=true) EntityManager bookingDatabase;

Seam will bootstrap a Hibernate SessionFactory from your hibernate.cfg.xml file if you install the built-in component named org.jboss.seam.core.hibernate.

We will also need to configure a managed session if we want a Seam managed Hibernate Session to be available via injection.

To configure our Seam component, as usual, we use components.xml:

<component class="org.jboss.seam.core.Hibernate"/>

<component name="bookingDatabase"
          class="org.jboss.seam.core.ManagedHibernateSession">
    <property name="sessionFactoryJndiName">java:/bookingSessionFactory</property>
</component>

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

<session-factory name="java:/bookingSessionFactory">
    ...
</session-factory>

We can now have a managed Hibernate Session injected into our JavaBean components using the following code:

@In(create=true) Session bookingDatabase;

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

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

The built-in Seam component named org.jboss.seam.core.microcontainer bootstraps the microcontainer. As before, we probably want to use a Seam managed session.

<component class="org.jboss.seam.core.Microcontainer"/>
        
<component name="bookingDatabase"
          class="org.jboss.seam.core.ManagedHibernateSession">
    <property name="sessionFactoryJndiName">java:/bookingSessionFactory</property>
</component>

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

You'll need to provide a jboss.beans.xml file that installs JNDI, JTA, your JCA datasource and Hibernate into the microcontainer:

<?xml version="1.0" encoding="UTF-8"?>

<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="urn:jboss:bean-deployer bean-deployer_1_0.xsd"
            xmlns="urn:jboss:bean-deployer">
            
   <bean name="Naming" class="org.jnp.server.SingletonNamingServer"/>

   <bean name="TransactionManagerFactory" class="org.jboss.seam.microcontainer.TransactionManagerFactory"/>
   <bean name="TransactionManager" class="java.lang.Object">
      <constructor factoryMethod="getTransactionManager">
         <factory bean="TransactionManagerFactory"/>
      </constructor>
   </bean>

   <bean name="bookingDatasourceFactory" class="org.jboss.seam.microcontainer.DataSourceFactory">
      <property name="driverClass">org.hsqldb.jdbcDriver</property>
      <property name="connectionUrl">jdbc:hsqldb:.</property>
      <property name="userName">sa</property>
      <property name="jndiName">java:/hibernateDatasource</property>
      <property name="minSize">0</property>
      <property name="maxSize">10</property>
      <property name="blockingTimeout">1000</property>
      <property name="idleTimeout">100000</property>
      <property name="transactionManager"><inject bean="TransactionManager"/></property>
   </bean>
   <bean name="bookingDatasource" class="java.lang.Object">
      <constructor factoryMethod="getDataSource">
         <factory bean="bookingDatasourceFactory"/>
      </constructor>
   </bean>
   
   <bean name="bookingDatabaseFactory" class="org.jboss.seam.microcontainer.HibernateFactory"/>
   <bean name="bookingDatabase" class="java.lang.Object">
      <constructor factoryMethod="getSessionFactory">
         <factory bean="bookingDatabaseFactory"/>
      </constructor>
      <depends>bookingDatasource</depends>
   </bean>

</deployment>

The WAR could have the following structure:

my-application.war/
    META-INF/
        MANIFEST.MF
    WEB-INF/
        web.xml
        components.xml
        faces-config.xml
        lib/
            jboss-seam.jar
            hibernate3.jar
            ...
            jboss-microcontainer.jar
            jboss-jca.jar
            ...
            myfaces-api.jar
            myfaces-impl.jar
            mc-conf.jar/
                jndi.properties
                log4j.xml
            my-application.jar/
                META-INF/
                    MANIFEST.MF
                    jboss-beans.xml
                seam.properties
                hibernate.cfg.xml
                log4j.xml
                org/
                    jboss/
                        myapplication/
                            User.class
                            Login.class
                            Register.class
                            ...
    login.jsp
    register.jsp
    ...

There is not yet any well-defined packaging format for jBPM configuration and process/pageflow definition files. In the Seam examples we've decided to simply package all these files into the root of the EAR. In future, we will probably design some other standard packaging format. So the EAR looks something like this:

my-application.ear/
    jboss-seam.jar
    jbpm-3.1.jar
    META-INF/
        MANIFEST.MF
        application.xml
    my-application.war/
        META-INF/
            MANIFEST.MF
        WEB-INF/
            web.xml
            components.xml
            faces-config.xml
        login.jsp
        register.jsp
        ...
    my-application.jar/
        META-INF/
            MANIFEST.MF
            persistence.xml
        seam.properties
        org/
            jboss/
                myapplication/
                    User.class
                    Login.class
                    LoginBean.class
                    Register.class
                    RegisterBean.class
                    ...
    jbpm.cfg.xml
    hibernate.cfg.xml
    createDocument.jpdl.xml 
    editDocument.jpdl.xml 
    approveDocument.jpdl.xml
    documentLifecycle.jpdl.xml

Remember to add jbpm-3.1.jar to the manifest of your EJB-JAR and WAR.