JBoss.orgCommunity Documentation

Seam Developer Tools Reference Guide

Version: 4.0.0

1. Introduction
1.1. What is Seam?
1.2. Key Features of JBoss Seam
2. Creating a New Seam Project via the New Seam Project wizard
2.1. Create standalone Seam Web Project
2.2. Selecting the Project Facets
2.2.1. Seam project with JPA facets
2.3. Java application building configuration
2.4. How to Configure Web Module Settings
2.5. Adding JSF Capabilities
2.6. Configure Seam Facet Settings
3. Maven Integration for Seam Projects
3.1. Creating Maven ready Seam project
3.2. Existing Maven Projects Import
4. Directory Structure of the Generated Project
4.1. WAR Deployment
4.2. EAR Deployment
4.3. Changing the Seam Version
4.4. Changing Seam Parent Project
4.5. Renaming the Projects and Folders
5. Seam Menus and Actions
5.1. File Menu Actions
5.2. Navigate Menu Actions
5.2.1. Find Seam References/Declarations
5.2.2. Open Seam Component
6. Seam Wizards
6.1. New Seam Action
6.2. New Seam Form
6.3. New Seam Conversation
6.4. New Seam Entity
7. Seam Generate Entities
8. Seam Editors
8.1. Visual Page Editor
8.2. Seam Pages Editor
8.2.1. Graphical Mode
8.2.2. Tree Mode
8.2.3. Outline Support for Seam Pages Editor
8.3. Seam Components Editor
8.4. Main Features of Seam Editors
8.4.1. Content Assist
8.4.2. Content Assist for Page Descriptors
8.4.3. OpenOn
8.4.4. Seam Validation
9. Seam Views
9.1. Seam Components View
9.2. Project Explorer integration
10. Seam Preferences
10.1. General Preferences
10.1.1. Validator Preferences
10.2. Project Preferences
10.3. Adding Custom Capabilities
11. Seam Refactoring Tools
11.1. Using the Refactorinig Wizard
11.2. Renaming Seam Components
11.2.1. Renaming Seam Components in the Java Editor
11.2.2. Renaming Seam Components in the Seam Components View
11.2.3. Renaming Seam Components in the Seam Components Editor
11.3. Renaming Seam Context Variables in EL
12. Adding Seam support to EAR project
13. Generate a CRUD Database Application
13.1. What is CRUD?
13.2. How to create the CRUD Database Application with Seam
14. The CRUD Application Walkthrough
14.1. Using CRUD Application
15. What is TestNG?
15.1. How to use the generated Seam-test project to run Seam tests?
16. FAQ
16.1. How to get Code Assist for Seam specific resources in an externally generated project?
16.2. How to import an example Seam project from jboss-eap directory?
16.3. How to change the deploy folders for Seam source code from src/hot and src/main?

For a start, we propose you to look through the table of main features of JBoss Seam:

Table 1.1. Key Functionality for JBoss Seam


Integrated JSF with EJB 3.0

JBoss Seam combines the component models of EJB3 and JSF, eliminating glue code, and thus, letting the developer think about the business problem.


Integrated AJAX

Developer can add AJAX capability to the user interface of his application without the need to write any JavaScript code as Seam supports JBoss RichFaces and ICEfaces - the best open source JSF-based AJAX solutions.



Bijection allows auto-assembly of stateful components by the container. It even allows a component to safely and easily manipulate the value of a context variable, just by assigning it to an attribute of the component.


New Seam Project wizard

An easy step-by-step wizard to create a stand alone Seam Web Project with a form to create runtime and server instances in order to get started creating, running, and debugging J2EE (only) applications. You may also add JSF capabilities.

Chapter 2, Creating a New Seam Project via the New Seam Project wizard

Seam component generations options

All the Seam component generations options known from Seam-gen are available as wizards (with sensible auto-defaulting) for creating various common Seam components.

Chapter 6, Seam Wizards

Seam Editors

Visual Page Editor, Seam Pages Editor and Seam Components Editor provide you with a range of great possibilities and will be helpful when working with JBoss Seam.

Chapter 8, Seam Editors

Seam Validator

A configured Seam Validator provides validation of various possible problematic definitions.

Section 8.4.4, “Seam Validation”

CRUD Database Application Generation

JBoss Seam allows adding CRUD support to a Seam Web application.

Chapter 13, Generate a CRUD Database Application

TestNG Framework

