RichFaces Migration Guide. 3.3.x - 4.x Migration - Upgrading

IMPORTANTThat document is under continous development. It's published in order you to have the fastest access to all the new info posted there even considering that document itself will be extended more in the same time. So please be patient, and do not forget leave your feedback and requests for additional information at RichFaces Space Forum. We could do it really great together!

To consider Before Upgrade

JSP Deprecation

JSF 2 specification deprecates JSP as a view definition language. And all the new components and most of the features do not works for JSP VDL in JSF 2 itself. So RichFaces 4 decided to drop that support starting from the first 4.0.0.Final version. So you have to use JSF 2 Facelets VDL.

Usage with Seam

     Seam 2 is not compatible with JSF 2. So if you evaluating RichFaces 4 and planning to estimate/review project migration to RichFaces 4 you should consider migration to Weld/Seam 3 also.

Libraries updates

Maven based projects

How to add RichFaces 4.x to maven based project

Projects without Maven dependencies management

How to add RichFaces 4.x to projects not based on maven

Application Descriptors updates

Web Application Descriptor

  1. RichFaces Filter not needed anymore as RichFaces 4 uses JSF 2 System Events for configuration and requests handling.
  2. remove org.ajax4jsf.VIEW_HANDLERS context parameter. it was needed to configure facelets view handler for JSF 1.2 only.
  3. Check the next table to learn about context-parameters changes:

TABLE TBD

 

Name 3.3.x

Name 4.x

DEFAULTDescription/Comments
org.richfaces.<name>org.richfaces.<name>

SKINskinDEFAULTdefault application skin
BASE_SKINbaseSkin-base skin for current skin
CONTROL_SKINNINGenableControlSkinningtrueenables stylesheets with standard skinning classes.
CONTROL_SKINNING_CLASSESenableControlSkinningClassesfalseenables stylesheets with predefined skinning classes for explicit usage on the component and containers definitions.
CONTROL_SKINNING_LEVEL-
Not going to be migrated becase old browsers support (IE 6, Safary 2..) dropped
LoadScriptStrategyresourceOptimization.enabledfalseThe Resource Loading Strategies has been re-introduced as Resource Optimization feature
LoadStyleStrategyresourceOptimization.enabledfalseThe Resource Loading Strategies has been re-introduced as Resource Optimization feature
org.ajax4jsf.<name>org.ajax4jsf.<name>

LOGFILE


VIEW_HANDLERS


CONTROL_COMPONENTS


ENCRYPT_RESOURCE_DATA


ENCRYPT_PASSWORD


COMPRESS_SCRIPT-
resource compression can be enabled using Resource Optimization feature
COMPRESS_STYLE-
resource compression can be enabled using Resource Optimization feature
RESOURCE_URI_PREFIX


SESSION_RESOURCE_URI_PREFIX


DEFAULT_EXPIRE


SERIALIZE_SERVER_STATE






























 

JSF Faces-Config

    1. At first declare your faces-configs as JSF 2 faces-config files by changing its version <faces-config xmlns="http://java.sun.com/xml/ns/javaee" version="2.0">
    2. Remove facelets view handler definition as it needed only to configure facelets in JSF 1.2

Components Namespaces updates

 

The namespace and library inclusions are the same as those for previous versions of RichFaces.

 

The RichFaces namespaces need to be declared in the project's XHTML pages.

 

<ui:composition xmlns:a4j="http://richfaces.org/a4j" xmlns:rich="http://richfaces.org/rich">
    ...
</ui:composition>

 

