RichFaces Migration Guide


1. Introduction
2. Scope of the document
3. Minimum requirements for the project with RichFaces 3.2.0
+4. The RichFaces Migration Issues
4.1. Most important
4.2. Issues with upgrading from previous versions
4.3. Issues with compatibility with third party frameworks

Chapter 1. Introduction

This document is aimed to provide guidelines for migrating RichFaces projects from 3.1.x versions to 3.2.0.

RichFaces Migration Guide implies descriptions concerning 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 3.2.0 in the Developer Guide.

Chapter 4. The RichFaces Migration Issues

This chapter includes only the issue with migration from previous versions to 3.2.0. Issues with new components and other problems are not included. The Jira contains everything.

4.1. Most important

4.1.1. non-ASCII characters in application with i18n

4.1.1.1. Description

Application with i18n does not work correctly caused by the validation error when non-ASCII characters is used

4.1.1.2. Links

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 (came with <rich:fileUpload> component)

4.1.1.5. Workarounds

The decision is to upgrade to RichFaces 3.2.0 SP1

4.1.2. Menu components and JSF-RI-1.2_08

4.1.2.1. Description

Menu components are not working 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 with showing XHTML invalid output

4.1.2.3. How to reproduce

Having JSF-RI 1.2_08 and menu components on a page.

4.1.2.4. Causes

Critical bug in JSF-RI 1.2_08. Already fixed for the further released there.

4.1.2.5. Workarounds

Downgrade to JSF-RI 1.2_07 or use recent JSF-RI SNAPSHOT.

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 "binding" attribute for RichFaces components. Wrong class-name is used in TLD generated from XML configuration files.

4.1.3.2. Links

4.1.3.3. How to reproduce

Just using binding attribute.

4.1.3.4. Causes

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

4.1.3.5. Workarounds

The decision 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 shown when intensive Ajax traffic is expected. No error or other diagnostic presents.

4.1.4.2. How to reproduce

Do not define an id for Ajax command component.


...
 <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

This is a specific of the dynamic id generation of the JSF 1.2 implementation. 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 from the component with old id just do not process.

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

4.1.5.3. How to reproduce

Usually reproduced after server restart when user refreshes page

4.1.5.4. Causes

Resources for standard skinning classes haven't been 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

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.

After time and apply elements have been added to calendar "ondateselected" gets fired after date selected but before 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

4.2.1.3. How to reproduce

Put <a4j:support> inside <rich:calendar>. If the "event" property is "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 is fired after any change which causes input to be updated, both date and time.

Notice, that

  • "ondateselected" event is fired after date is selected in popup

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

4.2.2. Paired <rich:datascroller> components aren't work

4.2.2.1. Description

Two <rich:datascroller> components bound to the same table aren't synchronized. Storing data component in session-scoped beans no more saves <rich:datascroller> state. It is a common pattern to have 2 <rich:datascroller> components: the first in header, the second in footer. The first will not work.

4.2.2.2. Links

4.2.2.3. How to reproduce

Add 2 <rich:datascroller> components to any table.

4.2.2.4. Causes

The <rich:datascroller> component is now responsible for managing data table's scroll state.

4.2.2.5. Workarounds

The decision 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 <rich:datascroller> component's "for" attribute 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

4.2.3.3. How to reproduce

Just add the following code, that will not work:


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

4.2.3.4. Causes

Please, see Jira

4.2.3.5. Workarounds

None for no

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

4.2.4.1. Description

The RichFaces components that have "ajaxSingle" = "true" will not work in "header" or "footer" facets of <h:dataTable>, e.g. <rich:datascroller> won't scroll.

4.2.4.2. Links

4.2.4.3. How to reproduce

Just add the following code. The <rich:datascroller> component will not work:


...
<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

Use <rich:dataTable> component.

4.3. Issues with compatibility with third party frameworks

4.3.1. "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.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". This parameter checks if the extensions-filter has been properly configured.

Why using JSF-RI 1.2_04 causes the problem is not yet examined.

4.3.1.5. Workarounds

To avoid generation of errors from MyFaces in case of invalid filter configuration you could 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

4.3.2.3. How to reproduce

Use the environment mentioned above.

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 fix 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

4.3.3.3. How to reproduce

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

Turn the Seam multi-part filter off.