TestNG ("Testing, the Next Generation") is a Java unit testing framework that aims to overcome many limitations of JUnit.

Chapter 15, What is TestNG?

In this chapter we provide you with the necessary steps to start working with Seam Framework.

It is suggested that you use the specific Seam perspective that combines a number of different views and editors needed for work with resources concerned. For that select WindowOpen PerspectiveOtherSeam.

The Open Web Browser action is directly available in the Seam perspective.

The best way to get started with Seam is to create a simple Seam Project and experiment with it.

Thus, you should select FileNewOtherSeamSeam Web Project to run the New Seam Project wizard. The wizard form allows you to create runtime and server instances in order to get started creating, running, and debugging J2EE (only) applications.

Seam Web Project wizard has an option for selecting the actual Server (not just WTP runtime) that will be used for the project. This allows the wizard to identify correctly where the required datasource and driver libraries need to go.

Let's get through the wizard step-by-step. First, you should enter a name and a location directory for your new project.

On the figure above you can see the runtime and the server already created.

If you need to create a new runtime, click on the New button in the Target Runtime section. It brings up the wizard where you can specify a new JBoss Server Runtime environment or the other type of runtime appropriate for your project configuration. Let's create one more JBoss Enterprise Application Platform 6.0 Runtime. Hence, after choosing it click on Next button.

All what you need here is to name runtime, type the path to its install directory or locate it by using Browse button, select a Java Runtime Environment, and select which configuration you want.

Clicking on Finish returns you to the Figure 2.2, “New Seam Project Wizard”.

The next step is to define a Server by clicking on New button in the Target Server section. In appeared New Server dialog the last server which matches the runtime will be selected.

All declared runtimes are listed in the combobox under the servers view. Here, you can indicate a server runtime that you need. Click Add if you want to add a new Server Runtime.

Next page allows you to verify the information for a chosen server. Leave everything as it is and click on Next.

On the last wizard step you can modify your projects to configure them on the Server.

Once you have the Target Server defined click on Finish button to return to the first page of the New Seam Project wizard.


Refer to the Application Server Manager Guide to find out more about runtimes and servers.

The last section on this wizard step is Configuration. Here, you can select one of the predefined project configurations either associated with Seam 1.2, Seam 2.0 or with Seam 2.1. Furthermore, you can create your own configuration by pressing the Modify button. It will open the dialog which allows to configure your own set of facets for adding extra functionality to your project.

Pass to the next section to find out more details on this dialog.

The Project Facets wizard allows you to enable or disable specific facets which define necessary features for the project. When you switch to this wizard form, all critical facets are already checked for the chosen Configuration.

Notice that this page of the wizard also allows you to set the necessary version for any facet.

Moreover, here you can specify your own preset of selected facets by checking needed ones in project facets window and clicking on the Save as button.

To see all available Server runtimes click on Runtimes tab on the left. You can create a new one using the New button. If more than one runtime is checked here, the Make Primary button will not be dimmed yet. Thus, you can make use of it to mark primary runtime.

Clicking the OK button will bring you to the Web Module wizard form again.

Maven integration is included by default, allowing you to create mavenized Seam projects and use Seam tools with imported Maven projects.

Maven Integration makes the Seam Wizard capable of creating Maven ready projects to let Maven get the libraries instead of using the Seam runtime.

To create a mavenized Seam project you should perform the following steps:

The organized Seam project contains five projects with the Maven nature, builder, Maven classpath and the pom.xml files added: projectname, projectname-ear, projectname-ejb, projectname-parent and projectname-test.

Maven Integration includes the Seam Maven configurator which is called when importing a project, changing pom.xml and/or calling MavenUpdate Project Configuration. When importing a Maven Seam project, the Seam Maven configurator picks up the settings set up in pom.xml and adds to the project the following:

If the Seam version from pom.xml matches a version of a Seam runtime configured in the workspace, Seam configurator will set that runtime, otherwise no Seam runtime will be set and you'll have to set it manually under Section 10.2, “Project Preferences”.

Seam configurator recognizes the Seam artifacts in the following way: the view folder is a web content folder from the WAR project, the source folder is the first Eclipse source folder. If there is a folder containing "hot" in the name, it will be chosen as the action source folder. Package is the first package that has children or doesn't have any subpackage.

Configuring the Seam when importing a Maven project as well as a Seam Runtime, Seam artifacts and some facets could be suspended in the JBoss Maven Integration preferences (WindowPreferencesJBoss ToolsJBoss Maven Integration).

