Brian Leonard's Blog

Trying out JBoss' Seam

JBoss does a nice job of documenting their sample registration Seam application. To really help you learn the framework, including its benefits, I thought I walk you through the steps required to port a standard JSF / EJB 3.0 application to one that uses the Seam framework. To be consistent with JBoss' example, I've rewritten the registration application using standard JSF / EJB 3.0. Now let's port it back :-).

Getting Started

• Download and install the NetBeans 5.5 Beta.
• Download and install JBoss 4.0.4. During installation, be sure to select the ejb3 profile.
• Download and extract JBoss Seam 1.0.0.CR3 (this is important, CR2 doesn't work with JBoss 4.0.4 GA)
• Download and extract the Registration application.

Step 1: Add the JBoss Server to NetBeans

1. Switch to the Runtime tab and right-click the Servers node to add a server.
   
   
   
   
2. Select JBoss Application Server 4 from the Server drop down list. Change the name to JBoss Application Server 4.0.4.
   
   
   
   
3. Complete the Add Server wizard.
4. Stop the Sun Java System Application Server if it is running (both servers use http port 8080 as their default).
5. Right-click the new JBoss server node and choose Start:
   
   

Step 2: Open the Registration Project

The Registration application is a NetBeans Enterprise Application Project, which is actually comprised of 3 projects: Registration, Registration-EJBModule and Registration-WebModule. Registraiton-EJBModule and Registration-WebModule are J2EE Modules of the Registration project. Registration-EJBModule generates the EJB jar file. Registration-WebModule generates the war file and Registration generates the ear file which contains the jar and war.

1. Open the Registration project. The Enterprise Application Project stores the absolute location to its J2EE Modules. So, unless you extracted your project to the exact same location as me, you will see this dialog when you open the project.




2. Click Close. The Registration project will be in bold red.
3. Right click the project and select Resolve Reference Problems from the context menu.
   
   
   
   
4. Use the Resolve Reference Problems dialog to map each module to its project, which you'll find are subdirectories beneath the Registration directory.
   
   
5. After the references are resolved, right-click the Registration project and select Open Required Projects (now that the dependencies are correct, these dependent projects will always open for you).
   
   
   
   
6. You'll notice the Registration-WebModule also has a reference problem, as it references the Registration-EJBModule. Use the same steps to correct the reference.

Step 3: Test Run the Registration Project

Remember, this is a standard JSF / EJB 3.0 project. Verify that it works before trying to use the Seam framework.

1. Press F6 to run the project. This will build, package, deploy, start JBoss and launch the application in a browser for you.
   
   
   
   It's a simple application, but it will demonstrate a lot of the functionality provided by the Seam framework, such as:
   • Elimination of the Managed Bean - we will be able to completely eliminate our managed bean. Our web module will no longer contain any java files.
   • Validation - the 3 fields above are required. Also, Username and Password require and entry between 5 and 15 characters. We'll be able to specify these requirements in our entity class, rather then in our JSP.
   • Additional Seam Components - such as a convenience class for providing messaging back to the user.

Step 4: Add and Integrate the Seam Framework Into Your Project

In this step we're only going to integrate the required Seam components so that we can begin using the framework. We won't actually start using Seam until the next step. If NetBeans had direct support for the Seam framework, this is the stuff you'd expect the IDE to do for you.

Create the Seam Library

1. Open the Library Manager (Tools menu) and create a new library called JBossSeam.
2. Set the Classpath to jboss-seam.jar.
3. Set the Sources to the JBoss Seam src directory.
4. Set the Javadoc to the JBoss Seam doc directory.

This library is now available for use by any project.

Add the Seam Library to Your Project

1. Right-click the Libraries node of the Registration-EJBModule project and choose Add Library.
2. Add the JBossSeam library to the project.

Configure web.xml

1. In the Registration-WebModule, open web.xml (under Configuration Files)
2. Remove the javax.faces.CONFIG_FILES context parameter to work around a bug in MyFaces. You can read all the gory details here.
3. Add the following Context Parameter:
        Param Name: org.jboss.seam.core.init.jndiPattern
        Param Value: registration/#{ejbName}/local
   
        
   
   Seam is going to bind your JSF action directly to a session bean, and it needs this pattern to do the JNDI lookup on your behalf. registration is the name of the ear file, so that would need to change accordingly for each application.
   
   
4. Add the following Web Application Listener: org.jboss.seam.servlet.SeamListener.
   
   
   

Configure faces-config.xml

1. Open faces-config.xml and add the following phase listener:
   
   

   <faces-config ...
   
   
       <lifecycle>
           <phase-listener>org.jboss.seam.jsf.SeamPhaseListener</phase-listener>          
       </lifecycle>
   </faces-config>
   

Add the Seam.properties file
It's interesting, the seam.properties file is empty, but Seam will not work without it.

1. Press Ctrl+N to create a new file. Make sure Registration-EJBModule is selected as the project and select the Other Category > Properties File File Type.
2. Name the file seam and put it in the src\conf Folder.

Unfortunately, the Seam framework expects to find this file in the root of the EJB jar file and not in the META-INF directory, so we have to create a custom Ant target to put it there.

1. Switch to the Files tab and open Registration-EJBModule's build.xml.
2. Add the following target:
   
   

   <target name="-pre-compile">
       <copy file="${meta.inf}/seam.properties" todir="${build.dir}/ear-module"/>
   </target> 

Configure ejb-jar.xml

1. Add the following assembly descriptor to ejb-jar.xml:
   
   

      <assembly-descriptor>
         <interceptor-binding>
            <ejb-name>*</ejb-name>
            <interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
         </interceptor-binding>
      </assembly-descriptor>

   The SeamInterceptor integrates Seam with the Session Beans.

Test Your Changes
We haven't actually done anything with Seam, but we want to make sure our app still runs and we'll use the log to verify Sean was loaded successfully.

1. Press F6 to run the project. The registration application should still run successfully and you should see an entry like the following in the JBoss log file.
   
   2006-05-24 19:13:27,968 INFO [javax.servlet.ServletContextListener] Welcome to Seam 1.0.0.CR3
   

Step 5: Eliminating Your Managed Bean

Mapping Directly to the Entity Class
In this section we're going to inject our JSF context variables directly into our entity class, which will allow us to eliminate the managed bean. If we look at our faces-config.xml, our managed bean is named "user" and has a "request" scope.

With Seam, we're going to provide this configuration information directly in our entity class, using annotations.

1. Open User.java and add 2 new annotations: @Name("user") and @Scope(ScopeType.EVENT)
   
   
   
   The SeamListener will now map the JSF "user" context variable directly to our entity class, bypassing our managed bean, and set the scope of the context variable to request.

Mapping Directly to the Action Class
Currently, JSF calls our managed bean which in turn calls our action class. If we give our action class a name, we can bind to it directly from JSF, like we did above with the entity class.

1. Open RegisterAction.java and add a Name annotation: @Name("register")
   
   
   
2. Open register.jsp and change the action on the command button from user.register (the call to our managed bean) to register.register (the call directly to our action class).
   
   
   

Now, action methods in JSF cannot take any arguments, which was true of the register method in our managed bean, but not the case with the register method in our action class.

To get past this problem, we'll use another Seam feature, bijection (because it's bidirectional), to inject the User context object above into our action class.

