SeamFramework.orgCommunity Documentation
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 a big ugly Ant script wrapped around Hibernate Tools, together with some templates. That makes it easy to customize if you need to.
Make sure you have JDK 5 or JDK 6 (see Section 40.1, “JDK Dependencies” for details), JBoss AS 4.2 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.
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 command line, 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
.
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-2.0.x 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 Java project workspace (the directory that contains your Seam projects) [C:/Projects] [C:/Projects] /Users/pmuir/workspace [input] Enter your JBoss home directory [C:/Program Files/jboss-4.2.2.GA] [C:/Program Files/jboss-4.2.2.GA] /Applications/jboss-4.2.2.GA [input] Enter the project name [myproject] [myproject] helloworld [echo] Accepted project name as: helloworld [input] Select a RichFaces skin (not applicable if using ICEFaces) [blueSky] ([blueSky], classic, ruby, wine, deepMarine, emeraldTown, sakura, DEFAULT) [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? [hsql] ([hsql], mysql, oracle, postgres, mssql, db2, sybase, enterprisedb, h2) 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 [input] Enter your ICEfaces home directory (leave blank to omit ICEfaces) [] [] [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 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/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.
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.
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).
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.
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
.
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
.
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 may be accomplished by touching the top level deployment descriptor: application.xml
for an EAR deployment, or web.xml
for a WAR deployment.)
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.
Seam 2.0 was developed for JavaServer Faces 1.2. When using JBoss AS, we recommend using JBoss 4.2, which bundles the JSF 1.2 reference implementation. However, it is still possible to use Seam 2.0 on the JBoss 4.0 platform. There are two basic steps required to do this: install an EJB3-enabled version of JBoss 4.0 and replace MyFaces with the JSF 1.2 reference implementation. Once you complete these steps, Seam 2.0 applications can be deployed to JBoss 4.0.
JBoss 4.0 does not ship a default configuration compatible with Seam. To run Seam, you must install JBoss 4.0.5 using the JEMS 1.2 installer with the ejb3 profile selected. Seam will not run with an installation that doesn't include EJB3 support. The JEMS installer can be downloaded from http://labs.jboss.com/jemsinstaller/downloads.
The web configuration for JBoss 4.0 can be found in the
server/default/deploy/jbossweb-tomcat55.sar
. You'll need to delete
myfaces-api.jar
any myfaces-impl.jar
from the
jsf-libs
directory. Then, you'll need to copy jsf-api.jar
,
jsf-impl.jar
, el-api.jar
, and el-ri.jar
to that directory. The JSF JARs can be found in the Seam lib
directory. The el JARs
can be obtained from the Seam 1.2 release.
You'll also need to edit the conf/web.xml
, replacing
myfaces-impl.jar
with jsf-impl.jar
.