ICEfaces 2.0.0 Release Notes

Table of Contents

ICEfaces 2.0.0 Release Notes

December 21st, 2010

About This Release

ICEfaces 2.0.0 is the official release of the next-generation of ICEfaces, designed for JSF 2.0.


These Release Notes include the following sections:


ICEfaces 2.0 is available for download in the following formats:

New Features

ICEfaces 2 provides some key feature enhancements over JSF 2, while inheriting all the new features available in JSF 2.

Framework Enhancements

The following framework enhancements extend the capabilities of standard JSF 2:

Automatic Ajax

ICEfaces 2 includes several innovative features that cumulatively result in Automatic Ajax, completely eliminating the need for developers to wire page updates together using standard JSF <f:ajax> tags.

  • Direct-to-DOM Rendering (D2D) renders component markup to a server-side DOM that reflects the current client view. Each time the JSF lifecycle runs, a DOM comparison is done, and if there are any changes, a concise set of page updates are sent back to the client to be applied to the page. Simply adding the ICEfaces 2 library to an existing JSF 2 application will provide dynamic partial-page-updates for all compliant components, without the need to specify the JSF <f:ajax> component in your pages.
  • Single Submit enables all components to automatically submit themselves base on user interaction. The JSF lifecycle executes on just that single component, and then the entire render phase is executed. From there the D2D mechanism determines the exact set of incremental page changes required in response to the Single Submit.

Ajax Push

Ajax Push enables real-time, multi-user collaboration in your JSF application. Any state change in the application can instantaneously push updates to other users of the application that need to be informed. New Ajax Push APIs make it simpler than ever to add collaborative features to your application.

Window Scope

The custom Window scope is designed to fill a gap in the existing scopes available for JSF 2.0, as it exists for the life of a browser window or tab, including surviving reloads and refreshes.

Bean Management

Annotations are provided that adjust the behavior of View-scoped beans. While View scope is a welcome addition for managing the lifecycle of beans, the behavior of View scope may not be intuitive in certain scenarios. Specifically, the annotations allow you to control the behavior of view-scoped beans across repeated navigation to the same view, and during view disposal.

Scoped Resource Registry

The ResourceRegistry allows an application to register javax.faces.application.Resource instances at run time. Each Resource is registered in a specified scope (Application, Session, View, Flash, or Window) so that the resource can be garbage collected when the scope expires.

Portlet Development

Portlet support in ICEfaces 2 is provided by the PortletFaces Bridge, an implementation of the JSR 329: Portlet 2.0 Bridge for JSF. The portlet bridge spec technically applies to JSF 1.2, but the PortletFaces version has been adapted to support JSF 2. The PortletFaces Bridge is tested and shipped with the ICEfaces 2 distribution and can be used to develop portlet applications with ICEfaces.

JavaScript Client API

In addition to enhancing the basic Ajax features provided by JSF 2, ICEfaces extends a client-side API for monitoring interesting events that occur on the client, such as form submission, event callbacks, and Ajax Push connection monitoring.

Streamlined Configuration

While JSF 2 simplifies configuration by leveraging annotations, ICEfaces also streamlines configuration in several areas. The ICEfaces-specific servlets and many of the configuration parameters in ICEfaces 1.x are no longer necessary with ICEfaces 2. This makes it even quicker and easier to add ICEfaces to your JSF application, and greatly reduces the possibility of lost productivity due to minor configuration errors.

Minimized Dependencies

ICEfaces 2 core has no 3rd-party library dependencies outside of those libraries specified in the JEE 6 "Web Profile". This further streamlines integration and software change management. Note that the ICEfaces 2 Compatibility Libraries do require additional 3rd-party libraries when used (same as those required by ICEfaces 1.8).

Rich Components

All components used under ICEfaces 2 inherit the benefits of Automatic Ajax, including the standard JSF components. ICEfaces 2 offers a vast array of rich components beyond the standard ones available in JSF 2.

  • The ICE Components include the components from ICEfaces 1.8 and use a compatibility layer that enables them to function with JSF 2.0, and ICEfaces 2. These components provide a smooth migration path from ICEfaces 1.8.
  • The ACE Components leverage all the features of the JSF 2.0 component architecture, and are based on the all-new Advanced Component Environment (ACE). The YUI JavaScript library provides rich, client-side web controls, but packaged as JSF components, so you don't need to know or use any JavaScript to include them in your application. Important features of the Advanced Components include flexible form definition, UI theming/skinning, and W3C ARIA accessibility.

Supported Platforms

