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.
In this release, seam-gen only works for people who want to use Seam with EJB 3.0 in JBoss AS. Future versions will support other deployment environments.
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 peformed from the command line.
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.
Make sure you have JDK 5 or JDK 6, JBoss AS 4.0.5 and Ant 1.6, along with recent versions of Eclipse, the JBoss IDE plugin for Eclipse and the TestNG 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.
The first thing we need to do is configure seam-gen for your environment: JBoss AS installation directory, Eclipse workspace, and database connection. It's easy, just type:
cd jboss-seam-1.1.x seam setup
And you will be prompted for the needed information:
C:\Projects\jboss-seam>seam setup Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml setup: [echo] Welcome to seam-gen :-) [input] Enter your Java project workspace [C:/Projects] [input] Enter your JBoss home directory [C:/Program Files/jboss-4.0.5.GA] [input] Enter the project name [myproject] helloworld [input] Enter the Java package name for your session beans [com.mydomain.helloworld] org.jboss.helloworld [input] Enter the Java package name for your entity beans [org.jboss.helloworld] [input] Enter the Java package name for your test cases [org.jboss.helloworld.test] [input] What kind of database are you using? [hsql] (hsql,mysql,oracle,postgres,mssql,db2,sybase,) mysql [input] Enter the Hibernate dialect for your database [org.hibernate.dialect.MySQLDialect] [input] Enter the filesystem path to the JDBC driver jar [lib/hsqldb.jar] ../../mysql-connector.jar [input] Enter JDBC driver class for your database [com.mysql.jdbc.Driver] [input] Enter the JDBC URL for your database [jdbc:mysql:///test] [input] Enter database username [sa] gavin [input] Enter database password  [input] Are you working with tables that already exist in the database? [n] (y,n,) y [propertyfile] Creating new property file: C:\Projects\jboss-seam\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: 1 minute 17 seconds C:\Projects\jboss-seam>
The tool provides sensible defaults, which you can accept by just pressing enter at the prompt.
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:
C:\Projects\jboss-seam>seam new-project Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml validate-workspace: validate-project: copy-lib: [echo] Copying project jars ... [copy] Copying 32 files to C:\Projects\helloworld\lib [copy] Copying 9 files to C:\Projects\helloworld\embedded-ejb file-copy-wtp: file-copy: [echo] Copying project resources ... [copy] Copying 12 files to C:\Projects\helloworld\resources [copy] Copying 1 file to C:\Projects\helloworld\resources [copy] Copying 5 files to C:\Projects\helloworld\view [copy] Copying 5 files to C:\Projects\helloworld [mkdir] Created dir: C:\Projects\helloworld\src new-project: [echo] A new Seam project was created in the C:/Projects directory [echo] Add the project from inside Eclipse (or type 'seam explode') and go to http://localhost: 8080/helloworld 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... -> Java Project -> Next, typing the Project name (myproject in this case), selecting your Java SE 5 or Java SE 6 JRE and then clicking Finish. Do not select Create new project from existing source. 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.)
If you're used to traditional action-style web frameworks, you're probably wondering how you can create a simple webpage with a stateless action method in Java. If you type:
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 ping Buildfile: C:\Projects\jboss-seam\seam-gen\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\hello\src\com\hello [copy] Copying 1 file to C:\Projects\hello\src\com\hello [copy] Copying 1 file to C:\Projects\hello\src\com\hello\test [copy] Copying 1 file to C:\Projects\hello\src\com\hello\test [copy] Copying 1 file to C:\Projects\hello\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. 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.
The next step is to create a form. Type:
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\com\hello [copy] Copying 1 file to C:\Projects\hello\src\com\hello [copy] Copying 1 file to C:\Projects\hello\src\com\hello\test [copy] Copying 1 file to C:\Projects\hello\view [copy] Copying 1 file to C:\Projects\hello\src\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 deploment each time you change the Java code).
Manually create some tables in your database. (If you need to switch to a different database, just run seam setup again.) Now type:
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 using seam-gen.
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.