JBoss Seam

FAQ

The FAQ can be found here.

Quick setup

For a head jump read this quick setup guide. For a lot more detailed introduction start with the preamble…

Make sure that you've installed Java JDK >= 1.5
Make sure that you've installed Apache Ant >= 1.6 (not 1.7 beta)
Set the JAVA_HOME environment variable to the JDK installation path (not JRE!)
Download and install Eclipse >= 3.3 (Europa)
Install the TestNG plugin in Eclipse (Download site: http://beust.com/eclipse)
Download, install, and start a database (MySQL or Postgres)
Test that your database is really up and working fine
Download a JDBC driver (MySQL or Postgres)
Download and install an SQL client (e.g. pgAdmin)
Download and install the JBoss Application Server 4.0.5.GA via the JEMS Installer (ATTENTION: you must use the 'ejb' profile)
Test that your Application Server works fine by pointing your browser to localhost:8080
Download and unpack JBoss Seam 1.2.1.GA
Put the root folder of JBoss Seam to the PATH environment variable
Create a role, password, and database with your SQL client or via SQL console
Open a console and setup your first Seam project via 'seam setup<enter>' (see screenshot below)
- 'seam new-project<enter>' creates the project
- 'seam new-entity<enter>' creates a new entity bean along with the associated HomeObject, QueryObject, master and detail page

Preamble

This wiki page is intended to serve as a quickstart guide enabling the reader to install and setup JBoss Seam. Additionally, this page goes along with the first steps needed to be able to develop web applications with the Seam web application framework.

most of the content of this page is taken from the original Seam Reference documentation 1.2.1
the main project site can be found here: http://labs.jboss.com/jbossseam/
ensure that you have JDK 5.0 or above and Ant 1.6 properly installed (not Ant 1.7 beta)

What is JBoss Seam?

JBoss Seam is a powerful new application framework for building next generation Web 2.0 applications by unifying and integrating technologies such as Asynchronous JavaScript and XML (AJAX), Java Server Faces (JSF), Enterprise Java Beans (EJB3), Java Portlets and Business Process Management (BPM).

Seam has been designed from the ground up to eliminate complexity at the architecture and the API level. It enables developers to assemble complex web applications with simple annotated Plain Old Java Objects (POJOs), componentized UI widgets and very little XML. The simplicity of Seam 1.0 will enable easy integration with the JBoss Enterprise Service Bus (ESB) and Java Business Integration (JBI) in the future.

Seam is an application framework for Java EE 5. It is inspired by the following principles:

Integrate JSF with EJB 3.0
Integrated AJAX
Integrate Business Process as a First Class Construct
One Kind of “Stuff”
Declarative State Management
Bijection
Workspace Management
Annotated POJOs Everywhere
Testability as a Core Feature
Get started now!

For more detailed information about these topics click here

The following image depicts the Seam architecture

What are the prerequisites for using Seam?

Java JDK >= 1.5 (not JRE)
a correctly set JAVA_HOME variable
Database system (e.g. PostgreSQL or MySQL)
JDBC driver JAR file (e.g. the Postgres JDBC driver)
Application server (e.g. JBoss Application Server)
TestNG Eclipse plugin (see here for download and installation instructions)
Web browser (e.g. Firefox)

Install and start the prerequisites

Installing the database system

Please refer to the corresponding documentation. I prefer using Postgres and additionally use pgAdmin to maintain the databases.

Start the database system and ensure that it's running correctly.

Best practises & common caveats

it is generally a good idea to install the database system on your computer. This way you have your own development environment
after installing the DB system you should assure that you've got the rights to access the DB system's default port (e.g. port 5432 for a Postgres installation). You have to configure this in the respective configuration files.
if using Postgres:
- edit the postgres.conf file and uncomment the listen_addresses property

Installing the JBoss application server (AS)

For Seam 1.2.x, you must use the JEMS 1.2 Installer to install the JBoss AS 4.0.5.GA (or newer) with the ejb3 profile selected. Download the latest JEMS Installer here.

For more information about the JEMS Installer see here.

Start JBoss AS with the bin/run.(sh|bat) script.

Notes

the new Seam 1.3 requires JBoss 4.2 but does not require the use of the JEMS installer to install EJB3 functionality
if using Seam 1.2.x you must install the AS via the JEMS Installer with the ejb3 profile selected
set the JAVA_HOME to the JDK >= 5.0 (not the JRE!), because the tools.jar is needed for code generation issues

Installing TestNG

Please refer to the TestNG documentation at http://testng.org/doc/

Install JBoss Seam

Download Seam ( here) and unpack it in a directory of your choice. Make sure that there are NO spaces in your path (e.g. c:\Program Files\..). Add the Seam root directory to the PATH environment variable.
Edit build.properties in your Seam directory and configure the path to your JBoss AS installation directory.

Test your Seam installation

In the jboss-seam/examples/booking directory, type ant deploy and check for any error messages (maybe you have to put Ant to the PATH environment variable)
Point your browser to http://localhost:8080/seam-booking/. Do you see the web application? Congratulations!

Create your first Seam project with seam-gen

What is seam-gen?

The Seam distribution includes a command line utility that makes it really easy to set up an Eclipse project, generate some simple Seam skeleton code, and reverse engineer an application from a pre-existing database.

This is the easy way to get your feet wet with Seam, and gives you some ammunition for next time you find yourself trapped in an elevator with one of those tedious Ruby guys ranting about how great and wonderful his new toy is for building totally trivial applications that put things in databases.

For the Seam 1.2.1 release, seam-gen works best for people with JBoss AS. You can use the generated project with other J2EE or Java EE 5 application servers by making a few manual changes to the project configuration. (Mark: “but I don't recommend this for us.”)

You can use seam-gen without Eclipse, but in this tutorial, we want to show you how to use it in conjunction with Eclipse for debugging and integration testing.

Seam-gen is basically just a big ugly Ant script wrapped around Hibernate Tools, together with some templates. Which means it is easy to customize if you need to.

Detailed information about seam-gen can be found here.

First steps

JBoss has sophisticated support for hot re-deployment of WARs and EARs. Unfortunately, due to bugs in the JVM, repeated redeployment of an EAR—which is common during development—eventually causes the JVM to run out of perm gen space. For this reason, we recommend running JBoss in a JVM with a large perm gen space at development time. If you're running JBoss from JBoss IDE, you can configure this in the server launch configuration, under “VM arguments”. We suggest the following values:

-Xms512m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512

If you don't have so much memory available, the following is our minimum recommendation:

-Xms256m -Xmx512m -XX:PermSize=128m -XX:MaxPermSize=256

If you're running JBoss from the commandline or you don't use the JBoss IDE, you can configure the JVM options in bin/run.conf.

If you don't want to bother with this stuff now, you don't have to—come back to it later, when you get your first OutOfMemoryException.

Let's start with our first project

In this tutorial we'll name the test project myproject.

Set up the database:

make sure that your database server is running and accessible
create a DB user (role) named myproject with password myproject
create a database named myproject and set the DB owner to the just created user myproject

Setup and create the project

The first thing we need to do is configure seam-gen for your environment: JBoss AS installation directory, Seam project workspace, and database connection. It's easy, open a terminal and just type:

seam setup

If the seam command is not in the PATH variable then first 'changedir' into the Seam root directory.

You will be prompted for the needed information:

tobago:~ schmatz$ seam setup
Buildfile: build.xml

setup:
     [echo] Welcome to seam-gen :-)
    [input] Enter your Java project workspace (the directory that contains your Seam projects) [/Users/schmatz/projects/spikes/myproject]

    [input] Enter your JBoss home directory [/opt/jboss-as]

    [input] Enter the project name [myproject]

    [input] Is this project deployed as an EAR (with EJB components) or a WAR (with no EJB support) [ear] (ear,war,)

    [input] Enter the Java package name for your session beans [org.tztz.myproject.action]

    [input] Enter the Java package name for your entity beans [org.tztz.myproject.model]

    [input] Enter the Java package name for your test cases [org.tztz.myproject.test]

    [input] What kind of database are you using? [postgres] (hsql,mysql,oracle,postgres,mssql,db2,sybase,enterprisedb,)

    [input] Enter the Hibernate dialect for your database [org.hibernate.dialect.PostgreSQLDialect]

    [input] Enter the filesystem path to the JDBC driver jar [/opt/jboss-seam/lib/postgresql-8.2-504.jdbc3.jar]

    [input] Enter JDBC driver class for your database [org.postgresql.Driver]

    [input] Enter the JDBC URL for your database [jdbc:postgresql:myproject]

    [input] Enter database username [myproject]

    [input] Enter database password [myproject]

    [input] Enter the database schema name (it is OK to leave this blank) []

    [input] Enter the database catalog name (it is OK to leave this blank) []

    [input] Are you working with tables that already exist in the database? [n] (y,n,)

    [input] Do you want to drop and recreate the database tables and data in import.sql each time you deploy? [y] (y,n,)

[propertyfile] Updating property file: /opt/jboss-seam-root/jboss-seam-1.2.1.GA/seam-gen/build.properties
     [echo] Installing JDBC driver jar to JBoss server
     [echo] Type 'seam new-project' to create the new project

BUILD SUCCESSFUL
Total time: 36 seconds
tobago:~ schmatz$

The settings are stored in seam-gen/build.properties. You can modify them directly in this file or simply by running seam setup a second time.

Now we can create a new project in our workspace directory (which we've entered during seam setup), by typing:

seam new-project

The output is:

tobago:~ schmatz$ seam new-project
Buildfile: build.xml

validate-workspace:

validate-project:

copy-lib:
     [echo] Copying Seam jars to the /Users/schmatz/projects/spikes/myproject/myproject/lib directory...
     [copy] Copying 254 files to /Users/schmatz/projects/spikes/myproject/myproject/lib
     [copy] Copied 34 empty directories to 1 empty directory under /Users/schmatz/projects/spikes/myproject/myproject/lib
     [echo] Copying Embeddable EJB3 configuration to the /Users/schmatz/projects/spikes/myproject/myproject/embedded-ejb directory...
     [copy] Copying 9 files to /Users/schmatz/projects/spikes/myproject/myproject/embedded-ejb

file-copy-war:

file-copy-ear:
     [echo] Copying resources needed for EAR deployment to the /Users/schmatz/projects/spikes/myproject/myproject/resources directory...
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject/resources/WEB-INF
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject
     [copy] Copying 6 files to /Users/schmatz/projects/spikes/myproject/myproject/resources

setup-filters:

file-copy:
     [copy] Copying 8 files to /Users/schmatz/projects/spikes/myproject/myproject/resources
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject/resources
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject/.settings
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject/resources
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject/resources
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject/resources
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject/resources
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject/resources
     [copy] Copying 14 files to /Users/schmatz/projects/spikes/myproject/myproject/view
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject/src/action/org/tztz/myproject/action
     [copy] Copying 6 files to /Users/schmatz/projects/spikes/myproject/myproject
    [mkdir] Created dir: /Users/schmatz/projects/spikes/myproject/myproject/src/model
    [mkdir] Created dir: /Users/schmatz/projects/spikes/myproject/myproject/src/test
    [mkdir] Created dir: /Users/schmatz/projects/spikes/myproject/myproject/nbproject
     [copy] Copying 3 files to /Users/schmatz/projects/spikes/myproject/myproject/nbproject

new-project:
     [echo] A new Seam project named 'myproject' was created in the /Users/schmatz/projects/spikes/myproject directory
     [echo] Type 'seam explode' and go to http://localhost:8080/myproject
     [echo] Eclipse Users: Add the project into Eclipse using File > New > Project and select General > Project (not Java Project)
     [echo] NetBeans Users: Open the project in NetBeans

BUILD SUCCESSFUL
Total time: 10 seconds
tobago:~ schmatz$

This copies the Seam jars, dependent jars and the JDBC driver jar to a new Eclipse project, and generates all needed resources and configuration files, a facelets template file and stylesheet, along with Eclipse metadata and an Ant build script. The Eclipse project will be automatically deployed to an exploded directory structure in the Boss AS as soon as you add the project using New → Project… → General → Project → Next, typing the Project name (myproject in this case), and then clicking Finish. Do not select Java Project from the New Project wizard.

If your default JDK in Eclipse is not a Java SE 5 or Java SE 6 JDK, you will need to select a Java SE 5 compliant JDK using Project → Properties → Java Compiler.

Alternatively, you can deploy the project from outside Eclipse by typing seam explode.

Go to http://localhost:8080/myproject to see a welcome page. This is a facelets page, view/home.xhtml, using the template view/layout/template.xhtml. You can edit this page, or the template, in eclipse, and see the results immediately, by clicking refresh in your browser.

Don't get scared by the XML configuration documents that were generated into the project directory. They are mostly standard Java EE stuff, the stuff you need to create once and then never look at again, and they are 90% the same between all Seam projects. (They are so easy to write that even seam-gen can do it.)

The generated project includes three database and persistence configurations. The jboss-beans.xml, persistence-test.xml and import-test.sql files are used when running the TestNG unit tests against HSQLDB. The database schema and the test data in import-test.sql is always exported to the database before running tests. The myproject-dev-ds.xml, persistence-dev.xmland import-dev.sql files are for use when deploying the application to your development database. The schema might be exported automatically at deployment, depending upon whether you told seam-gen that you are working with an existing database. The myproject-prod-ds.xml, persistence-prod.xmland import-prod.sql files are for use when deploying the application to your production database. The schema is not exported automatically at deployment.

Let's add an entity

Now, that we have a running web application we can add some content. The first thing we can think of is user management since every cool web application needs authorisation and authentication .

In Seam any model object which has to be persistent (in a database) must be expressed as an entity. Since our users should be persistent we have to create a user entity, by typing:

seam new-entity

You will be asked to give a class name, and a name for the master resp. detail page:

tobago:~ schmatz$ seam new-entity
Buildfile: build.xml

validate-workspace:

validate-project:

entity-input:
    [input] Enter the entity class name
User
    [input] Enter the master page name [userList]

    [input] Enter the detail page name [user]


setup-filters:

new-entity:
     [echo] Creating a new entity bean, with home and list components
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject/src/model/org/tztz/myproject/model
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject/src/action/org/tztz/myproject/action
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject/src/action/org/tztz/myproject/action
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject/view
     [copy] Copying 1 file to /Users/schmatz/projects/spikes/myproject/myproject/view
     [echo] Type 'seam restart' and go to http://localhost:8080/myproject/userList.seam

BUILD SUCCESSFUL
Total time: 4 seconds
tobago:~ schmatz$

Now, you can point your browser to the userList.seam page by typing http://localhost:8080/myproject/userList.seam. Note that the page ends with .seam while the corresponding file ends with .xhtml. The mapping is done by the corresponding filter in the WEB-INF/web.xml file.

TODO….

Testing with TestNG

Before you write any tests put the following line in the ./resources/META-INF/persistence-test.xml file:

<property name="hibernate.cache.provider_class" value="org.hibernate.cache.HashtableCacheProvider"/>

You need a Test.xml file in the ./src/test folder:

<!DOCTYPE suite SYSTEM "http://beust.com/testng/testng-1.0.dtd">

<suite name="njustrts" verbose="2" parallel="false">
   <test name="UserTest">
     <classes>
       <class name="org.cs3.nrts.test.UserTest"/>
     </classes>
   </test>
</suite>

The following code is a sample TestNG test class:

package org.cs3.nrts.test;

import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;
import org.jboss.seam.mock.SeamTest;
import org.testng.Assert;
import org.testng.annotations.Configuration;
import org.testng.annotations.Test;

public class UserTest extends SeamTest
{
    private EntityManagerFactory emf;

    
	EntityManager getEntityManager()
    {
		if( emf == null )
		{
			emf = Persistence.createEntityManagerFactory("njustrts");
		}
    	EntityManager em = emf.createEntityManager();
    	Assert.assertNotNull(em);
    	Assert.assertTrue(em.isOpen());
    	return em;
    } 

   /**
    * DO NOT USE THIS METHOD!
    * Otherwise you get a "Local server is not initialized" errer.
    */
    @Configuration(beforeTestClass=true)
    public void setup()
    {
    	System.out.println("************ SETUP");
    }

    @Configuration(afterTestClass=true)
    public void destroy()
    {
    	System.out.println("************ TEAR DOWN");
        emf.close();
    }


	@SuppressWarnings("unchecked")
	@Test
    public void testSomething()
    {
	EntityManager em = getEntityManager();
        em.getTransaction().begin();

        // Your test code goes here...
        
        em.getTransaction().commit();
        em.close();
    }
}

Debugging

To debug your Seam application just uncomment the respective line in the ${JBOSS_HOME}/bin/run.conf file and change the suspend attribute to 'n'. After the change the line should look like this:

# Sample JPDA settings for remote socket debuging
JAVA_OPTS="$JAVA_OPTS -Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n"

The next thing you have to do is to connect from Eclipse. This is very easy and is explained in detail here.

You like short words? OK: Run → Open Debug Dialog… → Remote Java Application → New → Enter project and port (usually 8787)

You like screenshots? OK:

Use of the generic entity converter

use the converter where appropriate via:
```
<s:convertEntity />
```

— Mark Schmatz 2007-06-11 17:20

SDA SE Wiki

Sidebar

Table of Contents

JBoss Seam

FAQ

Quick setup

Preamble

What is JBoss Seam?

Further reading

Online

Books

Discuss with others

Posts & Potcasts

What are the prerequisites for using Seam?

Install and start the prerequisites

Installing the database system

Best practises & common caveats

Installing the JBoss application server (AS)

Notes

Installing TestNG

Install JBoss Seam

Test your Seam installation

Create your first Seam project with seam-gen

What is seam-gen?

First steps

Let's start with our first project

Let's add an entity

Testing with TestNG

Debugging

Use of the generic entity converter

SDA SE Wiki

User Tools

Site Tools

Sidebar

Table of Contents

JBoss Seam

FAQ

Quick setup

Preamble

What is JBoss Seam?

Further reading

Online

Books

Discuss with others

Posts & Potcasts

What are the prerequisites for using Seam?

Install and start the prerequisites

Installing the database system

Best practises & common caveats

Installing the JBoss application server (AS)

Notes

Installing TestNG

Install JBoss Seam

Test your Seam installation

Create your first Seam project with seam-gen

What is seam-gen?

First steps

Let's start with our first project

Let's add an entity

Testing with TestNG

Debugging

Use of the generic entity converter

Page Tools