¶ Ajax Push - APIs
¶ Overview
Ajax Push enables real-time collaborative applications, based on a mechanism call ICEpush. Check out the Ajax Push overview before delving into the API.
¶ ICEpush Library - icepush.jar
To enable Ajax Push with ICEfaces, you simply include the icepush.jar library with your application.
¶ API
¶ PushRenderer
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.
¶ Rendering in a JSF Context
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:
//Group Mangagement
PushRenderer.addCurrentView(String groupName);
PushRenderer.addCurrentSession(String groupName);
PushRenderer.removeCurrentView(String groupName);
PushRenderer.removeCurrentSession(String groupName);
//Rendering
PushRenderer.render(String groupName);
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.
¶ Group Management
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.
¶ Adding
Add a session and all associated pages (views) to a group using,
PushRenderer.addCurrentSession(String groupName);
Add only a particular page to a group using,
PushRenderer.addCurrentView(String groupName);
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:
@ManagedBean
@SessionScoped
public class MySessionBean {
public static final String GLOBAL_RENDER_GROUP = "everyone";
public MySessionBean() {
PushRenderer.addCurrentSession(GLOBAL_RENDER_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:
@ManagedBean
@ViewScoped
public class MyViewBean {
public MyViewBean() {
PushRenderer.addCurrentView(myCustomId);
...
Ensure you use the appropriate API for the scope of your bean or it can lead to unpredictable behaviour. For example, if you call addCurrentView in a SessionScopedBean, only the active view when the session is initially created gets added to the group. Subsequent views are not added because the bean constructor is not called again.
¶ Removing
You can also remove sessions or views from a group.
PushRenderer.removeCurrentView(String groupName);
PushRenderer.removeCurrentSession(String groupName);
The PushRenderer automatically manages the removal of unused group members, so programmatic removal is not strictly necessary.
¶ Push Rendering
When something of note changes in the application, you can push to a group from a valid JSF context by calling,
PushRenderer.render(groupName);
¶ PortableRenderer - Pushing from outside the JSF context
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:
PortableRenderer PushRenderer.getPortableRenderer();
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:
PortableRenderer PushRenderer.getPortableRenderer(HttpSession session);
Enhancing the SessionScoped example from earlier, here's how you would get an instance of a PortableRenderer:
@ManagedBean
@SessionScoped
public class MySessionBean {
public static final String GLOBAL_RENDER_GROUP = "everyone";
private PortableRenderer portableRenderer;
public MySessionBean() {
PushRenderer.addCurrentSession(GLOBAL_RENDER_GROUP);
portableRenderer = PushRenderer.getPortableRenderer();
...
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):
portableRenderer.render(GLOBAL_RENDER_GROUP);
Since ICEfaces 4.0 the group management methods were added also to the PortableRenderer:
//Group Mangagement
PortableRenderer.addCurrentView(String groupName);
PortableRenderer.addCurrentSession(String groupName);
PortableRenderer.removeCurrentView(String groupName);
PortableRenderer.removeCurrentSession(String groupName);
¶ Porting
¶ API changes
In ICEfaces 1.8.x, there were two distinct APIs available for using Ajax Push.
¶ SessionRenderer
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.
¶ RenderManager and Renderable
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:
com.icesoft.faces.async.render.RenderManager
com.icesoft.faces.async.render.Renderable
com.icesoft.faces.async.render.OnDemandRenderer
com.icesoft.faces.async.render.IntervalRenderer
com.icesoft.faces.webapp.xmlhttp.PersistentFacesState
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.
¶ ICEpush Configuration
The ICEpush library supports specific configuration parameters that can be used to optimize performance and reliability as required.
Details on ICEpush configuration can be found in the ICEpush Configuration Parameters topic in the ICEpush product Wiki.