View Source

h1. Overview

Ajax Push enables real-time collaborative applications, based on a mechanism call [ICEpush|http://www.icepush.org/product/overview.html]. Check out the [Ajax Push overview|Ajax Push - Overview] before delving into the API.

h1. ICEpush Library - icepush.jar

To enable Ajax Push with ICEfaces, you simply include the icepush.jar library with your application.

h1. API

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

h3. Rendering in a JSF Context



h3.

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:
{code:java}//Group Mangagement
PushRenderer.addCurrentView(String groupName);
PushRenderer.addCurrentSession(String groupName);
PushRenderer.removeCurrentView(String groupName);
PushRenderer.removeCurrentSession(String groupName);

//Rendering
PushRenderer.render(String groupName);
{code}
For triggering push rendering outside of a JSF context (i.e. on a non-JSF thread), use the [PortableRenderer|#portableRendererAnchor] API described later in this document.


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

h4. Adding


Add a session and all associated pages (views) to a group using,
{code:java}PushRenderer.addCurrentSession(String groupName);
{code}
Add only a particular page to a group using,
{code:java}PushRenderer.addCurrentView(String groupName);
{code}


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:
{code:java}
@ManagedBean
@SessionScoped
public class MySessionBean {

public static final String GLOBAL_RENDER_GROUP = "everyone";

public MySessionBean() {
PushRenderer.addCurrentSession(GLOBAL_RENDER_GROUP);
...
{code}
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:
{code:java}
@ManagedBean
@ViewScoped
public class MyViewBean {

public MyViewBean() {
PushRenderer.addCurrentView(myCustomId);
...
{code}

{note}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.{note}

h4. Removing

You can also remove sessions or views from a group.
{code:java}PushRenderer.removeCurrentView(String groupName);
PushRenderer.removeCurrentSession(String groupName);
{code}
{note}The PushRenderer automatically manages the removal of unused group members, so programmatic removal is not strictly necessary.{note}

h3. Push Rendering

When something of note changes in the application, you can push to a group from a valid JSF context by calling,

{code:java}PushRenderer.render(groupName);
{code}
{anchor:portableRendererAnchor}

h3. 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:

{code:java}PortableRenderer PushRenderer.getPortableRenderer();{code}
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:
{code:java}PortableRenderer PushRenderer.getPortableRenderer(HttpSession session);{code}
Enhancing the SessionScoped example from earlier, here's how you would get an instance of a PortableRenderer:
{code:java}
@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();
...
{code}
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):

{code:java}portableRenderer.render(GLOBAL_RENDER_GROUP);{code}

Since ICEfaces 4.0 the group management methods were added also to the PortableRenderer:
{code:java}//Group Mangagement
PortableRenderer.addCurrentView(String groupName);
PortableRenderer.addCurrentSession(String groupName);
PortableRenderer.removeCurrentView(String groupName);
PortableRenderer.removeCurrentSession(String groupName);
{code}
h1. Porting

h2. API changes

In ICEfaces 1.8.x, there were two distinct APIs available for using Ajax Push.

h3. 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_.

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

h1. 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|PUSH:ICEpush Configuration Parameters] topic in the ICEpush product [Wiki|PUSH:].