ICEfaces® v1.8.0-RC2 Release Notes March 20th, 2009

Overview

This document contains the following sections:

• Changes in v1.8 RC2 (This Release)
• Changes in v1.8 RC1
• Changes in v1.8 DR#2
• Changes in v1.8 DR#1
• Supported Platforms
  • Java 
  • Browsers
  • Application Servers
  • Portal Containers
  • IDE Tools
• Known Issues
  
  • General
  • JSP Markup
  • ICEfaces Component Suite
  • Spring WebFlow
  • Portlets
  • Sample Applications
  • Application Servers
• Support
• About ICEfaces
• License information

Changes in v1.8 RC2 (This Release)

ICEfaces v1.8 RC#2 is a release-candidate build that provides a feature-complete preview of the new features, enhancements, and fixes that will be included in the upcoming ICEfaces v1.8 release. Although this build has successfully completed regression testing issues may still exist, thus, it is not recommended for production use.

Review the Known Issues prior to using this release. Please report any issues with this build to the ICEfaces Development Build Feedback forum.

This release includes 100 fixes and enhancements since 1.8 RC#1. Refer to the ICEfaces JIRA Change Log for detailed information on all the changes included in this release.

Notable Improvements & Enhancements

• New Push Server for Asynchronous (Ajax Push) Applications
  
  
  • The ICEfaces Push Server provides a simple solution to the problem of supporting multiple ICEfaces asynchonrous (Ajax Push) applications deployed to the same server/host-name. As most browsers have limitations on the number of concurrent connections that can be made to the same server/host-name it is necessary for multiple asynchronous  on the same server to share a blocking connection back to the server. The Push Server provides this functionality in a lightweight implementation with minimal configuration required.
    
    
  • If there is the possibility of multiple push applications being deployed to the same server (including future deployments), it is recommended that the Push Server also be deployed to that server. Even though accessing a single ICEfaces asynchronous application from a browser will function correctly without the Push Server, making a habit of deploying the push-server.war along with your ICEfaces applications will avoid any issues if/when a second ICEfaces application is deployed, potentially at a later time, etc.
  • Note that by default ICEfaces is configured for asynchronous mode. See the "Asynchronous vs. Synchronous Updates
    " topic on pg. 29 of the ICEfaces Developer's Guide for details.
  • To use the Push Server, you simply deploy the push-server.war file (located in the "/icefaces/push-server/" directory) to the server you are deploying your ICEfaces push applications to. The ICEfaces  will discover the Push Server at startup and automatically configure themselves to use it.
  • If...
  • the Application Server is configured to use a custom (non-default) port #
  • and
  • the Application Server does not support at least Servlet 2.4
  • or a Portal Server is used
  • then the local IP address of the Application/Portal Server and the port # must be specified using the following configuration parameters in the web.xml files of both the ICEfaces application(s) and the push-server.war: 
  • com.icesoft.faces.localAddress
  • com.icesoft.faces.localPort
  • The Push Server is a functional replacement for the Asynchronous HTTP Server (AHS), which is no longer required or  supported in this release. 

• Framework 
  
  
  • New "Busy" Indicator. The ICEfaces bridge has been enhanced to support a new "busy" indicator and user-interaction blocking mechanism. Users will now see an hourglass cursor and be prevented from interacting with the user-interface with the mouse (no focus changes, button-clicks, etc.) while a submit or partial-submit is in progress. This feature prevents users from "chaining" numerous interactions and submits while a previous submit is still pending, avoiding possible problems with mismatched state and potentially long delays while waiting for the appllication to catch up with the user interactions.
  • This feature is enabled by default, but may be disabled by specifying "com.icesoft.faces.blockUIOnSubmit=false" in the web.xml file.
  
  
  • New JavaScript Callback APIs for Bridge Communication Events. The ICEfaces bridge has been enhanced to support new JavaScript callback APIs to enable application developers to implement custom behaviors for common communication events. The following APIs are provided:
  • Ice.onSendReceive(id, sendCallback, receiveCallback) 
  • Ice.onAsynchronousReceive(id, callback)
  • Ice.onServerError(id, callback) 
  • Ice.onSessionExpired(id, callback) 
  • Ice.onConnectionTrouble(id, callback) 
  • Ice.onConnectionLost(id, callback)

