Richfaces migration diaries

I always wanted to do this. I always wanted to write down a detailed description of the work I do. So, here’s the deal, my task was to migrate a web application running on RichFaces 3.X to RichFaces 4.X.

Simple and clean application running on JBoss 5. Just a couple of pages and quite many validations happening with JavaScript.

Replacing the RichFaces jars

So, I went about removing RichFaces 3.X jars and replaced them with the 4.X variants. The core framework and the component related bundles are :

  • richfaces-core-api-4.2.0.Final.jar
  • richfaces-core-impl-4.2.0.Final.jar
  • richfaces-components-api-4.2.0.Final.jar
  • richfaces-components-ui-4.2.0.Final.jar

If you are wondering the download it is.. These jars are dependent on the following ones too

  • guava-10.0.1.jar
  • cssparser-0.9.5.jar
  • sac-1.3.jar

Application Descriptor Change

There are quite a few things that should be looked into here..

  1. RichFaces 4 does not use Filter anymore. So, off with the <filter> and <filter-mapping> tags
  2. Removed the orj.ajax4jsf.VIEW_HANDLER context param

and so on.. the official guide does justice to the descriptor changes.

Upgrading JBoss

Once the libraries and descriptors are updated, I tried starting my server. Only to end up in an Exception. There seems to be an error in building the JSF tree.

Apparantly, JBoss 5 is not compatible with JSF 2.0 as said here. So, created a new server instance for JBoss 7.

Also, the JSF-impl.jar should be removed from the lib folder.

Components Missing

Finally, the server is up. Still, there is a long way to go. Lot of RF component had to go through upgrades and a few of them even phased out. Our application widely used one of them, the <rich:spacer>.

A custom spacer component had to be built to provide the effect. Here is how to do it using the resources framework of JSF 2.0.

Some more components had changes too.. here’s a quick outline of the rich componets.

  • <rich:toolBar> to <rich:toolbar>
  • <rich:toolBarGroup> to <rich:toolbarGroup>
  • <rich:modalPanel> to <rich:popupPanel>

It’s not limited to these.. the list for the most of the components can be found here

a4j components had changes too..

  • <a4j:support> to <a4j:ajax>
  • <a4j:actionparam> to <a4j:param>
  • <a4j:form> was done away with.. had to use <h:form> instead

The list of a4j component changes can be found here

Miscellanious changes in component properties

Most of the changes I needed was covered in the officail RichFaces migration document.

  • reRender was to be replaced by render
  • process replaced by execute
  • The ajaxSingle propery was taken away. So we user execute=”@this” instead

However, the official document had a few misgivings.. We have widely used the < rich:dropDownMenu > and a key property of this component is ‘direction’. Quite elementory, the property denotes which direction the dropdown opens up. I had used a ‘botton-right’ property for all the dropdowns in our application.

Somehow, the ‘bottom-right’ property value was throwing an error. After almost an hour of digging through several forums. I can’t seem to understand why they missed such a thing in their official documentation. The direction properties were renamed to topLeft, topRight, bottomLeft, bottomRight

See their documentation on the topic..

Another key feature they missed in the documentation is on the ‘data’ property of the <a4j:jsFunction>.

Should the data be passed to another method, it should be passed as ‘’.

For example :

<a4j:jsFunction name="callScript" data="#{bean.someProperty}" oncomplete="myScript(data)"/>
should be repalced with
<a4j:jsFunction name="callScript" data="#{bean.someProperty}" oncomplete="myScript("/>

Page looks all Jumbled ??

So finally, the component issues were resolved and the page finally loaded. But something’s missing. The buttons are not where they were supposed to be. The entire application looks a bit.. crazy.. It did not take long to find the reason.. certain styles were not getting loaded.

Adhering the JSF Standards

Well, I would not call this a richface migration challenge. But, my application pages were all using <head> tag instead of <h:head>. Now here’s the difference. While we use the <h:head> tag, it becomes part of the JSF Tree. Also, JSF uses the <h:head> as a hook to load the necessary js/css files as part of the HTML DOM <head>. Somehow, while using RichFaces 3.X (which does not fully utilize JSF 2 ), this worked. But moving onto JSF 2.0 and RichFaces 4, this fell apart. The styles and javaScripts were not getting loaded.

So, a simple change find all <head> and </head> and replace them with <h:head> and </h:head>

Missing Functionality

So the page’s up, and it looks how it is supposed to look. But there is one last problem. Certain functionalities are not working. Nothing breaks in the server end, and as it seems, it’s throwing up a script error. Certain methods does not seem to exist anymore.

The reason for such a behaviour was jQuery

Apparantly, RichFaces 3.X user jQuery 1.4 and RichFaces 4.X uses jQuery 1.7.

One of the striking changes I had to accomodate was to escape the colon character in the ID of and element.

$(‘parentForm:button’) works well with jQuery 1.4. However, when jQuery encounters a ‘:’ somewhere along the line, it’s expecting a JSON object value-key pair.

To get the desided effect, $(‘#parentForm\\:button’) has to be used.

That’s that.. everything seems well now..

Definitely there will be much more changes related to RichFaces and jQuery than this.. their official guide is a good start.

Composite Spacer Component for RichFaces 4

I have been working with richfaces 3.X.X and recently did a migration to richfaces 4.X.X. Many changes had to be done. Many tags got renamed, many properties suffered similar fate and some tags were retired.

<rich:spacer> was one among the many tags not supported in RF4. So, I though I would make a composite component to rectify the gap.

Well it’s a simple component which takes in two properties.

  1. Height
  2. Width

The component uses an image, a white plain image with the user defined height and width to build the spacer.

Well, basics in 5 seconds. A composite component has two parts.

  1. Interface – This denotes the component properties.
  2. Implementation – This denotes what the component does with the properties

So, our custom spacer component takes in the width and height as properties.

Without much adieu, here’s the code..


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">
<html xmlns=""
	<composite:attribute name="width" default="0" type="java.lang.Integer"/>
	<composite:attribute name="height" default="0" type="java.lang.Integer"/>

	<h:panelGroup rendered="#{cc.attrs.height > 0}">

	<h:graphicImage library="images" name="spacer.png" width="#{cc.attrs.width}px" height="#{cc.attrs.height}px" />

As we discussed, the height and width parameters are used as properties. Also, an image is used.

This is placed in a folder images withing the resources folder. We use the resources concept of JSF 2.0


The composite component is under the folder custom. So we have to add a namespace to access it.


Once the namespace is registered, the component can be used.

<custom:spacer height="5" width="100" ></arbcustom:spacer>

The component name will be same as that of the xhtml file.

JSF 2.0 Resources Concept

JSF 2.0 has introduced a wonderful concept for easy storage and easy retrieval of resources for a particular project.

The project resources like css stylesheets, images and JavaScripts can be stored under a folder named ‘resources’ in the root of the web application.

See the example below.


The resources can be accessed using the library keyword.

The above figure depicts the resources I used to create a custom spacer component.

The spacer.png file can be accessed via..

<h:graphicImage library="images" name="spacer.png" width="100px" height="100px" />

This is as easy as it gets. The folders immediately below the resources folder should be specified as the library property, and in the above case images.

This resource concept provides an easy mechanism to provide themes to the application. Consider the example below.


There are three different folders under resources..

  • Cobalt
  • Lime
  • Ruby

We have already seen that the folders immediately below the resources folder can be accessed via the library property. So, these three folders are libraries on their own. In other words themes.

Each theme is minimal and has only one image. Based on the theme selected, the image can be loaded ..

<h:graphicImage library="#{backingBean.theme}" name="images/bg_img.png" width="100px" height="100px" />