Send your remarks, comments or wishes to doc team
Subject:
Message:
Your name:
Your email:

JBoss.org Community Documentation

# RichFaces Migration Guide

### Gleb Galkin

`<ggalkin@exadel.com>`

Copyright © 2008 Red Hat

Last published: January 13, 2009

PDF version

## Chapter 1. Introduction

This document is aimed to provide guidelines for migrating RichFaces projects.

RichFaces Migration Guide covers troublesome issues caused by migration and provides suitable workarounds and examples.

## Chapter 2. Scope of the document

- This document should not be used as a tutorial for RichFaces framework since it is created to describe the issues caused by migration process

- It is assumed that you are familiar with basic tenets of RichFaces framework. If you are newbie in RichFaces you can find RichFaces documentation here.

- Concepts related to Web or application servers configuration, JSF, JSF implementations are beyond the scope of this document

## Chapter 3. Minimum requirements for the project with RichFaces 3.2.0

You can find all technical requirements to start working with RichFaces in the Developer Guide.

## Chapter 4. The RichFaces Migration Issues 3.1.x - 3.2.0

This chapter includes only those issues that concern migration from from 3.1.x versions to 3.2.0. Issues, related to the new components and other problems are not covered here. However, Jira contains all issues and if you can not find your case there, please, feel free to report it.

## 4.1. Most important issues

Migrating to RichFaces 3.2.0 you can encounter with malfunction of the components caused by a number of reasons. However, most of the problems can be positively solved. This section covers the most significant issues you can potentially encounter, providing ways to handle the cases.

### 4.1.1. non-ASCII characters in application with i18n

#### 4.1.1.1. Description

An application with i18n does not work correctly due to the validation error that occurs when non-ASCII characters are used.

#### 4.1.1.2. Links

- Jira

- RichFaces Forum

#### 4.1.1.3. How to reproduce

    ...

    <select id="j_id27:cbxUser" name="j_id27:cbxUser" size="1" style="width:120px">

            <option value="Al Korbeli& #269;o">Al Korbeli& #269;o</option>

            <option value="Al Nagyov& aacute;">Al Nagyov& aacute;</option>

            <option value="Al Tothov& aacute;">Al Tothov& aacute;</option>

            <option value="An Gajdov& aacute;">An Gajdov& aacute;</option>

            ...

    </select>

    ...

#### 4.1.1.4. Causes

Bug is caused by the<rich:fileUpload> component

#### 4.1.1.5. Workarounds

You need to update to RichFaces 3.2.0 SP1

### 4.1.2. Menu components and JSF-RI-1.2_08

#### 4.1.2.1. Description

Menu components do not work with JSF-RI-1.2_08:

- The <rich:contextMenu> component is not invoked by the right mouse click

- The <rich:dropDownMenu> component causes the exception, displaying a XHTML invalid output message

#### 4.1.2.2. Links

- JavaServer Faces issues

- Jira

- RichFaces Forum

#### 4.1.2.3. How to reproduce

The described above problems occur if JSF-RI 1.2_08 and menu components are used on a page

#### 4.1.2.4. Causes

It is a critical bug in JSF-RI 1.2_08 which has been already fixed in the further releases.

#### 4.1.2.5. Workarounds

Upgrade to JSF-RI 1.2_09 or above

### 4.1.3. Binding problem in JSP

#### 4.1.3.1. Description

Binding does not work for all components in JSP: it is impossible to use the"binding" attribute for RichFaces components, since wrong class-name is used in TLD generated from XML configuration files.

#### 4.1.3.2. Links

- Jira

- RichFaces Forum

#### 4.1.3.3. How to reproduce

The described above problem occurs if binding attribute is used with RichFaces components.

#### 4.1.3.4. Causes

There was a wrong `<classname>java.lang.String</classname>` specified instead of `<classname>javax.faces.component.UIComponent</classname>` in configuration files.

#### 4.1.3.5. Workarounds

The solution is to use Facelets upgrade to RichFaces 3.2.0 SP1

### 4.1.4. Ajax requests in JSF 1.2

#### 4.1.4.1. Description

Ajax requests stop to work without any errors messages displayed, when intensive Ajax traffic is expected. No errors or other messages to detect cause of the defect are shown.

#### 4.1.4.2. How to reproduce

