Ajax Push - APIs

compared with
Current by Mircea Toma
on Dec 01, 2014 11:22.


 
Key
These lines were removed. This word was removed.
These lines were added. This word was added.

View page history


There are 2 changes. View first change.

 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 ServletContext:
 {code:java}PortableRenderer PushRenderer.getPortableRenderer(ServletContext servletContext);{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:].

© Copyright 2018 ICEsoft Technologies Canada Corp.