ICEfaces® v1.8.1 Release Notes

Overview

This document contains the following sections:

Changes in v1.8.1 (This Release)
Changes in v1.8.0
Migration Notes
Supported Platforms
Known Issues
Support
About ICEfaces
License information

Changes in v1.8.1 (This Release)

ICEfaces v1.8.1 is a maintenance release featuring over 60 fixes and improvements.

Review the Known Issues prior to using this release. Review the Migration Notes if you plan to use an existing ICEfaces 1.7.x application with 1.8.x.

Please report any issues with this release to the ICEfaces forums or the ICEfaces JIRA issue tracker.

Notable Improvements & Enhancements

ICEfaces Component Suite
- The ice:inputTextarea component has been enhanced to support the "maxlength" attribute.
- The ice:outputChart now supports the horizontal orientation for the "barstacked" chart-type.
- The ice:dataExporter component has been improved to support both the generation of an export file and the initiation of the download of the file in response to a single user click, instead of the previously required two clicks. As a result, the 'clickToCreateFileText' attribute has been deprecated in this release and is now a no-op attribute.
- The ice:outputStyle component now supports Internet Explorer 8 (IE8), such that an IE8-specific theme css file will automatically be included in the page when using IE8.
- The ice:inputRichText component has been updated to use FCKeditor library v2.6.4.
- The ice:menuBar component has been improved to avoid displaying child menus off the top of the visible viewport, in addition to the previous positioning enhancements included in 1.8.0.
- The ice:panelGroup's drag & drop features have been improved to resolve some issues when using drag & drop within scrollable <DIV>s in the IE browser browser. In addition, a Scriptaculous bug that prevented the Drop event.getTargetDropValue() method from returning the correct value has been resolved. Note that a new "dropTargetScrollerId" attribute must be specified in some cases to avoid this issue. See the TLD documentation for this component for details.
- The TLD documentation for the ice:inputFile component has been updated to warn against performing long-running operations in the actionListener for this component as doing so may result in the inputFile component disappearing in browser.

Framework

Support has been added for the Facelets ui:debug tag in this release. To enable this feature press Ctrl-Shift-D in your browser.
Preliminary support for the Google App. Engine application hosting environment has been added in this release, with certain limitations. See JIRA ICE-4394 for details.
A navigation issue related to ICEfaces handling of a redirect from a forwarded page has been resolved to align with the JSF RI's behavior, as well as ICEfaces behavior prior to 1.7.2. See JIRA ICE-4428 for details.
An issue introduced in 1.8.0 that resulted in request-scoped beans being disposed and recreated upon a page reload when "concurrentDOMViews=false" and "standardRequestScope=false" has been resolved. See JIRA ICE-4459 for details.
An issue that could cause browser focus to be lost when a partialSubmit was triggered from an inputText component has been resolved. This issue was limited to Internet Explorer (IE) browsers. For more information, refer to JIRA ICE-4461.
An issue that could cause an UnsupportedOperationException to be thrown when using JBoss Portal 2.6.x has been resolved.
An issue that could cause push operations to stop working when viewing multiple asynchronous ICEfaces applications in the Opera 9.6.x browser has been fixed.

Sample Applications
- Component Showcase

Documentation

API JavaDoc

The API JavaDoc for the new SessionRenderer API introduced in 1.8.0 was incorrectly ommitted from the API JavaDoc in that release. It has been added in 1.8.1.

ICEfaces Developer's Guide

To clarify the "Push Server" section in "Chapter 5 - Advanced Topics" section on pg. 74 - the Push Server MUST always be deployed with asynchronous ICEfaces portlets or the push functions of these portlets will not work.
The usage example in the Bridge Connection Status Events section in "Chapter 4 - ICEfaces Reference Information", on pg. 28 is incorrect. The corrected usage example is noted below:

<body>

...

<script type="text/javascript">

 Ice.onSessionExpired('document:body', function() {

 alert('Session has expired!');

});

</script>

...

</body>

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

Changes in v1.8.0

