JBoss.orgCommunity Documentation

Chapter 5. Advanced features

5.1. JSF 2 integration
5.2. Error handling
5.2.1. Client-side errors
5.2.2. Server-side errors
5.3. Other functions
5.4. Resource loading
5.4.1. Configuring ResourceServlet
5.4.2. Resource optimization
5.4.3. Resource mapping

Read this chapter for details on some of the advanced features and configuration possibilities for the RichFaces framework.

5.1. JSF 2 integration

JavaServer Faces (JSF) is the Java-based web application framework upon which the RichFaces framework has been built. RichFaces is now integrated with JSF 2, which features several improvements to the framework.

  • The standard display technology used by JSF 1 was JavaServer Pages (JSP). With JSF 2, the standard display technology has been changed to Facelets, which is a more powerful and more efficient View Declaration Language (VLD) than JSP.

5.2. Error handling

RichFaces allows standard handlers to be defined for processing different application exceptions. Custom JavaScript can be executed when these exceptions occur.

JSF provides a global onError handler on the client. The handler provides the relevant error code and other associated data. The RichFaces Ajax components provide the error attribute if extra functionality needs to be defined.

Additional processing is available through a number of components, such as the following:

  • The <a4j:status> component has an additional error state.
  • The <a4j:queue> component can be used to process errors.

Use the JSF 2 ExceptionHandler class to handle server-side errors such as session expiration.

5.3. Other functions

RichFaces provides a number of advanced functions, such as managing user roles and identifying elements. Refer to the Functions chapter in the RichFaces Component Reference for further details.

5.4. Resource loading

The RichFaces improves a standard JSF resource handling in order to achieve following features:

  • resource optimization - serves optimized component resource dependencies (JavaScript, CSS)
  • resource mapping - re-routes resource requests (maps an one resource to an another resource)

For leveraging RichFaces resource loading improvements, the ResourceServlet needs to be registered.

ResourceServlet is automatically registered in the Servlet 3.0 and higher environments.

In the Servlet 2.5 and lower environments, it is necessary to register the ResourceServlet manually in the WEB-INF/web.xml configuration file:


<servlet>

    <servlet-name>Resource Servlet</servlet-name>

    <servlet-class>org.richfaces.webapp.ResourceServlet</servlet-class>

    <load-on-startup>1</load-on-startup>

</servlet>



<servlet-mapping>

    <servlet-name>Resource Servlet</servlet-name>

    <url-pattern>/org.richfaces.resources/*</url-pattern>

</servlet-mapping>

The resource optimization feature provides optimized component dependencies - JavaScript, CSS - which are compressed and aggregated to resource packages.

The loading of compressed resource packages may lead into significant client performance boost, since many small files are aggregated into one big file - the number of HTTP connections necessary to download application resources is significantly decreased.

Example 5.1. Enabling resource optimization

To enable the resource optimization, add a following configuration to web.xml:


<context-param>

    <param-name>org.richfaces.resourceOptimization.enabled</param-name>

    <param-value>true</param-value>

</context-param>

Example 5.2. Resource optimization in development JSF project stage

Resource optimization is influenced by the project stage:

  • resources are not compressed in the development stage and during unit-testing to enable client-side debugging
  • resources are compressed in the production stage and during a system-testing to minimize network bandwidth

Switch to the development project stage during a development:


<context-param>

    <param-name>javax.faces.PROJECT_STAGE</param-name>

    <param-value>Development</param-value>

</context-param>

The resource mapping feature maps an existing JSF resource (determined by library and name) to a another resource.

This feature can help to solve the following cases:

  • providing alternative versions of JSF resources
  • map several JSF resources to one
  • using external resources
  • moving resources to servers serving static content

Configuring the resource mapping means adding new records to the class-path file META-INF/richfaces/static-resource-mappings.properties.

Each line in the configuration file represents one relocation.

A following sample shows a JSF resource with the name resourceLibrary:resourceName relocated to a resource anotherResourceLibrary:anotherResourceName:

resourceLibrary\:resourceName=anotherResourceLibrary/anotherResourceName

Mapping resource name to relative URL

The definition above contains a JSF resource name on the left side of the expression and a relative path on the right side.

The expression on the right side represents a path relative to a JSF resource root, thus resource path anotherResourceLibrary/anotherResourceName actually maps to a JSF resource with name anotherResourceLibrary:anotherResourceName.

Additional mapping files

It is possible to define additional resource mapping configuration files by using a contextual parameter identifying the class-path locations where the files reside: org.richfaces.resourceMapping.mappingFile (a comma-separated list of the class-path files).

Example 5.3. Providing alternative file

All requests for jquery.js are served as requests for jquery-alternative-version.js:

jquery.js=jquery-alternative-version.js

Example 5.4. Mapping several resources to one

Both some:jquery.js and another:jquery.js are mapped to final:jquery.js:

some\:jquery.js=final/jquery.js
another\:jquery.js=final/jquery.js

Example 5.5. Using external resources

Mappings with a resource path starting with http:// or https:// are served as absolute resource locations:

A following sample instructs to load jquery.js from CDN:

jquery.js=http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js