To enable Ajax Push with ICEfaces, you simply include the icepush.jar library with your application.
ICEfaces provides a new API for using Ajax Push from within your application. The main class of interest is org.icefaces.application.PushRenderer, which contains the methods to support Ajax Push in your application. The PushRenderer API is similar to the SessionRenderer API from ICEfaces 1.8.x, and revolves around establishing named groups of pages, and asking them to update themselves in response to an Ajax Push trigger.
It's very important to note that certain methods provided by the PushRenderer API require a valid JSF context to operate properly. In general, a valid JSF context can provide a FacesContext instance by calling FacesContext.getCurrentInstance(). Invocation of the following methods must be done in this context:
For triggering push rendering outside of a JSF context (i.e. on a non-JSF thread), use the PortableRenderer API described later in this document.
Adding views (pages) to groups allows you to control which pages get which push updates. The group names are application-specific and can be organized to include only individual views, all views for all users, or variations in between. You add views to groups using the following APIs.
Add a session and all associated pages (views) to a group using,
Add only a particular page to a group using,
Again, it's important to remember that these methods must be called within a valid JSF context. A common approach is to use an active JSF bean constructor where the scope of the bean aligns with the appropriate API used. For example, if you want to add an application wide group so that all views get all updates pushed to them, you could use a SessionScoped bean that adds all views for each newly created session to a global group:
Or, if instead you wanted to add only a particular view for a certain set of users, you could use a ViewScoped bean and provide a more selective name for each group:
You can also remove sessions or views from a group.
When something of note changes in the application, you can push to a group from a valid JSF context by calling,
As noted previously, the various APIs described above must be called from within a JSF context. This is typical in collaborative interactions, as Ajax Push is triggered by a user of the application, and thus from inside the JSF context for that user. Other trigger points could come from outside the JSF context, such as a web service, messaging services, or a database.
If the initial reference to the PortableRenderer is retrieved in a valid JSF context (e.g. a JSF bean constructor), then you can use:
If the initial reference to the PortableRenderer needs to be retrieved in a non-JSF context (e.g. a Servlet constructor), there is an API that takes a valid HttpSession:
Enhancing the SessionScoped example from earlier, here's how you would get an instance of a PortableRenderer:
Once the PortableRenderer reference has been acquired, it can be used to trigger a push from anywhere in your application, including a non-JSF thread (e.g. a JMS message):
Since ICEfaces 4.0 the group management methods were added also to the PortableRenderer:
In ICEfaces 1.8.x, there were two distinct APIs available for using Ajax Push.
There is a compatible version of the com.icesoft.faces.async.render.SessionRenderer based on the org.icefaces.application.PushRenderer. The SessionRenderer exposes an API that is compatible with ICEfaces 1.8.x, so applications that used the SessionRenderer API in ICEfaces 1.8.x should be transparently mapped to use the new PushRenderer.
The RenderManager API is no longer supported in ICEfaces after version 1.8.x. Specifically, this means that the following classes are not available in the current version of ICEfaces:
The recommendation for porting existing applications is to change the code to use the PushRenderer API. For IntervalRenderer-equivalent functionality based on PushRenderer and java.util.Timer, see the ClockBean of the Auction demo. The Auction example can be found under [icefaces2.install.dir]/samples/auction.
The ICEpush library supports specific configuration parameters that can be used to optimize performance and reliability as required.
© Copyright 2021 ICEsoft Technologies Canada Corp.