SeamFramework.orgCommunity Documentation

Chapter 29. Configuring Seam and packaging Seam applications

29.1. Basic Seam configuration
29.1.1. Integrating Seam with JSF and your servlet container
29.1.2. Using facelets
29.1.3. Seam Resource Servlet
29.1.4. Seam servlet filters
29.1.5. Integrating Seam with your EJB container
29.1.6. Don't forget!
29.2. Using Alternate JPA Providers
29.3. Configuring Seam in Java EE 5
29.3.1. Packaging
29.4. Configuring Seam in J2EE
29.4.1. Boostrapping Hibernate in Seam
29.4.2. Boostrapping JPA in Seam
29.4.3. Packaging
29.5. Configuring Seam in Java SE, without JBoss Embedded
29.6. Configuring Seam in Java SE, with JBoss Embedded
29.6.1. Installing Embedded JBoss
29.6.2. Packaging
29.7. Configuring jBPM in Seam
29.7.1. Packaging
29.8. Configuring SFSB and Session Timeouts in JBoss AS
29.9. Running Seam in a Portlet
29.10. Deploying custom resources

Configuration is a very boring topic and an extremely tedious pastime. Unfortunately, several lines of XML are required to integrate Seam into your JSF implementation and servlet container. There's no need to be too put off by the following sections; you'll never need to type any of this stuff yourself, since you can just copy and paste from the example applications!

First, let's look at the basic configuration that is needed whenever we use Seam with JSF.

Of course, you need a faces servlet!

    <servlet-name>Faces Servlet</servlet-name>

    <servlet-name>Faces Servlet</servlet-name>

(You can adjust the URL pattern to suit your taste.)

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


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

Some JSF implementations have a broken implementation of server-side state saving that interferes with Seam's conversation propagation. If you have problems with conversation propagation during form submissions, try switching to client-side state saving. You'll need this in web.xml:


There is a minor gray area in the JSF specification regarding the mutability of view state values. Since Seam uses the JSF view state to back its PAGE scope this can become an issue in some cases. If you're using server side state saving with the JSF-RI and you want a PAGE scoped bean to keep its exact value for a given view of a page you will need to specify the following context-param. Otherwise if a user uses the "back" button a PAGE scoped component will have the latest value if it has changed not the value of the "back" page. (see Spec Issue ). This setting is not enabled by default because of the performance hit of serializing the JSF view with every request.


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

    <filter-name>Seam Filter</filter-name>

    <filter-name>Seam Filter</filter-name>

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

The Seam filters share a number of common attributes, you can set these in components.xml in addition to any parameters discussed below:

Note that the patterns are matched against the URI path of the request (see HttpServletRequest.getURIPath()) and that the name of the servlet context is removed before matching.

Adding the master filter enables the following built-in filters.

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


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

For JBoss AS, the following pattern is correct:

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

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

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

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

You'll have to experiment to find the right setting for other application servers. Note that some servers (such as GlassFish) require you to specify JNDI names for all EJB components explicitly (and tediously). In this case, you can pick your own pattern ;-)

In an EJB3 environment, we recommend the use of a special built-in component for transaction management, that is fully aware of container transactions, and can correctly process transaction success events registered with the Events component. If you don't add this line to your components.xml file, Seam won't know when container-managed transactions end:


Seam comes packaged and configured with Hibernate as the default JPA provider. If you require using a different JPA provider you must tell seam about it.

Telling seam about a different JPA provider can be be done in one of two ways:

Update your application's components.xml so that the generic PersistenceProvider takes precedence over the hibernate version. Simply add the following to the file:

<component name="org.jboss.seam.persistence.persistenceProvider" 

If you want to take advantage of your JPA provider's non-standard features you will need to write you own implementation of the PersistenceProvider. Use HibernatePersistenceProvider as a starting point (don't forget to give back to the community :). Then you will need to tell seam to use it as before.

<component name="org.jboss.seam.persistence.persistenceProvider" 

All that is left is updating the persistence.xml file with the correct provider class, and what ever properties your provider needs. Don't forget to package your new provider's jar files in the application if they are needed.

If you're running in a Java EE 5 environment, this is all the configuration required to start using Seam!

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