• ICEfaces Component Suite 
  
  
  • New ice:outputBody 'focus' Attribute - Manage Focus via Value-binding
  • Using the focus attribute it is possible to define both the initial focus on the page as well to dynamically set the focus on each render via a simple value-binding on the attribute.
  • Augments the existing "requestFocus()" method on ice: input components that require component binding to use.
  
  
  • Row Selector now supports Double-Click Events and Actions 
  • The ice:rowSelector can be used to register event listeners for double-click events that occur over a row.

• New Scatter Chart support 
• The ice:outputChart has been enhanced to support a new "scatterplot" type.
• Thanks to Keith Garry Boyce for this contribution.

• 3rd Party Frameworks
  
  
  • Spring WebFlow. ICEfaces support for Spring WebFlow 2.x has been improved in this release. See ICE-4186 and ICE-4200 for more information.

• Documentation
  
  
  • ICEfaces Getting Started Guide. The ICEfaces Getting Started Guide has been revised for changes in 1.8. It should be considered in near final draft form in this release.
  • ICEfaces Developer's Guide. The ICEfaces Developer's Guide has been revised for changes in 1.8. It should be considered in near final draft form in this release.

• Sample Applications
  • Component Showcase
  • The demo for the ice:setEventPhase component has been enhanced.
  • Sample Application Ant Builds
  • New ant build targets have been added for WebSphere 7.0, JBoss 5.0, and Glassfish v3.

Note: WebLogic 9.2 and 10.3 are not supported in this release due to a known issue (ICE-4247). This issue will be resolved prior to the 1.8.0 final release.

Changes in v1.8 RC1

ICEfaces v1.8 RC#1 is a release-candidate build that provides a feature-complete preview of the new features, enhancements, and fixes that will be included in the upcoming ICEfaces v1.8 release. Although this build has successfully completed regression testing issues may still exist, thus, it is not recommended for production use.

Review the Known Issues prior to using this release. Please report any issues with this build to the ICEfaces Development Build Feedback forum.

This release includes over 100 fixes and enhancements since 1.8 DR#2. Refer to the ICEfaces JIRA Change Log for detailed information on all the changes included in this release.

Notable Improvements & Enhancements

• ICEfaces Component Suite 
  
  
  • New Confirmation Panel component
  • A new ice:panelConfirmation component has been added. This component can be used to display a client-side confirmation dialog panel when the user triggers an action event on the ice:commandLink or ice:commandButton components. If the user cancels the action no action event will be fired.
  • Simple to configure and can contain custom titles, labels, and button configurations.
  
  
  • New Data Export component 
  • A new ice:dataExporter component can be used to provide user-downloadable exports of ice:dataTable data contents.
  • Supports exporting of data in various formats via an extensible outputTypeHandler.
  • CSV and Excel outputTypeHandlers are provided with the component, developers can define custom output formats by creating new outputTypeHandler implementations.

• New JSF Lifecycle Event Phase manipulation component
• A new ice:setEventPhase component has been added. This component can be used to specify the JSF lifecycle phase that certain events will be broadcasted in for events originating from child components of this component.
• This component is useful in cases where a valueChangeListener for one component needs to affect the value of another input component. By controlling the JSF life-cycle phase that the ValueChangeEvent is processed in, it is possible to prevent a submitted value from superceding a value change applied by the valueChangeListener.
• For more information, see the "Set Event Phase" demo on the Component Showcase sample application and the TLD documentation for this component.

• New support for Date & Time entry 
• The ice:selectInputDate component has been enhanced to optionally support entering just dates, or dates and times, in either 24 or 12-hour formats.

• Improved Popup Component positioning
• The following components have been improved to automatically position their "popup" elements such that they remain visible on the screen/viewport without the need for scrolling.
• ice:menuBar (sub-menus now position intelligently relative to the current window position, available space)
• ice:menuPopup
• ice:panelTooltip
• ice:selectInputDate (popup mode)
• See ICE-3512 for more information.

• New Keyboard Support for dataTable Row Selection 
• The ice:rowSelector component now provides an optional usage-mode that supports using the keyboard in conjunction with the mouse to enable multiple row selection, range selection, etc. based on industry-standard key combinations.

• Improved support for Dynamic Popup Menus
• The ice:menuPopup component has been enhanced with the addition of a displayListener. The displayListener can be used to modify the popup menu contents immediately prior to the menu becoming visible.

