SeamFramework.org Community Documentation

- Prev
- Next

## Chapter 2. Getting started with Seam, using 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 preexisting 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.

In this 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.

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. If you don't want to install Eclipse, you can still follow along with this tutorial—all steps can be performed from the command line.

seam-gen is basically just an intricate Ant script wrapped around Hibernate Tools, together with some templates. That makes it easy to customize if you need to.

## 2.1. Before you start

Make sure you have JDK 6 (see Section 39.1, “JDK Dependencies” for details), JBoss AS 7.1.1 and Maven 3.x, along with recent versions of Eclipse, the JBoss IDE plugin for Eclipse correctly installed before starting. Add your JBoss installation to the JBoss Server View in Eclipse. Start JBoss in debug mode. Finally, start a command prompt in the directory where you unzipped the Seam distribution.

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=512m

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

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

If you're running JBoss from the command line, you can configure the JVM options in `bin/standalone.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`.

## 2.2. Setting up a new project

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

    cd jboss-seam-2.3.0
    seam setup

And you will be prompted for the needed information:

    ~/workspace/jboss-seam$ ./seam setup
    Buildfile: build.xml

    init:

    setup:
         [echo] Welcome to seam-gen :-)
        [input] Enter your project workspace (the directory that contains your Seam projects) [C:/Projects] [C:/Projects]
    /Users/pmuir/workspace
        [input] Enter your JBoss AS home directory [C:/Program Files/jboss-as-7.1.1.Final] [C:/Program Files/jboss-as-7.1.1.Final]
    /Applications/jboss-as-7.1.1.Final
        [input] Enter the project name [myproject] [myproject]
    helloworld
         [echo] Accepted project name as: helloworld
        [input] Select a RichFaces skin [blueSky] ([blueSky], emeraldTown, ruby, classic, japanCherry, wine, deepMarine, DEFAULT, plain)

        [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 [com.mydomain.helloworld] [com.mydomain.helloworld]
    org.jboss.helloworld
        [input] Enter the Java package name for your entity beans [org.jboss.helloworld] [org.jboss.helloworld]

        [input] Enter the Java package name for your test cases [org.jboss.helloworld.test] [org.jboss.helloworld.test]

        [input] What kind of database are you using? [h2]  ([h2], hsql, mysql, oracle, postgres, mssql, db2, sybase, enterprisedb)
    mysql
        [input] Enter the Hibernate dialect for your database [org.hibernate.dialect.MySQLDialect] [org.hibernate.dialect.MySQLDialect]

        [input] Enter the filesystem path to the JDBC driver jar [lib/hsqldb.jar] [lib/hsqldb.jar]
    /Users/pmuir/java/mysql.jar
        [input] Enter JDBC driver class for your database [com.mysql.jdbc.Driver] [com.mysql.jdbc.Driver]

        [input] Enter the JDBC URL for your database [jdbc:mysql:///test] [jdbc:mysql:///test]
    jdbc:mysql:///helloworld
        [input] Enter database username [sa] [sa]
    pmuir
        [input] Enter database password [] []

        [input] skipping input as property hibernate.default_schema.new has already been set.
        [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], )
    y
        [input] Do you want to drop and recreate the database tables and data in import.sql each time you deploy? [n]  (y, [n], )
    n

    [propertyfile] Creating new property file: /Users/pmuir/workspace/jboss-seam/seam-gen/build.properties
         [echo] Installing JDBC driver jar to JBoss server
         [echo] Type 'seam create-project' to create the new project

    BUILD SUCCESSFUL
    Total time: 1 minute 32 seconds
    ~/workspace/jboss-seam $

The tool provides sensible defaults, which you can accept by just pressing enter at the prompt.

The most important choice you need to make is between EAR deployment and WAR deployment of your project. EAR projects support EJB 3.0 and require Java EE 5. WAR projects do not support EJB 3.0, but may be deployed to a J2EE environment. The packaging of a WAR is also simpler to understand. If you installed an EJB3-ready application server like JBoss, choose `ear`. Otherwise, choose `war`. We'll assume that you've chosen an EAR deployment for the rest of the tutorial, but you can follow exactly the same steps for a WAR deployment.

If you are working with an existing data model, make sure you tell seam-gen that the tables already exist in the database.

The settings are stored in `seam-gen/build.properties`, but you can also modify them simply by running `seam setup` a second time.

Now we can create a new project in our Eclipse workspace directory, by typing:

    seam new-project

    C:\Projects\jboss-seam>seam new-project
    Buildfile: build.xml

    ...

    new-project:
         [echo] A new Seam project named 'helloworld' was created in the C:\Projects directory
         [echo] Type 'seam explode' and go to http://localhost:8080/helloworld
         [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: 7 seconds
    C:\Projects\jboss-seam>

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 JBoss AS as soon as you add the project using `New -> Project... -> General -> Project -> Next`, typing the `Project name` (`helloworld` 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 6 JDK, you will need to select a Java SE 6 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/helloworld` 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 `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.xml`and `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.xml`and `import-prod.sql` files are for use when deploying the application to your production database. The schema is not exported automatically at deployment.

## 2.3. Creating a new action

If you're used to traditional action-style web frameworks, you're probably wondering how you can create a simple web page with a stateless action method in Java. If you type:

    seam new-action

Seam will prompt for some information, and generate a new facelets page and Seam component for your project.

    C:\Projects\jboss-seam>seam new-action
    Buildfile: build.xml

    validate-workspace:

    validate-project:

    action-input:
        [input] Enter the Seam component name
    ping
        [input] Enter the local interface name [Ping]

        [input] Enter the bean class name [PingBean]

        [input] Enter the action method name [ping]

        [input] Enter the page name [ping]

    setup-filters:

    new-action:
         [echo] Creating a new stateless session bean component with an action method
         [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld
         [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld
         [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld\test
         [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld\test
         [copy] Copying 1 file to C:\Projects\helloworld\view
         [echo] Type 'seam restart' and go to http://localhost:8080/helloworld/ping.seam

    BUILD SUCCESSFUL
    Total time: 13 seconds
    C:\Projects\jboss-seam>

Because we've added a new Seam component, we need to restart the exploded directory deployment. You can do this by typing `seam restart`, or by running the `restart` target in the generated project `build.xml` file from inside Eclipse. Another way to force a restart is to edit the file `resources/META-INF/application.xml` in Eclipse. Note that you do not need to restart JBoss each time you change the application.

Now go to `http://localhost:8080/helloworld/ping.seam` and click the button. You can see the code behind this action by looking in the project `src` directory. Put a breakpoint in the `ping()` method, and click the button again.

Finally, locate the `PingTest.xml` file in the test package and run the integration tests using the TestNG plugin for Eclipse. Alternatively, run the tests using `seam test` or the `test` target of the generated build.

## 2.4. Creating a form with an action

The next step is to create a form. Type:

    seam new-form

    C:\Projects\jboss-seam>seam new-form
    Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml

    validate-workspace:

    validate-project:

    action-input:
        [input] Enter the Seam component name
    hello
        [input] Enter the local interface name [Hello]

        [input] Enter the bean class name [HelloBean]

        [input] Enter the action method name [hello]

        [input] Enter the page name [hello]

    setup-filters:

    new-form:
         [echo] Creating a new stateful session bean component with an action method
         [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello
         [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello
         [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello\test
         [copy] Copying 1 file to C:\Projects\hello\view
         [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello\test
         [echo] Type 'seam restart' and go to http://localhost:8080/hello/hello.seam

    BUILD SUCCESSFUL
    Total time: 5 seconds
    C:\Projects\jboss-seam>

Restart the application again, and go to `http://localhost:8080/helloworld/hello.seam`. Then take a look at the generated code. Run the test. Try adding some new fields to the form and Seam component (remember to restart the deployment each time you change the Java code).

## 2.5. Generating an application from an existing database

Manually create some tables in your database. (If you need to switch to a different database, just run `seam setup` again.) Now type:

    seam generate-entities

Restart the deployment, and go to `http://localhost:8080/helloworld`. You can browse the database, edit existing objects, and create new objects. If you look at the generated code, you'll probably be amazed how simple it is! Seam was designed so that data access code is easy to write by hand, even for people who don't want to cheat by using seam-gen.

## 2.6. Generating an application from existing JPA/EJB3 entities

Place your existing, valid entity classes inside the `src/main`. Now type

    seam generate-ui

Restart the deployment, and go to `http://localhost:8080/helloworld`.

## 2.7. Deploying the application as an EAR

Finally, we want to be able to deploy the application using standard Java EE 5 packaging. First, we need to remove the exploded directory by running `seam unexplode`. To deploy the EAR, we can type `seam deploy` at the command prompt, or run the `deploy` target of the generated project build script. You can undeploy using `seam undeploy` or the `undeploy` target.

By default, the application will be deployed with the dev profile. The EAR will include the `persistence-dev.xml` and `import-dev.sql` files, and the `myproject-dev-ds.xml` file will be deployed. You can change the profile, and use the prod profile, by typing

    seam -Dprofile=prod deploy

You can even define new deployment profiles for your application. Just add appropriately named files to your project—for example, `persistence-staging.xml`, `import-staging.sql` and `myproject-staging-ds.xml`—and select the name of the profile using `-Dprofile=staging`.

## 2.8. Seam and incremental hot deployment

When you deploy your Seam application as an exploded directory, you'll get some support for incremental hot deployment at development time. You need to enable debug mode in both Seam and Facelets, by adding this line to `components.xml`:

    <core:init debug="true">

Now, the following files may be redeployed without requiring a full restart of the web application:

- any facelets page

- any `pages.xml` file

But if we want to change any Java code, we still need to do a full restart of the application. (In JBoss this can be handled by configuring deployment scanner mode - more details how to do that are in `$JBOSS_HOME/standalone/deployments/README.txt`

But if you really want a fast edit/compile/test cycle, Seam supports incremental redeployment of JavaBean components. To make use of this functionality, you must deploy the JavaBean components into the `WEB-INF/dev` directory, so that they will be loaded by a special Seam classloader, instead of by the WAR or EAR classloader.

You need to be aware of the following limitations:

- the components must be JavaBean components, they cannot be EJB3 beans (we are working on fixing this limitation)

- entities can never be hot-deployed

- components deployed via `components.xml` may not be hot-deployed

- the hot-deployable components will not be visible to any classes deployed outside of `WEB-INF/dev`

- Seam debug mode must be enabled and `jboss-seam-debug.jar` must be in `WEB-INF/lib`

- You must have the Seam filter installed in web.xml

- You may see errors if the system is placed under any load and debug is enabled.

If you create a WAR project using seam-gen, incremental hot deployment is available out of the box for classes in the `src/hot` source directory. However, seam-gen does not support incremental hot deployment for EAR projects.

- PrevChapter 1. Seam Tutorial
- Top of page
- Front page
- NextChapter 3. Getting started with Seam, using JBoss...