From richfaces-svn-commits at lists.jboss.org Thu Nov 29 12:40:03 2007
Content-Type: multipart/mixed; boundary="===============6519027282423678161=="
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: r4358 -
 trunk/docs/userguide/en/src/main/docbook/included.
Date: Thu, 29 Nov 2007 12:40:01 -0500
Message-ID: <E1IxnMn-0000Qf-Fr@committer01.frg.pub.inap.atl.jboss.com>

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

Author: vkorluzhenko
Date: 2007-11-29 12:40:01 -0500 (Thu, 29 Nov 2007)
New Revision: 4358

Modified:
   trunk/docs/userguide/en/src/main/docbook/included/poll.desc.xml
   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.desc.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.desc.xml	2007-11=
-29 17:39:25 UTC (rev 4357)
+++ trunk/docs/userguide/en/src/main/docbook/included/poll.desc.xml	2007-11=
-29 17:40:01 UTC (rev 4358)
@@ -1,6 +1,6 @@
 <?xml version=3D'1.0' encoding=3D'UTF-8'?>
 <root>
-    <section>
+    <section id=3D"poll_d">
         <title>Description</title>
         <para>The <emphasis role=3D"bold">
                 <property>&lt;a4j:poll&gt;</property>

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-29 1=
7:39:25 UTC (rev 4357)
+++ trunk/docs/userguide/en/src/main/docbook/included/poll.xml	2007-11-29 1=
7:40:01 UTC (rev 4358)
@@ -63,18 +63,18 @@
     <title>Key attributes and ways of usage</title>
     <para id=3D"attributes">The <emphasis role=3D"bold">
         <property>&lt;a4j:poll&gt;</property>
-      </emphasis> componet is used for periodical polling of a server. In =
order to use the component
+      </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 a polling interval in milliseconds bee=
tween the previous
+      </emphasis> attribute defines an interval in milliseconds beetween t=
he 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>
       </emphasis> component is a sum of an<emphasis>
         <property>&quot;interval&quot;</property>
-      </emphasis> attribute value and a server response time. Default valu=
e for <emphasis>
+      </emphasis> attribute value and server response time. Default value =
for <emphasis>
         <property>&quot;interval&quot;</property>
-      </emphasis> attribute is set to 1000 milliseconds (1 second). See an=
 example of definition in
+      </emphasis> attribute is set to &quot;1000&quot; milliseconds (1 sec=
ond). See an example of definition in
       the <link linkend=3D"creating">&quot;Creating on a page&quot; sectio=
n</link>. </para>
     <para>The <emphasis>
         <property>&quot;timeout&quot;</property>
@@ -95,7 +95,7 @@
       </emphasis> attribute. You can use an EL-expression for <emphasis>
         <property>&quot;enabled&quot;</property>
       </emphasis> attribute to point to a bean property. An example of usa=
ge of <link
-        linkend=3D"attributes">all mentioned above attributes</link> is pl=
aced below:</para>
+        linkend=3D"attributes">mentioned above attributes</link> is placed=
 below:</para>
 =

     <para>
       <emphasis role=3D"bold">Example:</emphasis>
@@ -132,20 +132,16 @@
         <property>&quot;reRender&quot;</property>
       </emphasis> attribute for <emphasis role=3D"bold">
         <property>&lt;a4j:poll&gt;</property>
-      </emphasis> contains value of own Id. Hence, it renders itself for a=
pplying the current value
+      </emphasis> contains value of its own Id. Hence, it renders itself f=
or applying the current value
       of <emphasis>
         <property>&quot;enabled&quot;</property>
       </emphasis> attribute.</para>
+    =

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

-    <!--It&apos;s also necessary to define an ID of the <emphasis role=3D"=
bold">
-        <property>&lt;a4j:poll&gt;</property>
-      </emphasis> componet in its <emphasis>
-        <property>&quot;reRender&quot;</property>
-      </emphasis> attribute to apply the current value of <emphasis>
-        <property>&quot;enabled&quot;</property>
-      </emphasis> attribute. </para>
-
-    <para>The component decodes all necessary JavaScript for time count an=
d on the expiry of some
+    <!--para>The component decodes all necessary JavaScript for time count=
 and on the expiry of some
       interval for calling of a RichFaces utility method for Ajax request =
sending (A4J.AJAX.Submit
       (Some request parameters)). </para>
     <para> The timer could be stopped or started in any time. The current =
state is controlled on the

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-29 1=
7:39:25 UTC (rev 4357)
+++ trunk/docs/userguide/en/src/main/docbook/included/push.xml	2007-11-29 1=
7:40:01 UTC (rev 4358)
@@ -1,52 +1,106 @@
 <?xml version=3D'1.0' encoding=3D'UTF-8'?>
 <chapter>
-  =

