From richfaces-svn-commits at lists.jboss.org Fri Nov 30 11:34:01 2007
Content-Type: multipart/mixed; boundary="===============0635930494187439860=="
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: r4394 -
 trunk/docs/userguide/en/src/main/docbook/included.
Date: Fri, 30 Nov 2007 11:34:00 -0500
Message-ID: <E1Iy8oS-0004FT-VP@committer01.frg.pub.inap.atl.jboss.com>

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

Author: vkorluzhenko
Date: 2007-11-30 11:34:00 -0500 (Fri, 30 Nov 2007)
New Revision: 4394

Modified:
   trunk/docs/userguide/en/src/main/docbook/included/poll.xml
   trunk/docs/userguide/en/src/main/docbook/included/push.xml
Log:
http://jira.jboss.com/jira/browse/RF-657 - improved description.

Modified: trunk/docs/userguide/en/src/main/docbook/included/poll.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
--- trunk/docs/userguide/en/src/main/docbook/included/poll.xml	2007-11-30 1=
5:10:24 UTC (rev 4393)
+++ trunk/docs/userguide/en/src/main/docbook/included/poll.xml	2007-11-30 1=
6:34:00 UTC (rev 4394)
@@ -66,7 +66,7 @@
       </emphasis> componet is used for periodical polling of server data. =
In order to use the component
       it&apos;s necessary to set an update interval. The <emphasis>
         <property>&quot;interval&quot;</property>
-      </emphasis> attribute defines an interval in milliseconds beetween t=
he previous
+      </emphasis> attribute defines an interval in milliseconds between th=
e previous
       response and the next request. The total period beetween two request=
s generated by the
         <emphasis role=3D"bold">
         <property>&lt;a4j:poll&gt;</property>
@@ -78,7 +78,7 @@
       the <link linkend=3D"creating">&quot;Creating on a page&quot; sectio=
n</link>. </para>
     <para>The <emphasis>
         <property>&quot;timeout&quot;</property>
-      </emphasis> attribute defines response wating time in milliseconds. =
If the response
+      </emphasis> attribute defines response waiting time in milliseconds.=
 If a response
       isn&apos;t received during this period a connection is aborted and t=
he next request is
       sent. Default value for <emphasis>
         <property>&quot;timeout&quot;</property>

Modified: trunk/docs/userguide/en/src/main/docbook/included/push.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
--- trunk/docs/userguide/en/src/main/docbook/included/push.xml	2007-11-30 1=
5:10:24 UTC (rev 4393)
+++ trunk/docs/userguide/en/src/main/docbook/included/push.xml	2007-11-30 1=
6:34:00 UTC (rev 4394)
@@ -49,30 +49,83 @@
     <title>Key attributes and ways of usage</title>
     <para>The <emphasis role=3D"bold">
         <property>&lt;a4j:push&gt;</property>
-      </emphasis> component is similar to the <emphasis role=3D"bold">
-        <property>&lt;a4j:poll&gt;</property>
-      </emphasis>
-      <link linkend=3D"poll_d"> one</link>. The main difference is that th=
e<emphasis role=3D"bold">
+      </emphasis> implements reverse Ajax technique. The component makes r=
equests to minimal code
+      (not to JSF tree) in order to check presence of messages in a queue.=
 If a message exists, a
+      complete request is performed. <emphasis role=3D"bold">
+      <property>&lt;a4j:push&gt;</property>
+      </emphasis> registers <property>EventListener</property> in the bean,
+      which receives messages about an event presence.</para>
+
+    <para>The bean, for example, could be subscribed to Java Messaging Ser=
vice (<ulink
+        url=3D"http://java.sun.com/products/jms/">JMS</ulink>) topic or it=
 could be implemented as
+      Message Driven Bean (MDB) in order to send a message to the <emphasi=
s role=3D"bold">
         <property>&lt;a4j:push&gt;</property>
-      </emphasis> makes request to minimal code (not to JSF tree) in order=
 to check presence of
-      messages in a queue. If a message exists, a complete request is perf=
ormed. The component
-      doesn&apos;t poll registered bean. It registers <property>EventListe=
ner</property>, which
-      receives messages about event presence. See an example below:</para>
+      </emphasis> component about an event presence. In the presence of th=
e event some action
+      occurs.</para>
 =