The described above problem occurs if an id for Ajax command component is not defined.

    ...

     <h:form>

        <h:panelGrid columns="2">

            <h:inputText id="myinput" value="#{userBean.name}">

                <a4j:support event="onkeyup" reRender="outtext" />

            </h:inputText>

            <h:outputText id="outtext" value="#{userBean.name}" />

        </h:panelGrid>

     </h:form>

    ...

#### 4.1.4.3. Causes

The problem occurred due to specific usage of the dynamic id generation implementing JSF 1.2. In case of simultaneous request processing, the id of the command component becomes out-of-sync with id of the same component on the page. After that any Ajax requests of the component with old id is not processed.

#### 4.1.4.4. Workarounds

You should define the id for the command component and parent namespace components (<h:form>, <f:subview>, <h:dataTable> and so on) explicitly. As soon as this is a core JSF 1.2 functionality, the problem cannot be solved on the RichFaces level.

### 4.1.5. Resources for standard skinning classes

#### 4.1.5.1. Description

When standard skinning classes or background images are inaccessible `"Resource not registered : org.richfaces.renderkit.html.images.InputBackgroundImage"` (another name is possible) exception appears in server log.

#### 4.1.5.2. Links

- Jira

- RichFaces Forum

#### 4.1.5.3. How to reproduce

The described above problem usually occurs after server restart when user refreshes the page

#### 4.1.5.4. Causes

The problem is caused when resources for standard skinning classes are not available to be registered during RichFaces library build

#### 4.1.5.5. Workarounds

Switch off standard skinning classes by setting initial parameter in web.xml:

    ...

    <context-param>

        <param-name>org.richfaces.CONTROL_SKINNING_CLASSES</param-name>

        <param-value>disable</param-value>

    </context-param>

    ...

Add META-INF/resources-config.xml to the application classpath.

## 4.2. Issues with upgrading from previous versions

This section covers issues you can encounter upgrading to RichFaces 3.2.0 from previous versions.

### 4.2.1. <rich:calendar> and "ondateselected" event problem

#### 4.2.1.1. Description

The <rich:calendar> date selected event is fired before input update.

If time and apply elements are added to the calendar, "ondateselected" gets fired when a date is selected but before it's updated in input. Now we have three events instead of one. But it causes compatibility problem because this event was used by customers to save selected value via Ajax.

#### 4.2.1.2. Links

- RichFaces Forum

#### 4.2.1.3. How to reproduce

The described above problem occurs when <a4j:support>is put inside <rich:calendar>. If the "event" property is set to "ondateselected" previous value of the <rich:calendar> is stored after selection.

#### 4.2.1.4. Causes

Events firing sequence was changed.

#### 4.2.1.5. Workarounds

You need "onchanged" event to be fired after any change which causes input to be updated, both date and time.

Note, that

- "ondateselected" event is fired after a date is selected in popup

- "ontimechanged" event is fired after new time is selected.

### 4.2.2. Paired <rich:datascroller> components do not work

#### 4.2.2.1. Description

Two <rich:datascroller> components bound to the same table aren't synchronized. Having two <rich:datascroller>components on a page, session-scoped beans saves the data for only one <rich:datascroller> component. It is a common pattern to have 2 <rich:datascroller> components: the first in the header, the second in the footer. In this case the first one will not work.

#### 4.2.2.2. Links

- Jira

- RichFaces Forum

#### 4.2.2.3. How to reproduce

The described above problem occurs if two <rich:datascroller> components are added to any table.

#### 4.2.2.4. Causes

The <rich:datascroller> component does not manage the scroll state of a data table.

#### 4.2.2.5. Workarounds

The solution is to use "page" attribute and bind it to the same property for all <rich:datascroller> components.

### 4.2.3. Static "for" attribute in <rich:datascroller>

#### 4.2.3.1. Description

The "for"attribute of <rich:datascroller> component doesn't allow EL expressions in 3.2.0.GA.

Custom tags exploiting the ability of the <rich:datascroller> to have dynamic "for" attribute doesn't work.

#### 4.2.3.2. Links

- Jira

#### 4.2.3.3. How to reproduce

The described above problem occurs if the following code is used:

    ...

    <rich:datascroller for="#{bean.property}"/>

    ...

#### 4.2.3.4. Causes

Please, see Jira

#### 4.2.3.5. Workarounds

None, so far.

