JavaHelp.info

This short tutorial gives you the needed steps to integrate SEAM into an existing WAR-project or to build such a WAR from the beginning.

1. Including Dependencies

First of all you need to add the SEAM dependencies and of course JSF, if not already present:

		<dependency>
			<groupId>javax.faces</groupId>
			<artifactId>jsf-api</artifactId>
			<version>1.2_15</version>
		</dependency>
		<dependency>
			<groupId>javax.faces</groupId>
			<artifactId>jsf-impl</artifactId>
			<version>1.2_15</version>
		</dependency>
		<dependency>
			<groupId>com.sun.facelets</groupId>
			<artifactId>jsf-facelets</artifactId>
			<version>1.1.15.B1</version>
		</dependency>
		<dependency>
			<groupId>org.jboss.seam</groupId>
			<artifactId>jboss-seam</artifactId>
			<version>2.2.1.Final</version>
			<exclusions>
				<exclusion>
					<groupId>javax.el</groupId>
					<artifactId>el-api</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
		<dependency>
			<groupId>org.jboss.seam</groupId>
			<artifactId>jboss-seam-ui</artifactId>
			<version>2.2.1.Final</version>
		</dependency>

2. Modify web.xml

Here you have to add the FacesServlet for JSF, the Seam-Filter for SEAM and a Listener for SEAM. Additionally you can define some CONTEXT-variables for JSF / SEAM.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
	version="2.5">
	<!-- Context Variables -->
	<context-param>
		<param-name>facelets.SKIP_COMMENTS</param-name>
		<param-value>true</param-value>
	</context-param>
	<!-- Seam Listener -->
	<listener>
		<listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
	</listener>
	<!-- Seam Filter -->
	<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>
	<!-- JSF 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>*.html</url-pattern>
	</servlet-mapping>
	<!-- Seam Resource Servlet -->
	<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>
</web-app>

3. Configure JSF

Then you have to add an faces-config.xml to the WEB-INF directory.

<?xml version="1.0" encoding="UTF-8"?>
<faces-config version="1.2" xmlns="http://java.sun.com/xml/ns/javaee"
 xmlns:xi="http://www.w3.org/2001/XInclude"
 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">
</faces-config>

4. Configure SEAM
Just add some empty configuration files to enable seam for your WAR.

<?xml version="1.0" encoding="UTF-8"?>
<components xmlns="http://jboss.com/products/seam/components"
	xmlns:core="http://jboss.com/products/seam/core" xmlns:transaction="http://jboss.com/products/seam/transaction"
	xmlns:web="http://jboss.com/products/seam/web" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<core:init debug="false" />
</components>

And also put an empty seam.properties to your classpath (in directory src/main/resources).

Sometimes you could have some facelets, which are no entry-sites and which should never be called directly by the user. Typical types are template-files.
Seam provides here an easy function to restrict the access to such pages. You can define this restriction in the pages.xml or the associated *.page.xml.
For the pages.xml you have to add:

1
2
3
4
5
6
7
8

< ?xml version="1.0" encoding="UTF-8"?>
<pages xmlns="http://jboss.com/products/seam/pages" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...
	<page view-id="/templates/template.xhtml">
		<restrict />
	</page>
...
</pages>

Because you also can use wildcards, it is also possible to restrict a whole directory:

1
2
3
4
5
6
7
8

< ?xml version="1.0" encoding="UTF-8"?>
<pages xmlns="http://jboss.com/products/seam/pages" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...
	<page view-id="/templates/*">
		<restrict />
	</page>
...
</pages>

Seam will now throw an exception, if a user will access this page, but instead we want to send the typical HTTP-error 403. So we have to define some more rules in pages.xml:

1
2
3
4
5
6
7
8
9
10
11

< ?xml version="1.0" encoding="UTF-8"?>
<pages xmlns="http://jboss.com/products/seam/pages" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...
	<exception class="org.jboss.seam.security.NotLoggedInException">
		<http -error error-code="403" />
	</exception>
	<exception class="org.jboss.seam.security.AuthorizationException">
		<http -error error-code="403" />
	</exception>
...
</pages>

Another way would be an own Servlet or Servlet-Filter, which would send the errorcode directly.

If you use XHTML as HTML-Standard, which is recommended, to build your sites and you use JavaScript, you could have problems with document.write. Especially third-party JavaScript extensions like GoogleMaps or CKEditor use document.write to easily inject own JavaScript code.

But this is denied by specification for XHTML-Documents delivered with content-type application/xhtml+xml instead of text/html. You will receive the DOM Exception #7 by calling document.write or while using innerHTML (Example in Safari: “Error: NO_MODIFICATION_ALLOWED_ERR: DOM Exception 7″; in Firefox: uncaught exception: [Exception... "Component returned failure code: 0x80004003 (NS_ERROR_INVALID_POINTER) [nsIDOMNSHTMLElement.innerHTML]“  nsresult: “0×80004003 (NS_ERROR_INVALID_POINTER)”  location: … ]). The solution is to deliver the Website with content-type “text/html” instead of “application/xhtml+xml”.

In SEAM using Facelets (with JSF) as View, you can set the content-type in the f:view-Tag. This would look like:

1
2
3
4
5

...
<f :view contentType="text/html">
....
</f>
...

SEAM doesn’t only extends JSF and Facelets, but also gives you a possibility to define other resources or components via annotations. To define a simple Servlet Filter you only need to annotate a class with the @Filter-annotation. There is no need to extend the web.xml or other.

One simple Filter would be:

1
2
3
4
5
6
7
8
9
10

@Scope(ScopeType.APPLICATION)
@Name("myFilter")
@Install(precedence = Install.FRAMEWORK)
@BypassInterceptors
@Filter(within = { "org.jboss.seam.web.rewriteFilter" })
public class MyFilter extends AbstractFilter {
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        chain.doFilter(request, response);
    }
}

With the parameters within or around of the @Filter annotation, you can define when you filter will be called.