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))" />