ICEfaces v1.8.0 is a certified production release featuring over 350 enhancements, improvements, and bug fixes.

Review the Known Issues prior to using this release. Review the Migration Notes if you plan to use an existing ICEfaces application with 1.8.

Please report any issues with this release to the ICEfaces forums or the ICEfaces JIRA issue tracker.

Notable Improvements & Enhancements

ICEfaces Component Suite
- New Confirmation Panel component
- New Data Export component

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.

New support for Date & Time entry

The ice:selectInputDate component has been enhanced to support entering 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)

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.

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.

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.

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.

Simplified File Upload Progress

The ice:inputFile component has been enhanced to simply the application-level code required to present upload progress to the user. These changes apply to both synchronous and asynchronous applications.
See the ice:inputFile TLD documentation for details.

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.
A new "preStyleOnSelection" attribute has been added to the ice:rowSelector component. When "preStyleOnSelection=true" the perceived responsiveness of the ice:rowSelector is improved by applying row selection style changes in the browser client prior to the server roundtrip associated with the row selection event.

Framework

Memory & Performance Optimizations. 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% vs. 1.7.2, varying depending on the nature of the application and the use of the new "compressDOM" configuration parameter.
- Server-side rendering performance has been improved up to 30% for the same content vs. 1.7.2.
- Several new optimization configuration parameters are available, see the "Optimizing Server Memory Consumption" section on page 64 of the ICEfaces Developer's Guide for details.

Clustered Fail-Over Support. This release introduces support for clustered fail-over for high-availability ICEfaces applications.

Asynchronous ICEfaces applications (Ajax Push) require the Enterprise Push Server to support clustered fail-over configurations.
Synchronous-mode ICEfaces applications can deployed into clustered fail-over configurations without any additional requirements.

Improvements to JSF State-Saving. Support for JSF state saving has been improved to reduce memory consumption and lower 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.
As the configuration mechanism has changed, the ICEfaces com.icesoft.faces.doJSFStateManagement configuration parameter is no longer supported.
Note that 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 JSF 1.2 Support. ICEfaces can now be used in JSF 1.2 runtime 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.8.0 when used with older JSF 1.2 runtimes) 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. 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.

New user-interface "busy" state indicator. The ICEfaces bridge has been enhanced to support a new "busy" indicator and user-interaction blocking mechanism.

When enabled, users will 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.
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 disabled by default, but may be enabled by specifying "com.icesoft.faces.blockUIOnSubmit=true" 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)

Improved Browser Support. Support for the following new browsers is added in this release:

Apple Safari 4.0 Beta
BlackBerry Bold
Google Chrome v1.0
Microsoft Internet Explorer 8 (IE8)

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

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

3rd Party Frameworks
- Spring WebFlow 2.0
- JAAS Security

New Push Server for Asynchronous (Ajax Push) Applications
- A new 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.
- The Push Server is recommended to be deployed with all asynchronous ICEfaces applications.
- The Push Server is a functional replacement for the Asynchronous HTTP Server (AHS), which is not supported with this release.
- See the "Push Server" section on pg. 74 of the ICEfaces Developer's Guide for more information.

Sample Applications
- Component Showcase
- New "Location" portlet sample
- Sample Application Ant Builds

Documentation

ICEfaces Getting Started Guide. The ICEfaces Getting Started Guide has been updated, including the addition of the following new chapter:

"Chapter 5 - ICEfaces SessionRenderer Tutorial: Easy Ajax Push" on pg. 51

ICEfaces Developer's Guide. The ICEfaces Developer's Guide has been significantly revised. The following sections have been added/enhanced:

JavaScript API Reference, pg. 26
ICEfaces Focus Mgmt., pg. 43
ICEfaces Library Dependencies , pg. 46
Server-initiated Rendering (Ajax Push) APIs, pg. 50
State Saving, pg. 62
Optimizing Server Memory Consumption, pg. 64
Connection Management, pg. 66
Push Server, pg. 74
Using ICEfaces in Clustered Environments, pg. 77
JBoss Seam Integration, pg. 91
Spring Web Flow Integration, pg. 97
Appendix A - ICEfaces Library/App. Server Dependencies, pg. 110
Appendix B - ICEfaces Configuration Parameter Overview, pg. 114