You should declare jboss-seam.jar as an ejb module in META-INF/application.xml; jboss-el.jar should be placed in the EAR's lib directory (putting it in the EAR classpath.

If you want to use jBPM or Drools, you must include the needed jars in the EAR's lib directory.

If you want to use facelets (our recommendation), you must include jsf-facelets.jar in the WEB-INF/lib directory of the WAR.

If you want to use the Seam tag library (most Seam applications do), you must include jboss-seam-ui.jar in the WEB-INF/lib directory of the WAR. If you want to use the PDF or email tag libraries, you need to put jboss-seam-pdf.jar or jboss-seam-mail.jar in WEB-INF/lib.

If you want to use the Seam debug page (only works for applications using facelets), you must include jboss-seam-debug.jar in the WEB-INF/lib directory of the WAR.

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

I really wish that was all there was to say on the topic of configuration but unfortunately we're only about a third of the way there. If you're too overwhelmed by all this tedious configuration stuff, feel free to skip over the rest of this section and come back to it later.

Seam is useful even if you're not yet ready to take the plunge into EJB 3.0. In this case you would use Hibernate3 or JPA instead of EJB 3.0 persistence, and plain JavaBeans instead of session beans. You'll miss out on some of the nice features of session beans but it will be very easy to migrate to EJB 3.0 when you're ready and, in the meantime, you'll be able to take advantage of Seam's unique declarative state management architecture.

Seam JavaBean components do not provide declarative transaction demarcation like session beans do. You could manage your transactions manually using the JTA UserTransaction or declaratively using Seam's @Transactional annotation. But most applications will just use Seam managed transactions when using Hibernate with JavaBeans.

The Seam distribution includes a version of the booking example application that uses Hibernate3 and JavaBeans instead of EJB3, and another version that uses JPA and JavaBeans. These example applications are ready to deploy into any J2EE application server.

It is possible to use Seam completely outside of an EE environment. In this case, you need to tell Seam how to manage transactions, since there will be no JTA available. If you're using JPA, you can tell Seam to use JPA resource-local transactions, ie. EntityTransaction, like so:

<transaction:entity-transaction entity-manager="#{entityManager}"/>

If you're using Hibernate, you can tell Seam to use the Hibernate transaction API like this:

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

Of course, you'll also need to define a datasource.

A better alternative is to use JBoss Embedded to get access to the EE APIs.

JBoss Embedded lets you run EJB3 components outside the context of the Java EE 5 application server. This is especially, but not only, useful for testing.

The Seam booking example application includes a TestNG integration test suite that runs on JBoss Embedded via SeamTest.

The booking example application may even be deployed to Tomcat.

Embedded JBoss must by installed into Tomcat for Seam applications to run correctly on it. Embedded JBoss runs with JDK 5 or JDK 6 ( see Section 40.1, “JDK Dependencies” for details on using JDK 6). Embedded JBoss can be downloaded here. The process for installing Embedded JBoss into Tomcat 6 is quite simple. First, you should copy the Embedded JBoss JARs and configuration files into Tomcat.

  • Copy all files and directories under the Embedded JBoss bootstrap and lib directories, except for the file, into the Tomcat lib directory.

  • Remove the annotations-api.jar file from the Tomcat lib directory.

Next, two configuration files need to be updated to add Embedded JBoss-specific functionality.

  • Add the Embedded JBoss listener EmbeddedJBossBootstrapListener to conf/server.xml. It must appear after all other listeners in the file:

    <Server port="8005" shutdown="SHUTDOWN">

      <!-- Comment these entries out to disable JMX MBeans support used for the 
           administration web application -->
      <Listener className="org.apache.catalina.core.AprLifecycleListener" />
      <Listener className="org.apache.catalina.mbeans.ServerLifecycleListener" />
      <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />
      <Listener className="org.apache.catalina.storeconfig.StoreConfigLifecycleListener"/>
    <!-- Add this listener -->
      <Listener className="org.jboss.embedded.tomcat.EmbeddedJBossBootstrapListener"/>
  • WAR file scanning should be enabled by adding the WebinfScanner listener to conf/context.xml:

        <!-- Default set of monitored resources -->
        <!-- Uncomment this to disable session persistence across Tomcat restarts -->
        <Manager pathname="" />
    <!-- Add this listener -->
      <Listener className="org.jboss.embedded.tomcat.WebinfScanner"/>
  • If you are using JDK 6, you must set the Java option sun.lang.ClassLoader.allowArraySyntax to true in Tomcat's startup script (either catalina.bat or

    set JAVA_OPTS=%JAVA_OPTS% -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djava.util.logging.config.file="%CATALINA_BASE%\conf\" -Dsun.lang.ClassLoader.allowArraySyntax=true

