Ajax Push - APIs

Version 17 by Deryk Sinotte
on May 11, 2012 12:26.

<< Changes from 16 to 17

compared with

Version 18 by Deryk Sinotte
on May 11, 2012 13:14.

Changes from 18 to 19 >>

Key

These lines were removed. This word was removed.

These lines were added. This word was added.

View page history

There are 21 changes. View first change.

-h3. Rendering in Context
+h3. Rendering in a JSF Context
-It's very important to note that most of the methods provided by the PushRenderer API require a valid JSF context to operate properly:
-{code:java}PushRenderer.addCurrentView(String groupName);
+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().&nbsp; Invocation of the following methods *must* be done in this context:
+{code:java}//Group Mangagement
+PushRenderer.addCurrentView(String groupName);
+//Rendering
+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.
-Invocation of these methods *must* be done in a valid JSF context.&nbsp; This means that the current thread is a JSF thread and a valid FacesContext instance can be acquired by calling FacesContext.getCurrentInstance(). For rendering operations outside of a JSF context (i.e. on a non-JSF thread), use the [PortableRenderer|#portableRendererAnchor] API described later in this document.
-Group naming is performed in some application-specific manner using the following APIs:
+Adding views (pages) to groups allows you to control which pages get which push updates.&nbsp; The group names are application-specific and can be organized to include only individual views, all views for all users, or variations in between.&nbsp; You add views to groups using the following APIs.
+h4. Adding
+Again, it's important to remember that these methods must be called within a valid JSF context.&nbsp; A common approach is to use an active JSF bean constructor where the scope of the bean aligns with the appropriate API used.&nbsp; 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
-{note}The _PushRenderer_ automatically manages the removal of unused group members, so programmatic removal is not strictly necessary.
-{note}
+{note}The PushRenderer automatically manages the removal of unused group members, so programmatic removal is not strictly necessary.{note}
-When something of note changes in the application, you can push to a group using,
+When something of note changes in the application, you can push to a group from a valid JSF context by calling,
+{anchor:portableRendererAnchor}
-{anchor:portableRendererAnchor}
-As noted previously, the 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.
+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 valid JSF bean constructor), then you can use:
+If the initial reference to the PortableRenderer is retrieved in a valid JSF context (e.g. a JSF bean constructor), then you can use:
+Enhancing the SessionScoped example from earlier, here's how you would get an instance of a PortableRenderer:
+{code:java}
+@ManagedBean
+@SessionScoped
+public class MySessionBean {
-Once the PortableRenderer reference has been acquired, a Push can be triggered from the PortableRenderer on a non-JSF thread (e.g. a JMS message):
+    public static final String GLOBAL_RENDER_GROUP = "everyone";
+    private PortableRenderer portableRenderer;
-{code:java}PortableRenderer.render(String groupName);{code}
+    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}