Seam Tutorial 1.1: RichFaces and paged table (datascroller)

In this two-part tutorial you will learn how to get started with the development of Seam applications with RichFaces using Eclipse with JBoss Tools. In the 2^nd part we will create a simple page with a table presenting data on multiple pages using Ajax and its model stored as a POJO Component in the Seam Conversation scope. I assume that you already have some basic knowledge of Seam and JSF, for instance that you know what a Component or the Conversation scope are.

My aim in this tutorial series is to create a Seam portlet displaying data in a paged (and ideally also sortable and filterable, but let's be realistic) table running in the Liferay portal. The tutorial will follow my steps with all the dead ends and mistakes so that you too can learn from them.

Why Seam?

In my opinion, Seam is one of the best application frameworks for Java web application development. It's not the best one because none is and it always depends on the task at hand what solution/tool is the most suitable one. I like Seam because it integrates so well some of the most popular and standard or de facto standard technologies (all of them are optional in a Seam application) including JSF, EJB 3.0, JPA, and Hibernate. Not only does it integrate them but also fixes their shortcomings (especially in JSF) and adds invaluable features you've been looking for for ages, like the conversation scope, eventing, or runtime component injection.

Why RichFaces?

The answer is simple: go to see the RichFaces demo :-). RichFaces is a library of good-looking, dynamic (Ajax) JSF components and support for ajaxifying just about anything. With RichFaces you can easily create Web 2.0 applications with a professional look and feel that let users forget that they're working in a browser with a remote server. You can use context menus, modal dialogs, sortable, filterable, and pageable tables, rich text editor, cool visual effects, and more.

RichFaces isn't the only such library, another popular one is ICEfaces, which has been embraced by Sun. But RichFaces is supported by JBoss and works well with its server, portal, and Seam. Remember I told you Seam is an integration framework?

Why Liferay portal?

Though developing portlet applications is considerably more difficult than plain old web applications as has been discussed recently and as we will certainly yet see, there are also the benefits of content integration, unified front-end to applications etc. that sometimes outweigh the problems.

I use Liferay because that's the portal chosen (for the majority that can't afford WebSphere Portal) by the bright guys in the portal group of my company, IBA CZ. And also because, as a user, I find it more appealing than JBoss Portal.

Environment setup

You will need the software listed below. Make sure to have the same versions or  unexpected problems may happen (examples later).

• JBoss Portal 2.7.1 (with bundled JBoss AS 4.2.3)

• JDK 1.5 (mine is jdk1.5.0_17 )

• Seam 2.0.2 SP1 (I've preferred this to the latest 2.1.1 GA as it works better with JBoss Tools)It's already bundled with RichFaces, no separate download of them needed.

  • Check the unpacked folder - there most interesting things are the documentation example applications.
    
• Eclipse Ganymede for Java EE v. 3.4.1 (SR1) though you can prefer to try your luck with the latest one (3.4.2 as of today).
  

• JBoss Tools as of 2008-12-19 - Seam Tools and JBoss Tools RichFaces 3.0.0 CR1-R200, JBossAS Tools 2.0.0 CR1-R200, JBoss Portlet 1.0.0 CR1-R200, plus some others. I've installed them via Eclipse Update Manager (Help > Software Updates) from the update site http://download.jboss.org/jbosstools/updates/development/ Today it contains an updated version CR2 from 2009-01-28. You can install an older version after unchecking "Show only the latest versions ..."
  

For the sake of completeness I should say that I'm developing under Linux, namely Ubuntu 8.04 Hardy.

I won't describe how to install Eclipse and JBoss Tools, you'll surely manage that :-). The other items you can just download and unpack somewhere. for example to /tmp/tutorial/.

Eclipse preparation

After having installed Eclipse and its JBoss Tools plugins:

1. Let Eclipse know about the JDK 1.5: Window > Preferences > Java > Installed JREs > Add... > Standard VM > enter path to the unpacked JDK etc.
   Name it “jholy-jdk1.5.0_17” (sorry, I was lazy to rename mine for this tutorial).

2. Let Eclipse know about the JBoss server: Window > Preferences > Server > Runtime Environments > Add... > select JBoss, a division of Red-Hat – JBoss 4.2 runtime, ..., browse to/enter the directory where you unpacked JBoss to (/tmp/tutorial/jboss-portal-2.7.1/), and make sure select the previously defined JRE (JDK) 1.5. "jholy-jdk1.5.0_17".
   Name it “JBoss 4.2.3 Runtime and Portal 2.7.1”.

Creating the project

Create the project: File > New > Project > Seam > Seam Web Project

• Project name: seamTutorial1
  Note: Seam requires the project name to start with a lower-case letter.

• Target Runtime: JBoss 4.2.3 Runtime and Portal 2.7.1

• Dynamic Web Module Version: 2.5

• Target Server: click New > select JBoss AS 4.2, enter Server name JBoss_4.2.3, select the recently defined Server runtime environment JBoss 4.2.3 Runtime and Portal 2.7.1, click Next >, enter Name JBoss_4.2.3, Next, Finish.

• Configuration: select Dynamic Web Project with Seam 2.0 (and not the default 1.2).
  