For more configuration options, please see the Embedded JBoss Tomcat integration wiki entry.

Seam's jBPM integration is not installed by default, so you'll need to enable jBPM by installing a built-in component. You'll also need to explicitly list your process and pageflow definitions. In components.xml:


No further special configuration is needed if you only have pageflows. If you do have business process definitions, you need to provide a jBPM configuration, and a Hibernate configuration for jBPM. The Seam DVD Store demo includes example jbpm.cfg.xml and hibernate.cfg.xml files that will work with Seam:


    <service name="persistence">
          <bean class="org.jbpm.persistence.db.DbPersistenceServiceFactory">
             <field name="isTransactionEnabled"><false/></field>
    <service name="tx" factory="org.jbpm.tx.TxServiceFactory" />
    <service name="message" factory="org.jbpm.msg.db.DbMessageServiceFactory" />
    <service name="scheduler" factory="org.jbpm.scheduler.db.DbSchedulerServiceFactory" />
    <service name="logging" factory="org.jbpm.logging.db.DbLoggingServiceFactory" />
    <service name="authentication" 
             factory="" />


The most important thing to notice here is that jBPM transaction control is disabled. Seam or EJB3 should control the JTA transactions.

It is very important that the timeout for Stateful Session Beans is set higher than the timeout for HTTP Sessions, otherwise SFSB's may time out before the user's HTTP session has ended. JBoss Application Server has a default session bean timeout of 30 minutes, which is configured in server/default/conf/standardjboss.xml (replace default with your own configuration).

The default SFSB timeout can be adjusted by modifying the value of max-bean-life in the LRUStatefulContextCachePolicy cache configuration:


        <!-- SFSB timeout in seconds; 1800 seconds == 30 minutes -->


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

    <!-- HTTP Session timeout, in minutes -->

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

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

Seam scans all jars containing /, /META-INF/components.xml or /META-INF/ on startup for resources. For example, all classes annotated with @Name are registered with Seam as Seam components.

You may also want Seam to handle custom resources. A common use case is to handle a specific annotation and Seam provides specific support for this. First, tell Seam which annotations to handle in /META-INF/

# A colon-separated list of annotation types to handle

Then, during application startup you can get hold of all classes annotated with @Foo:

public class FooStartup {

   private Set<Class<Object>> fooClasses;
   private Set<Class<Object>> hotFooClasses;

   public void create() {
      for (Class clazz : fooClasses) {
      for (Class clazz : hotFooClasses) {


You can also handle any resource. For example, you process any files with the extension .foo.xml. To do this, we need to write a custom deployment handler:

public class FooDeploymentHandler implements DeploymentHandler {
   private Set<InputStream> files = new HashSet<InputStream>();
   public String getName() {
      return "fooDeploymentHandler";
   public Set<InputStream> getFiles() {
      return files;
   public void handle(String name, ClassLoader classLoader) {
      if (name.endsWith(".foo.xml")) {

Here we are just building a list of any files with the suffix .foo.xml.

Then, we need to register the deployment handler with Seam. In /META-INF/

# For standard deployment
# For hot deployment

You can register multiple deployment handler using a comma separated list.

Seam uses deployment handlers internally to install components and namespaces, therefore the handle() is called too early in inside Seam bootstrap to normally be useful. However, you can easily access the deployment handler during an APPLICATION scoped component's startup:

public class FooStartup {

   private MyDeploymentHandler myDeploymentHandler;
   private MyDeploymentHandler myHotDeploymentHandler;

   public void create() {
      for (InputStream is : myDeploymentHandler.getFiles()) {
      for (InputStream is : myHotDeploymentHandler.getFiles()) {