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 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 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] 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] 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 [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: 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 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 JBoss with the ejb3 profile, 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:
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.)
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.
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. 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.
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 by 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.
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.