### 4.2.4. The ajaxSingle/region components in facets of <h:dataTable>

#### 4.2.4.1. Description

The RichFaces components that have "ajaxSingle" set to "true" does not work in "header" or "footer" facets of <h:dataTable>, e.g. <rich:datascroller> - scrolling doesn't work.

#### 4.2.4.2. Links

- Jira

#### 4.2.4.3. How to reproduce

The described above problem occurs if the following code is used. As a result the <rich:datascroller> component stops working.

    ...

    <h:dataTable>

        <f:facet name="header">

            <rich:datascroller ajaxSingle="true"/>

        </f:facet>

        ...

    </h:dataTable>

    ...

#### 4.2.4.4. Causes

The ajaxSingle/region requires `invokeOnComponent()` to work properly. For more details, please, see JavaServer Faces issues reporting page.

#### 4.2.4.5. Workarounds

The solution is to use <rich:dataTable> component.

### 4.2.5. Action listeners calling problem with <a4j:actionparam> on JSP page

#### 4.2.5.1. Description

As it has been mentioned above we've migrated to JSF 1.2 standard in RichFaces 3.2.0. The order of calling action listeners has been changed in JSF 1.2: first the listener of the component itself is called then the other listeners are called.

This is why the <a4j:actionparam> component setter is called after "actionListener" of the component itself. In the following example `#{bean.action}` is called before `#{bean.value}`:

Example:

    ...

    <a4:support actionListener="#{bean.action}"  event="onclick">

        <a4j:actionparam assignTo="#{bean.value}" value="John"/>

    </a4j:support>

    ...

This issue occurs in JSP pages only.

#### 4.2.5.2. Links

- Jira

#### 4.2.5.3. How to reproduce

    ...

    <f:view>

        <h:form>

            <h:panelGrid width="120" border="5">

                <a4j:support event="onclick" reRender="rep" actionListener="#{actionPlanBean.actionListener}">

                    <a4j:actionparam name="username" value="John" assignTo="#{actionPlanBean.name}" />

                </a4j:support>

                <h:outputLabel value="Panel 1 - John"/>

            </h:panelGrid>

            <rich:panel>

                <h:outputText id="rep" value="I say: #{actionPlanBean.helloLabel}"/>

            </rich:panel>

        </h:form>

    </f:view>

    ...

#### 4.2.5.4. Causes

Please, see Jira.

#### 4.2.5.5. Workarounds

The solution is to use <a4j:actionParam> before:

    ...

    <f:actionListener binding="#{skin.binding}"/>

    ...

### 4.2.6. Behavior of the "immediate" attribute is changed

#### 4.2.6.1. Description

Since we've migrated to the JSF 1.2 standard in RichFaces 3.2.0 the "immediate" attribute works exactly like it should according to the JSF 1.2 specification: the default ActionListener stops execution after the Apply Request Values phase, so there is no interaction with a model any more. We could not use the standard JSF API before as soon as we had to support not only JSF 1.2, but JSF 1.1 as well. We used our own hack that emulated the behavior of the attribute. This approach had a side effect that allowed interacting with a model but now this side effect is gone.

#### 4.2.6.2. Links

- RichFaces Forum

#### 4.2.6.3. How to reproduce

    ...

    <h:form>

        <h:inputText id="oneA" value="#{bean.name}" size="8">

            <a4j:support event="onkeyup" reRender="three" immediate="true" focus="oneA" action="#{bean.actionOne}"/>

        </h:inputText>

        <h:selectBooleanCheckbox id="twoA" value="#{bean.option}">

            <a4j:support event="onclick" reRender="three" immediate="true" focus="twoA" action="#{bean.actionOne}"/>

        </h:selectBooleanCheckbox>

        <h:commandButton id="go" value="Submit"/>

    </h:form>

    <h:outputText id="three" value="#{bean.name} #{bean.option}"/>

    ...

#### 4.2.6.4. Causes

Behavior of the "immediate" attribute is changed according to to JSF 1.2 specification.

#### 4.2.6.5. Workarounds

The solution includes the following steps:

- replace "immediate" attribute with `ajaxSingle="true"`

- add "process" attribute. This attribute points to the components that should be processed together with the command component.

## 4.3. Issues with compatibility with third party frameworks

This section covers issues related to compatibility with third party frameworks.

