Step by step tutorial to setup a JBoss Seam application

Tutorial version 1.0 by Sebastian Hennebrueder

Library versions

PDF of this tutorial

http://www.laliluna.de/download/first-jboss-seam-en.pdf

Example project

http://www.laliluna.de/download/first-jboss-seam-source.zip

Advanced Training and Education

Range of advanced trainings on Hibernate, EJB3, JBoss Seam, Design Patterns, and Enterprise Best Practices

The training can be customized to your needs.

Support, consulting and development

Get the amount of help you need by experienced trainers and developers. An hour of support can save you a lot of time, Code and Design Reviews insures that the best practices are being followed! Reduce solving and testing time. We can implement a part of your application, create prototypes or proof of concepts.

We need the following configuration files.

components.xml

This file configures Seam and our own components. I prefer to configure my components with annotations and not in this file but still we can do it here as well.

Place: WEB-INF folder in a WAR archive, META-INF folder in a JAR. We have a WAR archive.

Just tell Seam that we don't want it to manage transactions (at the moment).

<?xml version="1.0" encoding="UTF-8"?>
<components xmlns="http://jboss.com/products/seam/components"

xmlns:core="http://jboss.com/products/seam/core"

xmlns:persistence="http://jboss.com/products/seam/persistence"

xmlns:security="http://jboss.com/products/seam/security"

xmlns:drools="http://jboss.com/products/seam/drools"

xmlns:web="http://jboss.com/products/seam/web"

xmlns:mail="http://jboss.com/products/seam/mail"

xmlns:transaction="http://jboss.com/products/seam/transaction"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation=

"http://jboss.com/products/seam/core http://jboss.com/products/seam/core-2.0.xsd

http://jboss.com/products/seam/persistence http://jboss.com/products/seam/persistence-2.0.xsd

http://jboss.com/products/seam/security http://jboss.com/products/seam/security-2.0.xsd

http://jboss.com/products/seam/web http://jboss.com/products/seam/web-2.0.xsd

http://jboss.com/products/seam/drools http://jboss.com/products/seam/drools-2.0.xsd

http://jboss.com/products/seam/mail http://jboss.com/products/seam/mail-2.0.xsd

http://jboss.com/products/seam/transaction http://jboss.com/products/seam/transaction-2.0.xsd

http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.0.xsd">


<core:init transaction-management-enabled="false"/>

<transaction:no-transaction/>

</components>

seam.properties

Includes settings which can be used in components.xml. Apart from this, it is a marker for Seam that a archive (WAR or JAR) includes Seam components. So just create an empty file.