• Improved Localization Support. Thanks to community contributions the icefaces-comps.jar now includes the following language resource files:
• Arabic (new)
• English
• Dutch
• French
• German (new)
• Spanish (revised)

• Miscellaneous Improvements  
• The ice:panelPopup component has been improved to support using both "autoCentre" or "autoPosition" and "draggable" attributes at the same time. When either "autoCentre" or "autoPosition" are set to true as well as "draggable=true", the panelPopup will initially be positioned as defined by "autoCentre" or "autoPosition". However, if the panelPopup is subsequently moved by the user (via dragging) it will no longer autocentre or autoposition.
• The ice:menuBar component has been improved to hide any displayed menus when the mouse leaves the menu area, when "displayOnClick=false". This aligns better with the "display on hover" / "hide on hover exit" user-interface standard for popup menus than the previous behavior which required the user to click on the page outside of the menu area to hide the menu.
•  A new "varStatus" attribute has been added to the ice:panelSeries component. The varStatus can be used as a convenience in determing the current index, first, last, etc. when iterating through the panelSeries during rendering. See the TLD document for more details.
• A new "target" attribute has been added to the ice:outputResource component. The target attribute can be used to control which browser window should be used for a specific resource download operation.
• The percieved responsiveness of the ice:rowSelector has been improved by applying row selection style changes in the client prior to the server roundtrip associated with the row selection event.

• Framework 
  
  
  • Improvements to JSF State-Saving Support. Support for JSF state saving has been optimized in this release to improve memory consumption and CPU utilization, resulting in the following changes to how ICEfaces is configured for state-saving:
  • ICEfaces now provides two custom JSF State Manager implementations:
  • ViewRootStateManagerImpl.java preserves the UIViewRoot between requests. This is the traditional  approach taken by previous ICEfaces releases (though not previously implemented as a custom StateManager) and offers the fastest and most memory efficient way to save state. A limitation of this approach is that the UIComponent structure is not serialized and therefore, failover cannot be supported when using this approach.
  • SingleCopyStateManagerImpl.java implements virtually the same algorithm that the default JSF State Manager uses, with the exception that it only saves one copy per View, and makes some accomodations for ICEfaces unique Ajax Push features. This approach is required in deployments where serialization of the saved state is required, such as in clustered fail-over deployments. Note that this state saving implementation consumes significantly more server memory and CPU resources than the ViewRootStateManager, so it should be used only as required.
  • The ViewRootStateManager is configured by default in the faces-config.xml included in the icefaces.jar.
  • The ICEfaces configuration parameter com.icesoft.faces.doJSFStateManagement is no longer valid or required (deprecated).
  • State-saving is not supported in JSF1.1 environments, the legacy approach of retaining the view root is automatically used when running in a JSF 1.1 environment.
  • Client-side state-saving is not supported.

• Improved Application Server Support. This version of ICEfaces has been certified on the following recently-released application servers:
• Sun Glassfish v2.1
• Sun Glassfish v3 "Prelude"
• JBoss v5.0
• IBM WebSphere v7.0

• Clustered Fail-Over Support for JBoss. Support for clustered fail-over deployments of asynchronous ICEfaces applications on JBoss application servers has been added in this release.

• Support for Glassfish v3 Prelude "Grizzly" ARP. Support for "Grizzly" Asynchronous Request Processing (ARP) on Glassfish v3 Prelude has been added in this release.

• 3rd Party Libraries
• The Sun JSF 1.2 runtime libraries included in the icefaces/lib directory has been updated to JSF1.2_12.
• The commons-beansutils.jar included in the icefaces/lib directory has been updated to v1.8.0.
• The commons-discovery.jar included in the icefaces/lib directory has been updated to v0.4.
• The jstl.jar included in the icefaces/lib directory has been updated to v1.1.2.

• Documentation
  
  
  • ICEfaces Developer's Guide. The ICEfaces Developer's Guide has been revised for changes in 1.8. It should be considered in draft form in this release.

• Sample Applications
  
  
  • Component Showcase
  • Added preliminary demos for the following new components:
  • ice:dataExporter
  • ice:setEventPhase
  • Enhanced the Download Resources demo to illustrate a use-case whereby a resource file is dynamically generated after the user requests it.
  • Added a German language translation resource file for the Component Showcase sample applications. We are seeking community contributors to provide additional language language translation files. If you are interested see the How To Contribute page for more information.