This release has been tested on the following:

  • Mojarra JSF 2.0.3-FCS, JSF 2.0.4-b06, and JSF 2.1-b09 (Dec. 10th, 2010)
  • Tomcat 6, 7
  • Glassfish 3.0, 3.1-M7
  • JBoss 6.0.0.CR1
  • Liferay Portal 6.0

(Note that any JEE6-compliant platform should work)

For a complete list of all changes in this release, see the related JIRA Change Log.

Known Issues

The following section describes the most commonly encountered known issues with this release:


  • JSPs are not supported by ICEfaces 2.0 - use Facelets.
  • It is required to specify "h:head" and "h:body" tags in your ICEfaces application pages.
  • Due to an apparent bug in the Sun Mojarra JSF 2.0.3 runtime library, component binding is not reliable when used within a View scope. The recommended workaround is to use the ICEfaces "Window" or JSF "Session" scopes instead if component-binding is required. Alternatively, applications can be modified to avoid the requirement for using component-binding in View scope by using techniques similar to that used in the Data Paginator demo section of Compatible Component Showcase application. For details, see ICE-5226.
  • An apparent bug in Mojarra JSF 2.0.3 (root cause not determined) causes ajax postbacks to ignore navigation. Upgrade to JSF 2.1 is required.


  • ICEpush (icepush.jar) asynchronous update support is limited to a single ICEfaces application per host-name/server.
    • Viewing multiple ICEfaces applications in the same browser from the same host server concurrently will result in only one of the applications having functional push capabilities.
    • Support for pushing asynchronous updates to multiple ICEfaces applications from the same server/host-name requires the use of the Enterprise Push Server (EPS), which is included in ICEfaces EE (Enterprise Edition).
    • This is necessary because the browser cannot support multiple concurrent push connections, so all push traffic must be multiplexed at a single point on the server.

1.8.x Compatibility

  • In ICEfaces 2.0, the "Request" scope is the "standard" JSF Request scope, and not the "Extended" Request scope that was the default in ICEfaces 1.x.. This change may result in failures for ICEfaces 1.x applications that relied on the Extended Request Scope behavior that are being moved to ICEfaces 2.0. The workaround for this issue is to adopt one of "View", "Window", or "Session" scopes in JSF/ICEfaces 2.0 instead.
  • The following ICEfaces 1.8.2 Component Suite components are deprecated for ICEfaces 2.0 and are not present in ICEfaces 2:
    • ice:inputFile (use ace:fileEntry instead)
    • ice:outputDeclaration (use Facelets standard approach / "<DOCTYPE ...>" instead)
    • ice:outputBody (use h:body instead)
    • ice:outputHead (use h:head instead)
    • ice:outputHtml (use <HTML> tag instead)

Advanced Components

  • Due to a bug in Mojarra JSF 2.0.x, it is not possible to use the Advanced Components in a dynamic page, such as having components be included via Facelets ui:include, with the JSF-default Partial State Saving enabled. It is required to disable Partial-State-Saving via the following context parameter in the web.xml file:
    This bug is fixed in Mojarra JSF 2.1 preview releases.
  • ace:fileEntry - occasionally the JavaScript error "Failed to load resource: javax.faces.resource/listen.icepush.jsf" will appear in the JavaScript console after a successful file upload. This error can be ignored as it has no functional impact.


  • Using ICEfaces 2.0.0 for portlet development requires the use of the included icefaces/libs/portlets/jsf-api-2.0.4-b06a.jar, and jsf-impl-2.0.4-b06a.jar, which contain JSF fixes necessary for portlet development.
  • The Advanced Components are not currently supported for portlet development on Liferay 6, with the exception of the fileEntry component. Using the fileEntry component on Liferay 6 requires that the mandatoryResourceConfiguration configuration parameter be set in the web.xml as follows:
    See the Configuration topic for more information on mandatoryResourceConfiguration.

Application Servers

  • Tomcat 6.0
    • In some cases, when running Tomcat on Windows, undeploying an ICEfaces 2 compatible application (i.e. that includes the icefaces-compat.jar) can cause an exception. See ICE-5222 for additional information about this issue. To prevent this, include a context.xml file with your application that includes the following Context attributes to prevent jar and resource locking:
      <Context antiJarLocking="true" antiResourceLocking="true"/>
  • Glassfish 3 / JBoss 6 (JEE 6 Platforms)
    • It is necessary to have Mojarra JSF 2.0.3-FCS or greater installed. This may require updating the JSF Mojarra runtime libraries in Glassfish 3 or JBoss 6, depending on which JSF version is currently installed.


Open source community support is available at

The ICEfaces community forums are available for questions, comments, or general discussions regarding ICEfaces 2.0.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

© Copyright 2021 ICEsoft Technologies Canada Corp.