SeamFramework.orgCommunity Documentation

Seam Servlet Module

Reference Guide

3.0.0-SNAPSHOT


Introduction
1. Installation
2. Servlet event propagation
2.1. Servlet context lifecycle listener
2.2. Application initialization
2.3. Servlet request lifecycle listener
2.4. Servlet response lifecycle listener
2.5. Session lifecycle listener
2.6. Session activation listener
3. Injectable Servlet objects and request state
3.1. @Inject @RequestParam
3.2. @Inject ServletContext
3.3. @Inject HttpSession
3.4. @Inject HttpServletRequest
3.5. @Inject @ContextPath
3.6. @Inject List<Cookie>
4. Servlet Context attribute BeanManager provider

The goal of the Seam Servlet module is to provide portable enhancements to the Servlet API. Features include producers for implicit Servlet objects and HTTP request state, propagating Servlet events to the CDI event bus, forwarding uncaught exceptions to the Seam Catch handler chain (planned) and binding the BeanManager to a Servlet context attribute for convenient access.

Most features of Seam Servlet are installed automatically by including the seam-servlet.jar and seam-servlet-api.jar in the web application library folder. If you are using Maven as your build tool, you can add the following single dependency to your pom.xml file:


<dependency>
    <groupId>org.jboss.seam.servlet</groupId>
    <artifactId>seam-servlet-impl</artifactId>
    <version>${seam.servlet.version}</version>
</dependency>

Tip

Substitute the expression ${seam.servlet.version} with the most recent or appropriate version of Seam Servlet. Alternatively, you can assign the version number to the property of the same name inside the properties element of your pom.xml.

In a Servlet 3.0 or Java EE 6 environment, your configuration is now complete.

If you are using Servlet 2.5 or Java EE 5, then you need to manually register several Servlet components in your application's web.xml to activate the features provided by this module:


<listener>
   <listener-class>org.jboss.seam.servlet.event.ServletEventBridgeListener</listener-class>
</listener>

<filter>
   <filter-name>Servlet Event Bridge Filter</filter-name>
   <filter-class>org.jboss.seam.servlet.event.ServletEventBridgeFilter</filter-class>
</filter>

<filter-mapping>
   <filter-name>Servlet Event Bridge Filter</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>

<filter>
   <filter-name>Catch Exception Filter</filter-name>
   <filter-class>org.jboss.seam.servlet.filter.CatchExceptionFilter</filter-class>
</filter>

<filter-mapping>
   <filter-name>Catch Exception Filter</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>

You're now ready to dive into the Servlet enhancements provided for you by the Seam Servlet module!

By including the Seam 3 Servlet module in your web application (and performing the necessary listener configuration for pre-Servlet 3.0 environments) you will also have the servlet lifecycle events propagated to the CDI event bridge so you can observe them in your beans. The event bridge works by installing a servlet listener and firing events on the BeanManager with associated qualifiers, passing along the event object.

Seam Servlet provides producers that expose a wide-range of information available in a Servlet environment (e.g., implicit objects such as ServletContext and HttpSession and state such as HTTP request parameters) as beans. You access this information by injecting the beans produced. This chapter documents the Servlet objects and request state that Seam Servlet exposes and how to inject them.

The @RequestParam qualifier allows you to inject an HTTP request parameter (i.e., URI query string or URL form encoded parameter).

Assume a request URL of /book.jsp?id=1.

@Inject @RequestParam("id")

private String bookId;

The value of the specified request parameter is retrieved using the method HttpServletRequest.getParameter(String). It is then produced as a dependent-scoped bean of type String qualified @RequestParam.

The name of the request parameter to lookup is either the value of the @RequestParam annotation or, if the annotation value is empty, the name of the injection point (e.g., the field name).

Here's the example from above modified so that the request parameter name is implied from the field name:

@Inject @RequestParam

private String id;

If the request parameter is not present, and the injection point is annotated with @DefaultValue, the value of the @DefaultValue annotation is returned instead.

Here's an example that provides a fall-back value:

@Inject @RequestParam @DefaultValue("25")

private String pageSize;

If the request parameter is not present, and the @DefaultValue annotation is not present, a null value is injected.

Although discouraged as a general practice, there are circumstances access to the BeanManager is required outside of the CDI context. Seam Servlet includes a provider that retrieves the BeanManager from the Servlet context attribute named javax.enterprise.inject.spi.BeanManager, an alternative to the standard JNDI lookup mechanism defined in the JSR-299 specification. The Servlet module also handles binding the BeanManager to this attribute when the application is initialized. The work is performed in a CDI observer that is notified by the Servlet-CDI bridge provided by this very module.

Refer to the BeanManager provider chapter of the Weld Extensions reference guide for information on how to leverage the Servlet context provider to access the BeanManager from outside the CDI environment.