Changes in v1.8 DR#2 

ICEfaces v1.8 DR#2 is a Development Build that provides an early-access preview of new features, enhancements, and fixes that will be included in the upcoming ICEfaces v1.8 release. This build has been lightly tested and is unsuitable for production use.

Review the Known Issues prior to using this release. Please report any issues with this build to the ICEfaces Development Build Feedback forum.

This release includes over 100 fixes and enhancements. Refer to the ICEfaces JIRA Change Log for detailed information on all the changes included in this release.

Notable Improvements & Enhancements

• Framework 
  
  
  • Support for Clustered Fail-Over. ICEfaces now supports clustered fail-over configurations whereby an ICEfaces application can be run in a clustered deployment and, when a failure one one server node in the cluster occurs, user sessions are seamlessly transferred to another node in the cluster (without interruption to the users). 
  • Fail-over is generally supported for synchronous mode applications (com.icesoft.faces.synchronousUpdate="true" in web.xml).
  • For asynchronous mode (Ajax Push) applications, fail-over support requires specific coding practices and application server and load-balancer combinations.
  • For more information, see the new ICEfacesFailOverGuide.pdf included in the ../icefaces/docs directory. This guide provides detailed instructions on using asynchronous failure with Tomcat 6 and Apache 2.2. For information on using asynchronous fail-over with other app. server / load balancer combinations please contact ICEfaces product support.
  
  
  • Support for JSF State-Saving. In previous releases ICEfaces used a persistent component-tree model but starting with this release JSF state-saving is now supported. 
  • ICEfaces now uses state-saving by default when running in JSF1.2 runtime environments (equiv. to com.icesoft.faces.doJSFStateManagement="true" in web.xml).
  • State-saving is neither supported, nor enabled by default, in JSF1.1 environments.
  • Client-side state-saving is not supported.
  • ICEfaces support for state-saving has not been optimized in this release.

• JSF 1.2 Support. ICEfaces can now be used in JSF 1.2 environments utilizing the JSF 1.2 document schemas for the faces-config.xml and web.xml files when used with Sun JSF 1.2_09 or greater. Previous ICEfaces versions (and  1.7.2+ used with older JSF 1.2 runtimes) still require the use of the JSF 1.1 document DTDs (so-called "compatibility mode").
  

