Migration JSF 1.2 – RF 3 to JSF 2.2 – RF 4 : How to save days of manual rewriting by automating the process


A few months ago, we made the migration of our JSF1.2/RichFaces 3.3 applications to the last versions JSF2.2/RichFaces 4.5. Replacing the old jars by the new ones and taking care of the configuration files was just not enough as in RF4.5 lots of xml tags and attributes were renamed or even removed.

So the migration consisted in rewriting arround 500 xhtml files with the new syntax… Faced with the scale of the task, we thought about an effortless way a bit more “computerized”… and so we wondered : Is there any technology capable of transcribe an xml file from one syntax to another ? XSL/XSLT of course !

Before diving into the subject, I am going to set the context back and explain why this migration was a necessity.

RichFacesSince 2009, we have been working on JavaEE business applications built with JSF 1.2. At that time to build a responsive dynamic page in AJAX we had to use RichFaces which is a framework upon JSF. RF especially offers a set of advanced UI skined components with AJAX capabilities (pop-up, sortable/filtered arrays with pagination). In the meantime, web browsers have evolved and also their javascript intepreter, and thus it broke some RF 3 ajax components. It became really annoying regarding to our business extranets. To get back a full compatibility with all the web browsers, we had to migrate from RF 3 to RF 4, which implied as a consequence to ugrade from JSF 1.2 to JSF 2.2.

The main work was to set down the transformation rules thanks to the migration guides provided by RF :

Here after is the XSLT files we built :

XSL makes possible simple renamings as well as more complex ones involving tests and regular expressions. Here after are some examples :

The modalPanel tag becomes popupPanel and showWhenRendered attribute of modalPanel becomes show

ajaxSingle attribute becomes execute=”@this” if the current tag haven’t got any execute attribute, else it is removed

value attribute of graphicImage is transformed into 3 attributes : library, name and alt

The value of event attribute must not be prefixed with “on” any more : onclick -> click

The json data data is now got back with syntax into oncomplete and not anymore with the data keyword

All the rules set down end-to-end make it possible to obtain something like :



N.B : The RichFaces migration guides takes an inventory of ~80% of the transformation rules, the 20% left has been added regarding to the tests.

To execute these transformations, we have simply built a classical java project under Eclipse in the same workspace as the project to migrate.


We use the Saxon library as the XSLT engine (especially to take advantage of the string replacement functions offers by XSL 2). So that means this jar is in the BuildPath of the project.

The Main Class makes all the job :

The constants indicates where the project to migrate is and where the libs, css and xhtml files inside the projet are.

  1. Remove old jars and copy the new ones (Yes, we don’t use Maven it might be the subject of a future post : How to successfully perform a migration to Maven ;) )
  2. css Transformations
  3. xhtml Transformations
    The script scans all the folders starting from WebContent
    Copy the original file and prefixed it with “old_”
    Apply the transformation onto “old_” file and write the result in the original file
    Thanks to this technique you can modify the xsl and then relaunch as many time as you want the script

The 2nd step of the algorithm consists in rewriting the Richfaces CSS class that we overloaded.

Using a properties files which lists all the transformation, we apply the java replaceAll function onto each line of each css file.


In addition to all these automatisms, we also used the good old CTRL+H of eclipse to apply massively these replacements :

Richfaces.showModalPanel and Richfaces.hideModalPanel doesn’t exist anymore

Search: Richfaces.(hide|show)ModalPanel(‘([a-zA-Z0-9#{}]*)’)
Replace by : #{rich:component(‘$2′)}.$1()

Search : Richfaces.(hide|show)ModalPanel(‘([a-zA-Z0-9#{}]*)’)
Replace by : #{rich:component(‘$2′)}.$1()


Voilà ! Thanks to a java program and XSL/XSLT, we were able to automate the migration of our Richfaces projets ! :)

Of course, once the transformations are made, you need to set up the xml configuration file to match the JSF 2 specifications :

  • web.xml
  • faces-config.xml

(Here after is a useful link on that subject : stackoverflow)

At Last, you will have to test your application ! Keep in mind that this is not a magical migration technique, but at least it makes you get rid of the repetitive tasks to focus on resolving issues specific to the JSF 1.2 > JSF 2.2 upgrade. If you are starting with JSF2 and RF4, you will probably face some surprises depending on the JSF implementation you use :

  • the scope of ui:param in facelets is different
  • f:setPropertyActionListener is not allowed any more in a4j:support
  • the way columnClasses are applied on a dataTable whose columns are hidden/shown
  • some overloads of some Richfaces components doesn’t work anymore

In case of issues, the Richfaces forum is really helpful. But, they will be more disposed to answer you with a minimal code example, tested on the last release…

See you soon for the next post!

  1. R.Hawkins

    Hi there. Thanks for this example on how to automate migration from JSF 1 to JSF 2. Are you able to provide your source code for the other three java classes as well? Thanks.

  2. Federico Moglia

    Hi! You are made a great job! Is the complete project available for download? I will really appreciate it if you post the link here.
    Thanks, regards!

Leave Comment

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">

clear formSubmit