Place: root source folder (same folder as your Java classes.

pages.xml

Includes navigation rules and is comparable to the JSF faces-config.xml. In addition we could add security rules as well.

Place: WEB-INF of a war project

<?xml version="1.0" encoding="UTF-8"?>
<pages xmlns="http://jboss.com/products/seam/pages"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://jboss.com/products/seam/pages http://jboss.com/products/seam/pages-2.0.xsd"

no-conversation-view-id="/home.xhtml"

login-view-id="/login.xhtml">

 <page view-id="*">

<navigation>

<rule if-outcome="home">

<redirect view-id="/home.xhtml"/>

</rule>

</navigation>
 </page>

 <exception>

<redirect view-id="/error.xhtml">

<message>Unexpected error, please try again</message>

</redirect>
 </exception>

</pages>

faces-config.xml

Normal JavaServer Faces configuration file. The default rendering of Seam is JavaServer Faces, this is why we need this config file.

We define default and supported languages and the prefix of the resource bundle.

This example will use facelets for rendering. This is why we have to define the facelets view handler in this configuration file.

Do not place JSF navigation rules here as with Seam we will use the pages.xml for navigation.

<?xml version='1.0' encoding='UTF-8'?>
<faces-config version="1.2"

xmlns="http://java.sun.com/xml/ns/javaee"

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">

<application>

<message-bundle>messages</message-bundle>

<locale-config>
 <default-locale>en</default-locale>
 <supported-locale>en</supported-locale>

</locale-config>

<view-handler>com.sun.facelets.FaceletViewHandler</view-handler>

</application>
</faces-config>

web.xml

Place: well it is where it always should be in a webapp

Defines Seam and JSF specific settings, filters and servlets.

<?xml version="1.0" ?>
<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"
 id="WebApp_ID" version="2.5">


<!-- Seam -->


<listener>

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

</listener>

<filter>

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

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

</filter>

<filter-mapping>

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

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

</filter-mapping>


<!-- Facelets development mode (disable in production) --> 

<context-param>

<param-name>facelets.DEVELOPMENT</param-name>

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

</context-param>



<!-- JSF -->


<context-param>

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

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

</context-param>


<context-param>

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

<param-value>.xhtml</param-value>

</context-param>

<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>

</web-app>

We start with a minimal configured JBoss Seam. As a consequence with this library set you cannot use Seam Email, Seam PDF, ...

JBoss 4.2 provides already the jsf-api and jsf-impl libraries. Don't deploy them. Tomcat or Jetty will need them of course.

<project xmlns="http://maven.apache.org/POM/4.0.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

<modelVersion>4.0.0</modelVersion>

<groupId>de.laliluna</groupId>

<artifactId>seamWeb</artifactId>


<packaging>war</packaging>

<version>1.0-SNAPSHOT</version>

<name>seamWeb</name>

<url>http://maven.apache.org</url>


<build>

<finalName>seamWeb</finalName>

<plugins>

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-compiler-plugin</artifactId>

<configuration>

<source>1.5</source>

<target>1.5</target>

</configuration>

</plugin>

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-idea-plugin</artifactId>

<configuration>

<downloadSources>true</downloadSources>

<downloadJavadocs>true</downloadJavadocs>

</configuration>

</plugin>

</plugins>


</build>

<repositories>

<repository>

<id>repository.jboss.org</id>

<url>http://repository.jboss.org/maven2</url>

<snapshots>

<enabled>true</enabled>

</snapshots>

</repository>

</repositories>


<dependencies>


<!-- JBoss Seam minimal -->

<dependency>

<groupId>org.jboss.seam</groupId>

<artifactId>jboss-seam</artifactId>

<version>2.0.1.GA</version>

<scope>compile</scope>

</dependency>

<dependency>

<groupId>org.jboss.seam</groupId>

<artifactId>jboss-seam-ui</artifactId>

<version>2.0.1.GA</version>

<scope>compile</scope>

</dependency>

<!-- Seam makes use of Hibernate validator and sadly depends on JTA and JPA even if we don't use it -->

<dependency>

<groupId>javax.transaction</groupId>

<artifactId>jta</artifactId>

<version>1.1</version>

</dependency>

<dependency>

<groupId>javax.persistence</groupId>

<artifactId>persistence-api</artifactId>

<version>1.0</version>

</dependency>

<dependency>

<groupId>org.hibernate</groupId>

<artifactId>hibernate-validator</artifactId>

<version>3.0.0.ga</version>

</dependency>


<!-- JSF and facelets -->

<dependency>

<groupId>javax.faces</groupId>

<artifactId>jsf-api</artifactId>

<version>1.2_04-p02</version>

</dependency>

<dependency>

<groupId>javax.faces</groupId>

<artifactId>jsf-impl</artifactId>

<version>1.2_04-p02</version>

</dependency>

<dependency>

<groupId>com.sun.facelets</groupId>

<artifactId>jsf-facelets</artifactId>

<version>1.1.11</version>

</dependency>



<!-- I like to have log4j without Hibernate as well -->

<dependency>

<groupId>log4j</groupId>

<artifactId>log4j</artifactId>

<version>1.2.14</version>

<scope>compile</scope>

</dependency>


</dependencies>
</project>

In addition we need the following libraries.

If you prefer Maven, here are the additional dependencies.

 <dependency>

<groupId>org.hibernate</groupId>

<artifactId>hibernate</artifactId>

<version>3.2.5.ga</version>

<scope>compile</scope>
 </dependency>
 <dependency>

<groupId>c3p0</groupId>

<artifactId>c3p0</artifactId>

<version>0.9.1.2</version>

<scope>compile</scope>
 </dependency>
 <dependency>

<groupId>net.sf.ehcache</groupId>

<artifactId>ehcache</artifactId>

<version>1.3.0</version>
 </dependency>
 <dependency>

<groupId>org.hibernate</groupId>

<artifactId>hibernate-annotations</artifactId>

<version>3.3.0.ga</version>

<scope>compile</scope>
 </dependency>
 <dependency>

<groupId>org.hibernate</groupId>

<artifactId>hibernate-commons-annotations</artifactId>

<version>3.3.0.ga</version>
 </dependency>
 <!-- other -->
 <dependency>

<groupId>postgresql</groupId>

<artifactId>postgresql</artifactId>

<version>8.2-507.jdbc3</version>

<scope>compile</scope>
 </dependency>

We need a Hibernate configuration file hibernate.cfg.xml in the root source folder.

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE hibernate-configuration PUBLIC

"-//Hibernate/Hibernate Configuration DTD 3.0//EN"

"http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

<hibernate-configuration>
<session-factory>
 <!--
postgre SQL configuration-->
 <property name="connection.url">

jdbc:postgresql://localhost:5432/learninghibernate
 </property>
 <property name="connection.username">postgres</property>
 <property name="connection.password">p</property>
 <property name="connection.driver_class">
 org.postgresql.Driver
 </property>
 <property name="dialect">

org.hibernate.dialect.PostgreSQLDialect
 </property>
 <property name="c3p0.max_size">4</property>
 <property name="c3p0.min_size">1</property>

 <property name="cache.provider_class">

org.hibernate.cache.EhCacheProvider
 </property>
 <property name="transaction.factory_class">

org.hibernate.transaction.JDBCTransactionFactory
 </property>

<property name="transaction.flush_before_completion">true</property>

<property name="connection.release_mode">after_statement</property>


<property name="hbm2ddl.auto">update</property>
 <property name="default_batch_fetch_size">4</property>
 <mapping class="de.laliluna.seam.Hedgehog" />
</session-factory>
</hibernate-configuration>

In the components.xml we have to change the transaction handling. The factory is just a work around for a naming problem. We cannot inject a Hibernate session with the name session into the transaction, but

I wanted to use this component name in my application.

<!--

<core:init transaction-management-enabled="false" debug="true"/>

<transaction:no-transaction/>

-->


<core:init debug="true"/>

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

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

auto-create="true"

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

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

<factory name="session"

scope="STATELESS"

auto-create="true"

value="#{xsession}"/>

We must add the loading and saving of hedgehogs to the HedgehogService class.

First we inject the component session into our class.

Then we define that the Data model has a factory method which is loading our hedgehogs.

I changed the Scope to conversation so that the hedgehogs are reloaded when we create a new hedgehog.

@Name("hedgehogService")
@Scope(ScopeType.CONVERSATION)
public class HedgehogService implements Serializable {

@In

private Session session;
 

@DataModel

private List<Hedgehog> hedgehogs;


@Factory("hedgehogs")

public void loadHedgehogs() {

hedgehogs = session.createCriteria(Hedgehog.class).list();

}


public void createHedgehog() {

session.save(new Hedgehog("Name " + new Date()));

}

The Hedgehog class needs the Hibernate specific annotations.

@Entity
public class Hedgehog implements Serializable{


@Id

@GeneratedValue(strategy = GenerationType.SEQUENCE)

private Long id;

// getter and setter are omitted

Finally we need to improve our hello.xhtml. We add an action link to create new hedgehogs.

<s:link action="#{hedgehogService.createHedgehog}">Create a hedgehog</s:link>

<s:fragment rendered="#{empty hedgehogs}">

No hedgehogs
</s:fragment>
<h:dataTable value="#{hedgehogs}" var="h" rendered="#{! empty hedgehogs}">

<h:column>

<f:facet name="header">#{messages['hedgehog.name']}</f:facet>

#{h.name}

</h:column>
</h:dataTable>