3rd Party Libraries

The Sun JSF 1.2 runtime libraries included in the "../icefaces/lib" directory has been updated to JSF1.2_12_b01.
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 commons-fileupload.jar included in the "../icefaces/lib" directory has been updated to v1.2.1.
The jstl.jar included in the "../icefaces/lib" directory has been updated to v1.1.2.

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

Migration Notes

The following changes may affect applications that were originally developed with a previous version of ICEfaces.

Asynchronous ICEfaces applications should be deployed with the new Push Server

Asynchronous ICEfaces applications (push) should now be deployed with the new Push Server.
If you deploy more than one asynchronous ICEfaces application to the same application server/host-name and view more than one of these applications in a single browser (via multiple tabs or windows), the push updates only function correctly for one of the applications. This restriction is due to HTTP 1.1 connection-limit recommendations that many browsers enforce. Changes in 1.8.0 make this issue more prevelant on all browsers than in previous releases.
Note that the Push Server MUST be deployed when using any ICEfaces asynchronous portlets.
See the "Push Server" section on pg. 74 of the ICEfaces Developer's Guide for more information.

Asynchronous HTTP Server (AHS)

The ICEfaces Asynchronous HTTP Server (AHS) is no longer supported with ICEfaces 1.8.0.
If your application was previously configured to use AHS you will need to deploy the new Push Server with your application instead.
See the "Push Server" section on pg. 74 of the ICEfaces Developer's Guide for more information.

Session Renderer API Repackaging

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. If your application uses the SessionRenderer it will need to be updated to reflect the new package name.

Former package-name (experimental): org.icefaces.x.core.push.SessionRenderer.
New package-name (official): com.icesoft.faces.async.render.SessionRenderer

ice:inputFile Component Changes

The behavior and features of the ice:inputFile component have changed to better support indicating progress without requiring as much application-level code.
In previous ICEfaces releases, a technique of using the ICEfaces push APIs (e.g. PersistentFacesState.renderxxx(), RenderManager, etc.) to push progress updates to the browser was used. In this release this technique is unnecesary and deprecated. The specific case of using the PeristentFacesState.render() API can cause nested JSF lifecycles to occur which can cause unpredictable results.
See the ice:inputFile TLD documentation for details.

Glassfish Grizzly ARP Support

If you would like to leverage the Glassfish Grizzly ARP mechanism with ICEfaces 1.8.0 you must include the new "grizzly-compat.jar" in your project classpath. This jar is located in the "../icefaces/libs" directory.

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	2.x, 3.x, 4.0 Beta
Google	Chrome	1.0
Microsoft	Internet Explorer	6, 7, 8
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
IBM	Rational Application Developer (RAD)	7.5
Sun	NetBeans	6.5, 6.7 Beta

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.

Documentation

ICEfaces Developer's Guide

In the "Busy Indicator" section on pg. 32, and also in Appendix B on pg. 116, it incorrectly states that the "com.icesoft.icefaces.blockUIOnSubmit" configuration parameter is "TRUE" by default. In fact, this parameter is "FALSE" (disabled) by default.

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 &nbsp. Similarly, & characters must be escaped as &.

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
- Negative values are not supported in "barstacked" chart-types. This is a limitation of the krysalis.jcharts library used to generate the chart images.
- 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.

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+ 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.

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.

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 Enterprise Push Server 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 & 10

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.
When deploying an ICEfaces application that uses the ice:inputFile and/or ice:dataExporter components to WebLogic 9 or 10 you must use an exploded directory copied to the domain's autodeploy directory, rather than simply using .war files or using the console. Otherwise, the file-write operations these components depend on will fail (as there is no writeable directory in a .war file).

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 apps., 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:

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.
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.