Setting Up JBoss Tools for Seam Application Development

n the Java enterprise development ecosystem, you’ll find a wide proliferation of frameworks and solutions. However, unlike in the Microsoft development world, very few of them provide an end-to-end solution from the framework right down to development tools. JBoss is one of the few players in the Java world that has attempted?with pretty good results?to achieve smooth integration across its core development offerings:

  • JBoss Tools
  • Seam Web Framework
  • JBoss EJB 3.0 Application Server
  • RichFaces JavaServer Faces (JSF) Component Library
  • Facelets
  • Hibernate Validators

Together, these components comprise the JBoss web development stack. This article examines each of these offerings individually and then demonstrates how to set up a JBoss Tools environment for developing Seam applications.

What You Need
At least a basic knowledge of Seam (If you are new to Seam, please read at least the
introductory chapters from the extremely well written Seam manual before proceeding.)
Version 3.3.1 or later of the Eclipse IDE for Java EE Developers
Version 4.2.2 of the JBoss Application Server

Seam Web Framework
Seam provides the glue between the world of JSF and EJB 3.0 (see Sidebar 1. Seam and Web Beans) by allowing EJBs to act as managed beans (which gives you direct access to all the features of EJB 3.0, such as JPA and dependency injection). Also, it provides a new context called conversations, which allows you to tie a typical use case that spans multiple web pages into one logical unit easily (thus, avoiding the necessity to manipulate the session context to keep track of the current user process).

RichFaces JSF Component Library
RichFaces is a fully AJAX-enabled JSF component library that allows you to perform the usual JSF post-back cycle without having to refresh the entire page. This basically makes your web application AJAX-enabled out of the box. No additional hand coding of JavaScript is required. In short, RichFaces is designed to help you create a professional-looking Web 2.0 application with minimum effort.

RichFaces includes such AJAX-enabled JSF components as:

  • Menus (context, dropdown, etc.)
  • Tree controls
  • Graphics panels (allow dynamic painting of images using Java’s graphics capabilities)
  • Tab panels
  • Date input calendars
  • Numeric input slider and spinner controls
  • Typical add/remove list controls (see Figure 1)
  • Graphical effects (fade, fold, squish, etc.)
  • Professional data grid/data table controls (see Figure 2)

To appreciate what RichFaces brings to the table, check out their online demo and then read through their very detailed manual.


Figure 1. RichFaces Skinned AJAX Data Table Components: These are typical add/remove list controls in RichFaces.
 
Figure 2. RichFaces Skinned AJAX Shuttle List Component: RichFaces provides professional data grid/data table controls.

Facelets
Although Seam supports JSP pages, the default view technology is Facelets, which has many benefits for JSF development. Its main advantages include support for templates, reusable page components, faster performance, and more detailed error reporting. Gavin King, the creator of Seam, recommends Facelets over JSPs in all the Seam documentation. The Facelets templating support alone makes it the a worthwhile choice (no more messing with Tiles for all you Struts fans).

Hibernate Validators
Hibernate Validators is a small but very useful project (which despite the name is not tied to the Hibernate library itself). It basically adds additional validators for JPA entities (see Figure 3). In particular, it allows you to specify quite a few new validations, such as:

  • @Length(min/max)
  • @Max(value=)
  • @Min(value=)
  • @NotNull
  • @NotEmpty (for strings)
  • @Past and @Future (for dates)
  • @Pattern (for regular expression based validation)
  • @Range(min=,max=)

Please refer to the Hibernate Validators manual for a complete list.

 
Figure 3. Using Hibernate Validators While Coding JPA Entities in JBoss Tools: Hibernate Validators basically adds additional validators for JPA entities.

Hibernate Validators are included in the Seam runtime and as such are automatically added to the classpath of any new Seam web project. In order to use Hibernate Validators in your code and integrate them fluidly with Seam, you need to use the built-in Seam tag , as per the example below from the Seam manual:

    
Country:
Zip code:

For more details on form validation in Seam, please read the form validation tutorial.

JBoss EJB 3.0 Application Server
In its initial release, Seam was called JBoss Seam and was closely tied to the JBoss Application Server (AS). However, the Seam team was eager to see it spread beyond the JBoss platform so they changed the name to just Seam and created a non-JBoss site for it: seamframework.org.

Nevertheless, Seam integrates best with JBoss AS and JBoss AS is the environment in which Seam applications most often are developed. I was able to deploy a Seam application to Glassfish, but it required a lot more configuration (in particular, all the EJB JSF managed beans had to be manually registered as EJB references in the web.xml file).

 
Figure 4. Visual Editor for Developing JSF/Seam/RichFaces/Facelets Pages: JBoss Tools offers a graphical editor for JSF web page development.