NameDefaultDescription
org.richfaces.SKINDEFAULTIs a name of a skin used in an                                                   application. It can be a                                                   literal string with a skin                                                   name, or the                                                    EL                                                   expression                                                   (#{...})                                                   pointed to a                                                    String                                                   property (skin                                                   name) or a property of a                                                   org.richfaces.framework.skin                                                   type. Skin in last case, this                                                   instance is used as a current                                                   skin
org.richfaces.LoadScriptStrategyDEFAULTDefines how the RichFaces script                                                   files are loaded to                                                   application. Possible values                                                   are: ALL, DEFAULT, NONE. For                                                   more information see "Scripts                                                   and Styles Load                                                   Strategy".
org.richfaces.LoadStyleStrategyDEFAULTDefines how the RichFaces style                                                   files are loaded to                                                   application. Possible values                                                   are: ALL, DEFAULT, NONE. For                                                   more information see "Scripts                                                   and Styles Load                                                   Strategy".
org.ajax4jsf.LOGFILEnoneIs an URL to an application or a                                                   container log file (if                                                   possible). If this parameter                                                   is set, content from the given                                                   URL is shown on a                                                    Debug                                                   error page in the                                                    iframe                                                   window
org.ajax4jsf.VIEW_HANDLERSnoneIs a comma-separated list of                                                   custom                                                    ViewHandler                                                   instances for                                                   inserting in chain. Handlers                                                   are inserted BEFORE RichFaces                                                   viewhandlers in the given                                                   order. For example, in                                                   facelets application this                                                   parameter must contain                                                   com.sun.facelets.FaceletViewHandler,                                                   instead of declaration in                                                   faces-config.xml
org.ajax4jsf.CONTROL_COMPONENTSnoneIs a comma-separated list of                                                   names for a component as a                                                   special control case, such as                                                   messages bundle loader, alias                                                   bean components, etc. Is a                                                   type of component got by a                                                   reflection from the static                                                   field                                                    COMPONENT_TYPE                                                   . For components                                                   with such types encode methods                                                   always are called in rendering                                                   Ajax responses, even if a                                                   component isn't in an                                                   updated part
org.ajax4jsf.ENCRYPT_RESOURCE_DATAfalseFor generated resources, such as                                                   encrypt generation data,                                                   it's encoded in the                                                   resource URL. For example, URL                                                   for an image generated from                                                   the                                                    mediaOutput                                                   component contains                                                   a name of a generation method,                                                   since for a hacker attack, it                                                   is possible to create a                                                   request for any JSF baked                                                   beans or other attributes. To                                                   prevent such attacks, set this                                                   parameter to                                                   "true" in                                                   critical applications (works                                                   with JRE > 1.4                                                   )
org.ajax4jsf.ENCRYPT_PASSWORDrandomIs a password for encryption of                                                   resources data. If                                                   isn't set, a random                                                   password is used
org.ajax4jsf.COMPRESS_SCRIPTtrueIt doesn't allow                                                   framework to reformat                                                   JavaScript files (makes it                                                   impossible to debug)
org.ajax4jsf.RESOURCE_URI_PREFIXa4j Defines prefix which is added to                                                   all URIs of generated                                                   resources. This prefix                                                   designed to handle RichFaces                                                   generated resources requests                                                  
org.ajax4jsf.GLOBAL_RESOURCE_URI_PREFIXa4j/g Defines prefix which is added to                                                   URIs of global resources. This                                                   prefix designed to handle                                                   RichFaces generated resources                                                   requests
org.ajax4jsf.SESSION_RESOURCE_URI_PREFIXa4j/s Defines prefix which is used for                                                   session tracking for generated                                                   resources. This prefix                                                   designed to handle RichFaces                                                   generated resources requests                                                  
org.ajax4jsf.DEFAULT_EXPIRE86400 Defines in seconds how long                                                   streamed back to browser                                                   resources can be cached                                                  
org.ajax4jsf.SERIALIZE_SERVER_STATEfalse If enabled the component state                                                   (not the tree) will be                                                   serialized before being stored                                                   in the session. This may be                                                   desirable for applications                                                   that may have issues with view                                                   state being sensitive to model                                                   changes. Instead of this                                                   parameter can use                                                   com.sun.faces.serializeServerState                                                   and                                                    org.apache.myfaces.SERIALIZE_STATE_IN_SESSION                                                   parameters for                                                   corresponding environments.