In this chapter we describe where the Seam wizard puts the generated files for both EAR and WAR deployments.

The Seam Project wizard generates projects like Eclipse WTP style in order to utilize Eclipse WTP features and to have a correct classpath. To be more precise it generates one project per artifact.

In this chapter we provide a description of Seam actions that are available from

  • Menu bar

  • Toolbar

  • Context menus in views

In the next sections we are going to describe Seam actions which can help you to easily navigate through the source code.

This chapter introduces you with Seam Components.

All the Seam component generations options known from Seam-gen are available as wizards (with sensible auto-defaulting) for creating various common Seam components:

  • Seam Action

  • Seam Form

  • Seam Entity

  • Seam Conversation

Go to FileNew and select the component wizard.

The wizards create multiple resources and place it in the appropriate folders depending on your project structure (WAR or EAR).

Let's create a WAR project using the New Seam Project wizard.

After the project is created you need deploy it on server.

Generate Entities is available by navigating to FileNewOtherSeamSeam Generate Entities

The wizard generates a set of CRUD Seam components and web pages based on existing tables in a database or on existing entities in your application.

By default, the generation mode is set to Reverse engineer from database. The reverse engineering from a database could be described in four steps:

  1. The wizard gets in database, extracts the tables and their connections

  2. On basis of this metainfomation the Entity classes are generated into org.domain.project.entity package

  3. For the entities from step 2 the classes EntityList and EntityHome are generated into org.domain.project.session package

  4. The xhtml pages are generated.


The entities are generated from a database based on the console configuration that is created automatically during a Seam project creation. (Read more about the console configuration in the Hibernate guides). The created console configuration is based on the connection profile set on the Section 2.6, “Configure Seam Facet Settings” while creating a project. Configured connection profile settings are hold in the generated hibernate-console.properties. To change the connection profile, double-click the console configuration. It could be found in the Hibernate Configurations view (WindowShow viewOtherHibernateHibernate Configurations or just switch to the Hibernate perspective).

Checking the Use existing entities mode the wizard executes only 3 and 4 steps. It generates missing classes and xhtml pages.

Read the Chapter 13, Generate a CRUD Database Application chapter in order to see how the Generate Seam Entities wizard can be used.

This chapter tells about Seam Editors and their features.

Seam Pages Editor provides a handy way to edit the pages.xml file.

You can edit the pages.xml file in three modes: Graphical, Tree and Source.

Seam Pages Editor supports synchronization with Package Explorer.This means that while renaming files in the Package Explorer all the changes immediately affect the pages.xml file.

Graphical mode provides you with a set of visual tools to organize your project pageflow, exception handling etc.

The Graphical part of the editor has some visual elements. The table below shows graphical representation of the elements and explains their meanings.

Pageflow relations are shown with gray arrows, when you select a relationship the arrow is changed to orange.

On the left hand side of the Graphical view of Seam Page Editor you can find a toolbar with a set of icons for the most frequently used commands.

Context menus are also available when you click either on an item or a blank space.

A context menu called on a blank space of the diagram provides the following options:

  • Page creates a new page element on the diagram

  • Exception creates a new exception element on the diagram

  • Auto Layout formats the layout of the diagram automatically

  • Select Element calls the Select Element Wizard with a filter to perform a quick search through the pages.xml file

Right clicking on a selected <page> element calls a context menu where you can choose the following options if you click on the New menu item:

  • Rule opens the Add Navigation Rule dialog in which you can browse your project for a view page to set the view-id in the navigation rule and specify render or redirect navigation options

  • Param calls a dialog box where you can define a parameter (using the <param> tag) for the <page> element

In this chapter you will know what Seam Editors features are and how to work with them.

OpenOn lets you easily navigate through your project without using the Package Explorer or Project Explorer. After pressing Ctrl + left click (or just F3) you will see a corresponding method or class.

OpenOn is available for the following files:


For more information on OpenOn, see the Visual Web Tools Reference Guide.

OpenOn in XHTML files

Using OpenOn in .xhtml files you can open:

OpenOn in XML files

OpenOn is also supported in Page Descriptors (.page.xml and pages.xml). OpenOn allows you to navigate to Java beans as well as to view pages. You can Ctrl + left click on a bean or on view page file (for example, a XHTML file) to navigate to the file you clicked on.