### 4.3.1. The "fileUploadListener" with MyFaces or JSF-RI 1.2_04

#### 4.3.1.1. Description

The "fileUploadListener"("UploadEvent" event) is not invoked when MyFaces or JSF-RI 1.2_04 is used. But file is uploaded successfully.

#### 4.3.1.2. Links

- Jira(for MyFaces)

- RichFaces Forum

#### 4.3.1.3. How to reproduce

MyFaces or JSF-RI 1.2_04 with default configuration

#### 4.3.1.4. Causes

In case MyFaces `org.apache.myfaces.CHECK_EXTENSIONS_FILTER` parameter is set to "true", the parameter checks if the extensions-filter has been properly configured.

The reason why usage of JSF-RI 1.2_04 causes the problem is not yet identified.

#### 4.3.1.5. Workarounds

To avoid generation of errors from MyFaces in case of invalid filter configuration you can set up the following parameters in web.xml:

    ...

    <context-param>

        <param-name>org.apache.myfaces.CHECK_EXTENSIONS_FILTER</param-name>

        <param-value>false</param-value>

    </context-param>

    ...

In case of JSF 1.2_04, upgrading to JSF-RI 1.2_07 (last stable version) works.

### 4.3.2. RichFaces 3.2.0 with MyFaces 1.2.2 on WebLogic 10 MP1

#### 4.3.2.1. Description

If you try to use RichFaces 3.2.0 with MyFaces 1.2.2 on a WebLogic 10 MP1 server the following error appears:

    java.lang.IllegalStateException: Servlet response already use stream, Writer not possible

    ...

The same project works on Tomcat 6.016, Tomcat 5.5.25 WebLogic 10MP1 with RichFaces 3.1.4.

#### 4.3.2.2. Links

- RichFaces Forum

#### 4.3.2.3. How to reproduce

The problem occurs if the environment mentioned above is set.

#### 4.3.2.4. Causes

Unknown. Possible problem with MyFaces on WebLogic 10MP1.

#### 4.3.2.5. Workarounds

Switching to JSF-RI 1.2_07 fixes the problem (see forum post)

### 4.3.3. <rich:fileUpload> with Seam multi-part filter

#### 4.3.3.1. Description

The <rich:fileUpload> component does not work with Seam multi-part filter.

#### 4.3.3.2. Links

- RichFaces Forum

#### 4.3.3.3. How to reproduce

The problem occurs if you use the <rich:fileUpload> component and Seam multi-part filter at the same time.

#### 4.3.3.4. Causes

Lack of specification on the Servlet level does not allow to use stuff doing the same thing. One of them should be turned off.

#### 4.3.3.5. Workarounds

The solution is turn the Seam multi-part filter off.

## Chapter 5. The RichFaces Migration Issues 3.2.x - 3.3.0

This chapter includes only those issues that concern migration from from 3.2.x versions to 3.3.0. Issues, that are related to the new components and other problems are not covered here. However, Jira contains all issues and if you can not find your case there, please, feel free to report it.

## 5.1. Ajax request calls encode() methods of <rich:dataTable> even if it is not necessary

### 5.1.1. Description

Any Ajax request reloads the list that is related to the <rich:dataTable> component even if the Ajax request is related to another bean. It happens because the Ajax request checks whether the <rich:dataTable> has nested <rich:outputPanel> or <rich:messages> components that should be updated. If there are no <rich:outputPanel>, <rich:messages> components inside the <rich:dataTable> will not be updated, but anyway the `encode()` methods is called by the Ajax request.

### 5.1.2. Links

- Jira

- RichFaces Forum

### 5.1.3. How to reproduce

Place the following code on a page and click the button. The list in `myBean1.myList` will be reloaded.

    ...

    <h:form  id="form1">

        <rich:dataTable id="myTable" value="#{myBean1.myList}" var="comp">

            ...

        </rich:dataTable>

    </h:form>

    <h:form id="form2">

        <h:outputText value="#{myBean2.test}"/>

        <a4j:commandButton event="onclick" reRender="form2" />

    </h:form>

    ...

### 5.1.4. Causes

Bug is caused by <rich:dataTable> implementation peculiarity.

### 5.1.5. Workarounds

Wrap the zone of a page that should be processed and updated in the <a4j:region> component with `renderRegionOnly="true"`. The <rich:dataTable> should be outside of the <a4j:region>.