JBoss Rich Faces SVN: r22261 - in modules/docs/trunk/Component_Reference/src/main/docbook/en-US: extras and 1 other directory.
by richfaces-svn-commits@lists.jboss.org
Author: SeanRogers
Date: 2011-03-18 01:34:23 -0400 (Fri, 18 Mar 2011)
New Revision: 22261
Added:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jpush-Basic_usage.xml_sample
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jpush-Handling_a_push_notification.xml_sample
Modified:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Actions.xml
Log:
Updated push documentation
Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Actions.xml
===================================================================
--- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Actions.xml 2011-03-18 02:12:38 UTC (rev 22260)
+++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Actions.xml 2011-03-18 05:34:23 UTC (rev 22261)
@@ -575,10 +575,56 @@
<section id="sect-Component_Reference-Actions-a4jpush">
<title><sgmltag><a4j:push></sgmltag></title>
+ <!--
<para>
- The <sgmltag><a4j:push></sgmltag> component periodically performs an Ajax request to the server, simulating "push" functionality. While it is not strictly pushing updates, the request is made to minimal code only, not to the <acronym>JSF</acronym> tree, checking for the presence of new messages in the queue. The request registers <classname>EventListener</classname>, which receives messages about events, but does not poll registered beans. If a message exists, a complete request is performed. This is different from the <sgmltag><a4j:poll></sgmltag> component, which performs a full request at every interval.
+ The <sgmltag><a4j:push></sgmltag> component periodically performs an Ajax request to the server, simulating "push" functionality.
</para>
-
+ <para>
+ While it is not strictly pushing updates, the request is made to minimal code only, not to the <acronym>JSF</acronym> tree, checking for the presence of new messages in the queue. The request registers <classname>EventListener</classname>, which receives messages about events, but does not poll registered beans. If a message exists, a complete request is performed. This is different from the <sgmltag><a4j:poll></sgmltag> component, which performs a full request at every interval.
+ </para>
+ -->
+ <para>
+ The <sgmltag><a4j:push></sgmltag> component performs real-time updates on the client side from events raised at the server side. The events are pushed out to the client through the Java Message Service (<acronym>JMS</acronym>). When the <sgmltag><a4j:push></sgmltag> component is triggered by a server event, it can in turn cause Ajax updates and changes.
+ </para>
+
+ <section id="sect-Component_Reference-a4jpush-Basic_usage">
+ <title>Basic usage</title>
+ <para>
+ RichFaces requires the use of the <filename>jquery-atmosphere.js</filename> client plug-in for push functionality. The plug-in is added automatically by the push component renderer, but needs to additionally be added as a build dependency to your project.
+ </para>
+ <para>
+ The JMS instance on the back-end must be configured to work with your <sgmltag><a4j:push></sgmltag> components. Create topics on the JMS server for the push functionality to check for new messages. Refer to <citetitle>JMS Documentation</citetitle> for details on configuring JMS.
+ </para>
+ <para>
+ Use the <sgmltag><a4j:push></sgmltag> component's <varname>address</varname> attribute to reference the topic on the JMS server that contains the pushed messages.
+ </para>
+ <para>
+ The <sgmltag><a4j:push></sgmltag> component should also include the <varname>error</varname> event attribute to inform the user when an error has occurred with the push notifications.
+ </para>
+ <example id="exam-Component_Reference-a4jpush-Basic_usage">
+ <title>Basic usage</title>
+ <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-a4jpush-Basic_usage.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <para>
+ The example demonstrates a simple use of the <sgmltag><a4j:push></sgmltag> component to manage a list of users in a chat room. The <sgmltag><a4j:push></sgmltag> component refers to the <code>#{chatBean.listSubtopic}@chat</code> address, which has been created on the JMS server. When a new message arrives, the <sgmltag><a4j:ajax></sgmltag> behavior causes the user list to update. If an error occurs, the user is alerted.
+ </para>
+ </example>
+ </section>
+
+ <section id="sect-Component_Reference-a4jpush-Handling_a_push_notification">
+ <title>Handling a push notification</title>
+ <para>
+ A push notification sent to the <sgmltag><a4j:push></sgmltag> behavior will cause it to trigger any <sgmltag><a4j:ajax></sgmltag> components attached as sub-elements. Alternatively, use the <varname>dataavailable</varname> event attribute to define a handler.
+ </para>
+ <example id="exam-Component_Reference-a4jpush-Handling_a_push_notification">
+ <title>Handling a push notification</title>
+ <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-a4jpush-Handling_a_push_notification.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <para>
+ The example uses the <varname>dataavailable</varname> event attribute with JavaScript to update messages in a chat room.
+ </para>
+ </example>
+ </section>
+
+ <!--
<section id="sect-Component_Reference-a4jpush-Timing_options">
<title>Timing options</title>
<para>
@@ -588,6 +634,7 @@
The <varname>timeout</varname> attribute defines the response waiting time in milliseconds. If a response isn't received within the timeout period, the connection is aborted and the next request is sent. By default, the timeout is not set. In combination with the <varname>interval</varname> attribute, checks for the queue state can short polls or long connections.
</para>
</section>
+ -->
<section id="sect-Component_Reference-a4jpush-Reference_data">
<title>Reference data</title>
Added: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jpush-Basic_usage.xml_sample
===================================================================
--- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jpush-Basic_usage.xml_sample (rev 0)
+++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jpush-Basic_usage.xml_sample 2011-03-18 05:34:23 UTC (rev 22261)
@@ -0,0 +1,8 @@
+<rich:list value="#{chatBean.users}" var="user" id="users" type="unordered">
+ #{user.nick}
+</rich:list>
+...
+<a4j:push address="#{chatBean.listSubtopic}@chat"
+ onerror="alert(event.rf.data)">
+ <a4j:ajax event="dataavailable" render="users" execute="@none" />
+</a4j:push>
Added: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jpush-Handling_a_push_notification.xml_sample
===================================================================
--- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jpush-Handling_a_push_notification.xml_sample (rev 0)
+++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jpush-Handling_a_push_notification.xml_sample 2011-03-18 05:34:23 UTC (rev 22261)
@@ -0,0 +1,5 @@
+<a4j:push address="#{chatBean.messagesSubtopic}@chat"
+ onerror="alert(event.rf.data)"
+ ondataavailable="jQuery('<div/>').
+ prependTo('.#{chatBean.channelName}Output').text(
+ getMessageString(event.rf.data))" />