From richfaces-svn-commits at lists.jboss.org Fri Mar 18 01:34:24 2011
Content-Type: multipart/mixed; boundary="===============0912287986518377975=="
MIME-Version: 1.0
From: richfaces-svn-commits at lists.jboss.org
To: richfaces-svn-commits at lists.jboss.org
Subject: [richfaces-svn-commits] JBoss Rich Faces SVN: r22261 - in
 modules/docs/trunk/Component_Reference/src/main/docbook/en-US: extras and 1
 other directory.
Date: Fri, 18 Mar 2011 01:34:24 -0400
Message-ID: <201103180534.p2I5YOVd028580@svn01.web.mwc.hst.phx2.redhat.com>

--===============0912287986518377975==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

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/exa=
m-Component_Reference-a4jpush-Basic_usage.xml_sample
   modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exa=
m-Component_Reference-a4jpush-Handling_a_push_notification.xml_sample
Modified:
   modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Compo=
nent_Reference-Actions.xml
Log:
Updated push documentation

Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/cha=
p-Component_Reference-Actions.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Comp=
onent_Reference-Actions.xml	2011-03-18 02:12:38 UTC (rev 22260)
+++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Comp=
onent_Reference-Actions.xml	2011-03-18 05:34:23 UTC (rev 22261)
@@ -575,10 +575,56 @@
 	=

 	<section id=3D"sect-Component_Reference-Actions-a4jpush">
 		<title><sgmltag>&lt;a4j:push&gt;</sgmltag></title>
+		<!--
 		<para>
-			The <sgmltag>&lt;a4j:push&gt;</sgmltag> component periodically performs=
 an Ajax request to the server, simulating "push" functionality. While it i=
s not strictly pushing updates, the request is made to minimal code only, n=
ot to the <acronym>JSF</acronym> tree, checking for the presence of new mes=
sages in the queue. The request registers <classname>EventListener</classna=
me>, which receives messages about events, but does not poll registered bea=
ns. If a message exists, a complete request is performed. This is different=
 from the <sgmltag>&lt;a4j:poll&gt;</sgmltag> component, which performs a f=
ull request at every interval.
+			The <sgmltag>&lt;a4j:push&gt;</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 minima=
l code only, not to the <acronym>JSF</acronym> tree, checking for the prese=
nce of new messages in the queue. The request registers <classname>EventLis=
tener</classname>, which receives messages about events, but does not poll =
registered beans. If a message exists, a complete request is performed. Thi=
s is different from the <sgmltag>&lt;a4j:poll&gt;</sgmltag> component, whic=
h performs a full request at every interval.
+		</para>
+		-->
+		<para>
+			The <sgmltag>&lt;a4j:push&gt;</sgmltag> component performs real-time up=
dates 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>&lt;a4j:push&gt;</sgmltag> component is trig=
gered by a server event, it can in turn cause Ajax updates and changes.
+		</para>
+
+		<section id=3D"sect-Component_Reference-a4jpush-Basic_usage">
+			<title>Basic usage</title>
+			<para>
+				RichFaces requires the use of the <filename>jquery-atmosphere.js</file=
name> client plug-in for push functionality. The plug-in is added automatic=
ally 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>&lt;a4j:push&gt;</sgmltag> components. Create topics on the JMS se=
rver for the push functionality to check for new messages. Refer to <citeti=
tle>JMS Documentation</citetitle> for details on configuring JMS.
+			</para>
+			<para>
+				Use the <sgmltag>&lt;a4j:push&gt;</sgmltag> component's <varname>addre=
ss</varname> attribute to reference the topic on the JMS server that contai=
ns the pushed messages.
+			</para>
+			<para>
+				The <sgmltag>&lt;a4j:push&gt;</sgmltag> component should also include =
the <varname>error</varname> event attribute to inform the user when an err=
or has occurred with the push notifications.
+			</para>
+			<example id=3D"exam-Component_Reference-a4jpush-Basic_usage">
+				<title>Basic usage</title>
+				<programlisting language=3D"XML" role=3D"XML"><xi:include parse=3D"tex=
t" href=3D"extras/exam-Component_Reference-a4jpush-Basic_usage.xml_sample" =
xmlns:xi=3D"http://www.w3.org/2001/XInclude" /></programlisting>
+				<para>
+					The example demonstrates a simple use of the <sgmltag>&lt;a4j:push&gt=
;</sgmltag> component to manage a list of users in a chat room. The <sgmlta=
g>&lt;a4j:push&gt;</sgmltag> component refers to the <code>#{chatBean.listS=
ubtopic}@chat</code> address, which has been created on the JMS server. Whe=
n a new message arrives, the <sgmltag>&lt;a4j:ajax&gt;</sgmltag> behavior c=
auses the user list to update. If an error occurs, the user is alerted.
+				</para>
+			</example>
+		</section>
+
+		<section id=3D"sect-Component_Reference-a4jpush-Handling_a_push_notifica=
tion">
+			<title>Handling a push notification</title>
+			<para>
+				A push notification sent to the <sgmltag>&lt;a4j:push&gt;</sgmltag> be=
havior will cause it to trigger any <sgmltag>&lt;a4j:ajax&gt;</sgmltag> com=
ponents attached as sub-elements. Alternatively, use the <varname>dataavail=
able</varname> event attribute to define a handler. =

+			</para>
+			<example id=3D"exam-Component_Reference-a4jpush-Handling_a_push_notific=
ation">
+				<title>Handling a push notification</title>
+				<programlisting language=3D"XML" role=3D"XML"><xi:include parse=3D"tex=
t" href=3D"extras/exam-Component_Reference-a4jpush-Handling_a_push_notifica=
tion.xml_sample" xmlns:xi=3D"http://www.w3.org/2001/XInclude" /></programli=
sting>
+				<para>
+					The example uses the <varname>dataavailable</varname> event attribute=
 with JavaScript to update messages in a chat room.
+				</para>
+			</example>
+		</section>
+
+		<!--
 		<section id=3D"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 perio=
d, the connection is aborted and the next request is sent. By default, the =
timeout is not set. In combination with the <varname>interval</varname> att=
ribute, checks for the queue state can short polls or long connections.
 			</para>
 		</section>
+		-->
 		=

 		<section id=3D"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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/ex=
am-Component_Reference-a4jpush-Basic_usage.xml_sample	                     =
   (rev 0)
+++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/ex=
am-Component_Reference-a4jpush-Basic_usage.xml_sample	2011-03-18 05:34:23 U=
TC (rev 22261)
@@ -0,0 +1,8 @@
+<rich:list value=3D"#{chatBean.users}" var=3D"user" id=3D"users" type=3D"u=
nordered">
+   #{user.nick}
+</rich:list>
+...
+<a4j:push address=3D"#{chatBean.listSubtopic}@chat"
+          onerror=3D"alert(event.rf.data)">
+   <a4j:ajax event=3D"dataavailable" render=3D"users" execute=3D"@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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/ex=
am-Component_Reference-a4jpush-Handling_a_push_notification.xml_sample	    =
                    (rev 0)
+++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/ex=
am-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=3D"#{chatBean.messagesSubtopic}@chat"
+          onerror=3D"alert(event.rf.data)"
+          ondataavailable=3D"jQuery('&lt;div/&gt;').
+             prependTo('.#{chatBean.channelName}Output').text(
+             getMessageString(event.rf.data))" />


--===============0912287986518377975==--