• SessionRenderer is now an official API.  The SessionRenderer API was introduced as an experimental API in ICEfaces 1.7.1. Based on positive feedback from the community it has been repackaged and is now an official API (as of 1.8 DR#2). The SessionRenderer provides a very simple API for adding Ajax Push into ICEfaces applications that don't require the more specialized asynchronous update capabilities provided by the existing RenderManager API. 
• Former package-name (experimental): org.icefaces.x.core.push.SessionRenderer.
• New package-name (official): com.icesoft.faces.async.render.SessionRenderer.
• Existing applications utilizing the SessionRenderer will need to be updated to use the new package-name.

• Improved Browser Support. Support for the following new browsers is added in this release:
• BlackBerry Bold
• Preliminary support for using ICEfaces on RIM Blackberry devices is provided in this release.
• Requires newer Blackberry browser capable of supporting Ajax applications, such as that available on the Blackberry Bold.
• See ICE-3574 for more information.
• Google Chrome v1.0
• Microsoft Internet Explorer v8 (beta)

• 3rd Party Libraries
• The Sun JSF 1.2 runtime libraries included in the icefaces/lib directory has been updated to JSF1.2_10.
• The commons-fileupload.jar included in the icefaces/lib directory has been updated to v1.2.1.

• Asynchronous HTTP Server (AHS)
  
  
  • Simplified AHS Configuration. The ICEfaces AHS packages are now included in the core icefaces.jar and just-ice.jar libraries. Previously the standalone icefaces-ahs.jar was required to use AHS.  
  • In order to configure your application to use AHS you must now specify "icefaces-ahs" as the blockingRequestHandler in the web.xml file via the com.icesoft.faces.blockingRequestHandler configuration parameter. Previously, AHS would be auto-configured for use if the icefaces-ahs.jar was detected on the classpath.

• Sample Applications
  
  
  • New "timezone-failover" tutorial
  • Demonstrates using ICEfaces Ajax-push techniques in a clustered fail-over environment.
  • Can be found in the "../icefaces/samples/tutorial/timezone-failover" directory.
  • For more information, see the new ICEfacesFailOverGuide.pdf included in the ../icefaces/docs directory.
  
  
  • Component Showcase
  • Added support for user-selectable languages (dynamic locale change) in the Component Showcase sample applications. This release includes resource files for English and Spanish. We are seeking community contributors to provide additional language language translation files. If you are interested see the How To Contribute page for more information.
  • Examples of using standard JSF validators have been added to the "Text Entry" demo under "Extended Components".

• 3rd Party Frameworks
  
  
  • JAAS Security
  • JAAS security is now supported for user-role authentication (renderedOnUserRole, enabledOnUserRole, etc.).

Documentation Changes

• ICEfaces Developer's Guide 

• com.icesoft.faces.doJSFStateManagement, default value = true.

  Specifies whether or not ICEfaces uses JSF state-saving to persist component state between renders. The default value is 'true'. When set to 'false' ICEfaces will revert to a long-lived component-tree model which does note utilize JSF state-saving mechanisms.

  Note: JSF state-saving is not supported for JSF1.1 runtime environments. Client-side state-saving is not supported.

Changes in v1.8 DR#1

ICEfaces v1.8 DR#1 is a Development Build that provides an early-access preview of new features, enhancements, and fixes that will be included in the upcoming ICEfaces v1.8 release. This build has been lightly tested and is unsuitable for production use.

Review the Known Issues prior to using this release.

You may report any issues with this build to the ICEfaces Development Build Feedback forum.

Notable Improvements & Enhancements

• Framework Optimization
  
  
  • Significant changes to ICEfaces' internal implementation were made in this release as part of a comprehensive memory and CPU optimization effort. These changes do not affect backwards-compatibility.
  • Typical Java heap consumption is reduced approx. 30-50% in this release vs. 1.7.x, varying depending on the use of the new "compressDOM" feature and the nature of the application.
  • Server-side rendering performance in this release has been improved approx. 10% - 25% for the same content vs. 1.7.2.
  • ICEfaces now supports optional compression of the server-side DOM to reduce Java heap consumption between view renders.
  • Additional configuration parameters related to new optimization features have been introduced in this release. See the "Documentation" section in Known Issues for details.

• Sample Applications
  
  • New "Location" portlet sample
  • Demonstrates using ICEfaces Ajax-push techniques for inter-portlet communication between three different ICEfaces portlets.
  • Can be found in the "../icefaces/samples/portlet/location" directory.
  • Also included in the ICEfaces 1.7.2 release.
  • Component Showcase
  • The "Source" view feature in the facelets-enh version of the ICEfaces Component Showcase application has been enhanced to support code syntax highlighting.

• 3rd Party Frameworks
  
  
  • Spring WebFlow 2.0
  • An known-issue in ICEfaces 1.7.2 that prevented forced-login-redirects from working properly has been resolved in this release.

Refer to the ICEfaces JIRA Change Log for detailed information on all the changes included in this release.

Supported Platforms

This release of ICEfaces has been verified on the following platforms:

Java

ICEfaces is supported on the following Java versions:

• JDK 1.4 and greater
• MyFaces and Sun JSF 1.1 runtimes
• Sun JSF 1.2 runtime

Browsers

Vendor	Product	Version
Apple	Safari	3.x
Google	Chrome	1.0
Microsoft	Internet Explorer	6, 7, 8-RC1
Mozilla	Firefox	2.0, 3.0
Opera	Opera	9.x

Mobile Browsers

Vendor	Product	Platform	Version
Apple	Safari	iPhone, iPod Touch	1.x, 2.x
Opera	Opera Mobile	Windows Mobile	8.65, 9.21b2
RIM	Blackberry	Blackberry Bold	All

Application Servers

Vendor	Product	Version
Apache	Tomcat	5.5, 6.0
BEA Systems Inc.	Weblogic Server	8.1, 9.2, 10.3
JBoss Inc.	JBoss Application Server	4.0.5, 4.2.x, 5.0
IBM	Websphere Application Server	6.0.2, 6.1, 7.0
Oracle	Oracle Application Server Container for J2EE (OC4J)	10.1.3
SAP	NetWeaver	7.0
Sun Microsystems	GlassFish	v2.x, v3 Prelude
Sun Microsystems	Sun Java System Application Server	8.1, 9.x
Webtide	Jetty	6.1.x

Portal Containers

Vendor	Product	Version
Apache	Pluto	1.1.4
Apache	Jetspeed 2	2.1.3
BEA	WebLogic Portal	10
Liferay	Liferay Portal	4.3.x, 5.x
RedHat	JBoss Portal	2.6.x

IDE Tools

ICEfaces IDE integration bundles are available for the following development tools:

Vendor	Product	Version
Eclipse	Eclipse/Web Tools Platform	3.4
Genuitec LLC	MyEclipse Enterprise Workbench	6.5, 7.x
Sun	NetBeans	6.5

Note: Tool integration bundles may be updated independently from ICEfaces releases. Refer to
http://downloads.icefaces.org for the most recent tool bundles and associated ICEfaces runtime libraries.

Note: ICEfaces can generally be used with any Java IDE that supports JEE 1.4 0 (+JSF) and JEE 1.5 projects. If a specific ICEfaces integration is not available for your IDE, ICEfaces can be manually included into your project classpath. See the ICEfaces Tools forum and Tutorials for more information on using ICEfaces with a variety of IDEs.

Known Issues

The following section describes the most commonly encountered known issues with this release. For a complete reference of all outstanding issues please refer to the ICEfaces.org JIRA issue tracker.

General

• If at any time the asynchronous connection between the browser and the server is lost due to a network interruption, reloading the page will generally restore normal operation from the previous application state.

• ICEfaces pages included via <jsp:include> or <tiles:insert> have distinct PersistentFacesContext objects even if they are included by the same parent page. For this reason, application-initiated renders will apply only to the inclusion associated with the particular PersistentFacesContext.

• Inclusion of ICEfaces content from JSP is not compatible with MyFaces.

• Attempting to retrieve a Request parameter in the url using the following syntax is not supported (returns null):
     FacesContext.getCurrentInstance().getExternalContext().getRequestParameterMap().get(paramName);
  A workaround for this issue is to retrieve the Request parameter using the following alternative syntax:
   ((HttpServletRequest)FacesContext.getCurrentInstance().getExternalContext().getRequest()).getParameter(paramName);

• Cookies can be set though the ((BridgeExternalContext) FacesContext.getCurrentInstance().getExternalContext()).addCookie(new Cookie("test","test")); method.

• If you are using the Sun JSF 1.2 RI and experience the following exception:
  "javax.faces.application.ViewExpiredException: viewId:/xxx.iface - View /xxx.iface could not be restored. at com.sun.faces.lifecycle.RestoreViewPhase.execute(RestoreViewPhase.java:xxx)"
  It may be necessary to include the following configuration in web.xml:
  
  <context-param>
   <param-name>com.sun.faces.enableRestoreView11Compatibility</param-name>
   <param-value>true</param-value>
</context-param>

JSP Markup

• UIComponentBodyTag processing supports only a single call to doAfterBody(). The full JSP lifecycle for iterative body processing is not supported.

• The first-generation children of the DataTable's table-header and column-header facets must be standard JSF components. For example, plain markup cannot be contained on its own within these facets, it must be wrapped in a panelGrid and the panelGrid, in turn, can be contained within the facet.

• JSP Page to Document conversion escapes &nbsp, but &nbsp in JSP Documents must be manually escaped by the developer as &amp;nbsp. Similarly, & characters must be escaped as &amp;.

• Non-JSF JSP tags (<jsp:xxx/>, etc.) embedded in JSP Pages and Documents are ignored by the ICEfaces parser with the exception of the inclusion mechanism (see Markup Reference in Developer's Guide for details).

• Java code (<% ...%>, etc.) embedded in JSP Pages and Documents is ignored by the ICEfaces parser with the exception of the inclusion mechanism (see Markup Reference in Developer's Guide for details).

• Input documents must be well-formed XML.

• Deprecated HTML elements, specifically the FONT element, do not respond properly to DOM manipulation functions in the ICEfaces client-side JavaScript bridge. (see HTML 4.01 Specification for details on deprecated HTML Elements).

• Pages should contain both a <head> tag and a <body> tag so that they are well-formed XHTML and ICEfaces can easily add a link to its own custom JavaScript library.

• Any ICEfaces page included from a JSP via <jsp:include/> must contain a <body> tag as the content of the <body> tag is precisely the content inserted into the including page.

• Tiles tags are not supported within ICEfaces pages, but ICEfaces pages may be included via Tiles.

• If multiple ICEfaces inclusions are performed by the same parent JSP, each ICEfaces form must have a manually applied unique ID.

• JSP Pages are dynamically converted to JSP Documents for processing by the ICEfaces parser, so it is important not to mix JSP Page and JSP Document types when performing static inclusion.

• UTF-8 encoding must be used for all source files for ICEfaces (jsp jspx, etc.)

ICEfaces Component Suite

• All ICEfaces Component Suite components must be enclosed in a JSF form component (i.e. ice:form, h:form, or ui:form).

• Effects (various components)
  • In Internet Explorer the Fade, Appear, and Pulsate effects will not transition when used with select elements.
  • In Safari the Highlight effect will does not work on buttons and lists.

• gMap 
  • Requires an API key which must be obtained from the Google Maps website.
  • Client browser must be able to access the Google Maps website URL (http://maps.google.com)

• menuPopup
  • menuPopup is not supported in the Opera browser due to a browser security feature that prevents the override of the browser's own context menu.

• inputRichText
  • The FCKeditor JavaScript library that is the basis for the ice:inputRichText component does not currently support the Opera browser.

• outputChart
  • When using the ice:outputChart component with IE6 the following warning log messages may appear in the ICEfaces server log:  "java.net.SocketException: Connection reset by peer: socket write error". This is the result of IE6 closing connections abruptly and is a browser quirk. It has no impact on the functionality of the component.

Portlets

• The following ICEfaces components are known not to work correctly in a portlet environment:
  • ice:gMapDirection
  • ice:inputRichText - using this component in more than one portlet on a page may cause problems with the functioning of this component.
  • Drag & drop (via ice:panelGroup) - using drag-and-drop in more than one portlet on a page may cause drag-and-drop to not function in some of the portlets on the page.

• When using ICEfaces with Liferay Portal positioning problems may occur with components that rely on dynamic positioning, such as ice:panelPopup, ice:menuBar, and menuPopup. This issue is related to an aggressive styling behavior in Liferay and there is a work-around identified. See ICE-2967 for details.

• The ICEfaces Component Showcase portlet sample application may have styling and layout related issues related to the specific portal container and portal theme being used. The primary intention is to show component functionality in a portlet context. It may be necessary to customize the specific styles being used to work well within the portal theme, etc.

• Liferay 5.2.x automatically compresses all resources being served by the Portal container. By default this will conflict with ICEfaces automatic resource compression. When running with Liferay 5.2.x it is necessary to either disable Liferay's resource compression, or disable ICEfaces resource compression by specifying the "com.icesoft.faces.compressResources=false" configuration parameter setting in the web.xml file.

Spring WebFlow

• In Spring WebFlow 2.0.5 there is a ViewHandler delegation issue that prevents the logic that determines whether a view is restorable from working correctly resulting in the flow being continuously restarted. A workaround is to define a Spring FlowViewHandler in the application faces-config.xml file. 


<application>

<view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
<view-handler>com.icesoft.faces.facelets.D2DFaceletViewHandler</view-handler>
<view-handler>org.springframework.faces.webflow.FlowViewHandler</view-handler>
<variable-resolver>org.springframework.web.jsf.DelegatingVariableResolver</variable-resolver>

</application>

Sample Applications

• Of the four varieties of the Component Showcase application (jsp, portlet, portlet-enh, and portlets), only the facelet-enh version includes the Description and Source tabs for viewing documentation and resources related to the  components being demonstrated.

• The Component Showcase enhanced facelets sample application  (icefaces/samples/component-showcase/facelet-enh) requires JDK 1.5 to compile and run. All other samples in this release require JDK 1.4+.

Application Servers

• General

• Due to an apparent bug in Tomcat 5.x, users have occasionally reported seeing the following error when using ICEfaces with Tomcat 5.x or JBoss 4.0.x: "SEVERE: ICEfaces could not initialize JavaServer Faces. Please check that the JSF .jar files are installed correctly." This issue can be resolved by including the following listener in the web.xml:
  
  <listener>
    <listener-class>
       com.sun.faces.config.ConfigureListener
    </listener-class>
</listener>

• Apache Tomcat v5.5

• Tutorials bundled with the ICEfaces release will not build and deploy to Tomcat 5.5 with MyFaces due to a conflict related to jsp-api.jar.  To build and deploy tutorials on Tomcat 5.5 with MyFaces, it is necessary to modify the .../install_dir/ICEfaces-1.5/icefaces/samples/tutorial/build.properties and set tomcat55=true prior to building the application.

• Apache Tomcat v6.0

• To use ICEfaces with Tomcat v6.0 these jars that are included in the ICEfaces distribution must be removed from the web application (note that the sample application build script target for Tomcat 6 will include the correct .jars in the .war file):
  • el-api.jar
  • xercesImpl.jar
  • xml-apis.jar

• Tomcat v6.0 / JBoss 4.2 with NIO Connector

• When using the optional Tomcat 6 NIO connector (can also be used with JBoss 4.2) with asynchronous ICEfaces applications a NullPointerException can be thrown when using the TomcatPushServlet (located in the com.icesoft.faces.webapp.http.servlet package) due to Tomcat recycling objects that are still in use by the TomcatPushServlet. The issue seems to be timing related and is more apparent with multiple users.
• Workarounds for this issue include not configuring the optional Tomcat NIO connector and configuring the ICEfaces AHS server configuration for NIO asynchronous communications instead.

• Sun Glassfish v2.1

• Due to a bug in the JSF RI included in the Glassfish v2.1 distribution (v1.2_04), exception redirection may not work correctly with ICEfaces. The work-around is to install or use Sun JSF RI 1.2_05 or newer.

• BEA Weblogic Server 9

• In order to run ICEfaces on the BEA Weblogic Server 9, the html and core tld files located in jsf-impl.jar should be extracted from the jar file and placed into the WEB-INF folder of any application you want to deploy.

• Websphere Application Server 6.0.0.1, 6.1

• Websphere requires a special class-loader configuration for use with ICEfaces. See the Application Server Deployment Guides in the ICEfaces knowledge-base for details.

• A bug in the application server prevents the Timezone Step 3+ tutorials from running correctly. A WebSphere patch is available from IBM that resolves this issue: APAR numberPQ99195, http://www-1.ibm.com/support/docview.wss?rs=180&uid=swg1PQ99195.

Support

Open source community support is available at http://www.icefaces.org.

For information on commercial support, professional services, and training, please visit http://support.icefaces.org.

About ICEfaces

ICEfaces delivers extensions to Java ServerFaces (JSF) that provide an AJAX-enabled rich presentation environment for JSF applications. ICEfaces brings value to any Java EE development project that needs to provide superior presentation capabilities to the web application user. In particular, ICEfaces provides the following features:

• Smooth, incremental page updates that do not require a full page refresh to achieve presentation changes in the application.
• Server-initiated asynchronous presentation updates for dynamic instantaneous data push (Ajax Push/Comet).
• The ICEfaces Component Suite, a complete rich JSF component suite that fully leverages ICEfaces capabilities.
• Intelligent form processing that facilitates fine-grained interactions with the user as they manipulate a form.
• API support for rapid development of group-aware and collaborative applications, such as Chat, Webcast, social applications, etc.
• JSP or Facelets based development.
• Tool integrations for leading Java IDEs.
• Support for leading Java EE frameworks, such as Spring and JBoss Seam.
• Support for portlet development.

Learn More

This ICEfaces release comes with extensive documentation that will help you understand the product thoroughly. Documentation for this release is located in your installation directory at .../install_dir/icefaces/docs/. The following documents are provided in PDF format:

1. ICEfaces Getting Started Guide: This guide takes you through product installation, environment configuration, demo app installation, and a basic 7-stage tutorial. This guide also contains information related to support for different application server environments and development tools.
2. ICEfaces Developer's Guide: This guide contains information relevant to developing applications with ICEfaces. It describes the ICEfaces architecture, and explains key concepts that the ICEfaces developer should be aware of. It also provides a complete reference guide that covers APIs, configuration, components (including the ICEfaces Component Suite) and TLDs, and covers advanced topics like server-initiated rendering.

ICEfaces documentation is also available on-line at http://documentation.icefaces.org/.

License Notice

License agreements can be found in the .../install_dir/icefaces/docs/license directory.

© Copyright 2005-2009 ICEsoft Technologies, Inc.