1. Add a user field to RegisterAction.java, annotated with @In, as follows:
   
   
   
2. Then remove the arguments from the register method and pull the necessary values from the injected user field. Your updated method should look as follows:
   
   
   Also notice the convenience class FacesMessages that allows me to easily add a templated error message. This is one of the built-in Seam components that streamlines development.
   
   
3. Don't forget to update the register method signature in the RegisterActionLocal interface.

Delete the Managed Bean
Are you ready?

1. Delete the managed bean, BackingBean.java (yes, it's ok, you can do it).
   
   
2. Delete the managed-bean entry from faces-config.xml. Otherwise, the faces servlet will fail trying to load the managed bean we just deleted.

Step 6: Test Our Seam Managed Application

1. Press F6 to run the application. It should behave exactly as before, yet under the covers, it's now using Seam.
   
   Here's the completed application. You'll have to reslove the same reference problems as you did above.

Next Steps

I'd also like to use Seam to handle validation as well as page navigation. However, this blog entry has grown longer than I expected. Stay tuned for an additional entry covering these Seam features.

Comments

• How does seam map the form fields to the entity properties? What if there are multiple objects related to the fields that are on the form? How does it know what fields go with what objects?

  Posted by: rcollette on May 26, 2006 at 10:10 AM

• It's not really that different from what standard JSF does today. The SeamListener just binds the fields to the getters and setters on the enity class rather then the backing bean. Actually, since the entity class is just a POJO, you can do this with straight JSF today. To me, the real power with Seam is its ability to instantiate the session bean and inject it with the context object.

  Posted by: bleonard on May 26, 2006 at 11:16 AM

• Thank you for this very interesting blog!
  I was trying to work with Seam and Netbeans for a few days but i couldn't get out of all the messy configuration files!
  I'm waiting for the next steps

  Posted by: heulin on May 29, 2006 at 08:44 AM

• I tried this example with the latest version of jboss (4.0.4GA) and Seam (1.0.1GA)... and it throws an exception. Does anyone else get this exception?

  Posted by: paradimgza on June 28, 2006 at 12:33 AM

• If you are using Seam 1.0.0 GA or 1.0.1 GA, you need to also upgrade your ejb3 container to RC8. Installation instructions are included in the download. Alternatively, you can use the JEMS 1.2.0.BETA1 installer, which already contains the proper ejb3 container.

  Posted by: bleonard on June 28, 2006 at 05:12 AM

• I pulled the JBoss-Seam over from Source Forge and deployed the Registration demo on JBoss 4.0.4 GA. It was using Seam 1.0.0 CR2. It works great. I just saw comments on the web that Seam 1.0.1 GA does not work in JBoss 4.0.4 GA.
  

  Posted by: gschneider on July 11, 2006 at 09:09 AM

• Hi Brian,

  First of all Thanks for the tutorial..I am trying to set up the helloworld remoting app in NetBeans5.5 Dev version.

  How ever when i tried to point my browser to the URL

  http://localhost:8080/MySeamTest-war/index.html i am getting the Save as popup saving that you are trying to open a SEAM File..

  It seems the the servlet mapping is not getting picked up..

  Thanks
  Sateesh

  Posted by: klsateesh on July 31, 2006 at 08:06 AM

• Hi Sateesh,

  The helloworld remoting application uses Facelets, so you also need to set up the view handler in faces-config.xml as follows:

  
  <application>
  <view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
  </application>

  
  You'll also need to add the Facelets jars (jsf-facelets.jar, el-api.jar and el-ri.jar) to the web modules libraries.

  Good Luck, Brian

  Posted by: bleonard on August 07, 2006 at 12:50 PM

• Hello, I've used suggested envirnoment, but error occured after adding annonations in User.java file ( cannot find symbol , class Name) . Also same error apear after editnig other annonations in RegisterActionBean.java). Until Step 5: Eliminating Your Managed Bean, I was able to run and test. Thank you.

  Posted by: darioj on September 04, 2006 at 03:40 AM

• It sounds like your MDR might be corrupt. Try this:

  Choose Help > About > Detail tab and note your User Dir.
  Under that directory you'll find a ./var/cache/mdrstorage directory. Delete the mdrstorage directory and restart NetBeans.
  

  Posted by: bleonard on February 12, 2007 at 11:50 PM

• can this example be done in Tomcat 6.0? what is there to look for when doing it in Tomcat ?

  Posted by: hsalameh on February 26, 2007 at 12:16 AM

• oh... i forget to say, using NB 6.0...

  Posted by: hsalameh on February 26, 2007 at 12:18 AM

• Yes, using Seam 1.1, this example can be run on Tomcat. The article, JBoss Seam for J2EE Developers II: Examples and Configurations describes the steps necessary to configure Seam 1.1 for Tomcat. Good luck, Brian

  Posted by: bleonard on February 27, 2007 at 10:55 AM

• This is great tutorial. I have question. Does anyone have to manually copy Registration-WebModule.war into jboss deploy dir every time in order to successfully run the application? I examed registration.ear file, it has already included the .war file.

  Posted by: bigeyejenny on April 18, 2007 at 03:12 PM

• hi,
  I am trying to run this example .
  I get the following error when I press F6

  D:\Registration\Registration\Registration-ejb\src\java\org\examples\registration\RegisterActionBean.java:6: package javax.faces.application does not exist

  How to resolve it.
  Thanks,
  Mintara

  Posted by: mintara on September 16, 2007 at 03:51 AM

• Hi Mintara,

  Since so much has changed since this example was written, I recently posted an update: Seam Refresh. I hope that helps.

  /Brian

  Posted by: bleonard on September 16, 2007 at 10:28 AM

• Thanks, I was looking for what u have written here

  Posted by: saurabhjuneja82 on October 10, 2007 at 10:48 PM

• Step-by-Step Tutorial: Achieve Rapid Application Development with Seam+Eclipse+Tomcat

  
  I wrote a step-by-step screencast tutorial to make Seam development as RAD - Rapid Application Development with Eclipse and Tomcat, focusing on developer productivity.

  
  http://techieexchange.wordpress.com/2007/11/11/rad-seam-development-with-eclipse-and-tomcat-step-by-step-tutorial-screencast

  I hope this tutorial will be useful for J2EE/JEE developers.

  Posted by: techieexchange on November 13, 2007 at 10:58 AM

This work is licensed under a Creative Commons License.