JBoss.orgCommunity Documentation
Read this chapter for details on some of the advanced features and configuration possibilities for the RichFaces framework.
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.
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.
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.
Resources which RichFaces uses in components, like style sheets, JavaScript code or images are handled by standard JSF resource handling.
However JSF resource handling feature falls short when using static resources which refers to another resources (style sheets refering to images, JavaScript refering to style sheets). These resources doesn't carry informations necessary to address JSF resources (servlet context path, servlet mapping, library name).
RichFaces provides ResourceServlet which handles framework static resources:
third-party JavaScript libraries or style sheets
pre-generated dynamic resources (ECSS, dynamic images)
ResourceServlet is automatically registered in Servlet 3.0 and higher environments.
In Servlet 2.5 and lower environments, it is necessary to register ResourceServlet manually in 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>
This servlet is strictly limited in what it can process to the RichFaces resource libraries only.
RichFaces resources are determined by notion of resource libraries and loaded by standard JSF resource handling mechanism.
There are situations where it may be favourable to use alternative resource location:
loading pre-processed resources (packed or compressed resource)
loading modified resource (patched or alternative resource)
loading resource from external location (static HTTP server, Content Delivery Network)
Resource mapping feature is in default state disabled. You can enable it with contextual parameter org.richfaces.resourceMapping.enabled with value true.
Resource mapping is controlled by two configurations:
mapped resources location
resource mapping configuration file
While mapped resources location determines the base URL from which all resource locations are derived, resource mapping file contains resource-specific locations.
Absolute resource location is determined from base URL, which is string that contains EL expression #{resourceLocation}.
This base URL can be configured using contextual parameter org.richfaces.resourceMapping.location.
Resource mapping configuration is properties file with records in format:
resourceLibrary:resourceName=resourceLocation
It is possible to define custom resource mapping configuration file using contextual parameter identifying class-path location where file resides: org.richfaces.resourceMapping.mappingFile
The resourceLocation can be absolute resource URL, allowing to relocate selected resources to another server.
Example 5.1. Example of resource mapping web.xml configuration
<context-param>
<param-name>org.richfaces.resourceMapping.enabled</param-name>
<param-value>true</param-value>
</context-param>
<context-param>
<param-name>org.richfaces.resourceMapping.mappingFile</param-name>
<param-value>META-INF/custom-mapping.properties</param-value>
</context-param>
<context-param>
<param-name>org.richfaces.resourceMapping.location</param-name>
<param-value>#{facesContext.externalContext.requestContextPath}/resources/com.acme/#{resourceLocation}</param-value>
</context-param>
First context-param is enabling resource mapping. Both other context-params are configuring the behavior.
Second context-param instructs RichFaces to look for META-INF/custom-mapping.properties file on class-path (either in your WAR: WEB-INF/classes/META-INF/custom-mapping.properties or any JAR on class-path in META-INF/custom-mapping.properties).
Last context-param configures the root resource location and uses expressions #{facesContext.externalContext.requestContextPath} to retrieve context path and #{resourceLocation} to retrieve location of specific resource (as provided from resource mapping configuration file).
Example 5.2. Example of resource mapping configuration file
The contents of META-INF/custom-mapping.properties file:
javax.faces:jsf.js=patched-jsf.js
jquery.js=http://some.cdn/jquery/1.6.4/jquery.min.js
First property in the META-INF/custom-mapping.properties specifies resource mapping for resource with qualifier javax.faces:jsf.js which stands for Java Server Faces 2.0 JavaScript implementation. It instructs resource handler to look for patched-jsf.js source file (in this sample located on WAR relative location resources/com.acme/patched-jsf.js).
Using the resource location root, it will specifically look for #{facesContext.externalContext.requestContextPath}/resources/com.acme/patched-jsf.js
Second property defines mapping for jquery.js resource. This line instructs resource handler to locate this resource on external URL, specifically from CDN.
Resource loading strategies are special configuration of resource mapping.
RichFaces framework bundles static versions of all components' resources which are processed to optimize performance in certain scenarios:
static resources - suitable for environments, where dynamic generation is not enough performant or can't be processed at all
compression - suitable as network bandwidth and client performance optimization and client side code obfuscation
packing - suitable for providing dependencies for all components in one package, limiting number of requests to one per resource type
Previous features aren't configured directly, it is necessary to choose project stages in which given feature will be applied.
Resource mapping needs to be enabled for using resource loading strategies.
It is necessary to choose stages, where compression is applied and where packed resource will be used. If both compression and packing are disabled, simple static resources will be served.
It is possible to provide following options for project stages: Development, UnitTest, SystemTest, Production or keywords None and All.
For configuration, you can use any combination of project stages (separated by commas) or keywords None (for feature turned off in all stages) or All (for feature turned off in all stages).
Compression is configured in web.xml using context-param org.richfaces.resourceMapping.compressedStages.
Compression is by default set to Production,SystemTest, enabling this feature for production and system testing.
Packing is configured in web.xml using context-param org.richfaces.resourceMapping.packedStages.
Packing is by default set to All, enabling this feature in all stages.
It specifically means that with resource mapping enabled, packed resources are served and compression is turned off in development and unit tests and turned on in production and for system tests.
For serving static versions of regular resources, you will need to turn off both compression and packing.
Example 5.3. Resource loading strategies configuration
Following sample turns off packing in all stages, so only compression will be applied.
<context-param>
<param-name>org.richfaces.resourceMapping.enabled</param-name>
<param-value>true</param-value>
</context-param>
<context-param>
<param-name>org.richfaces.resourceMapping.packedStages</param-name>
<param-value>None</param-value>
</context-param>
Resource loading strategies are just special case of resource mapping, thus once you will provide custom resource mapping configuration or location, bundled default resources won't be referenced correctly.
For using compressed/packed resources you will need to copy properties from one of files located in richfaces-components-ui.jar:/META-INF/richfaces/staticResourceMapping/.