To develop applications with Seam 2.0.1 on JBoss AS, you need to download JBoss Application Server 4.2.2. Surprisingly, the default version of Seam 1.2.1 does not seem to play very well with this JBoss AS version, as I got deployment errors related to Apache MyFaces. This presumably is because, beginning with version 4.2, JBoss has used Sun’s JSF reference implementation and stopped including the somewhat moribund Apache MyFaces implementation.

JBoss Tools
JBoss Tools basically is a suite of Eclipse plugins that is intended to make developing Seam applications easy and productive, using the entire software stack described above. It includes all the wizards related to creating new Seam projects and their subcomponents (e.g., conversations, entities from database), as well as a graphical editor for JSF web page development (see Figure 4).

Although it is outside of the scope of this article, the default JBoss Tools installation includes a plug-in for Struts development as well, which is very beneficial considering how entrenched Struts is in most JSP Java shops.

Setting Up JBoss Tools
My experiences with installing the JBoss Tools set of plugins were quite different depending on the platform. (See Sidebar 2 to learn about an important Eclipse error caused by the PermGen setting.) On my Windows XP box, downloading the JBoss Tools “All Plugins” bundle worked without a hitch. However, the equivalent Linux version of the bundle was quite a different story. Most of the features failed to register due to errors regarding missing dependencies (see Figure 5).

 
Figure 5. Failed Default Installation of JBoss Tools Under Ubuntu: Most of the features failed to register under Ubuntu due to errors regarding missing dependencies.

It turned out I had to download the JBoss XDoclet, Struts Tools, Seam Tools, RichFaces VPE Tools, and jBPM Designer plugins individually from the JBoss Tools download site. This is quite surprising considering that JBoss is owned by Red Hat, one of the world’s most ardent Linux supporters.

Although it is possible to simply deploy the plugins into the main Eclipse folder, I personally preferred to deploy them into a separate location and then just link them into my main Eclipse installation. I simply created a folder underneath Eclipse called links and added a jbosstools.link file to it with the path to the JBoss plugins installation, for example:

  • File name: /home/jacek/Dev/Java/IDE/eclipse-3.3.1/eclipse/links/jbostools.link
  • jbosstools.link file content: path=/home/jacek/Dev/Java/IDE/JbossTools

To follow this technique yourself, you will need to restart Eclipse with the “-clean” switch in order for it to register the new link.

After completing the JBoss Tools plugins installation, be sure to go to Help -> Software Updates -> Manage Configuration. Expand the first node and verify that all the plugins are registered successfully without any errors.

Author’s Note: JBoss/Red Hat offers a commercial distribution of all of its plugins, pre-configured and with support. It is called JBoss Developer Studio and it is available for the very reasonable subscription fee of $99 per year.

Creating Your First Seam Project
In order to create a new Seam project, you need to invoke the “New Seam Web Project” wizard (see Figure 6). The name is somewhat misleading, since this project will contain not only the web part but also all the separate projects required to host your EJBs, EAR configuration, and unit tests.

 
Figure 6. New Seam Web Project Wizard: In order to create a new Seam project you need to invoke the “New Seam Web Project” wizard.
Author’s Note: Do not use a dash (-) in the project name (e.g., “devx-seam”). I used one and got a deployment exception. I then had to go to the ${PROJECT_ROOT}/resources/-ds.xml file and change the default name of the Entity Manager.

Before you can create your first project, you must complete a few prerequisite steps. The first step is to create a new runtime for the application/web server that you will be using, JBoss in this case (see Figure 7).

Next, you need to create a configuration for an actual server, using the previously specified runtime (see Figure 8). Make sure you have the administrator user name/password on hand (the default in JBoss is “admin”/”admin”), in order to have access to the JMX console.


Figure 7. New JBoss Runtime Wizard: Use this wizard to create a new runtime for the application/web server that you will be using.
 
Figure 8. New JBoss Server Wizard: You need to create a configuration for an actual server, using the previously specified runtime.

The wizard also will ask you to create a new Seam runtime, which will point to your local installation of the Seam libraries (see Figure 9). Surprisingly, the runtime is not included with the base version of JBoss Tools. Since I had deployment issues with the combination of Seam 1.2.1 and JBoss 4.2.2, I did most of my testing with the brand new Seam 2.0.1 runtime.

After all of this, you your initial setup of the project should be complete (see Figure 10).


Figure 9. New Seam Runtime Wizard: These are typical add/remove list controls in RichFaces.
 
Figure 10. Finishing the New Seam Web Project Setup: Your initial setup of the project should look like this.

However, because Seam provides functionality for automatically creating new entities (and maintenance pages for them) from the database, you will need to define a database connection for your project’s JPA Entity Manager. The first step for meeting this requirement is to define the database driver to use (see Figure 11). Make sure you have it downloaded locally. (In my case, it was the MySQL JDBC driver.)