+    <para>Thus, a work paradigm with the <emphasis role=3D"bold">
+        <property>&lt;a4j:push&gt;</property>
+      </emphasis> component corresponds to an anisochronous model, but not=
 to pools as for <emphasis
+        role=3D"bold">
+        <property>&lt;a4j:poll&gt;</property>
+      </emphasis> component. See the simplest example below:</para>
+
     <para>
       <emphasis role=3D"bold">Example:</emphasis>
     </para>
-    <programlisting role=3D"XML"><![CDATA[<a4j:push reRender=3D"msg" event=
Producer=3D"#{pushBean.addListener}" interval=3D"2000"/>
+    <programlisting role=3D"JAVA"><![CDATA[...
+class MyPushEventListener implements PushEventListener {
+    public void onEvent(EventObject evt) {
+        System.out.println(evt.getSource());
+            //Some action
+    }
+...
 ]]></programlisting>
-    <para>In the example <emphasis>
+
+    <para>Code for <property>EventListener</property> registration in the =
bean is placed below:</para>
+    <para>
+      <emphasis role=3D"bold">Example:</emphasis>
+    </para>
+    <programlisting role=3D"JAVA"><![CDATA[...
+public void addListener(EventListener listener) {
+synchronized (listener) {
+        if (this.listener !=3D listener) {
+        this.listener =3D (PushEventListener) listener;
+}
+...
+]]></programlisting>
+
+    <para>A page code for this example is placed below.</para>
+
+    <para>
+      <emphasis role=3D"bold">Example:</emphasis>
+    </para>
+    <programlisting role=3D"XML"><![CDATA[...
+    <a4j:status startText=3D"in progress" stopText=3D"done"/>
+     <a4j:form>
+        <a4j:region>
+            <a4j:push reRender=3D"msg" eventProducer=3D"#{pushBean.addList=
ener}" interval=3D"2000"/>
+        </a4j:region>
+        <a4j:outputPanel id=3D"msg" >
+            <h:outputText value=3D"#{pushBean.date}">
+                <f:convertDateTime type=3D"time"/>
+            </h:outputText>
+        </a4j:outputPanel>
+        <a4j:commandButton value=3D"Push!!" action=3D"#{pushBean.push}" aj=
axSingle=3D"true"/>
+    </a4j:form>
+... =

+]]></programlisting>
+
+    <para>The example shows how date is updated on a page in compliance wi=
th data taken from a
+      server. In the example <emphasis>
         <property>&quot;interval&quot;</property>
       </emphasis> attribute has value &quot;2000&quot;. This attribute def=
ines an interval
-      in milliseconds beetween the previous response and the next request.=
 Default value is set to
+      in milliseconds between the previous response and the next request. =
Default value is set to
       &quot;1000&quot; milliseconds (1 second). It&apos;s possible to set =
value equal to
       &quot;0&quot;. In this case connection is permanent. </para>
     <para>The <emphasis>
         <property>&quot;timeout&quot;</property>
-      </emphasis> attribute defines response wating time in milliseconds. =
If the response
+      </emphasis> attribute defines response waiting time in milliseconds.=
 If a response
       isn&apos;t received during this period a connection is aborted and t=
he next request is
       sent. Default value for <emphasis>
         <property>&quot;timeout&quot;</property>
@@ -81,22 +134,11 @@
       </emphasis> and <emphasis>
         <property>&quot;timeout&quot;</property>
       </emphasis> attributes gives an opportunity to set short polls of qu=
eue state or long
-      connections or permanent connection generally.</para>
-    <para>Code for <property>EventListener</property> registration in a be=
an is placed below:</para>
-    <para>
-      <emphasis role=3D"bold">Example:</emphasis>
-    </para>
-    <programlisting role=3D"JAVA"><![CDATA[...
-public void addListener(EventListener listener) {
-synchronized (listener) {
-        if (this.listener !=3D listener) {
-        this.listener =3D (PushEventListener) listener;
-}
-...
-]]></programlisting>
+      connections, or permanent connection.</para>
 =

-<para></para>
-
+    <note><title>Note:</title> The form around the <emphasis role=3D"bold">
+        <property>&lt;a4j:push&gt;</property>
+      </emphasis> component is required.</note>
   </section>
 =

   <!--section>


--===============0635930494187439860==--