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.