Click Next, don't modify anything

Click Next, don't modify anything

Click Next to get to the Seam Facet page:

• Seam Runtime: click Add..., browse to the directory where you unpacked Seam to (/tmp/tutorial/jboss-seam-2.0.2.SP1/), give it the name jboss-seam-2.0.2.SP1 and set version to 2.0.

• Deploy as: WAR

• Database

  • Database Type: Derby

  • Connection profile: click New... > select Derby, enter Name SeamTutorial1Derby, Next >, from Drivers select “Derby Embedded JDBC Driver 10.2 Default” (if you haven't it there, download it and add it via the small (+) icon), enter a non-existent folder as the Database location (e.g. /tmp/tutorial/SeamTutorial1Derby), User name sa, leave the password empty

    • Test Connection. This will fail if the database location folder already exists otherwise it says Ping succeeded!

    • Finish the connection profile creation.
      

• Leave the other fields as they are and click Finish to finish the new Seam project wizard.
  

Two new projects are created: seamTutorial1 and seamTutorial1-test. The project seamTutorial1 contains quite a handful of files:

Open the Seam perspective: Window > Open > Other... > Seam. This gives you some useful views, including Seam Components (shows name, scope) and (for page development) JBoss Tools Palette. I'd recommend you to open also JBoss Server View to view and manage your JBoss and Tomcat servers.

Running the generated application

Attempt 1:

• Right-click on the file seamTutorial1/WebContent/home.xhtml > Run As > Run on Server > select Choose an existing server and select the previously defined JBoss_4.2.3.

• Click Next, you should see the page Add and Remove Projects with the Configured projects seamTutorial1/resources/seamTutorial1-ds.xml and seamTutorial1, click Finish.

• There may be the warning “The connection was refused when attempting to contact localhost:8080”. That's nothing to worry about, the browser is just faster than the server.

• A Console view should pop up where you can see the log of the starting JBoss application server.

  • If you see there errors similar to
    UnsupportedOperationException: setProperty must be overridden by all subclasses of SOAPMessage.
    then you haven't been attentive enough and are running the server with Java 1.6 instead of 1.5. Either switch to 1.5 or read the release notes of JBoss to learn how to fix this.

  • You may see there
    IllegalArgumentException: Exception setting property org.jboss.seam.core.init.jndiPattern on component org.jboss.seam.core.init. Expression @jndiPattern@ evaluated to null.

    • Seam applications are prepared for being deployed by Ant, which would replace the token @jndiPattern@ in components.xml with a correct value. Unfortunately this version of JBoss Tools forgets to do it so you must do it manually.

    • Replace the token @jndiPattern@ in components.xml with a valid expression, for example #{ejbName}/local. See Seam reference, chapter 26.1.5. Integrating Seam with your EJB container.
      Or better change the project's build path to WebContent/WEB-INF/classes to get this token replaced with a valid value automatically, see the update from 2009-03-23 at the end of this post.
      

Attempt 2:

• Start the application as before. It may take over 7 minutes, get a cup of tee. You might notice in the Console view that Seam prints name, scope, and type of each installed component. The interesting lines there are:
  INFO [Server] JBoss (MX MicroKernel) [4.2.3.GA (build: SVNTag=JBoss_4_2_3_GA date=200807181417)] Started in 4m:45s:459ms
  ...
  INFO [TomcatDeployer] deploy, ctxPath=/seamTutorial1, warUrl=...
  INFO [ServletContextListener] Welcome to Seam 2.0.2.SP1
  ...
  INFO [SeamFilter] Initializing filter: org.jboss.seam.debug.hotDeployFilter (the last line)
  

• Enter the address http://localhost:8080/seamTutorial1 to your browser. It may take a couple of minutes to load.

Request for feedback

If you find anything inaccurate or not enough clear in this tutorial or if you encounter some other problems that you would like to share with others to help them avoid these, please let me know. Make the continuous improvement through collaboration possible :-).

Summary

We have set up a Seam development environment, overcame some problems, and managed to get a simple application running.

In the next part we will develop our own conversation-scope Component and a page with a RichFaces paged table.

Update 2009-03-23

Replacing  @jndiPattern@ with a valid value in the correct way

During the first deploy we've got the following error:

IllegalArgumentException: Exception setting property org.jboss.seam.core.init.jndiPattern on component org.jboss.seam.core.init. Expression @jndiPattern@ evaluated to null.

As Dan Allen has pointed out, the token @jndiPattern@ should be replaced by Seam in runtime using the property jndiPatter from components.properties. And actually this property is defined in the project's src/main/components.properties as jndiPattern=\#{ejbName}/local ('\' tells the properties that the # isn't a comment start). So why it doesn't replace the token? It turns out that the project has its compile path set incorrectly and a likely side effect is that this file isn't deployed to the server.

To fix it, In Project > Properties > Java Build Path > Source change the Default output folder from seamTutorial1/build/classes to seamTutorial1/WebContent/WEB-INF/classes. After a redeployment, everything is suddenly working.

By the way I really recommend you reading Allen's article about improving Seam application performance.

Tags: library