-      <table>
-      <title>Component identification parameters </title>
-      <tgroup cols=3D"2">
-        <thead>
-          <row>
-            <entry>Name</entry>
-            <entry>Value</entry>
-          </row>
-        </thead>
-        <tbody>
-          <row>
-            <entry>component-type</entry>
-            <entry>org.ajax4jsf.Push</entry>
-          </row>
-          <row>
-            <entry>component-family</entry>
-            <entry>org.ajax4jsf.components.AjaxPush</entry>
-          </row>
-          <row>
-            <entry>component-class</entry>
-            <entry>org.ajax4jsf.component.html.AjaxPush</entry>
-          </row>
-          <row>
-            <entry>renderer-type</entry>
-            <entry>org.ajax4jsf.components.AjaxPushRenderer</entry>
-          </row>
-        </tbody>
-      </tgroup>
-    </table>
-  =

+
+  <table>
+    <title>Component identification parameters </title>
+    <tgroup cols=3D"2">
+      <thead>
+        <row>
+          <entry>Name</entry>
+          <entry>Value</entry>
+        </row>
+      </thead>
+      <tbody>
+        <row>
+          <entry>component-type</entry>
+          <entry>org.ajax4jsf.Push</entry>
+        </row>
+        <row>
+          <entry>component-family</entry>
+          <entry>org.ajax4jsf.components.AjaxPush</entry>
+        </row>
+        <row>
+          <entry>component-class</entry>
+          <entry>org.ajax4jsf.component.html.AjaxPush</entry>
+        </row>
+        <row>
+          <entry>renderer-type</entry>
+          <entry>org.ajax4jsf.components.AjaxPushRenderer</entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </table>
+
   <section>
     <title>Creating on a page</title>
-    <programlisting role=3D"XML"><![CDATA[
-<a4j:push reRender=3D"msg" eventProducer=3D"#{messageBean.addListener}" in=
terval=3D"3000"/>]]></programlisting>
+    <programlisting role=3D"XML"><![CDATA[<a4j:push reRender=3D"msg" event=
Producer=3D"#{messageBean.addListener}" interval=3D"3000"/>]]></programlist=
ing>
   </section>
- =

- <section>
+
+  <section>
     <title>Dynamical creation of a component from Java code</title>
-   <programlisting role=3D"JAVA"><![CDATA[import org.ajax4jsf.component.ht=
ml.AjaxPush;
+    <programlisting role=3D"JAVA"><![CDATA[import org.ajax4jsf.component.h=
tml.AjaxPush;
 ...
 AjaxPush myPush =3D new AjaxPush();
 ...]]></programlisting>
   </section>
-  =

+
+
   <section>
     <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">
+        <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>
+
+    <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>
+    <para>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
+      &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
+      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>
+      </emphasis> attribute isn&apos;t set. Usage of <emphasis>
+        <property>&quot;interval&quot;</property>
+      </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>
+
+<para></para>
+
+  </section>
+
+  <!--section>
+    <title>Key attributes and ways of usage</title>
 	<para>The main difference between <emphasis role=3D"bold"><property>&lt;a=
4j:push&gt;</property></emphasis>and
 	<emphasis role=3D"bold"><property>&lt;a4j:poll&gt;</property></emphasis> =
components
 	is that <emphasis role=3D"bold"><property>&lt;a4j:push&gt;</property></em=
phasis> makes request to minimal code only (not to JSF tree) in order to ch=
eck the presence of messages in the queue. =

@@ -58,7 +112,7 @@
 </para>
 <para>
 &quot;interval&quot; - Interval (in ms) for call push requests. Default va=
lue 1000 (1 sec).
-<!-- If "0" a connection is permanent. Also you can set different value fo=
r parameter 'timeout'. -->
+< If "0" a connection is permanent. Also you can set different value for p=
arameter 'timeout'.>
 </para>
 <para>
 Code for registration of listener:
@@ -83,14 +137,14 @@
 <para>
 Thus, component 'push' uses asynchronous model instead of polls.
 </para>
-  </section>
- =

+  </section-->
+
   <section>
     <title>Relevant resources links</title>
-	<para>
-	  <ulink url=3D"http://livedemo.exadel.com/richfaces-demo/richfaces/push.=
jsf?c=3Dpush">Here
-	  </ulink> you can see the example of <emphasis role=3D"bold"
-	    ><property>&lt;a4j:push&gt;</property></emphasis> usage and sources f=
or the given example. =

-	</para>
-  </section> =

-</chapter>
\ No newline at end of file
+    <para>
+      <ulink url=3D"http://livedemo.exadel.com/richfaces-demo/richfaces/pu=
sh.jsf?c=3Dpush">Here </ulink>
+      you can see the example of <emphasis role=3D"bold">
+        <property>&lt;a4j:push&gt;</property>
+      </emphasis> usage and sources for the given example. </para>
+  </section>
+</chapter>


--===============6519027282423678161==--