If you use Rule-based authorization with Drools in your Seam application you can apply OpenOn in components.xml to open the files containing rule definitions in the "rule-files" tag.

You can also use OpenOn to open jBPM components that are described in Seam component descriptor. Two places where it works are available:

OpenOn in Java files

OpenOn is also supported in seam components where In annotation is presented. After pressing Ctrl + left click on the seam component specified in @In you will get the possibility to open the file where the component is declarated as well as all of the seam components where it is used in the next declarations:

Validation of various possible problematic definitions is implemented for Seam applications.

If an issue is found it will be shown in the standard Problems View.


Please note, only files within source path and web content are validated, meaning temporary files or test files are not included.

In the preferences page for Seam Validator you can see and modify the validator behavior. Go to WindowPreferencesJBoss ToolsWebSeamValidator and select the severity level for the optional Seam Validator problem.

On WTP projects validation are enabled by default and thus executed automatically, but on normal Java projects you will have to go and add the Validation builder of your project . It is available in the properties of your project under Validation.

The validations can be run manually by clicking Validate via the context menu on your project (folder or file inside your project) which will execute all the active WTP validations. Following to the project's preferences under Validation it's possible to enable/disable any validator.

It's also possible to turn off the validation for some resource (a file, folder) inside your project via the Exclude Validation context menu option.

As a result, if you've turned off the validation for a folder (or file), it is put to the excluded group of the Validation filters and be ignored during the validation.

This chapter introduces you with Seam Components View.

The Seam Components view is available from Seam perspective. It provides a list of seam components found in a project.

By right-clicking on a project and bringing up the context menu, you can create a new Seam project, action, conversation, form or entity. You can also generate entities from this menu and it is all able to be done from the Seam Components view.

The Seam Components View can show a components default scope in two ways:

  • as labels on each component (click on the triangular symbol at the top of the Seam Components View page and select Scope PresentationLabel)

  • as a node per scope where the components are grouped under a node representing its default scope.

The Seam Packages can be presented in two ways:

  • Flat

  • Hierarchical

The Seam Components view can be filtered by choosing Customize View.

Select the Seam Components from Libraries under the Filters tab. This will make the view ignore components defined in jars. This will hide the many built-in Seam components and leave only those that are actually defined in the project or have been actively configured via components.xml. Therefore, deselecting the filter will show you all available components.

Selecting the Seam Components from Referenced Projects will hide the components that depend on other projects.

In this chapter you get to know how Seam preferences can be modified during the development process.

Seam preferences can be set using the Seam preference page. Click on WindowPreferencesJBoss ToolsWebSeam.

On this page you can manage the Seam Runtime. Use the appropriate buttons to Add more runtimes or to Remove those that are not needed.

Clicking on Edit button you get the form where you can change the path of Seam runtime home folder, modify name and version. Press Finish to apply the changes.


If you try to delete the Seam Runtime that is already in use by some project in the current workspace, then a warning message will appear. To confirm the removal press OK

Besides, when you right-click on your Seam project with deleted runtime in Project Explorer and select PropertiesSeam Settings the error message "Runtime <runtime_name> does not exist" will appear.

The goal of Seam components refactoring is to make system-wide code changes without affecting the behavior of the program. Seam Tools provides assistance with code refactoring.

Seam refactoring tools includes the following refactoring operations:

Refactoring commands are available from the context menus of several views and editors; for details, see Section 11.1, “Using the Refactorinig Wizard”.


Seam refactoring could be only performed in the file that is not marked as Read only in its properties.

From this chapter you will find out how to add Seam support to EAR project

For example you have several WTP projects:

To enable Seam support for an existing EAR, WAR or EJB project, right-click on the project in the Project Explorer to bring up the context menu and navigate to ConfigureEnable Seam Support.

Copy required JAR files manually into the project. For EAR projects specifically, copy library folders into the projects /lib folder and they will be automatically detected.

  • First, you should download the employee-hsqlb database, extract the employee-hsqldb.zip and start it by running ./runDBServer.sh or runDBServer.bat from the database directory.

  • Create a new Seam Web Project using New Seam Project wizard or main menu FileNewSeam Web Project.

  • Name your project as crudapp, specify Target Runtime, Server and Seam Runtime configuration. Then press Next and follow the next wizard steps keeping default settings.


