In this document we have gathered all the information which may be useful for upgrading your applications to JSF 2 while using RichFaces 3.3.3+. Please review it carefully before moving forward with migration because the support of JSF 2 is limited in 3.3.X version and these may effect your migration plans.  For complete JSF 2.0 support we recommend using the RichFaces 4.0.0 release which is still in development.

If you have a problem not listed here, or have found a workaround you want to share please use our forums here - RichFaces.

Project Settings

1) First of all we need to add libraries to the project:

Project without dependency management

1. Go to the download section at the richfaces-project site.
2. Download RichFaces 3.3.3.Final binary archive.
3. Replace old richfaces-* libraries with new ones from libs folder.
   1. There are two richfaces-impl jar's packed
   2. Add only richfaces-impl-jsf2 jar

Maven based Project

In a maven based project:

1. Update richfaces-ui dependency to 3.3.3.Final as normal.
2. Add the following dependency to get the JSF 2.0 version of the impl jar:

    <dependency>
      <groupId>org.richfaces.framework</groupId>
      <artifactId>richfaces-impl-jsf2</artifactId>
      <version>3.3.3.Final</version>
    </dependency>

This additional dependency is needed because we provide two implementation jars (one for jsf1.2 and one jsf 2 compatible) so richfaces-impl removed from transitive dependencies.

NOTE - if you had no richfaces-ui dependency in your project ( assuming api and impl transitively added), but had all three dependencies listed (ui, api and impl) - you should replace richfaces-impl with richfaces-impl-jsf2 mentioned above.

2) Turn off the VDL viewhandler with the following context-param in web.xml:

<context-param>
     <param-name>javax.faces.DISABLE_FACELET_JSF_VIEWHANDLER</param-name>
     <param-value>true</param-value>
</context-param>

If you want to view a sample application configured in this way - download richfaces-demo-jsf2 application.  You could also check three other sample JSF 2/RichFaces 3.3.3 applications which also use Weld and are targeted to Jboss 6 there

Photoalbum example on AS6

For instructions on running the photo album example on JBoss AS 6 with JSF 2 see Deploying Photo Album Example to JBoss AS 6 with JSF 2

Limitations List

We have always meant the 3.3.3 release to be a stepping stone for JSF 2 support. We needed to make a trade off between retro-fitting 3.3.X completely for JSF 2.0 ( a major undertaking ), or have limited JSF 2.0 support in 3.3.X and push forward with RichFaces 4.0 where we can really get the most out of JSF 2.0. This is one of the reasons that we are working so hard to get RichFaces 4.0 out.

For more details on the RichFaces JSF 2.0 roadmap see this blog - JSF 2.0 Roadmap For RichFaces

RichFaces 3.3.3 does not support JSF 2 built-in facelets (VDL)

Facelets 1.1.15 should still be used because of dependencies in RichFaces from the Tag Handlers classes.

JSF 2 native ajax problems

f:ajax

As RichFaces 3.3.3 does not supports VDL - it does not support any new tags like f:ajax, h:outputScript and so on.  You should continue to use the RichFaces equivalent tags where appropriate.

JSF ajax java script api

As JSF 2 currently does not provide a mechanism of cleaning Script objects for components removed by ajax - memory leaks could arise on updated RF components via JSF native ajax.  If you see memory issue this may be the cause.

JSR-303 support

JSF 2 does not register bean validators while running in compatibility mode (with VDL turned off and external facelets used.). This is not a RichFaces 3.3.3 limitation but should be considered during porting applications to JSF 2.

http://java.net/jira/browse/JAVASERVERFACES-1518 - issue at mojarra tracker.

Annotations Scanning

     During initialization JSF 2 ConfigManager checks for faces-config presence and looks if it's version is equals to 2.0. This means in order to get JSF annotations working with your existing application you should:

• have no faces-config in application
• or version of the application config should be changed to 2.0

Running on GlasshFish application server

Again not a RichFaces limitation but should be considered while moving application to JSF 2 and deploying WAR to GlassFish v3 server. Your application descriptor should be defined with version 2.5 like:

<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

If this is not done you may see "EJB module not found" errors during publish.

Using new JSF 2 new scopes and new Navigation features

We found no limitations using the new scopes and new features of JSF 2 navigation. It worked out of the box with the richfaces-demo environment. So please update us if something will arise on your side.

MyFaces specific integration problems

IllegalStateException while running MyFaces 2 - RichFaces 3.3.3

Originally reported at that forum thread (thanks Matthew!). Problem caused by myFaces handling of setViewHandler which is used by RichFaces initialization PhaseListener. So we created this issue in MyFaces jira and current workaround is to define AjaxViewHandler explicitly in faces-config:

<application>     <view-handler>org.ajax4jsf.application.AjaxViewHandler</view-handler></application>

and define the other viewHandlers by using context parameter like this if using facelets:

  <context-param>
       <param-name>org.ajax4jsf.VIEW_HANDLERS</param-name>
       <param-value>com.sun.facelets.FaceletViewHandler</param-value>
  </context-param>

and this if using JSP

  <context-param>
       <param-name>org.ajax4jsf.VIEW_HANDLERS</param-name>
       <param-value>org.apache.myfaces.application.jsp.JspViewHandlerImpl</param-value>
  </context-param>