ICEfaces® v1.8 DR#1 Release Notes October 20th, 2008

Overview

This document contains the following sections:

• Changes in This Release (v1.8 DR#1)
• Changes in v1.7.2
• Changes in v1.7.1
• Changes in v1.7.0
• 1.6.x to 1.7.x Migration Notes
• Supported Platforms
  • Java 
  • Browsers
  • Application Servers
  • Portal Containers
  • IDE Tools
• Known Issues
  
  • Documentation
  • General
  • JSP Markup
  • ICEfaces Component Suite
  • JSF 1.2
  • Portlets
  • Async HTTP Server (AHS)
  • Sample Applications
  • Application Servers
• Support
• About ICEfaces
• License information

Changes in This Release (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 Changes" section below 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.

Documentation Changes

• ICEfaces Developer's Guide 

• com.icesoft.faces.compressDOM, default value = false.

  Specifies whether or not the server-side DOM should be compressed between view renders to reduce the amount of server heap memory required. Enabling this feature can provide significant memory consumption savings at the cost of some additional CPU cycles to perform the compression. 

• com.icesoft.faces.clientIdPoolMaxSize, default value = 100000.

  Specifies the size of the String pool used for caching client ID strings. The default value of 100,000 requires approx. 1MB of Java heap. Specifying an integer value of 0 will disable the client ID String pool. 

• com.icesoft.faces.cssNamePoolMaxSize, default value = 100000.

  Specifies the size of the String pool used for caching CSS class names strings. The default value of 100,000 requires approx. 1MB of Java heap. Specifying an integer value of 0 will disable the CSS class-name String pool. 

• com.icesoft.faces.elPoolMaxSize, default value = 100000.

  Specifies the size of the String pool used for caching EL expression strings. The default value of 100,000 requires approx. 1MB of Java heap. Specifying an integer value of 0 will disable the EL expression String pool. 

• com.icesoft.faces.xhtmlPoolMaxSize, default value = 100000.

  Specifies the size of the String pool used for caching literal XHTML tags and attributes strings. The default value of 100,000 requires approx. 1MB of Java heap. Specifying an integer value of 0 will disable the XHTML tags and attributes String pool. 

• com.icesoft.faces.standardRequestScope, default value = false.

  The behaviour of the standardRequestScope parameter has been slightly modified. The default value is false but, since the Seam framework requires that this be set to true, the ICEfaces framework now checks for Seam integration at runtime and sets standardRequestScope to true if Seam is detected. 

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

Changes in v1.7.2

ICEfaces v1.7.2 is a maintenance release that includes over 100 fixes and improvements. 

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

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

Notable Improvements & Enhancements

• ICEfaces Component Suite
  
  
  • A new ice:outputResource component has been added to ease download of application resources such as report documents (.pdf, .doc), images, etc.
  • An issue that could cause ice:inputFile file uploads to fail intermittently has been resolved.
  • ice:outputText has a new "nospan" attribute, which can be used to disable wrapping of outputText content with a <SPAN> element.
  • The ice:selectInputDate component has a new attribute, "inputTitle" which can be used to specify a "title" attribute on the input element only (only applies when "renderAsPopup=true").
  •  ice:dataTable supports a new attribute, "resizableColumnWidths", which can be used to capture and specify the column widths for each column in a dataTable with user-resizable columns.
  • ice:dataTable supports a new theme CSS styleclass, "iceDatTblActvSrtHdr", which can be used to style the active sort header in a sortable dataTable.
  • The performance of the ice:menuItem renderer has been improved which will result in greatly improved rendering performance for menus with a lot of menuItems. 
  • The "rows" attribute on the ice:selectInputText component is now supported.

• Framework
  
  
  • A new "sessionExpiredRedirectURI" configuration parameter has been added to support automatic redirection to a specified page upon session expiry. See "Documentation Changes" section below for details.
  • The text messages used by the ICEfaces bridge to display error message dialogs ("Connection Lost", "Session Expired", etc.) can now be specified in an application resource bundle for localization and customization. See ICE-3016 for details.
  • A new JavaScript API has been added to the ICEfaces bridge to permit closing and disposing of a view from within JavaScript in the browser. This is useful in situations such as portlet development where the portlet  region in the browser may have a widget to close the portlet. See ICE-3266 for details.
  • The mouse pointer will now change to an hourglass when a partial (or full) submit is pending.
  • New auto-detection and configuration for BEA WebLogic with ICEfaces AHS server.
  • ICEfaces will now automatically revert back to non-AHS async communications mode if the AHS configuration fails at any step. Log output clearly indicates when this occurs.
  • Improved DOMdiffing and serialization algorithm resulting in an approx. 10% performance throughput improvement, with potential for much greater improvement depending on the nature of the application content.
  • A new TRACE level log has been added that will dump the contents of each DOM update to be sent to the client to the log file. Use TRACE level logging for the "com.icesoft.faces.webapp.http.core.SendUpdates" class to enable this logging.
  • The icefaces-facelets.jar has been updated to version 1.1.15.B1 of Facelets.
  • The Sun JSF 1.2 runtime libraries included in the icefaces/lib directory has been updated to JSF1.2_09.

• 3rd Party Framework Support
  
  
  • Spring Web Flow
  • This release includes improved support for Spring WebFlow (v2.0.3). Support is generally complete, but see the Known Issues section for details on a specific outstanding issue.
  • For a usage example see the swf-booking-faces sample project.
  • JBoss Seam
  • Seam exception-redirection is now supported.
  • Seam 2.0.2 deployed to JBoss 4.2.3 (JSF1.2_09) is now supported. 
  • Seam 2.1 RC1 is now supported.
  • ICEfaces will now default to Standard Request mode ("com.icesoft.faces.standardRequestScope=TRUE") if Seam is detected at runtime. If Seam is not present, the normal default of "com.icesoft.faces.standardRequestScope=FALSE" will apply.

Documentation Changes

• ICEfaces Developer's Guide 

• com.icesoft.faces.connectionLostRedirectURI, default value = null.

  Specifies a page URI to redirect the client to when an asynchronous connection is lost. The parameter value must be surrounded by single quotes and an ice:outputConnectionStatus component must be present on the page. Note: This parameter is only applicable to asynchronous  applications as it is the async connection lost event that triggers the redirect (com.icesoft.faces.synchronousUpdate=false, which is the ICEfaces default). 

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

  The compressResources setting is used to tell the ICEfaces framework whether or not to compress (i.e. gzip) internal resources that are served directly by the framework. This includes theme CSS stylesheets, images, JavaScript,  etc. Some browsers can have difficulty with compression (notably IE 6) and compression can be redundant for resources that are already compressed. As of this release, ICEfaces, bu default, applies a list of mime-types to exclude from compression, even if the value is set to true. This list includes: 

  • application/java-archive
  • application/pdf
  • application/x-compress
  • application/x-gzip
  • application/zip
  • audio/x-mpeg
  • image/gif
  • image/jpeg
  • image/png
  • image/tiff
  • video/mp4
  • video/mpeg
  • video/x-sgi-movie

  If you wish to override or supplement this list and provide your own mime-types to be excluded from compression, use the com.icesoft.faces.compressResourcesExclusions parameter.
  

• com.icesoft.faces.compressResourcesExclusions, default value = "image/gif image/png image/jpeg image/tiff application/pdf application/zip application/x-compress application/x-gzip application/java-archive video/x-sgi-movie audio/x-mpeg video/mp4 video/mpeg".

  This parameter is used to override or supplement the default list of mime-types that are excluded from compression by ICEfaces. The compressResourcesExclusions parameter takes a space delimited list of mime types for which compression will not be applied. Please note that if you use this parameter, you are overriding the default list of mime-types that ICEfaces excludes by default and you'll need to specify all the mime-types that you want to exclude, including any of the  mime-types excluded by default.

• com.icesoft.faces.sessionExpiredRedirectURI, default value = null.

  Specifies a page URI to redirect the client to upon session expiry. Redirection will occur immediately when using asynchronous mode, or upon the first partial or full-submit after the session expires in synchronous mode.

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

Changes in v1.7.1

ICEfaces v1.7.1 is a maintenance release that includes over 100 fixes and improvements. 

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

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

Notable Improvements & Enhancements

• Asynchronous Rendering (Ajax Push) 

• New SessionRenderer API
• The new org.icefaces.x.core.push.SessionRenderer API allows an application to initiate rendering asynchronously and independently of user interaction for a session or a group of sessions.
• When a session is rendered, all windows or views that a particular user has open in their session will be updated via Ajax Push with the current application state.
• 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.
• Note: The SessionRenderer, as with all classes in the "org.icefaces.x.*" package, is considered experimental in this release and is subject to non-backwards compatible changes in future releases.
   
• New Broadcast Render capabilities 
• Both the new SessionRenderer API and the existing RenderManager API now support broadcasted renders, whereby a request for a render is broadcasted across the nodes in a cluster, enabling asynchrous (push) updates to span sessions on mutiple nodes in a cluster. 
• To enable broadcasting the com.icesoft.faces.async.render.broadcasted boolean property must be set to true in the web.xml. 
• The com.icesoft.faces.async.render.broadcasted property can be set inside an ICEfaces application's web.xml to enable or disable broadcasting. The RenderManager instance uses this property to set its default value of the broadcasted flag. This can be programmatically changed by using the setBroadcasted(boolean) method. Additionally, an AsyncRenderer can have its own value of the broadcasted flag for fine-grained control:
• If the RenderManager's flag is set to false broadcasting never happens, regardless of the AsyncRenderer's flag.
• If the RenderManager's flag is set to true, broadcasting happens if the AsyncRenderer's flag is set to true as well; otherwise broadcasting does not happen.

• Enhanced RenderManager 
• The RenderManager API has added support for fine-grained control of broadcasted renders as well as added session awareness.

• ICEfaces Component Suite
  
  
  • New ice:outputHtml, ice:outputHead, and ice:outputBody components have been added to support environments that require JSF components for all significant page elements, such as the NetBeans 6.1 Visual Designer.
  • The ice:dataTable footer can now optionally be rendered outside of the scrollable region via the new "scrollFooter" attribute on the dataTable component.
  • The ice:inputFile component is now easier to use in asynchronous update mode, and offers improved support for use in synchronous mode.
  • The ice:selectInputDate component can now optionally display drop-down lists for rapid selection of months and years. See the new "renderMonthAsDropdown" and "renderYearAsDropdown" attributes in the TLD documentation for details.
  • The ice:graphicImage component can now accept a byte[] for the image instead of a URL, which provides better support for rendering images from databases, blobs, etc.
  • The ice:panelPositioned component can now accept an Array in addition to the existing List types.
  • The ice:inputRichText component can now optionally save it's value with each form submit or partialSubmit, instead of requiring the user to first select the "Save" toolbar button. Use the new "saveOnSubmit" boolean attribute to enable this behavior.
  • The ice:panelPopup can now be configured to not partialSubmit it's form after each drag event via the new "clientOnly" boolean attribute.
  • Clicking on the label for an ice:selectManyCheckbox or ice:selectOneRadio will now toggle or select the corresponding checkbox or radiobutton.
  • Resizable dataTable Columns will now retain user-adjusted column widths across page refreshes, dataPaginator pages changes, etc.

• Framework
  
  
  • New auto-detection and configuration for Glassfish Grizzly ARP (Asynchronous Request Processing). See the updated configuration documentation in the "Documentation Changes" section below for details.
  • Using ICEfaces AHS together with Glassfish v2 is now supported.
  • A potential memory leak when using concurrentDomViews=true has been corrected.
  • The Firefox v3.0 and Opera v9.5 browsers are now officially supported.

• 3rd Party Framework Support
  
  
  • Spring Web Flow
  • This release includes preliminary support for Spring Web Flow v2.0 (final). ICEfaces 1.7.0 had support for SWFL 2.0 M4, but the SWFL APIs had changed significantly between the M4 milestone release and the Spring Web Flow v2.0 final release.
  • JBoss Seam
  • The Seam Mail feature is now supported.
  • Seam workspaces (Conversation switching) is now supported.

Documentation Changes

• ICEfaces Developer's Guide 

• Remove Step 1 (configuring the GrizzlyPushServlet) under "To configure ICEfaces to use Grizzly:". Beginning with ICEfaces 1.7.1 this configuration step is no longer required or supported. Note that Step 2 ("Add the cometSupport property to your http-listener") is still required.
• ICEfaces will now auto-detect GlassFish + Grizzly and will try to use the ARP capabilities of Grizzly if they are enabled. To disable using the ARP facilities of Glassfish Grizzly and Jetty, the com.icesoft.faces.useARP property can be set to false inside the web.xml. Note that the previous Jetty-specific com.icesoft.faces.useJettyContinuations configuration parameter can still be used but is now deprecated.
• If this auto-configuration fails, ICEfaces will revert to using the traditional Thread Blocking async IO mechanism. You can verify that ICEfaces is using the Grizzly ARP mechanism by reviewing the ICEfaces log file (at INFO level). The following log messages may be present:
• GlassFish ARP available: true
• Adapting to GlassFish ARP environment
• Failed to add Comet handler... (if ARP configuration fails only)
• Falling back to Thread Blocking environment (if ARP configuration fails only)

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

Changes in v1.7.0

ICEfaces v1.7.0 is a certified production release featuring over 450 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.7. 

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

ICEfaces Component Suite

• New Theme 
  • A new CSS style theme has been added in this release, "Rime".
  • Provides a fresh new look for the ICEfaces Components and a great starting of point for your own applications.

• New Tooltip Panel 
  • The new ice:panelTooltip component can be associated with a panelGroup component to automatically display when the user hovers over the panelGroup for a configurable period of time.
  • Can be configured to automatically hide when the user moves the mouse off the triggering component or  clicks outside the panelTooltip.
  • Supports both a static and dynamic usage mode so it's contents may be updated based on the source component triggering its display.

• New Popup/Context Menu
  • A new ice:menuPopup component can be associated to any panelGroup component to display a popup context menu when the user clicks the context menu (typically rt-mouse button) button over the panelGroup.
  • Can also be used on UIData components such as ice:dataTable and ice:panelSeries.

• New Divider Panel  (Split Pane)
  • New ice:panelDivider component can be used to divide a region of the page that contains two child panels or components. The user can drag the divider to resize the child component regions. 
  • Supports both vertical and horizontal orientations

• New Google Map Component
  • ice:gMap component supports display of interactive Google Maps.
  • Supports additional functionality via the following optional child components:
    • ice:gMapControl
    • ice:gMapDirection
    • ice:gMapGeoXml
    • ice:gMapLatLng
    • ice:gMapLatLngs
    • ice:gMapMarker

• New Portlet  Component
  • ICEfaces portlets must be contained within the new "ice:portlet" component.

• New Rich Text Editor Component 
  • New ice:inputRichText component provides comprehensive support for editing rich text and html content.
  • Leverages the industry-leading FCKeditor JavaScript library.    

• New Media Player Component 
  • New ice:outputMedia component supports embedding media players in your ICEfaces page.
  • Supported formats include Flash, WMV, RealPlayer, and Quicktime.

• New Layout Panel
  • The new ice:panelLayout component provides support for relative positioning of components within the panel, such as when using IDEs that support visual  design of JSP or Facelet pages.

• Data Table Enhancements
  • User-resizable datatable columns (drag column header border to resize column)
  • Headers can now span multiple rows and columns
  • Row-level grouping - individual cells can span multiple dataTable rows

• Improved Partial Submit Messages Support
  • ICEfaces input components that are in an invalid state as a result of user-interactions will now continue to display their error messages in any associated ice:message or ice:messages components, even after subsequent input components with "partialSubmit=true" are processed.

• New SelectOneRadio, SelectManyCheckbox Layout and Grouping Options
  • The ice:selectOneRadio and ice:selectManyCheckbox components can now support a "spread" layout capability that enables each radioButton or checkbox to be placed in different container components (e.g. across columns in a table, etc.).

• New Popup Panel Auto-Positioning
  • The ice:panelPopup component now supports active auto-positioning behaviors:
    • Auto Center: Positions the popup in the center of the page.
    • Auto Position: Positions the popup at the specified coordinates over the page.

• New activation mode for MenuBar
  • The ice:menuBar component has been enhanced to support a new "displayOnClick" attribute. When set the child menus will not display until one of the root-level menu-items is clicked on with the mouse.

• Connection Status Component with Error Dialogs
  • The ice:outputConnectionStatus component has been enhanced to optionally display popup error dialogs for session expiry or connection lost errors.

• Improved Drag & Drop Performance and Scalability
  • The panelGroup's draggable implemention has been optimized to drastically improve performance and scalabiliy when a large number of instances are used on a page, such as in dataTable rows or treeNodes.

• XHTML Compliance
  • The ICEfaces Component Suite components now render browser markup that is XHTML v1.0 Transitional compliant, as defined by the W3C specification.

Framework & Bridge

• Improved Asynchronous Connection Mgmt. and Robustness
  • Asynchronous connection mgmt. has been improved to reduce the frequency of "Connection Lost" failures.
  • Default connection settings values have been adjusted to be more tolerant of connections with higher latency.
  • Issues with logging of "Query does not contain parameter named: ice.session" have been resolved.
  • Async thread cleanup has been improved to reduce the possiblity of threads not being garbage-collected after session expiry.

• New DisposableBean API
  • A new, more reliable API for ensuring bean resources are cleaned up when views go out of scope has been added. See "The DisposableBean Interface" section in the ICEfaces Developer's Guide for details.

• Improved Performance
  • Significant client-side performance improvements have been made when handling large incremental changes to the UI, such as expanding or collapsing a tree node with a large number of child nodes, or updating a dataTable with a large number of rows and/or columns.

• Reduced Memory Consumption
  • The ICEfaces JavaScript Bridge has been optimized for reduced static and dynamic memory consumption in all browsers.

• Integration with Application Server Asynchronous Request Processing (ARP) APIs
  • ICEfaces now optionally supports ARP configurations for the following servers:
    • Glassfish v2 UR1
    • ICEfaces Asynchronous HTTP Server (AHS)
    • Jetty 6.1
    • Tomcat 6 and JBoss 4.2
  • See the "Optimizing Asynchronous Communications for Scalability" section in the ICEfaces Develpoer's Guide for more information.

Portlet Support

• ICEfaces now supports the following portal containers:
  • Liferay Portal
  • BEA WebLogic Portal
  • JBoss Portal
  • Apache Pluto
  • JetSpeed 2

• Support for JSR-168 Portlets
  • ICEfaces now supports the JSR-168 portlet APIs for PortletRequest (RenderRequest) and its affiliates (PortalContext, PortletMode, PortletSession, PortletContext, PortletPreferences and WindowState), as well as PortletConfig.
  • The ICEfaces Component Suite components now support the JSR-168 portlet theme style classes. ICEfaces components used in a portlet will automatically adopt the style theme of the containing portal page.S

• Improved ICEfaces portlet deployment flexibility and robustness
  • It is now possible to deploy ICEfaces portlets sourced from multiple .war files to a single portal page, including mixing of both synchronous and asynchronous portlets.
  • Support for multiple portlets in separate .war files requires configuring the new ICEfaces Async HTTP Server (AHS) servlet.

• New Portlet documentation
  • See the "Developing Portlets with ICEfaces" section in the ICEfaces Developer's Guide

• New portlet sample applications
  • A portlet version of the ICEfaces Component Showcase sample application demonstrates many of the ICEfaces components running as portlets.
  • A new Async Chat portlet demonstrates using ICEfaces ajax-push within a portlet.

Async HTTP Server (AHS)

• Now included in ICEfaces core distribution
  • Formerly a stand-alone project, the AHS is now included in the core ICEfaces distribution.
  • See the new "Introduction to the Asynchronous HTTP Server" section in the Advanced Topics chapter of the ICEfaces Developer's Guide for details.

• New Servlet deployment option
  • Servlet configuration enables straightforward deployment for use with ICEfaces portlets.
  • Required in a portal environment to support multiple asynchronous ICEfaces portlets deployed from different WAR files.

Improved Support for 3rd Party Frameworks

• JBoss Seam
  • Updated documentation, see the "JBoss Seam Integration" section in the Advanced Topics chapter of the ICEfaces Developer's Guide for details.
  • Enhanced Seam Component Showcase sample project adds new 1.7 components. Available as a separate download here or via SVN: "http://anonsvn.icefaces.org/repo/projects/seam-component-showcase/". Supports the following additional configurations:
    • Seam / ICEfaces / Glassfish 2.1
    • Seam / ICEfaces / JBoss 4.2
    • Seam / ICEfaces / JBoss Portal
    • Seam / ICEfaces / Tomcat 6
    • Seam / ICEfaces / WebLogic 10
    • Seam / ICEfaces / Liferay Portal / Glassfish 2

• Spring Web Flow
  • See the new "Spring Framework Integration" section in the Advanced Topics chapter of the ICEfaces Developer's Guide for details.
  • New Spring Web Flow 1. sample project ("Sell Item") available as a separate download here or via SVN: "http://anonsvn.icefaces.org/repo/projects/icefaces-swf-sellitem-jsf/".

Improved Documentation 

• ICEfaces Getting Started Guide
  • New chapter - "ICEfaces Design Decisions — Using ICEfaces in Your Project" covers important design decisions to be made regarding how ICEfaces will be configured, used, and deployed in your project.

• ICEfaces Developer's Guide
  • New and enhanced sections:
    • JavaScript API Reference
    • Using ICEfaces with JSF 1.2
    • ICEfaces Library Dependencies
    • Connection Mgmt.
    • Server-initiated Rendering API
    • Optimizing Asynchronous Communications
    • Developing Portlets with ICEfaces
    • Appendix A - ICEfaces Library Dependencies Matrix
    • Appendix B - ICEfaces Configuration Parameter Overview 

Improved Sample Applications

• All new Component Showcase 
  • Seperate apps. for JSP, Facelets, and Portlets versions (for ease of code-comprehension)
  • Simplification of some component demos that better illustrate best-practices
  • Cleaner styling and layout fully leverages the new "Rime" theme.
  • Now possible to view both page markup and backing-bean source code from within the app.
  • Each demo lists additional resources for components used in the demo, such as component tld docs, tutorials, etc.

• New Build Targets for most popular application servers
  • The build system for the sample applications and tutorials included in the ICEfaces bundle has been enhanced to provide specific build targets for the most popular JEE application servers making it easier to create sample .war files that will deploy successfully to the application server of your choice. 
  • See "Chapter 3 - Running the ICEfaces Sample Applications" in the ICEfaces Getting Started Guide for details.

• Default builds and prebuild .war files now target Tomcat 6 w/ JSF 1.2
• The default ant builds and prebuilt .war files for the sample applications now use the "tomcat6.0" build target, which is suitable for deployment to Tomcat 6 and uses the Sun JSF 1.2 runtime.
• To deploy the samples an application server other than Tomcat 6, you must use the build target for the desired server. Type "ant help" for more information.

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

1.6.x to 1.7.x Migration Notes

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

DEFAULT_SUFFIX Parameter Required

• Starting with 1.7 ICEfaces requires that the standard JSF “javax.faces.DEFAULT_SUFFIX” parameter be defined in the web.xml file. In previous releases the absence of a DEFAULT_SUFFIX entry was tolerated for some .jspx applications.

ice:message(s) with Partial Submit

• The behavior of ice:message(s) when used with partialSubmit-enabled components in a form has changed in 1.7 to better align it with standard JSF behavior.
• The change is to retain the display of error messages for any components that:
• Were in an invalid state prior to the partialSubmit
• Are not the component that is the subject of the partialSubmit
• This supports the use-case where a user enters data in a partial-submit form, enters an invalid value in field1, sees the error message, then moves to field2 and enters a value there without first correcting the entered value in field1. Prior to this release the original error message from the invalid entry into field1 would disappear when field2 was partialSubmitted. Now error messages for all invalid state components will continue to be displayed until they are in a valid state.
• See ICE-1883 for more information.

selectInputDate Timezone Support

• The ice:selectInputDate component has improved support for timezones which has affected the default timezone that it will now use if no timezone is specified.
• Care should be taken to use the same timezone between UIComponents that view and edit dates and times, otherwise data corruption and misrepresentation can occur.
• Tips:
• You should add an f:convertDateTime child tag with a timeZone attribute to specify a timezone for the ice:selectInputDate component to use. When no timeZone attribute is specified, the f:convertDateTime component will use GMT as a default.
• If the ice:selectInputDate component is used without a corresponding f:convertDateTime component it will also use GMT as the default timezone.
• Note for Seam users that the s:convertDateTime component uses the application server's local timezone as its default, and not GMT.

Command Sort Header Style Change

• The ice:commandSortHeader component has been improved to permit styling of the up/down arrows using images, tied to the themes. This provides more flexability in their appearance over the single arrow style supported previously.
• Note that the "arrow" attribute on this component is now deprecated and has no effect.
• Refer to the TLD documentation for the commandSortHeader for more information.

jsp:root Tag Support in Facelets

• Starting with 1.7 when using the jsp:root tag on a facelets-based page the following javascript error will occur and the page won't work anymore: "uncaught exception: couldn't find container for property: bridge".
• JSP directives should not be used in a Facelets context. A workaround is to use <jsp:root jsfc="f:view">, so that <jsp:root> will become <f:view>, or completely remove the <jsp:root> tag. 
  

Asynchronous Application Cleanup (ViewListener Deprecated)

• Managed beans, particularly session and request scoped beans, can have references to resources that may need to be specifically dealt with when the beans go out of scope.
• For asynchronous ICEfaces application, the previous recommended solution for this was the com.icesoft.faces.context.ViewListener interface. The ViewListener interface is now deprecated in favor of the  DisposableBean interface. While ViewListener could be applied more broadly (i.e., to non-bean classes), it was more difficult to use and worked in more restricted situations.
• For more information see “The DisposableBean Interface” section in the ICEfaces Developer's Guide.

Portlet Development

• ICEfaces support for portlet development has been completely revamped for 1.7, with new support for JSR-168 portlets.
• Refer to the “Developing Portlets with ICEfaces” section in the ICEfaces Developer's Guide for details.

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
Microsoft	Internet Explorer	6, 7
Mozilla	Firefox	2.0, 3.0
Opera	Opera	9.x
Opera	Opera Mobile	8.65

Application Servers

Vendor	Product	Version
Apache	Tomcat	5.5, 6.0
BEA Systems Inc.	Weblogic Server	8.1, 9.2, 10.0
JBoss Inc.	JBoss Application Server	4.0.5, 4.2.x
IBM	Websphere Application Server	6.0.2, 6.1
Oracle	Oracle Application Server Container for J2EE (OC4J)	10.1.3
SAP	NetWeaver	7.0
Sun Microsystems	GlassFish	v2
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.0.1, 6.5
Sun	NetBeans	6.1

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

• Page 12 of the ICEfaces Getting Started Guide incorrectly indicates that the path to the Component Showcase applications is "/icefaces/samples/componentshowcase2/...". The correct path to the Component Showcase applications is "/icefaces/samples/componentshowcase/...".

• Page 84 of the ICEfaces Developer's Guide contains an incorrect JNDI name reference. The "Glassfish v2" section under "Configuring the Asynchronous HTTP Server" in the "Advanced Topics" chapter should be changed as follows:

• Under "Configuring JMS for GlassFish v2", step 7 incorrectly states: 
• "Enter "icefacesContentEventTopic" as the JNDI Name and Physical Destination Name, select javax.jms.Topic as the Resource Type, and click OK."
• The correct configuration instruction is:
• "Enter "icefacesContextEventTopic" as the JNDI Name and Physical Destination Name, select javax.jms.Topic as the Resource Type, and click OK." 

• Starting with ICEfaces 1.7.1, the "Glassfish v2" section under "Optimizing Asynchronous Communications for Scalability" in the "Advanced Topics" chapter (on pg. 54) of the ICEfaces Developer's Guide should be changed as follows: 

• Remove Step 1 (configuring the GrizzlyPushServlet) under "To configure ICEfaces to use Grizzly:". Beginning with ICEfaces 1.7.1 this configuration step is no longer required or supported. Note that Step 2 ("Add the cometSupport property to your http-listener") is still required.
• ICEfaces will now auto-detect GlassFish + Grizzly and will try to use the ARP capabilities of Grizzly if they are enabled. To disable using the ARP facilities of Glassfish Grizzly and Jetty, the com.icesoft.faces.useARP property can be set to false inside the web.xml. Note that the previous Jetty-specific com.icesoft.faces.useJettyContinuations configuration parameter can still be used but is now deprecated.
• If this auto-configuration fails, ICEfaces will revert to using the traditional Thread Blocking async IO mechanism. You can verify that ICEfaces is using the Grizzly ARP mechanism by reviewing the ICEfaces log file (at INFO level). The following log messages may be present:
• GlassFish ARP available: true
• Adapting to GlassFish ARP environment
• Failed to add Comet handler... (if ARP configuration fails only)
• Falling back to Thread Blocking environment (if ARP configuration fails only)

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.

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.

• panelPopup
  • When using a modal panelPopup it may be necessary to ensure that the body region of the page covers the entire visible region of the document or the component used to block user interaction with the document may not cover the entire page. To accomplish this a surrounding DIV sized to 100% width and height can be used to enclose all content in the document body. For example:
    

    <html><body><div style="width:100%;height:100%;"> ...page content... </div></body></html> 

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

JSF 1.2

• ICEfaces must use JSF 1.1 "compatibility mode" within JSF 1.2 environments. See the "Using ICEfaces with JSF 1.2" topic in the ICEfaces Developer's Guide for details.

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.

Async HTTP Server (AHS)

• When shutting down or undeploying an ICEfaces application configured to use AHS, the application server may log harmless exceptions related to the classloader unloading classes before framework threads have finished running (related to JMS).

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

• ICEfaces does not support session persistence. Some application servers enable distributable session features by default. In these cases serialization exceptions may appear in the log. Session distribution should be disabled when deploying ICEfaces applications. Support for session persistence is planned for a future release.

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

• 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

• 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:

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-2008 ICEsoft Technologies, Inc.