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 location..here 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 ‘event.data’.

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(event.data)"/>

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.