The Seam distribution includes a tool named seam-gen to help you get started quickly using Seam. The tool collects information from you about your project and then uses that information to create a project structure. It can also generate a CRUD application by reverse engineering your database schema and generate various forms of stub code. In this entry, you'll learn how to get the generated project setup in Eclipse so that you can leverage the available tooling.
Two tools, one goal
There are actually two interfaces to seam-gen. The first is the commandline script named seam, which resides at the root of the Seam distribution. When we talk about seam-gen, we are usually referring to this script. There is also new project wizard in JBoss Tools (the open source project behind JBoss Developer Studio) that is a complement to this script. Both tools share the same FreeMarker templates inside the seam-gen directory of the Seam distribution to produce the Java code, Facelets views, and TestNG configuration. Aside from these common templates, the two tools work independently of one another in setting up a Seam project. The projects they generate differ in one fundamental way, though. The commandline tool produces projects that are built using Ant, while the JBoss Tools new project wizard creates projects that are build purely with Eclipse builders.
As you'd expect, when you create a project using the Eclipse plug-in, you can immediately start taking advantage of the tooling support for Seam in your project. However, like me, you may find it important to have a project that can be built outside of Eclipse using Ant. That means creating the project using the seam-gen commandline script. Don't fear that by creating the project outside of Eclipse, that the IDE is reduced to a syntax checker and Java compiler. The purpose of this article is to demonstrate how to fully activate the Seam tooling in Eclipse for projects created using the seam-gen commandline script, bringing you the best of both worlds. Plus, once the Seam tooling is activated, you can generate the CRUD application or stub code from either Eclipse or the commandline script.
Step 1. Create the project with seam-gen (i.e., the commandline script)
There are plenty of tutorials available for how to use seam-gen to create a project. You can find one in the Seam reference guide and another in chapter 2 of Seam in Action. Let's just quickly review the steps for completeness.
- Download and extract the Seam 2.x distribution
- If on Linux or Mac, run
chmod 755 seam
from the root of the distribution to make the seam script executable - Make sure the JAVA_HOME environment variable is defined and it points to a JDK installation (>= 1.5)
- In a terminal window, change your working directory to the Seam distribution and execute seam setup on Windows or ./seam setup on Linux or Mac (optionally, you can put the Seam distribution in your PATH to use seam like a system command)
- Execute the seam script again, this time supplying it the create-project command
Your project is now created. The next step is to get the JBoss Tools plug-in for Eclipse installed so that you can use the Seam tooling once you get the project imported into Eclipse.
Step 2. Install the JBoss Tools plug-in for Eclipse
If you are using JBoss Developer Studio, you can skip this step. JBoss Developer Studio comes with all the plug-ins you need to develop Seam applications (plus support). These instructions explain how to install the latest stable version of JBoss Tools, which should be used with Eclipse 3.3 (Europa). You can also install the development version, which works with Eclipse 3.4 (Ganymede).
- Download the
Eclipse IDE for Java EE Developers
via eclipse.org. JBoss Tools relies on the Eclipse Web Tools project and several other plug-ins that come with that distribution. - Select the menu item Help > Software Updates > Find and Install...
- Choose the option Search for new features to install
- Click the button New Remote Site...
- Enter the following values in the form:
Name: JBoss Tools Stable Updates
URL: http://download.jboss.org/jbosstools/updates/stable - Click Finish
- Check the option JBoss Tools Stable Updates and advance through the rest of the wizard
- Go get coffee while the plug-ins download
- Click Install All when the download completes and allow Eclipse to restart when the install is done
JBoss Tools is now installed. If you are interested in seeing other ways to install JBoss Tools, refer to this page on the JBoss Wiki.
Step 3. Import the project into Eclipse
When seam-gen creates a project, it also generates Eclipse project files. Therefore, Eclipse will recognize the project directory as a valid Eclipse project. You simply need to use the Eclipse project import wizard.
- In Eclipse, select File > Import project... and choose the Existing project into Workspace option
- Browse to the location of the generated project and Eclipse should recognize the project
- Click Finish
As soon as Eclipse imports the project you should notice output from Ant in the Console view. As I mentioned earlier, projects created with seam-gen use Ant to build and Eclipse drives those Ant tasks.
NOTE You should immediately right click on your project in the Project Explorer and select Refresh. This step gets Eclipse to recognize the output files from the Ant build that runs after the import. The Hibernate Console plug-in is then able to find the persistence unit configuration so you can open a session factory and start using it.
You're seam-gen project is now a JBoss Tools Seam project! That means you can take advantage of the core Seam tooling. However, you cannot yet use the code generation. You need to inform JBoss Tools where your Seam runtime is in order to do things such as create a new Seam action.
Step 4. Attach the project to the Seam runtime
JBoss Tools needs to know where the Seam distribution is because that is where the shared code generation templates are that I mentioned earlier. To make that connection, right click on the root node of the project and select Properties. Select the Seam Settings in the sidebar of the window that appears to bring up the Seam settings properties sheet as shown here.
To fully activate the Seam support, you need to create a Seam runtime.
- Click on the Add... button to open the dialog for defining a new runtime
- Browse to the location of the Seam distribution where you created the project, choose a name for the runtime, and select version 2.0.
- When you are done, click Finish
You should see that most of the form fields in the Seam settings property sheet are now active. However, you still need to establish a (database) connection profile.
- Click New... to open the dialog to define a new connection
- Select a connection type (HSQLDB or Generic JDBC)
- Progress through the wizard using the same connection information you used when creating the project
The Seam property sheet should now be fully populated, as shown here:
You will now be able to use all of the code generation tasks in JBoss Tools without having to go back to the commandline to run the seam script. For instance, if you select File > Other... > Seam Generate Entities, you can create a CRUD application by reverse engineering the database defined in the Hibernate console configuration. (The latest version of the Seam tools even offers selective generation of entities).
Once the code generation completes, you can open one of the Seam components by name using the Open Seam Component dialog:
JBoss Tools also provides EL completion, such as in a Facelets view:
You can also use the Hibernate Console, the Seam page descriptor editor, the Seam component descriptor editor, and so on. In fact, for the most part, you are able to work with your seam-gen project in JBoss Tools as if you had created the project using the Seam Web Project wizard in JBoss Tools. However, as of Seam 2.1, one features that you lose when you start with the commandline version of seam-gen is incremental deployment of the application through the Eclipse tooling.
Step 5. Deploy the application to JBoss AS
In order to deploy a seam-gen application to JBoss AS, you have to use the Ant targets in the project build file, even when developing in Eclipse. But you can drive those Ant tasks from Eclipse.
- Choose Window > Show View > Ant to bring up the Ant view
- Right click in the Ant view and select Add buildfiles...
- Select the build.xml at the root of the project
- When the Ant tree appears, expand it and scroll down to the explode target.
- Double click on the explode target to deploy the application to JBoss AS as an exploded archive
You can start JBoss AS either from the commandline or by setting up a JBoss AS runtime in Eclipse. However, as I mentioned in the last section, JBoss Tools cannot natively deploy a project created by seam-gen to the JBoss AS runtime at the moment. We are working on improving seam-gen to setup the Eclipse project so that the native incremental deployment works out of the box. Until then, you can still take advantage of incremental hot deployment because the explode Ant task is tied to the auto-build mechanism in Eclipse.
Step 6. Debug the application
If you start JBoss AS in debug mode, you can attach the Eclipse debugger to it by clicking on arrow next to the debug icon in the main toolbar and selecting debug-jboss-<projectName>, where <projectName> is the name you assigned to the project. (Close and open the project again if you don't see this option).
The debugger connects to JBoss AS as a Remote Java Application.
IntelliJ IDEA Sneak Peak
If you checkout Seam from SVN and use the seam script to create a new project, you can import that project into IntelliJ IDEA and take advantage of the Seam tooling provided in IntelliJ IDEA 8. IntelliJ IDEA 8 offers wide range of Seam tooling support, including EL completion, validation, and refactoring. You can check out a screencast of the new features here.
Summary
This tutorial demonstrated that you are able to use the Seam tooling provided by JBoss Tools for projects created using seam-gen. You learned how to import the project into Eclipse, setup a Seam runtime, configure a connection profile, and deploy and debug the application on JBoss AS. You also got a little sneak peak at the parallel tooling support for Seam in IntelliJ IDEA 8.
