Of course, you need a faces servlet!

<servlet>

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

    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>

    <load-on-startup>1</load-on-startup>

</servlet>



<servlet-mapping>

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

    <url-pattern>*.seam</url-pattern>

</servlet-mapping>

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

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

<listener>

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

</listener>

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

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

<context-param>

    <param-name>javax.faces.STATE_SAVING_METHOD</param-name>

    <param-value>client</param-value>

</context-param>

                <env-entry>
                    <env-entry-name>com.sun.faces.ClientStateSavingPassword</env-entry-name>
                    <env-entry-type>java.lang.String</env-entry-type>
                    <env-entry-value>INSERT_YOUR_PASSWORD</env-entry-value>
                </env-entry>

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.

<context-param>

    <param-name>com.sun.faces.serializeServerState</param-name>

    <param-value>true</param-value>

</context-param>

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

<servlet>

  <servlet-name>Seam Resource Servlet</servlet-name>

  <servlet-class>org.jboss.seam.servlet.SeamResourceServlet</servlet-class>

</servlet>

    

<servlet-mapping>

  <servlet-name>Seam Resource Servlet</servlet-name>

  <url-pattern>/seam/resource/*</url-pattern>

</servlet-mapping>

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

<filter>

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

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

</filter>



<filter-mapping>

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

    <url-pattern>/*</url-pattern>

</filter-mapping>

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

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

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.

<components xmlns="http://jboss.org/schema/seam/components"

            xmlns:web="http://jboss.org/schema/seam/web">



    <web:exception-filter url-pattern="*.seam"/>



</components>

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

<web:rewrite-filter view-mapping="*.seam"/>

<web:multipart-filter create-temp-files="true" 

                      max-request-size="1000000" 

                      url-pattern="*.seam"/>

<web:character-encoding-filter encoding="UTF-16" 

                               override-client="true" 

                               url-pattern="*.seam"/>

<web:ajax4jsf-filter force-parser="true" 

                     enable-cache="true" 

                     log4j-init-file="custom-log4j.xml"

                     url-pattern="*.seam"/>

<components xmlns="http://jboss.org/schema/seam/components"

            xmlns:web="http://jboss.org/schema/seam/web">

    <web:logging-filter url-pattern="*.seam"/>

</components>

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

<web:cache-control-filter name="commonTypesCacheControlFilter"

                          regex-url-pattern=".*(\.gif|\.png|\.jpg|\.jpeg|\.css|\.js)"

                          value="max-age=86400"/> <!-- 1 day -->



<web:cache-control-filter name="anotherCacheControlFilter"

                          url-pattern="/my/cachable/resources/*"

                          value="max-age=432000"/> <!-- 5 days -->

@Startup

@Scope(APPLICATION)

@Name("org.jboss.seam.web.multipartFilter")

@BypassInterceptors

@Filter(within="org.jboss.seam.web.ajax4jsfFilter")

public class MultipartFilter extends AbstractFilter {

In a Seam application, EJB components have a certain duality, as they are managed by both the EJB container and Seam. Actually, it's more that Seam resolves EJB component references, manages the lifetime of stateful session bean components, and also participates in each method call via interceptors. Let's start with the configuration of the Seam interceptor chain.

We need to apply the SeamInterceptor to our Seam EJB components. This interceptor delegates to a set of built-in server-side interceptors that handle such concerns as bijection, conversation demarcation, and business process signals. The simplest way to do this across an entire application is to add the following interceptor configuration in ejb-jar.xml:

<interceptors>

    <interceptor>

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

    </interceptor>

</interceptors>

   

<assembly-descriptor>

    <interceptor-binding>

        <ejb-name>*</ejb-name>

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

    </interceptor-binding>

</assembly-descriptor>

Seam needs to know where to go to find session beans in JNDI. One way to do this is specify the @JndiName annotation on every session bean Seam component. However, this is quite tedious. A better approach is to specify a pattern that Seam can use to calculate the JNDI name from the EJB name. Fortunately, new portable JNDI Syntax was introduced in Java EE 6. There are three JNDI namespaces for portable JNDI lookups - java:global, java:module and java:app. More in Java EE 6 tutorial We usually specify this option in components.xml.

For JBoss AS 7, the following pattern is correct:

<core:init jndi-name="java:app/<ejb-module-name>/#{ejbName}" />

In this case, <ejb-module-name> is the name of the EJB module (by default it is filename of ejb jar) in which the bean is deployed, Seam replaces #{ejbName} with the name of the EJB.

How these JNDI names are resolved and somehow locate an EJB component might appear a bit like black magic at this point, so let's dig into the details. First, let's talk about how the EJB components get into JNDI.

EJB components would get assigned a global JNDI name automatically, using the pattern described in Java EE 6 tutorial. The EJB name is the first non-empty value from the following list:

Let's look at an example. Assume that you have the following EJB bean and interface defined.

package com.example.myapp;


import javax.ejb.Local;


@Local

public interface Authenticator

{

    boolean authenticate();

}


package com.example.myapp;


import javax.ejb.Stateless;


@Stateless

@Name("authenticator")

public class AuthenticatorBean implements Authenticator

{ 

    public boolean authenticate() { ... }

}

Assuming your EJB bean class is deployed in an EAR named myapp, the global JNDI name myapp/AuthenticatorBean/local will be assigned to it on JBoss AS. As you learned, you can reference this EJB component as a Seam component with the name authenticator and Seam will take care of finding it in JNDI according to the JNDI pattern (or @JndiName annotation).

So what about the rest of the application servers? Well, according to the Java EE spec, which most vendors try to adhere to religiously, you have to declare an EJB reference for your EJB in order for it to be assigned a JNDI name. That requires some XML. It also means that it is up to you to establish a JNDI naming convention so that you can leverage the Seam JNDI pattern. You might find the JBoss convention a good one to follow.

There are two places you have to define the EJB reference when using Seam on non-JBoss application servers. If you are going to be looking up the Seam EJB component through JSF (in a JSF view or as a JSF action listener) or a Seam JavaBean component, then you must declare the EJB reference in web.xml. Here is the EJB reference for the example component just shown:

<ejb-local-ref>

    <ejb-ref-name>myapp/AuthenticatorBean</ejb-ref-name>

    <ejb-ref-type>Session</ejb-ref-type>

    <local>org.example.vehicles.action.Authenticator</local>

</ejb-local-ref>

This reference will cover most uses of the component in a Seam application. However, if you want to be able to inject a Seam EJB component into another Seam EJB component using @In, you need to define this EJB reference in another location. This time, it must be defined in ejb-jar.xml, and it's a bit tricker.

Within the context of an EJB method call, you have to deal with a somewhat sheltered JNDI context. When Seam attempts to find another Seam EJB component to satisfy an injection point defined using @In, whether or not it finds it depends on whether an EJB reference exists in JNDI. Strictly speaking, you cannot simply resolve JNDI names as you please. You have to define the references explicitly. Fortunately, JBoss recognized how aggravating this would be for the developer and all versions of JBoss automatically register EJBs so they are always available in JNDI, both to the web container and the EJB container. So if you are using JBoss, you can skip the next few paragraphs. However, if you are deploying to GlassFish, pay close attention.

For application servers that stubbornly adhere to the EJB specification, EJB references must always be defined explicitly. But unlike with the web context, where a single resource reference covers all uses of the EJB from the web environment, you cannot declare EJB references globally in the EJB container. Instead, you have to specify the JNDI resources for a given EJB component one-by-one.

Let's assume that we have an EJB named RegisterAction (the name is resolved using the three steps mentioned previously). That EJB has the following Seam injection:

@In(create = true)

Authenticator authenticator;

In order for this injection to work, the link must be established in the ejb-jar.xml file as follows:

<ejb-jar>

    <enterprise-beans>

        <session>

            <ejb-name>RegisterAction</ejb-name>

            <ejb-local-ref>

                <ejb-ref-name>myapp/AuthenticatorAction/local</ejb-ref-name>

                <ejb-ref-type>Session</ejb-ref-type>

                <local>com.example.myapp.Authenticator</local>

            </ejb-local-ref>

        </session>

    </enterprise-beans>



    ...

    

</ejb-jar>

Notice that the contents of the <ejb-local-ref> are identical to what we defined in web.xml. What we are doing is bringing the reference into the EJB context where it can be used by the RegisterAction bean. You will need to add one of these references for any injection of a Seam EJB component into another Seam EJB component using @In. (You can see an example of this setup in the jee5/booking example).

But what about @EJB? It's true that you can inject one EJB into another using @EJB. However, by doing so, you are injecting the actual EJB reference rather than the Seam EJB component instance. In this case, some Seam features will work, while others won't. That's because Seam's interceptor is invoked on any method call to an EJB component. But that only invokes Seam's server-side interceptor chain. What you lose is Seam's state management and Seam's client-side interceptor chain. Client-side interceptors handle concerns such as security and concurrency. Also, when injecting a SFSB, there is no guarantee that you will get the SFSB bound to the active session or conversation, whatever the case may be. Thus, you definitely want to inject the Seam EJB component using @In.

Finally, let's talk about transactions. In an EJB 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:

<transaction:ejb-transaction/>

There is one final item you need to know about. You must place a seam.properties, META-INF/seam.properties or META-INF/components.xml file in any archive in which your Seam components are deployed (even an empty properties file will do). At startup, Seam will scan any archives with seam.properties files for seam components.

In a web archive (WAR) file, you must place a seam.properties file in the WEB-INF/classes directory if you have any Seam components included here.

That's why all the Seam examples have an empty seam.properties file. You can't just delete this file and expect everything to still work!

You might think this is silly and what kind of idiot framework designers would make an empty file affect the behavior of their software?? Well, this is a workaround for a limitation of the JVM — if we didn't use this mechanism, our next best option would be to force you to list every component explicitly in components.xml, just like some other competing frameworks do! I think you'll like our way better.

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

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

You should declare jboss-seam.jar as an ejb module in META-INF/application.xml; 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 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.1.

faces-config.xml is not required in JSF 2, but if you want to set up something non-default you need to place it in WAR/WEB-INF.

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 will bootstrap a Hibernate SessionFactory from your hibernate.cfg.xml file if you install a built-in component:

<persistence:hibernate-session-factory name="hibernateSessionFactory"/>

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

<persistence:managed-hibernate-session name="hibernateSession"

                            session-factory="#{hibernateSessionFactory}"/>

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

<persistence:entity-manager-factory name="entityManagerFactory"/>

You will also need to configure a managed persistence context if you want a Seam managed JPA EntityManager to be available via injection.

<persistence:managed-persistence-context name="entityManager"

                            entity-manager-factory="#{entityManagerFactory}"/>

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

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

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

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
    lib/
       jboss-el.jar
       jbpm-jpdl.jar
    META-INF/
        MANIFEST.MF
        application.xml
        jboss-deployment-structure.xml
    my-application.war/
        META-INF/
            MANIFEST.MF
        WEB-INF/
            web.xml
            components.xml
            faces-config.xml
            lib/
                jboss-seam-ui.jar
        login.jsp
        register.jsp
        ...
    my-application.jar/
        META-INF/
            MANIFEST.MF
            persistence.xml
        seam.properties
        org/
            jboss/
                myapplication/
                    User.class
                    Login.class
                    LoginBean.class
                    Register.class
                    RegisterBean.class
                    ...
    jbpm.cfg.xml
    hibernate.cfg.xml
    createDocument.jpdl.xml
    editDocument.jpdl.xml
    approveDocument.jpdl.xml
    documentLifecycle.jpdl.xml