Please have a look at Chapter 2, Creating a New Seam Project via the New Seam Project wizard how to create Target Runtime and Seam Runtime in order to get started creating, running, and debugging J2EE applications.

  • On Seam Facet page click New... next to the Connection profile section to create a new Connection profile.

  • On New Connection Profile dialog select the HSQLDB connection profile type, name it cruddb and click Next.

  • On the next page click the round icon next to the Drivers field to select a database driver.

  • Now you should see the New Driver Definition dialog. On the first tab select the HSQLDB JBDC Driver. Underneath in the Driver name field you can change its name if you need.

  • You may notice the note on the previous figure. It prompts that you should specify the driver of the type you pointed. Set the location of the driver by selecting hsqldb.jar from the list and clicking the Edit JAR/ZIP button.

  • On the Properties tab set the Connection URL to jdbc:hsqldb:hsql://localhost:1701, Database Name to employee and User ID to sa and click OK.

  • After clicking OK to submit the newly created driver you can observe and if you need edit all specified connection details.

  • Now click Test Connection to be sure that connection can be established.

  • Validate JDBC Connection profile settings and press Finish or Back if something is wrong.

  • After clicking Finish two projects crudapp and crudapp-test will be created.

  • You can expand the WebContent folder of the crudapp project in the Project Explorer and open home.xhtml or login.xhtml with JBoss Visual Editor.

  • Switch to Database Development perspective with WindowOpen PerspectiveOther.

    Connect to the cruddb database if not already connected to it.

  • Expand cruddb nodes to view its Schemas, Tables, Columns etc.

  • Switch back to the Seam perspective. From the toolbar select NewSeam Generate Entities to create a set of CRUD Seam components and web pages based on existing tables in the database. On the first page of Generate Seam Entities wizard, select Reverse engineer from database click press Next.

  • Click Refresh to display all the tables from the database.

  • Now you can filter the tables. Use the Include button to include those that are necessary and click Finish.

  • Under WebContent folder you can find all generated xhtml files:

  • And under src folder java classes are created.

  • Switch to Hibernate perspective with WindowOpen PerspectiveOther.... On Hibernate Configurations view expand the crudapp configuration. Right click on Customers and select Open Mapping Diagram from the popup menu.

  • Observe the Mapping Diagram opened in the editor. Here you can see the relations between models and database tables. For better navigating on the diagram use the Outline view.

  • For example, select Customers entity, right click and select Open Source File. This will open the Customers.java file in the java editor. You can also do this by right-clicking on the same entity on the Mapping Diagram.

So far, you are ready to deploy your application to JBoss Application Server. This is described in the next chapter.

After you familiarized oneself with example of creating the CRUD Database Application with Seam, you can read this charter.

TestNG ("Testing, the Next Generation") is a Java unit testing framework that aims to overcome many limitations of JUnit. TestNG introduces some new functionalities that make it more powerful and easier to use, such as:

  • JDK 5 Annotations (JDK 1.4 is also supported with JavaDoc annotations)

  • Flexible test configuration

  • Support for data-driven testing (with @DataProvider)

  • Support for parameters

  • Allows distribution of tests on slave machines

  • Powerful execution model (no more TestSuite)

  • Supported by a variety of tools and plug-ins (Eclipse, IDEA, Maven, etc...)

  • Embeds BeanShell for further flexibility

  • Default JDK functions for runtime and logging (no dependencies)

  • Dependent methods for application server testing

  • Add Seam Action to your project via FileNewSeam Action.

  • Fill out the wizard fields. New Seam Action wizard will create resources and place them in the appropriate folders dependent on EAR project structure.

  • When Action is created you will see actionPage.xhtml in Package Explorer view. ActionBean.java will be automatically opened in Java Editor.

  • Select ActionLocalTest.xml in Seam-test project and run the test with right click Run AsTestNG Suite.


OpenOn is available in testNG XML files opened in JBoss XML Editor

The test process will start and its output will be written in Console View.

  • After running TestNG you will have the test results in test-output folder in Seam-test project (press F5 to refresh the Package Explorer view). Open index.html file with Web Browser or simply use the TestNG view.

The below view shows a successful run of the test.

You can see the test results in Web Browser.

After clicking on ActionLocal Tests link you will see the Results for ActionLocal Tests.

Select a result on the left-hand pane and its details will be displayed on the right-hand one.

Thus with Seam tooling you can easily take advantage of TestNG framework. As you can see, it generates its own TestNG project as a separate module within which you can easily monitor the tests execution and their output.