ICEfaces 1.x CompatibilityOverviewThe current version of ICEfaces has been developed specifically to take advantage of the improvements, optimizations, and new features of JSF 2, however, developers with existing ICEfaces 1.x applications that want to move their applications to use the latest ICEfaces and JSF 2 want to do so with minimal disruption and effort. To provide as smooth a migration as possible for developers that want to port their applications, ICEfaces provides a compatibility layer to help reduce the resources required to move an application from ICEfaces 1.8.x to run on the current ICEfaces release. This section of the documentation outlines what the different parts of the compatibility layer are as well as noting areas of an application that may need to be modified or updated. Page Description Language - JSP and FaceletsIn JSF 1.x, the standard mechanism for describing pages is JavaServer Pages (JSP), however, as the use and adoption of JSF increases, JSP is seen as a less than optimal solution for page development and alternatives were developed. The most popular of these is Facelets and it has now been adopted as the new standard page description language for JSF 2. FaceletsNew applications must be developed in Facelets. Existing applications that use Facelets can be migrated with little or no modifications to the pages. JSPJSP development is not supported by ICEfaces 2+. All development should be done in Facelets. PortingHere are some of the things you may need to adjust as you move your applications from ICEfaces 1.8.x to the current version:
ConfigurationJSF 2 provides a number of annotations to make configuration easier with JSF 2 applications. In fact it's possible to have an application that has no faces-config.xml file at all. Additionally, ICEfaces takes advantage or the various extension points and features provided by JSF 2 for better and more compatible integration. Porting
<application> <view-handler>com.icesoft.faces.application.D2DViewHandler</view-handler> </application>
<servlet> <servlet-name>Persistent Faces Servlet</servlet-name> <servlet-class>com.icesoft.faces.webapp.xmlhttp.PersistentFacesServlet</servlet-class> <load-on-startup> 1 </load-on-startup> </servlet> <servlet> <servlet-name>Blocking Servlet</servlet-name> <servlet-class>com.icesoft.faces.webapp.xmlhttp.BlockingServlet</servlet-class> <load-on-startup> 1 </load-on-startup> </servlet> <servlet-mapping> <servlet-name>Persistent Faces Servlet</servlet-name> <url-pattern>*.iface</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>Persistent Faces Servlet</servlet-name> <url-pattern>/xmlhttp/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>Blocking Servlet</servlet-name> <url-pattern>/block/*</url-pattern> </servlet-mapping>
<servlet> <servlet-name>Resource Servlet</servlet-name> <servlet-class>com.icesoft.faces.webapp.CompatResourceServlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>Resource Servlet</servlet-name> <url-pattern>/xmlhttp/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>/icefaces/*</url-pattern> </servlet-mapping>
<context-param> <param-name>javax.faces.FACELETS_SKIP_COMMENTS</param-name> <param-value>true</param-value> </context-param>
<context-param> <param-name>javax.faces.VALIDATE_EMPTY_FIELDS</param-name> <param-value>false</param-value> </context-param> ScopesBy default, ICEfaces 1.x operated under what was referred to as extended request scope. In a nutshell, extended request scope refers to the behavior that a new request is only associated with a change in view. This means that Ajax requests that occur within an existing view are not treated by ICEfaces as new requests. A request is not considered a new request unless it results in a new view so request-scoped beans would not be recreated until a new view was created. This behavior was configurable to allow for the more standard definition of request scope but was considered necessary at the time because the existing standard scopes (request, session, application, none) were not sufficient for supporting ICEfaces features like partial submit and Ajax Push. In addition to the View scope provided by JSF 2, ICEfaces introduces a custom scope called Window scope. This new scope is designed to fill a gap in the existing scopes available for JSF 2. A Window-scoped bean exists for the life of a browser window or tab but is also built to survive reloads and refreshes. This means it can last over the life of multiple ICEfaces views (Window Scope does not persist across non-ICEfaces views). PortingStarting with ICEfaces 2, extended request scope is no longer supported so if your application was relying specifically on this behaviour, you may need to adjust the scope of your beans. The options are:
@ManagedBean(name = "windowBean") @CustomScoped(value = "#{window}") public class MyBean implements Serializable { ... Both View Scope and Window Scope allow beans to be associated with individual views, thereby allowing the application to handle multi-tab/multi-window use. The choice of which one to use depends mainly on the expected behavior under the browser reload button. If "reload" should be a "reset" (clearing state in the current view) then View Scope should be used. If "reload" should be a "refresh" (having little or no impact on the application) then Window Scope should be used.
ComponentsThe current version of ICEfaces includes a version of the ICEfaces 1.8.x component suite that has been modified and tested to work with the latest ICEfaces core framework. This provides developers with a couple of benefits. First, the standard JSF components that come with the JSF implementation are fully supported by ICEfaces so you can start building ICEfaces-enabled applications immediately using those components. However, the basic set of components is typically not sophisticated enough for most applications. They require a richer set of components like those found in the ICEfaces 1.8.x framework. By including a library of compatible ICEfaces 1.8.x components, developers have immediate access to a large, mature, well-tested component suite. Additionally, for those existing ICEfaces 1.8.x applications that are being considered for migration to a newer version of ICEfaces, the compatible component library allows full support for all the components that developers are currently using, making it much simpler to port the application. The compatibility layer for components comes in one library:
Simply including this library with your application provides access to the components previously available in ICEfaces 1.8.x.
Porting
JavaScript APIThe client-side JavaScript API for the current version of ICEfaces has changed from the ICEfaces 1.8.x version. The new API is described in detail in the JavaScript Client API section. For compatibility and porting purposes, the original API from ICEfaces 1.8.x is still available in the compatibility library. For the most part, these are now just wrapper methods that call into the more current ICEfaces API. PortingUsage of the client-side JavaScript API is mostly transparent. The components that use the ICEfaces 1.8.x API will now simply use the wrapper versions of the older methods which end up calling through to the current ICEfaces APIs. If your application is calling the older API directly, you should see the same benefit. Server-side APIAlthough we've made every attempt to make the latest releases of ICEfaces as compatible as possible, there are some APIs that have changed or been dropped since 1.8.x. Porting
Ajax PushICEfaces now uses the ICEpush product for Ajax Push. For information on porting to or using Ajax Push in the current release of ICEfaces, see the documentation on Ajax Push - APIs. PortletsYou can now build and run your portlets under ICEfaces using the PortletFaces Bridge. You can find more details about running the examples and building your own porlets in the Portlet Development section. PortingTo port your existing portlets to use the current release of ICEfaces and the PortletFaces Bridge you should:
External ScriptsCertain components may rely on external 3rd-party scripts that will not work correctly unless the script is loaded and made available in the <head> on the initial GET request for the page. This can be difficult for components that might get added or rendered out dynamically after the initial page render. ICEfaces includes a feature for annotating the components that need this type of support for external scripts. @ExternalScript(scriptURL="_urlToScript_", contextParam="_contextParameterKey_" ) public class MyComponentRenderer... The annotation specifies the location of the script as well as the context parameter required to be set. If the component with the annotation is detected and the context parameter is set, then the script link will automatically be rendered out to the <head> of the document on the initial render. Dynamic Script EvaluationThe com.icesoft.faces.context.effects.JavascriptContext API, used for sending Javascript code from the server to the client for evaluation, continues to be available for use. New applications are encouraged to instead use the org.icefaces.util.JavaScriptRunner API, which is significantly simpler, with only one method: org.icefaces.util.JavaScriptRunner.runScript(javax.faces.context.FacesContext context, java.lang.String script). |
ICEfaces 1.x Compatibility Features of ICEfaces 3
© Copyright 2021 ICEsoft Technologies Canada Corp.