The next step is to specify the actual connection details for your development database (see Figure 12).


Figure 11. Setting Up the Database Driver: Figure 12. Setting Up the Database Connection Details: You will need to define a database connection for your project’s JPA Entity Manager.
 
Figure 12. Setting Up the Database Connection Details: You will need to specify the actual connection details for your development database.

At this point, you should have created a base project. Right-click on the main project node and select Run -> Run on Server should to deploy the project to the server, open the integrated browser within the Eclipse IDE, and show a login page, the base starting point of a new web application.

Occasionally when creating a new Seam project, I notice that the EJB portion of it shows up with compilation errors. In this case, clean and recompile your workspace to correct this.

Handling the Login/Authentication Logic
The project wizard does not only create the login, it also connects the login to a business object in your root package called simply Authenticator.java. Code all of your login validation in Authenticator.java and depending on whether it is successful or not, return true or false:

@Name("authenticator")public class Authenticator{    @Logger Log log;        @In Identity identity;       public boolean authenticate()    {        log.info("authenticating #0", identity.getUsername());        //write your authentication logic here,        //return true if the authentication was        //successful, false otherwise        identity.addRole("admin");        return true;    }}

Creating JPA Entities
Right-click on your project node in Eclipse’s Project Explorer and invoke the New -> Seam Generate Entities menu option. This will trigger a new wizard that will automatically generate JPA entities for you, using the connection profile defined during project creation (see Figure 13). Not only that, but it will also create the basic maintenance web pages for each of the entities, saving you countless hours of repetitive work.

 
Figure 13. Generate Seam Entities Wizard: A new wizard automatically generates JPA entities for you, using the connection profile defined during project creation.

The wizard worked fine for the trivial data model I made for this example, but when I ran it across a production database with hundreds of tables, it consistently choked and escaped with an exception. It seemed to try to create entities for every single table in the database and did not allow me to specify which ones to include. However, if I had already created entity classes, it allowed me to select them before generating the related maintenance pages.

Fortunately, for these more complicated database schemas, I was able to use the Dali JPA tools that come with Eclipse IDE for Java EE to create the entities and then import them into my Seam project. However, I lost some of the extra code it generates (such as the default actions and maintenance web pages).

Also, the generated Seam JPA code had to be massaged by hand; I had to remove the questionable inclusion of the actual schema name in the JPA entity. For example, I preferred to replace this:

@[email protected](name = "author", catalog = "devx")public classAuthor implements java.io.Serializable 

With just a pure table-based annotation:

@[email protected](name = "author")public class Author implements java.io.Serializable 

I do not quite understand the logic behind including the database name in the actual annotation, as that is really a property of the database connection that the JPA entity manager is using. As such, I believe it does not belong in the actual code.

However, all of these concerns were more than satisfied when Seam generated a perfect set of search/edit pages for each of my JPA entities, complete with navigation and integrated validation. All that was left was to do some minor massaging of the HTML to correct the layout and replace the default labels with something more user-friendly.

Last but not least, the default Facelets template (located in WebContent/layout/template.xhtml) can be modified to change how the default links to each of the generated pages are displayed (see Figure 14).

 
Figure 14. A Generated Search/Edit Page for a JPA Entity: The default Facelets template (located in WebContent/layout/template.xhtml) can be modified.

Creating a New Conversation
Instead of simply auto-generating pages for your JPA entities, it is also possible to create your own Seam conversations (i.e., a web page flow spanning multiple pages but represented by a single backing JSF bean). This involves invoking the New Seam Conversation wizard and specifying the default settings (see Figure 15).

The wizard generates the basic JSF backing bean as well as the initial start page, ready for your customizations (see Figure 16). Please note, however, that it always places that page in the root web folder, so for large applications you may want to move it manually to a module-specific subfolder.


Figure 15. New Seam Conversation Wizard: Create your own Seam conversations by invoking the New Seam Conversation wizard and specifying the default settings.
 
Figure 16. Default Start Page Generated by the New Seam Conversation Wizard: The wizard generates the basic JSF backing bean as well as the initial start page.

Smooth Sailing After Rough Start
Although my initial JBoss Tools experience was anything but smooth (See Sidebar 2), after correcting my runtime settings everything started to work much better. In particular, the support for generating entities from JPA entities, integrated Ajax support in RichFaces, and Seam conversation functionality convinced me how productive one can be with this integrated combination of tools and frameworks. After spending months developing old school Struts actions and coding Ajax by hand on a recent project, it was truly a breath of fresh air.

Share the Post:
Share on facebook
Share on twitter
Share on linkedin

Overview

Recent Articles: